hd-garden 0.8.3 → 0.8.4

package/README.md

@@ -50,7 +50,7 @@ npx garden ui catalog                          # 在 .garden/ui-catalog.html 生
 
 本地运行 `make dev` 后访问 `/garden`（英文版在 `/garden/en`），或直接阅读仓库内的文档：
 
-- **[Garden 使用说明（中文）](docs/handbook/index.md)** · **[Garden Handbook (English)](docs/handbook/en/index.md)**：快速开始、[用 AI 写作](docs/handbook/ai-writing.md)、[站点与专栏配置](docs/handbook/config.md)、[发布到 GitHub Pages](docs/handbook/deploy.md)、[写文章与随想](docs/handbook/writing.md)、[阅读排版](docs/handbook/design.md)、[12 个内置组件](docs/handbook/components.md) 与 [语法检查](docs/handbook/workflow.md)。
+- **[Garden 使用说明（中文）](docs/handbook/index.md)** · **[Garden Handbook (English)](docs/handbook/en/index.md)**：快速开始、[用 AI 写作](docs/handbook/ai-writing.md)、[站点与专栏配置](docs/handbook/config.md)、[发布到 GitHub Pages](docs/handbook/deploy.md)、[写文章与随想](docs/handbook/writing.md)、[阅读排版](docs/handbook/design.md)、[组件](docs/handbook/components.md)（12 个 `garden` 围栏，以及链接卡片、来源胶囊和本地图片）与 [语法检查](docs/handbook/workflow.md)。
 - **[从零开始](docs/quick-start.md)** 与 **[GitHub Pages 部署](docs/github-pages.md)**：单公开仓库或「私有源码仓库 + 公开页面仓库」的 Actions 配置与 Giscus 评论接入。
 - **[独立管理后台](docs/admin-service.md)**：可选的 `/admin` 服务（本地、Docker 或 Cloudflare Workers），支持网页发随想、阿里云 OSS 媒体直传与 `/admin/ui` 组件工作台。
 

package/app/lib/garden-docs-meta.ts

@@ -124,6 +124,9 @@ export const NAV_SHORT_TITLE: Record<string, string> = {
   "components/relations": "关系图",
   "components/list": "图标列表",
   "components/choice": "选择卡",
+  "components/link-card": "链接卡片",
+  "components/source": "来源胶囊",
+  "components/image": "本地图片",
   workflow: "语法检查与快捷输入",
   reference: "总览",
 };

package/docs/handbook/components/card.md

