shopify-blog-embedded-product-card
在 Shopify 博客文章正文里插入现有商品的产品卡,读者点卡片即可跳到该商品的 Shopify 产品页(价格与链接自动跟随访客币种和语言)。主题 Liquid 实现,无需往正文粘贴 HTML,无需第三方 App。当用户提到 Shopify 博客内嵌产品卡、在文章里放产品卡/产品推荐/CTA、让读者从博客跳到商品页、blog embedded product card、Shopify Liquid 产品卡、blog post shop the look 时使用。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/warmpawelle--shopify-blog-embedded-product-card)HTML
<a href="/listings/warmpawelle--shopify-blog-embedded-product-card"><img src="/api/listings/warmpawelle--shopify-blog-embedded-product-card/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Two files change.
git clone https://github.com/warmpawelle/shopify-blog-embedded-product-card.git
1. `assets/blog-card.liquid` → theme `snippets/blog-card.liquid` 2. `sections/main-article.liquid` (or wherever `{{ article.content }}` lives) → add the picker block before `<article>` and replace the single `{{ article.content }}` with the per-paragraph loop
Exact code for both steps is in [`SKILL.md`](SKILL.md). If you use an AI coding agent, drop this folder into its skills directory and ask it to "add the blog product card to my theme" — the skill walks through locating the right file, patching it and verifying the result.
# WorkBuddy / Claude Code style skill directories cp -r shopify-blog-embedded-product-card ~/.workbuddy/skills/ # or cp -r shopify-blog-embedded-product-card ~/.claude/skills/
Verify before you ship
export SHOPIFY_STORE="your-shop.myshopify.com" export SHOPIFY_ADMIN_TOKEN="shpat_xxx" export SITE_URL="https://www.your-domain.com" python scripts/check_content.py # which posts are unsafe to split on </p> python scripts/audit_cards.py # which published posts render a card, and which product
`check_content.py` matters: `split: '</p>'` shreds any block that has no `</p>` inside it (`<table>`, `<div>`, `<ul>`). It flags those posts before you touch the theme.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 243 lines
- ---
- name: shopify-blog-embedded-product-card
- description: 在 Shopify 博客文章正文里插入现有商品的产品卡,读者点卡片即可跳到该商品的 Shopify 产品页(价格与链接自动跟随访客币种和语言)。主题 Liquid 实现,无需往正文粘贴 HTML,无需第三方 App。当用户提到 Shopify 博客内嵌产品卡、在文章里放产品卡/产品推荐/CTA、让读者从博客跳到商品页、blog embedded product card、Shopify Liquid 产品卡、blog post shop the look 时使用。
- ---
- # Shopify 博客内嵌产品卡
- 在文章正文里插一张产品卡,正确做法是**让主题渲染,而不是往正文粘贴 HTML**。
- ## 这个技能做什么
- 在 Shopify 博客文章里,插入一张指向**你自己现有商品**的产品卡。读者读到那一段,看到卡片,
- 点一下就直接进到对应的 Shopify 商品详情页 —— 不用自己在正文里翻链接,也不用复制商品名去站内搜。
- 卡片由主题在渲染时生成,不是写死在正文里的 HTML。所以:
- - **价格自动换币种** —— 德国访客看到 €13,95,日本访客看到 ¥2,300,不是写死的 $13.99
- - **链接自动带语言** —— 在 `/de/blogs/...` 页面上,卡片指向 `/de/products/...`,不会把德语用户甩回英文站
- - **跟着商品走** —— 改价、换主图、补库存、下架,卡片自动同步;商品下架卡片自动隐藏,不留死链
- - **改样式只改一处** —— 全站文章、所有语言共用同一个模板,不用逐篇返工
- 一句话:**文章负责种草,卡片负责把读者送到能下单的页面。**
- ```
- 文章正文 …… 这一段提到某个商品(带 /products/ 链接)
- ↓ 主题在渲染时截断正文、定位段落
- [ 产品卡 ] ← 自动出现在该段之后
- ↓
- 价格 = product.price | money → 自动跟随访客币种
- 链接 = product.url → 自动带 /de/ /zh/ 语言前缀
- 文案 = 'xxx.label' | t → 自动跟随语言
- ```
- 作者:[Warm Paw Elle](https://www.warmpawelle.com)。这套流程在多语言、多币种的真实店铺上跑通过
- (含日元、韩元这类 0 位小数币种),踩过的坑集中在 `references/pitfalls.md`。
- ---
- ## 第 0 步:先确认该不该用这套方案
- | 方案 | 适用 | 代价 |
- |---|---|---|
- | **主题 snippet(本方案)** | 多语种、多币种、文章数量 > 10 | 需要改主题代码,一次性 |
- | 手写行内 CSS HTML 粘正文 | 单语种单币种、只有 1–2 篇想做特殊版式 | 价格写死不会换算;译文是独立副本(N 篇文章 × M 种语言都要手工补);商品改价/换图后卡片变死数据 |
- | 第三方 App | 完全不想碰代码 | 月费;卡片 DOM 不受控,常与主题样式打架;多语种覆盖取决于 App |
- **只要店铺开了多语言子目录或多币种 Market,就必须用主题方案。** 手写 HTML 的卡片只会出现在你粘贴的那一份正文里。
- 先跑四项检查,把结果记下来:
- ```bash
- # 1. 主题是否 Online Store 2.0(有 sections/ 目录)
- ls sections/ | head
- # 2. 正文在哪个文件渲染 —— 这一步最关键
- grep -rn "article.content" sections/ templates/ snippets/
- # 3. 语言数量
- ls locales/*.json | wc -l
- # 4. 是否多币种(后台 Settings → Markets 有多个市场即为是)
- ```
- 如果第 2 步搜不到 `article.content`,说明是旧版主题(`templates/article.liquid` 里直接输出 `{{ article.content }}`),
- 改法相同,只是把第 2 步的代码放进 `templates/article.liquid`。
- ---
- ## 第 1 步:放入 snippet
- 把 `assets/blog-card.liquid` 复制到主题的 `snippets/blog-card.liquid`。
- 它接受三个参数,只有 `product` 必填:
- ```liquid
- {% render 'blog-card', product: product, label: 'Featured', cta: 'View product' %}
- ```
- 不传 `label` / `cta` 时,自动读词条 `blog_card.label` / `blog_card.cta`;词条不存在则回退英文,
- **所以不加词条也能直接工作**,不会出现 `Translation missing`。
- 卡片自带完整样式,全部选择器挂在 `.rte` 作用域下,不污染主题其它部分。关键点:
- 图左文右(`flex-wrap`)→ 窄屏自动堆叠成全宽大图;价格与按钮同一行(`margin-left:auto`)→ 手机端按钮撑满剩余宽度。
- ## 第 2 步:改 section(核心逻辑)
- 在 `<article>` 之前算出「用哪个商品、插在第几段」,然后把 `{{ article.content }}` 换成逐段输出。
- **2.1 选品 + 定位段落**(放在 `<article ...>` 标签之前)
- ```liquid
- {%- comment -%}
- 选品优先级:
- 1. 文章元字段 custom.blog_card_product(product_reference,编辑可在后台指定)
- 2. 正文里第一个 /products/<handle> 链接,且该商品 available 为真
- {%- endcomment -%}
- {%- liquid
- assign bc_product = article.metafields.custom.blog_card_product.value
- assign bc_paras = article.content | split: '</p>'
- assign bc_at = -1
- if bc_product != blank
- if bc_product.handle
- assign bc_handle = bc_product.handle
- else
- assign bc_handle = bc_product | strip
- assign bc_product = all_products[bc_handle]
- endif
- if bc_product != blank
- assign bc_target = '/products/' | append: bc_handle
- assign bc_i = 0
- for para in bc_paras
- if para contains bc_target
- assign bc_at = bc_i
- break
- endif
- assign bc_i = bc_i | plus: 1
- endfor
- if bc_at == -1
- assign bc_at = 1
- if bc_paras.size < 3
- assign bc_at = 0
- endif
- endif
- endif
- else
- assign bc_i = 0
- for para in bc_paras
- if para contains '/products/'
- assign seg = para | split: '/products/' | last
- assign seg = seg | split: '"' | first
- assign seg = seg | split: '?' | first
- assign seg = seg | split: '#' | first
- assign seg = seg | split: '/' | first
- assign cand = all_products[seg]
- if cand.available
- assign bc_product = cand
- assign bc_at = bc_i
- break
- endif
- endif
- assign bc_i = bc_i | plus: 1
- endfor
- endif
- -%}
- ```
- **2.2 逐段输出并注入卡片**(替换原来那一行 `{{ article.content }}`)
- ```liquid
- <div class="rte">
- {%- for para in bc_paras -%}
- {{ para }}{% unless forloop.last %}</p>{% endunless %}
- {%- if bc_product and forloop.index0 == bc_at -%}
- {% render 'blog-card', product: bc_product %}
- {%- endif -%}
- {%- endfor -%}
- </div>
- ```
- > `split: '</p>'` 会吃掉分隔符,所以必须手工补回 `</p>`;最后一段不补(正文可能以 `</ul>`、`</div>` 结尾)。
- > 正文若含 `<table>`、`<div>` 这类内部没有 `</p>` 的块,会被切碎。**上主题前先跑
- > `scripts/check_content.py` 扫一遍全站文章**,有风险的文章改用「在文末统一挂一张卡」的降级逻辑(见 `references/theme-integration.md`)。
- **2.3 降级:正文里没有任何商品链接**
- 不要硬塞。两个选择:一是在文章编辑页填 `custom.blog_card_product` 元字段;二是这类文章本就没有转化路径,
- 应该在正文补一条商品链接(顺带把历史文章里的死链一起清了)。
- ## 第 3 步:加词条(可选但推荐)
- `locales/en.default.json`:
- ```json
- {
- "blog_card": {
- "label": "Featured",
- "cta": "View product"
- }
- }
- ```
- 其余语言同理(`locales/de.json`、`locales/ja.json` …)。批量维护建议维护一份 `{locale: {label, cta}}` 的
- JSON 源文件再生成,避免手改 11 个文件漏键。日/德/法/西参考译法见 `references/i18n.md`。
- ## 第 4 步:建元字段(可选,用于人工指定商品)
- 后台 **设置 → 自定义数据 → 文章 → 添加定义**:
- | 项 | 值 |
- |---|---|
- | 名称 | 博客产品卡(可选) |
- | 命名空间和键 | `custom.blog_card_product` |
- | 类型 | 商品(product_reference) |
- 或者用 Admin API(`metafieldDefinitionCreate`,`ownerType: ARTICLE`)。不建也能跑,只是少了人工覆盖能力。
- ## 第 5 步:验证(必做,五项)
- ```bash
- UA="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/131 Safari/537.36"
- curl -sL -A "$UA" "https://你的域名/blogs/news/某篇文章" | grep -c 'class="bc-card"'
- ```
- 1. **渲染出卡**:计数 ≥ 1,且卡片标题 = 期望商品
- 2. **正文没丢字**:把文章 `body` 和渲染结果都 strip_tags 后做纯文本 diff,必须完全一致(只允许尾部空白差)
- 3. **结构化数据未破坏**:页面里每个 `<script type="application/ld+json">` 单独 `json.loads()` 必须成功
- 4. **多语言/多币种**:`/de/...` 看按钮文案与价格符号是否跟着变
- 5. **两种视口截图**:1440px 与 390px,看有没有横向滚动条、图片是否糊
- ⚠️ 别用无头浏览器批量抓线上页面做验证,Shopify 前置风控会返回 429。用 `curl` 串行 + 1s 间隔,
- 或直接抓 HTML 后本地渲染。截图脚本模板见 `references/verification.md`。
- ---
- ## 绝对不要做
- | 坑 | 后果 |
- |---|---|
- | 用 `text-decoration: none` 去掉卡片标题的下划线 | 多数主题的 `.rte a` 下划线是 `box-shadow: inset 0 -1px 0` 画的,改 text-decoration 无效,标题下会留一条贯穿整行的细线 |
- | 把卡片直接接在 `{{ article.content }}` 后面 | 卡片永远跑到文末,跟正文提到的商品脱节 |
- | 在 snippet 里写死 `$13.99 USD` | 德国访客看到美元价,结账变欧元,信任崩塌 |
- | 用 `article.excerpt` 代替定位逻辑 | 摘要是纯文本,没有任何链接可供定位 |
- | 卡片不加 `.rte` 前缀选择器 | 主题的 `img{max-width:100%}`、`p{margin}` 会渗进来,卡片在部分模板下错位 |
- 细节与复现步骤见 `references/pitfalls.md`。
- ---
- ## 仓库内容
- ```
- SKILL.md 本文件
- assets/blog-card.liquid 可直接复制的 snippet
- references/theme-integration.md 三种主题结构的改法(2.0 section / 旧版 article.liquid / Dawn 系)
- references/pitfalls.md 8 个真实踩坑与修法
- references/verification.md 验证脚本与截图模板
- references/i18n.md 11 种语言的按钮文案参考译法
- scripts/check_content.py 上主题前扫描正文结构风险
- scripts/audit_cards.py 上线后统计「有商品链接却没出卡」的文章
- ```
- MIT License.
README.md · README · 120 lines
- # Shopify Blog Embedded Product Card
- **Put a product card inside a blog post — rendered by the theme, not pasted into the body.**
- A Liquid snippet that injects a card for one of your **existing products** right after the paragraph
- that mentions it, so a reader can tap it and land on that product's Shopify page. Prices follow the
- visitor's currency, links follow the visitor's language, and nothing breaks when you translate the
- article or change the product photo.
- 
- Works with Online Store 2.0 themes, legacy `article.liquid` templates, and Dawn-derived themes.
- No app, no monthly fee, no JavaScript.
- ---
- ## Why not paste inline-styled HTML into the post body?
- Because most Shopify stores are not monolingual anymore. This is the difference:
- | | Inline HTML in the body | This snippet |
- |---|---|---|
- | Price for a German visitor | stuck at `$13.99 USD` | `€13,95` automatically via `money` |
- | Link on `/de/blogs/...` | points to `/products/...` (loses locale) | `product.url` carries the locale prefix |
- | Add a 10th language | re-paste the card into every translated copy | nothing to do |
- | Product price / photo changes | card goes stale | follows the product |
- | Product goes out of stock | dead card, broken click | card disappears (`available` guard) |
- | Restyle every post | edit each post × N languages | edit one CSS block |
- The only case where inline HTML is fine: a single-language, single-currency store with one or two
- posts that need a bespoke layout. Everyone else should render it.
- ## What you get
- - **Flex layout, `flex-wrap`** — image left / text right on desktop, full-width stacked image under 640px, no horizontal scrollbar
- - **`money` filter** — correct symbol, decimal count (JPY/KRW have zero) and grouping per market
- - **`product.url`** — locale prefix is automatic
- - **i18n-ready** — reads `blog_card.label` / `blog_card.cta`, silently falls back to English when the key is missing (no `Translation missing` leaking to customers)
- - **Two product pickers** — an article metafield (`custom.blog_card_product`) for manual control, otherwise the first in-stock `/products/` link in the body
- - **Scoped CSS** — every rule is prefixed with `.rte`, so it cannot leak into the rest of the theme
- | Desktop | Mobile |
- |---|---|
- |  | <img src="assets/preview-mobile.jpg" width="260"> |
- ## Install
- Two files change.
- ```bash
- git clone https://github.com/warmpawelle/shopify-blog-embedded-product-card.git
- ```
- 1. `assets/blog-card.liquid` → theme `snippets/blog-card.liquid`
- 2. `sections/main-article.liquid` (or wherever `{{ article.content }}` lives) → add the picker block
- before `<article>` and replace the single `{{ article.content }}` with the per-paragraph loop
- Exact code for both steps is in [`SKILL.md`](SKILL.md). If you use an AI coding agent, drop this
- folder into its skills directory and ask it to "add the blog product card to my theme" — the skill
- walks through locating the right file, patching it and verifying the result.
- ```bash
- # WorkBuddy / Claude Code style skill directories
- cp -r shopify-blog-embedded-product-card ~/.workbuddy/skills/
- # or
- cp -r shopify-blog-embedded-product-card ~/.claude/skills/
- ```
- ### Verify before you ship
- ```bash
- export SHOPIFY_STORE="your-shop.myshopify.com"
- export SHOPIFY_ADMIN_TOKEN="shpat_xxx"
- export SITE_URL="https://www.your-domain.com"
- python scripts/check_content.py # which posts are unsafe to split on </p>
- python scripts/audit_cards.py # which published posts render a card, and which product
- ```
- `check_content.py` matters: `split: '</p>'` shreds any block that has no `</p>` inside it
- (`<table>`, `<div>`, `<ul>`). It flags those posts before you touch the theme.
- ## The bug that costs the most time
- Every theme draws `.rte a` underlines differently, and many do it with a box-shadow:
- ```css
- .rte a { box-shadow: inset 0 -1px 0 rgba(74,37,80,.35); }
- ```
- `text-decoration: none` will not remove it. Your card title gets a hairline running the full width of
- the container. The fix is one declaration — `box-shadow: none !important` — and it is already in the
- snippet. Seven more pitfalls (paragraph gluing, shredded tables, 429 from Shopify during batch
- verification, the 100× unit difference on JPY carts) are in
- [`references/pitfalls.md`](references/pitfalls.md).
- ## Repo layout
- ```
- SKILL.md step-by-step implementation, for humans or agents
- assets/blog-card.liquid the snippet, copy as-is
- assets/preview-*.{png,jpg} screenshots from a live store
- references/theme-integration.md 2.0 section / legacy article.liquid / Dawn variations
- references/pitfalls.md 8 real failures and their fixes
- references/verification.md five checks + screenshot script
- references/i18n.md 11 locale translations, and what not to translate
- scripts/check_content.py pre-flight content scan
- scripts/audit_cards.py post-deploy coverage audit
- ```
- ## Provenance
- Every pitfall in this repo was hit on live Shopify stores — multiple markets, multiple locales,
- zero-decimal currencies, out-of-stock products, theme updates. Nothing here came from a sandbox.
- Maintained by [Warm Paw Elle](https://www.warmpawelle.com).
- ## License
- MIT. Use it, fork it, ship it. A link back is appreciated but not required.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.