Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/warmpawelle--shopify-blog-embedded-product-card/badge.svg)](/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

i

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

Free to use. If it’s helped, pass it on.