@@ -19,7 +19,7 @@ points:
 ```
 
 - **什么时候用**：介绍一篇论文、一个仓库或一本书，需要标题、链接和几条说明；或者把几项参考资源放在一起，各附一句可借鉴的结论。
-- **什么时候不用**：正文里一两句话已经说清，或者只需要普通外链卡片时，直接写正文段落。
+- **什么时候不用**：正文里一两句话已经说清，或者只需要[链接卡片](/garden/components/link-card)时，直接写正文段落。
 
 可以这样对 AI 说：
 

package/docs/handbook/components/image.md

@@ -0,0 +1,26 @@
+---
+title: 本地图片
+navTitle: 本地图片
+description: 把配图放在文章同名目录里，并用 alt 生成图注。
+section: components
+order: 45
+---
+
+图片单独成段时会包进图框，并在下方显示图注。
+
+- **什么时候用**：这张图属于文章，读者需要看到图下说明。
+- **什么时候不用**：只是装饰时，把 `alt` 写成以 `image`、`截图` 或 `img` 开头的占位词，这样不会出现图注。要按部分高亮说明时用[分区结构图](/garden/components/figure)；要提供下载时用[文件下载与预览](/garden/components/file)。
+
+长文 `content/posts/my-post.md` 的配图放在同名目录 `content/posts/my-post/`。正文用 Markdown 图片语法引用，地址写成 `./my-post/diagram.svg`，方括号里的 `alt` 写成图注。
+
+构建时会复制图片，并读出像素宽高，避免图片加载前把后面的文字顶下去。宽图如何向外扩，见[阅读排版是怎么工作的](/garden/design)。
+
+图注优先用写在地址后面引号里的 Markdown 标题，没有标题时用 `alt`。`alt` 以 `image`、`截图` 或 `img` 开头时不当作图注。
+
+下面这张图的图注就是它的 `alt`：
+
+![正文列、宽图区与宽表区](../assets/reading-layout.svg)
+
+随想里的图片写在 Front Matter 的 `media` 中，多张拼成宫格，不使用这套图注。见[写文章与随想](/garden/writing)。
+
+这不是 `garden` 围栏，没有字段表。

package/docs/handbook/components/link-card.md

@@ -0,0 +1,50 @@
+---
+title: 外部链接卡片
+navTitle: 链接卡片
+description: 把一条外部链接渲染成带网站名、标题和简介的卡片。
+section: components
+order: 43
+---
+
+单独占一段的网址，或链接末尾紧跟 `{card}`，会渲染成链接卡片。正文里的普通外部链接不会变成卡片，例如 [Typora](https://typora.io/)：只在文字前加站点 Favicon，右上角标 `↗`，图标与第一个字留在同一行。
+
+- **什么时候用**：希望读者点开之前先看到网站名、标题和简介。
+- **什么时候不用**：句子里只要标出出处时用[来源胶囊](/garden/components/source)；要自己写几条要点时用[知识卡片](/garden/components/card)。
+
+## 单独一行的网址
+
+前后留空行，整段只有网址：
+
+```markdown
+https://spec.commonmark.org/
+```
+
+https://spec.commonmark.org/
+
+## 写在句子里的 `{card}`
+
+`)` 后面紧跟 `{card}`，中间不加空格。链接留在句子里，卡片跟在这一段后面：
+
+```markdown
+表格、任务列表和脚注都来自 [remark-gfm](https://github.com/remarkjs/remark-gfm){card}，它让 GFM 语法在这里生效。
+```
+
+表格、任务列表和脚注都来自 [remark-gfm](https://github.com/remarkjs/remark-gfm){card}，它让 GFM 语法在这里生效。
+
+## 单独一行的 `{card}`
+
+这一段只有带标记的链接时，这一行直接换成卡片：
+
+```markdown
+[KaTeX 支持的函数](https://katex.org/docs/supported.html){card}
+```
+
+[KaTeX 支持的函数](https://katex.org/docs/supported.html){card}
+
+`{card}` 写在代码里会原样显示，例如 `[文字](https://example.com){card}`。标记和 `)` 之间有空格时也不会变成卡片。指向本站的链接会去掉标记，仍是站内链接。
+
+构建时读取正文里的 `{card}` 链接，把对方页面的标题、简介和封面记入 `link-assets.json`。单独一行的网址同样变成卡片，标题和简介用同一份记录；这个网址没有以 `{card}` 出现过时，卡片上显示网址本身。抓取失败就沿用上次的结果，构建不会因此中断。只刷新这些信息时运行 `npx garden links`。离线构建时把 `GARDEN_OFFLINE` 设为 `1` 会跳过拉取。
+
+随想 Front Matter 里的 `type: link` 用你写的 `title`、`description` 和 `image`，字段见[写文章与随想](/garden/writing)。
+
+这不是 `garden` 围栏，没有字段表。12 个围栏组件的字段见[组件参考](/garden/reference)。

package/docs/handbook/components/source.md

@@ -0,0 +1,22 @@
+---
+title: 来源胶囊（{source}）
+navTitle: 来源胶囊
+description: 在句子里标出引用站点，显示为不带外链箭头的圆角胶囊。
+section: components
+order: 44
+---
+
+在外部链接的 `)` 后面紧跟 `{source}`（中间不加空格），会渲染成圆角来源胶囊：左侧是构建期抓到的站点 Favicon，没抓到时用可注册域名主体的首字母（`en.wikipedia.org` 是 `W`，`bbc.co.uk` 是 `B`），右侧是链接文字，不带 `↗`。
+
+- **什么时候用**：一句话里标出处，不需要整张卡片。
+- **什么时候不用**：希望看到标题和简介时用[链接卡片](/garden/components/link-card)。`garden` 组件上的来源写在该组件的 `source` 字段里，见[组件参考](/garden/reference)。
+
+```markdown
+引自维基百科词条 [wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}。
+```
+
+引自维基百科词条 [wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}。
+
+写在代码里的 `{source}` 会原样显示。标记和 `)` 之间有空格时，仍是普通外链。
+
+这不是 `garden` 围栏，没有字段表。

package/docs/handbook/components.md

@@ -1,7 +1,7 @@
 ---
 title: 组件总览
 navTitle: 组件总览
-description: 12 个内置组件的效果预览。
+description: 12 个 garden 围栏，以及链接卡片、来源胶囊和本地图片的效果预览。
 section: components
 order: 30
 ---
@@ -219,3 +219,15 @@ none:
   label: 都不合适 / 说不清
   reply: 没关系，我们会在群里再列几个场地。
 ```
+
+## [链接卡片 · {card}](/garden/components/link-card)
+
+[KaTeX 支持的函数](https://katex.org/docs/supported.html){card}
+
+## [来源胶囊 · {source}](/garden/components/source)
+
+引自维基百科 [wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}
+
+## [本地图片](/garden/components/image)
+
+![正文列、宽图区与宽表区](./assets/reading-layout.svg)

package/docs/handbook/en/components/card.md

@@ -19,7 +19,7 @@ points:
 ```
 
 - **When to use**: Introducing a paper, open-source project, or subsystem where a link and 2 to 4 numbered points belong together, or listing several tools or references with a takeaway line.
-- **When to skip**: A sentence or two of prose or a `[Title](url){card}` link card is enough.
+- **When to skip**: A sentence or two of prose, or a [link card](/garden/en/components/link-card), is enough.
 
 You can tell the AI:
 

package/docs/handbook/en/components/image.md

@@ -0,0 +1,26 @@
+---
+title: Local Image
+navTitle: Local image
+description: Put a figure in the post sidecar folder and render its alt text as a caption.
+section: components
+order: 45
+---
+
+An image that is its own paragraph is wrapped in a figure, with a caption underneath.
+
+- **When to use**: The figure belongs in the article, and the reader should see a caption under it.
+- **When to skip**: For a decorative image, start the alt text with `image` or `img` so there is no caption. Use an [annotated diagram](/garden/en/components/figure) when each region needs its own note, or [file download](/garden/en/components/file) when the reader should download the file.
+
+For a post at `content/posts/my-post.md`, put images in `content/posts/my-post/`. Reference them with Markdown image syntax, with the address `./my-post/diagram.svg` and the caption in the alt text.
+
+The build copies the file and records its pixel width and height, so later text does not jump when the image loads. How wide figures expand is covered in [How the Reading Layout Works](/garden/en/design).
+
+The caption is the Markdown image title when you write one in quotes after the address. Otherwise it is the alt text. Alt text that starts with `image` or `img` is not used as a caption.
+
+The caption under this figure is its alt text:
+
+![Reading column, wide figure zone, and wide table zone](../../assets/reading-layout-en.svg)
+
+Images on a thought go in the `media` list in Front Matter and form a grid, without this caption. See [Writing Posts & Thoughts](/garden/en/writing).
+
+This is not a `garden` fence, so it has no field table.

package/docs/handbook/en/components/link-card.md

@@ -0,0 +1,50 @@
+---
+title: External Link Card
+navTitle: Link card
+description: Render an external URL as a card with the site name, title, and summary.
+section: components
+order: 43
+---
+
+A URL on its own paragraph, or a link followed immediately by `{card}`, renders as a link card. An ordinary external link in prose stays a link, such as [Typora](https://typora.io/): it shows the site favicon before the text and a `↗` at the upper right, and the icon stays on the same line as the first word.
+
+- **When to use**: The reader should see the site name, title, and summary before opening the page.
+- **When to skip**: Use a [source chip](/garden/en/components/source) to cite a site inside a sentence, or a [reference card](/garden/en/components/card) when you are writing the takeaways yourself.
+
+## A URL on its own line
+
+Leave blank lines around a paragraph that contains only the URL:
+
+```markdown
+https://spec.commonmark.org/
+```
+
+https://spec.commonmark.org/
+
+## `{card}` inside a sentence
+
+Write `{card}` immediately after `)`, with no space. The link stays in the sentence, and the card follows the paragraph:
+
+```markdown
+Tables, task lists, and footnotes come from [remark-gfm](https://github.com/remarkjs/remark-gfm){card}, which enables GFM here.
+```
+
+Tables, task lists, and footnotes come from [remark-gfm](https://github.com/remarkjs/remark-gfm){card}, which enables GFM here.
+
+## `{card}` on its own line
+
+When the paragraph is only the marked link, that line becomes the card:
+
+```markdown
+[Supported KaTeX functions](https://katex.org/docs/supported.html){card}
+```
+
+[Supported KaTeX functions](https://katex.org/docs/supported.html){card}
+
+`{card}` inside code stays as written, for example `[text](https://example.com){card}`. A space between `)` and the marker also leaves an ordinary link. A link back to this site drops the marker and stays an internal link.
+
+At build time, Garden reads `{card}` links in the body and stores the page title, summary, and image in `link-assets.json`. A URL on its own line becomes a card too, using that same record; when the URL has never appeared as `{card}`, the card shows the URL itself. A failed fetch keeps the previous record, and the build continues. Run `npx garden links` to refresh just these records. Set `GARDEN_OFFLINE` to `1` to skip the fetch during an offline build.
+
+A thought can also carry an external link in Front Matter with `type: link`, using the `title`, `description`, and `image` you write. Those fields are in [Writing Posts & Thoughts](/garden/en/writing).
+
+This is not a `garden` fence, so it has no field table. Fields for the 12 fence components are in the [component reference](/garden/en/reference).

package/docs/handbook/en/components/source.md

@@ -0,0 +1,22 @@
+---
+title: Source Chip ({source})
+navTitle: Source chip
+description: Cite a site inline as a rounded chip, without the external-link arrow.
+section: components
+order: 44
+---
+
+Write `{source}` immediately after the `)` of an external link, with no space. It renders as a rounded source chip: the site favicon fetched at build time, or the uppercase first letter of the registrable domain's main label (`W` for `en.wikipedia.org`, `B` for `bbc.co.uk`), then the link text, without a `↗`.
+
+- **When to use**: Name a source inside a sentence, without a full card.
+- **When to skip**: Use a [link card](/garden/en/components/link-card) when the reader should see a title and summary. On a `garden` component, the source is that component's `source` field, documented in the [component reference](/garden/en/reference).
+
+```markdown
+Cited from the Wikipedia article [wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}.
+```
+
+Cited from the Wikipedia article [wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}.
+
+`{source}` inside code stays as written. A space between `)` and the marker leaves an ordinary external link.
+
+This is not a `garden` fence, so it has no field table.

package/docs/handbook/en/components.md

@@ -1,7 +1,7 @@
 ---
 title: Components Overview
 navTitle: Overview
-description: Live preview of all 12 built-in components.
+description: Live previews of the 12 garden fences, plus link cards, source chips, and local images.
 section: components
 order: 30
 ---
@@ -220,3 +220,15 @@ none:
   label: Neither / not sure
   reply: No problem. We will share a few more venues in the group chat.
 ```
+
+## [Link card · {card}](/garden/en/components/link-card)
+
+[Supported KaTeX functions](https://katex.org/docs/supported.html){card}
+
+## [Source chip · {source}](/garden/en/components/source)
+
+Cited from Wikipedia [wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}
+
+## [Local image](/garden/en/components/image)
+
+![Reading column, wide figure zone, and wide table zone](../assets/reading-layout-en.svg)

package/docs/handbook/en/index.md

@@ -171,7 +171,7 @@ items:
     caption: Maximum width for wide multi-column tables expanding symmetrically on desktop
 ```
 
-See [Components Overview](/garden/en/components) in the sidebar for all 12 built-in components and their live examples.
+The component pages cover the 12 `garden` fences, plus link cards, source chips, and local images. See [Components Overview](/garden/en/components) for the live examples.
 
 <h2 id="garden-admin-title">From Init to Daily Writing</h2>
 
@@ -189,4 +189,4 @@ Run `make update` when a post is ready; it runs the full check and build before
 - **[Quick Start](/garden/en/start)**: Directory layout, creating posts with `make new`, previewing drafts, and daily commands.
 - **[Site & Column Config](/garden/en/config)**: Every field in `site.config.yaml`, custom SVG icons, and ordering series in `content/columns.yaml`.
 - **[Deploy to GitHub Pages](/garden/en/deploy)**: A single GitHub Actions workflow that supports both one public repository and a private source repo paired with a public Pages repo.
-- **[Writing Posts & Thoughts](/garden/en/writing)** and **[How the Reading Layout Works](/garden/en/design)**: Front Matter fields, external link cards, three-tier adaptive widths, and color tokens.
+- **[Writing Posts & Thoughts](/garden/en/writing)** and **[How the Reading Layout Works](/garden/en/design)**: Front Matter fields, three-tier adaptive widths, and color tokens. Link cards, source chips, and local images are on [Components Overview](/garden/en/components).

package/docs/handbook/en/reference.md

@@ -1,13 +1,15 @@
 ---
 title: Component reference
 navTitle: Overview
-description: Every field, default, limit and error code for the 12 built-in components, one page each.
+description: Every field, default, limit, and error code for the 12 garden fence components, one page each.
 section: reference
 order: 0
 ---
 
 Each page shows the code on the left and the real rendered result on the right; on narrow screens, switch with Preview / Code. For when to use a component, see its usage page.
 
+Link cards, source chips, and local images have no field pages. Their usage pages are linked from [Components Overview](/garden/en/components).
+
 For every component: invalid YAML, or a top-level key the component does not support, reports `garden-yaml` on the whole block; a misspelled fence name reports `garden-name`.
 
 | Component | Use it for |

package/docs/handbook/en/writing.md

@@ -1,7 +1,7 @@
 ---
 title: Writing Posts & Thoughts
 navTitle: Writing Posts & Thoughts
-description: Front Matter fields for posts and thoughts, code diff toggles, callouts, link cards, math formulas, and Mermaid diagrams.
+description: Front Matter fields for posts and thoughts, code diff toggles, callouts, math formulas, and Mermaid diagrams, with links to local images, source chips, and link cards.
 section: writing-and-reading
 order: 10
 ---
@@ -112,13 +112,10 @@ func openStore(path string) (*Store, error) {
 
 ## 4. Local Images, Source Chips, and External Link Cards
 
-- **Local images and sidecar folders**: For a post at `content/posts/my-post.md`, place its images inside `content/posts/my-post/` and reference them with relative paths such as `./my-post/diagram.svg`. At build time, Garden copies the file, records its pixel dimensions, and renders the `alt` text (unless it starts with default placeholders like `image` or `img`) as a `<figcaption>`.
-- **Inline external links**: Regular external links in body text automatically display the target site's favicon and a trailing `↗` arrow, keeping the icon attached to the first word of the link so it never wraps alone.
-- **Inline source chips (`{source}`)**: Append `{source}` directly after the closing `)` of an external link (with no space), such as `[wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}`, to render it as an inline source chip: the site's build-time favicon (or the uppercase first letter of the registrable domain's main label, such as `W` for `en.wikipedia.org`) plus the link text, **without** the `↗` external-link arrow. For example: cited from Wikipedia [wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}.
-- **Link cards**: Turn an external URL into a preview card with site name, title, and description in either of two ways:
-  1. Put the full URL on its own paragraph line (surrounded by blank lines): `https://spec.commonmark.org/`
-  2. Append `{card}` directly to an inline link (with no space): `See the [CommonMark Spec](https://spec.commonmark.org/){card}.`
-  You can also run `make embed URL="https://example.com"` to fetch Open Graph metadata for a URL.
+These three are written in the Markdown body. Rendering rules live on the component pages. This section only records where the files go:
+
+- **Local images**: For a post at `content/posts/my-post.md`, put images in `content/posts/my-post/` and reference them as `./my-post/diagram.svg`. Captions are documented on [Local Image](/garden/en/components/image).
+- **Source chips** and **link cards** stay in the prose. See [Source Chip](/garden/en/components/source) and [Link Card](/garden/en/components/link-card).
 
 ## 5. Math Formulas and Mermaid Diagrams
 
@@ -154,4 +151,4 @@ media:
 A short note written in standard Markdown.
 ```
 
-The `media` array accepts four item types: `image` (multiple images automatically form a grid), `audio` (native `<audio>` player), `video` (native `<video>` player with optional `poster`), and `link` (rendered as an external link card supporting `src`, `title`, `description`, and `image`).
+The `media` array accepts four item types: `image` (multiple images automatically form a grid), `audio` (native `<audio>` player), `video` (native `<video>` player with optional `poster`), and `link` (a card built from the `src`, `title`, `description`, and `image` you write). Link cards in the body are documented on [Link Card](/garden/en/components/link-card).

package/docs/handbook/index.md

@@ -166,7 +166,7 @@ items:
     caption: 宽表格在桌面端向两侧对称外扩上限
 ```
 
-12 个内置组件的完整参数与实时示例见左侧导航的 [组件总览](/garden/components)。
+组件页包括 12 个 `garden` 围栏，以及链接卡片、来源胶囊和本地图片。效果见左侧导航的 [组件总览](/garden/components)。
 
 <h2 id="garden-admin-title">从初始化到日常写作</h2>
 
@@ -184,4 +184,4 @@ make dev
 - **[快速开始](/garden/start)**：目录结构、`make new` 新建长文、草稿预览与日常命令。
 - **[站点与专栏配置](/garden/config)**：`site.config.yaml` 各字段含义、自定义 SVG 图标与 `content/columns.yaml` 专栏编排。
 - **[发布到 GitHub Pages](/garden/deploy)**：单个公开仓库或「私有源码仓库 + 公开页面仓库」的完整 Actions 工作流。
-- **[写文章与随想](/garden/writing)** 与 **[阅读排版是怎么工作的](/garden/design)**：Front Matter 字段、外链卡片、三级自适应宽度与色彩变量。
+- **[写文章与随想](/garden/writing)** 与 **[阅读排版是怎么工作的](/garden/design)**：Front Matter 字段、三级自适应宽度与色彩变量。链接卡片、来源胶囊和本地图片见 [组件总览](/garden/components)。

package/docs/handbook/reference.md

@@ -1,13 +1,15 @@
 ---
 title: 组件参考
 navTitle: 总览
-description: 12 个内置组件的全部字段、默认值、取值限制和报错代码，每个组件一页。
+description: 12 个 garden 围栏组件的全部字段、默认值、取值限制和报错代码，每个组件一页。
 section: reference
 order: 0
 ---
 
 每页左边是代码，右边是同一段代码渲染出的真实效果；窄屏下用「效果 / 代码」切换。用法和什么时候用，见各组件的用法页。
 
+链接卡片、来源胶囊和本地图片没有字段页，用法在 [组件总览](/garden/components)。
+
 所有组件通用：YAML 语法错误，或顶层出现不支持的键名，整块报 `garden-yaml`；围栏名写错报 `garden-name`。
 
 | 组件 | 用途 |

package/docs/handbook/writing.md

@@ -1,7 +1,7 @@
 ---
 title: 写文章与随想
 navTitle: 写文章与随想
-description: 长文与随想的 Front Matter 字段、代码块对比、提示框、外链卡片、公式与流程图写法。
+description: 长文与随想的 Front Matter 字段、代码块对比、提示框、公式与流程图，以及配图、来源胶囊和链接卡片的入口。
 section: writing-and-reading
 order: 10
 ---
@@ -112,13 +112,10 @@ func openStore(path string) (*Store, error) {
 
 ## 4. 本地图片、来源胶囊与外部链接卡片
 
-- **本地图片与随文目录**：如果文章路径是 `content/posts/my-post.md`，把配图放在同名的 `content/posts/my-post/` 文件夹下，在文中以 `./my-post/diagram.svg` 相对路径引用。构建时会自动复制图片、读取像素宽高，并把 `alt` 文字（以 `image`、`截图`、`img` 开头的默认占位词除外）渲染成图注 `<figcaption>`。
-- **行内外部链接**：正文里的普通外部链接会自动加上目标站点的 Favicon 小图标与右上角 `↗` 箭头，并保证图标与链接第一个字同行不折断。
-- **行内来源胶囊（`{source}`）**：在行内外部链接的 `)` 后面紧跟 `{source}`（中间不加空格），例如 `[wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}`，会渲染成圆角来源胶囊：左侧是构建期抓到的站点 Favicon（未抓到时回退为可注册域名主体的首字母，如 `en.wikipedia.org` 显示 `W`），右侧是链接文字，**不带** `↗` 外链箭头。效果如：引自维基百科词条 [wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}。
-- **链接卡片**：有两种写法可以把外部链接渲染成带网站名、标题和简介的链接卡片：
-  1. 把完整网址单独写成一行段落（前后空行）：`https://spec.commonmark.org/`
-  2. 在段落内的链接末尾紧跟 `{card}`（中间不加空格）：`参见 [CommonMark 规范](https://spec.commonmark.org/){card}。`
-  也可以运行 `make embed URL="https://example.com"` 抓取目标网页的 Open Graph 标题、摘要和封面图。
+这三项写在 Markdown 正文里。渲染规则在组件页，这里只保留文件放哪：
+
+- **本地图片**：长文 `content/posts/my-post.md` 的配图放在同名目录 `content/posts/my-post/`，正文用 `./my-post/diagram.svg` 引用。图注见[本地图片](/garden/components/image)。
+- **来源胶囊**与**链接卡片**不另建文件。见[来源胶囊](/garden/components/source)和[链接卡片](/garden/components/link-card)。
 
 ## 5. 数学公式与 Mermaid 图表
 
@@ -154,4 +151,4 @@ media:
 记一段简短的想法，支持完整的 Markdown 语法。
 ```
 
-`media` 数组支持四类条目：`image`（多张图片自动拼成宫格图集）、`audio`（原生 `<audio>` 音频播放器）、`video`（原生 `<video>` 视频播放器，指向视频文件地址，可配 `poster` 封面）和 `link`（渲染为外部链接卡片，支持 `src`、`title`、`description`、`image`）。
+`media` 数组支持四类条目：`image`（多张图片自动拼成宫格图集）、`audio`（原生 `<audio>` 音频播放器）、`video`（原生 `<video>` 视频播放器，指向视频文件地址，可配 `poster` 封面）和 `link`（用你写的 `src`、`title`、`description`、`image` 做一张链接卡）。正文里的链接卡片见[链接卡片](/garden/components/link-card)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-garden",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "private": false,
   "description": "用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。",
   "license": "MIT",