hd-garden 0.14.12 → 0.14.13

package/docs/handbook/en/components/diagrams/tabs.md

@@ -0,0 +1,40 @@
+---
+title: "Tabs"
+navTitle: "Tabs"
+description: "Use this when several groups of notes are independent and the reader should see one group at a time"
+section: diagrams
+order: 121
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![Schematic for Tabs](../../../components/diagrams/previews/tabs.svg)
+
+Use this when several groups of notes are independent and the reader should see one group at a time.
+
+Do not hide facts that must be compared at the same time. This is not app navigation.
+
+Typora and VS Code / Cursor share this list. In the `/garden` picker, this row is the same figure and the same use case. Choosing it inserts a `garden compose` brief. Fill in your material and goal, then ask the AI to compile the post.
+
+The built-in picker currently inserts that brief in Chinese. The English wording below is the same recommended brief, written for the English handbook so you can copy it when you write in English.
+
+The recommended brief is a starting point, not a syntax lesson, and not the only valid form. You may still combine Markdown or safe HTML building blocks in the same `garden compose` fence.
+
+````markdown
+```garden compose
+Please make a "Tabs" diagram in garden compose from the material and the communication goal I provide.
+
+My material:
+- (paste the original items and wording to keep)
+
+My goal:
+- (what the reader should see at a glance)
+
+Please:
+- Organize only from the material; do not invent facts or conclusions
+- Handle the graphic syntax, layout, and mobile reading yourself; do not ask me to learn tags or write CSS
+- "Tabs" is the recommended starting point: Use tabs only when the groups can be read separately. Do not hide content that must be compared side by side
+- A recommended figure is not the only valid form; you may still combine necessary Markdown / HTML building blocks in the same compose fence
+- Do not start a different author fence or a new syntax; use only garden compose
+```
+````

package/docs/handbook/en/components/diagrams/timeline.md

@@ -0,0 +1,40 @@
+---
+title: "Timeline"
+navTitle: "Timeline"
+description: "Use this to arrange events by date or time"
+section: diagrams
+order: 101
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![Schematic for Timeline](../../../components/diagrams/previews/timeline.svg)
+
+Use this to arrange events by date or time.
+
+If the material is not a duration-scaled schedule, do not draw a Gantt chart with bar lengths.
+
+Typora and VS Code / Cursor share this list. In the `/garden` picker, this row is the same figure and the same use case. Choosing it inserts a `garden compose` brief. Fill in your material and goal, then ask the AI to compile the post.
+
+The built-in picker currently inserts that brief in Chinese. The English wording below is the same recommended brief, written for the English handbook so you can copy it when you write in English.
+
+The recommended brief is a starting point, not a syntax lesson, and not the only valid form. You may still combine Markdown or safe HTML building blocks in the same `garden compose` fence.
+
+````markdown
+```garden compose
+Please make a "Timeline" diagram in garden compose from the material and the communication goal I provide.
+
+My material:
+- (paste the original items and wording to keep)
+
+My goal:
+- (what the reader should see at a glance)
+
+Please:
+- Organize only from the material; do not invent facts or conclusions
+- Handle the graphic syntax, layout, and mobile reading yourself; do not ask me to learn tags or write CSS
+- "Timeline" is the recommended starting point: Arrange events by the dates or times in the source, and keep that order. Do not turn it into a duration-scaled progress bar
+- A recommended figure is not the only valid form; you may still combine necessary Markdown / HTML building blocks in the same compose fence
+- Do not start a different author fence or a new syntax; use only garden compose
+```
+````

package/docs/handbook/en/components/diagrams/trace.md

@@ -0,0 +1,40 @@
+---
+title: "Path callout"
+navTitle: "Path callout"
+description: "Use this to mark how far you have walked on an existing flow or state diagram"
+section: diagrams
+order: 181
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![Schematic for Path callout](../../../components/diagrams/previews/trace.svg)
+
+Use this to mark how far you have walked on an existing flow or state diagram.
+
+If you only need the structure, or there are too many nodes and edges, split it first.
+
+Typora and VS Code / Cursor share this list. In the `/garden` picker, this row is the same figure and the same use case. Choosing it inserts a `garden compose` brief. Fill in your material and goal, then ask the AI to compile the post.
+
+The built-in picker currently inserts that brief in Chinese. The English wording below is the same recommended brief, written for the English handbook so you can copy it when you write in English.
+
+The recommended brief is a starting point, not a syntax lesson, and not the only valid form. You may still combine Markdown or safe HTML building blocks in the same `garden compose` fence.
+
+````markdown
+```garden compose
+Please make a "Path callout" diagram in garden compose from the material and the communication goal I provide.
+
+My material:
+- (paste the original items and wording to keep)
+
+My goal:
+- (what the reader should see at a glance)
+
+Please:
+- Organize only from the material; do not invent facts or conclusions
+- Handle the graphic syntax, layout, and mobile reading yourself; do not ask me to learn tags or write CSS
+- "Path callout" is the recommended starting point: Mark the current step on an existing state or flow diagram. Do not invent nodes or transitions that are not in the source
+- A recommended figure is not the only valid form; you may still combine necessary Markdown / HTML building blocks in the same compose fence
+- Do not start a different author fence or a new syntax; use only garden compose
+```
+````

package/docs/handbook/en/components/diagrams/tunable.md

@@ -0,0 +1,40 @@
+---
+title: "Tunable chart"
+navTitle: "Tunable chart"
+description: "Use this when the reader should change one or two inputs and watch the result"
+section: diagrams
+order: 141
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![Schematic for Tunable chart](../../../components/diagrams/previews/tunable.svg)
+
+Use this when the reader should change one or two inputs and watch the result.
+
+If there is only one fixed example, or too many inputs, split it first. If one input should drive several outputs, use a conversion diagram.
+
+Typora and VS Code / Cursor share this list. In the `/garden` picker, this row is the same figure and the same use case. Choosing it inserts a `garden compose` brief. Fill in your material and goal, then ask the AI to compile the post.
+
+The built-in picker currently inserts that brief in Chinese. The English wording below is the same recommended brief, written for the English handbook so you can copy it when you write in English.
+
+The recommended brief is a starting point, not a syntax lesson, and not the only valid form. You may still combine Markdown or safe HTML building blocks in the same `garden compose` fence.
+
+````markdown
+```garden compose
+Please make a "Tunable chart" diagram in garden compose from the material and the communication goal I provide.
+
+My material:
+- (paste the original items and wording to keep)
+
+My goal:
+- (what the reader should see at a glance)
+
+Please:
+- Organize only from the material; do not invent facts or conclusions
+- Handle the graphic syntax, layout, and mobile reading yourself; do not ask me to learn tags or write CSS
+- "Tunable chart" is the recommended starting point: Name the inputs and the conclusion that changes with them. The default state should already make sense. Do not ask the author to write a program
+- A recommended figure is not the only valid form; you may still combine necessary Markdown / HTML building blocks in the same compose fence
+- Do not start a different author fence or a new syntax; use only garden compose
+```
+````

package/docs/handbook/en/components/diagrams/two-row.md

@@ -0,0 +1,40 @@
+---
+title: "Two-row contrast"
+navTitle: "Two-row contrast"
+description: "Use this to contrast a background process with the process you want to emphasize, on two rows"
+section: diagrams
+order: 51
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+![Schematic for Two-row contrast](../../../components/diagrams/previews/two-row.svg)
+
+Use this to contrast a background process with the process you want to emphasize, on two rows.
+
+If you are not contrasting two processes, or you are comparing options under the same conditions, do not use this two-row layout.
+
+Typora and VS Code / Cursor share this list. In the `/garden` picker, this row is the same figure and the same use case. Choosing it inserts a `garden compose` brief. Fill in your material and goal, then ask the AI to compile the post.
+
+The built-in picker currently inserts that brief in Chinese. The English wording below is the same recommended brief, written for the English handbook so you can copy it when you write in English.
+
+The recommended brief is a starting point, not a syntax lesson, and not the only valid form. You may still combine Markdown or safe HTML building blocks in the same `garden compose` fence.
+
+````markdown
+```garden compose
+Please make a "Two-row contrast" diagram in garden compose from the material and the communication goal I provide.
+
+My material:
+- (paste the original items and wording to keep)
+
+My goal:
+- (what the reader should see at a glance)
+
+Please:
+- Organize only from the material; do not invent facts or conclusions
+- Handle the graphic syntax, layout, and mobile reading yourself; do not ask me to learn tags or write CSS
+- "Two-row contrast" is the recommended starting point: Name the stages of the background process above and the focus process below, and say which row is the focus
+- A recommended figure is not the only valid form; you may still combine necessary Markdown / HTML building blocks in the same compose fence
+- Do not start a different author fence or a new syntax; use only garden compose
+```
+````

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

@@ -0,0 +1,100 @@
+---
+title: "Recommended figures"
+navTitle: "Recommended figures"
+description: "Names, schematics, use cases, and recommended briefs for the built-in Typora and VS Code figure list."
+section: diagrams
+order: 1
+---
+
+<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->
+
+
+The `/garden` list in Typora and in VS Code / Cursor comes from the same built-in list. There are currently 21 items: 20 common figures, and Other as the last item. Choosing one inserts a single `garden compose` brief, not a different author fence. That brief is for your material and goal, not a syntax lesson.
+
+Use Other when no built-in figure fits, or when you need to combine text and graphics freely. Do not treat the list below as a closed allowlist.
+
+For the entry and compile steps, see [Compose](/garden/en/components/compose) and [Checks & Shortcuts](/garden/en/workflow).
+
+![Schematic for Join diagram](../../components/diagrams/previews/columns-join.svg)
+
+**[Join diagram](/garden/en/components/diagrams/columns-join/)** Use this to show how two sides connect through a middle item.
+
+![Schematic for Fan-out diagram](../../components/diagrams/previews/fan-out.svg)
+
+**[Fan-out diagram](/garden/en/components/diagrams/fan-out/)** Use this to show a first stop that then branches to several places at once.
+
+![Schematic for Layer diagram](../../components/diagrams/previews/layers.svg)
+
+**[Layer diagram](/garden/en/components/diagrams/layers/)** Use this to show top-down layers that do not have to be walked in order.
+
+![Schematic for Aspect diagram](../../components/diagrams/previews/facets.svg)
+
+**[Aspect diagram](/garden/en/components/diagrams/facets/)** Use this to show several aspects of one thing, with no required order.
+
+![Schematic for Two-row contrast](../../components/diagrams/previews/two-row.svg)
+
+**[Two-row contrast](/garden/en/components/diagrams/two-row/)** Use this to contrast a background process with the process you want to emphasize, on two rows.
+
+![Schematic for Illustrated list](../../components/diagrams/previews/icon-rail.svg)
+
+**[Illustrated list](/garden/en/components/diagrams/icon-rail/)** Use this to explain independent items one by one.
+
+![Schematic for Flow diagram](../../components/diagrams/previews/sequence.svg)
+
+**[Flow diagram](/garden/en/components/diagrams/sequence/)** Use this to show the order in which something is done.
+
+![Schematic for Step diagram](../../components/diagrams/previews/steps.svg)
+
+**[Step diagram](/garden/en/components/diagrams/steps/)** Use this to explain something step by step, with room for detail inside a step.
+
+![Schematic for Comparison diagram](../../components/diagrams/previews/compare.svg)
+
+**[Comparison diagram](/garden/en/components/diagrams/compare/)** Use this to compare two or three options under the same conditions.
+
+![Schematic for Timeline](../../components/diagrams/previews/timeline.svg)
+
+**[Timeline](/garden/en/components/diagrams/timeline/)** Use this to arrange events by date or time.
+
+![Schematic for Message sequence](../../components/diagrams/previews/lanes.svg)
+
+**[Message sequence](/garden/en/components/diagrams/lanes/)** Use this to show who sent what to whom, and when.
+
+![Schematic for Tabs](../../components/diagrams/previews/tabs.svg)
+
+**[Tabs](/garden/en/components/diagrams/tabs/)** Use this when several groups of notes are independent and the reader should see one group at a time.
+
+![Schematic for Chart](../../components/diagrams/previews/chart.svg)
+
+**[Chart](/garden/en/components/diagrams/chart/)** Use this to turn numbers you already have into bars, lines, or shares.
+
+![Schematic for Tunable chart](../../components/diagrams/previews/tunable.svg)
+
+**[Tunable chart](/garden/en/components/diagrams/tunable/)** Use this when the reader should change one or two inputs and watch the result.
+
+![Schematic for Conversion diagram](../../components/diagrams/previews/converter.svg)
+
+**[Conversion diagram](/garden/en/components/diagrams/converter/)** Use this when one input should produce several results at once.
+
+![Schematic for Code walkthrough](../../components/diagrams/previews/code-walkthrough.svg)
+
+**[Code walkthrough](/garden/en/components/diagrams/code-walkthrough/)** Use this to walk through code line by line: what runs, and what the variables are.
+
+![Schematic for Stepper](../../components/diagrams/previews/stepper.svg)
+
+**[Stepper](/garden/en/components/diagrams/stepper/)** Use this when the reader should pause on a step and see how state changes.
+
+![Schematic for Path callout](../../components/diagrams/previews/trace.svg)
+
+**[Path callout](/garden/en/components/diagrams/trace/)** Use this to mark how far you have walked on an existing flow or state diagram.
+
+![Schematic for Checklist](../../components/diagrams/previews/plan.svg)
+
+**[Checklist](/garden/en/components/diagrams/plan/)** Use this when the reader should follow items one by one and come back to check progress.
+
+![Schematic for Grid diagram](../../components/diagrams/previews/inspect-grid.svg)
+
+**[Grid diagram](/garden/en/components/diagrams/inspect-grid/)** Use this to mark which cells in a two-dimensional structure matter, and why.
+
+![Schematic for Other](../../components/diagrams/previews/other.svg)
+
+**[Other](/garden/en/components/diagrams/other/)** Use this when no built-in figure fits, and you need to combine text and graphics freely.

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

@@ -6,7 +6,7 @@ section: components
 order: 43
 ---
 
-A URL on its own paragraph, or a link followed immediately by `{card}`, renders as a link card (same-site and external share one path). An ordinary titled link in prose stays a link, such as [Typora](https://typora.io/): an external one shows the site favicon before the text and a `↗` at the upper right; a titled same-site link still navigates in place.
+A URL on its own paragraph, or a link followed immediately by `{card}`, renders as a link card (same-site and external share one path). Exception: a playable YouTube or Bilibili video URL on its own line becomes an in-article player; see [Writing](/garden/en/writing). To keep a card, write `{card}` immediately after the link. An ordinary titled link in prose stays a link, such as [Typora](https://typora.io/): an external one shows the site favicon before the text and a `↗` at the upper right; a titled same-site link still navigates in place.
 
 - **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/compose) when you are writing the takeaways yourself.

package/docs/handbook/en/components.md

@@ -9,5 +9,6 @@ order: 30
 Use one `garden compose` fence for article layouts, rich content, semantic scenes and interactive explanations. Select components inside that entry; use ordinary Markdown when it already communicates the idea.
 
 - [Compose](/garden/en/components/compose)
+- [Recommended figures](/garden/en/components/diagrams)
 - [Compose reference](/garden/en/reference/compose)
 - [Icons](/garden/en/reference/compose-icons)

package/docs/handbook/en/start.md

@@ -21,7 +21,7 @@ make dev
 
 `npx hd-garden init` copies the site template into `my-blog` and writes the helper skills under `.agents/skills/`. When `--locale en` or `--locale en_US` is passed, it generates an English `site.config.yaml`, `Makefile`, and `README.md`, and installs `.github/workflows/pages.yml` from `templates/workflows/pages.en.yml` (default `zh_CN` initialization does not create `.github/workflows/pages.yml`; see [Deploy to GitHub Pages](/garden/en/deploy)). It does not run `npm install` automatically.
 
-On the first `make dev` run, if `node_modules` is missing, `make prepare` in the `Makefile` runs `npm install` before invoking `npx garden dev` (which syncs content first) and starting the local dev server at `http://localhost:3000`.
+On the first `make dev` run, if `node_modules` is missing, `make prepare` in the `Makefile` runs `npm install` before invoking `npx garden dev` (which syncs content first) and starting the local development server. The default preview is Node RSC; use `npx garden dev --worker` when you need Cloudflare Worker behavior.
 
 ## 2. Directory Structure
 

package/docs/handbook/en/workflow.md

@@ -104,8 +104,8 @@ The Obsidian plugin is not installed by this command.
 
 ### Use the plugins while writing
 
-1. **Insert an idea.** In VS Code / Cursor, use `Cmd+Alt+I` on macOS or `Ctrl+Alt+I` on Windows and Linux, or the Garden insert command. In Typora, type `/` and choose `/garden` (the next list has a small preview image on each row), or use the insert command to open the component list directly; Windows and Linux default to `Ctrl+Alt+I`. On macOS, record a shortcut under Settings, Keyboard Shortcuts, because Option rewrites the key. The insertion is a plain `garden` fence: a short brief naming the component and the facts to mention, which the `garden-compose` skill compiles later.
-2. **Preview.** Open the Markdown preview. In Typora, move the cursor out of the fence. A `ui` block renders the same component as the blog. An `intent` block renders as an idea card. Clicks on sliders and buttons stay in the preview.
+1. **Insert Compose.** In VS Code / Cursor, use `Cmd+Alt+I` on macOS or `Ctrl+Alt+I` on Windows and Linux, or the Garden insert command. In Typora, type `/` and choose `/garden`, then pick a figure type from the next list (the last item is Other; each row has a small preview), or use the insert command to open that list directly; Windows and Linux default to `Ctrl+Alt+I`. On macOS, record a shortcut under Settings, Keyboard Shortcuts, because Option rewrites the key. The selection inserts a `garden compose` fence with a draft brief for that figure, which the `garden-compose` skill compiles later. Do not insert a legacy `ui` or `intent` fence. For every built-in figure, see [Recommended figures](/garden/en/components/diagrams).
+2. **Preview.** Open the Markdown preview. In Typora, move the cursor out of the fence. A compiled `garden compose` fence renders the same component as the blog. An uncompiled plain-language fence renders as an idea card. Clicks on sliders and buttons stay in the preview.
 3. **Open the catalog.** In VS Code / Cursor, the catalog command inserts a recipe at the cursor. The terminal builds the same page:
 
    ```bash

package/docs/handbook/en/writing.md

@@ -1,7 +1,7 @@
 ---
 title: Writing Posts
 navTitle: Writing Posts
-description: Front Matter fields for posts, code diff toggles, callouts, math formulas, and Mermaid diagrams, with links to local images, source chips, and link cards.
+description: Front matter fields for long posts, code-and-diff switches, callouts, math and diagrams, plus images, audio and video, external players, footnotes, file downloads, and link cards.
 section: writing-and-reading
 order: 10
 ---
@@ -129,3 +129,84 @@ graph LR
   B --> C[Search & Static Assets]
   C --> D[Rendered Page]
 ```
+
+## 6. Local Audio and Video
+
+For a post at `content/posts/my-post.md`, put audio and video in `content/posts/my-post/`. Write them in the Markdown body. Do not wrap them in Compose, and do not put them inside a Compose `<html>` island. Use an `audio` or `video` tag with `controls`, and set `src` to a relative path such as `./my-post/clip.mp3` or `./my-post/clip.mp4`. Files in object storage use a full `https://` address. Do not autoplay.
+
+The build copies local attachments into the public directory. Do not commit large media to Git; prefer object storage.
+
+## 7. YouTube and Bilibili Players
+
+Paste a playable video URL on its own line, with blank lines around it. The page renders an in-article player that does not autoplay, and keeps a link to the original site:
+
+```markdown
+https://www.youtube.com/watch?v=VIDEO_ID
+
+https://www.bilibili.com/video/BV1xx411c7mD
+```
+
+`https://youtu.be/VIDEO_ID`, `/shorts/`, and `/embed/` also work, as do Bilibili `av` ids and `player.bilibili.com` player URLs. Tracking parameters are ignored. A YouTube start time such as `?t=90` or `?t=1m30s` starts at that second.
+
+These do not become a player:
+
+- A link inside a sentence, or more than one link in the same paragraph
+- A URL inside a code fence or inline code
+- An address that is not a single video (playlists, channels, article pages). A URL like that on its own line still renders as a [link card](/garden/en/components/link-card)
+- Lookalike or unrelated hosts that are not exactly YouTube or Bilibili
+- Short links such as `b23.tv` that need a redirect to discover the video. Rendering does not wait on the network to resolve them. Open the short link in a browser, or run `npx garden embed <short-url>`, then paste the printed full video URL on its own line
+- When you want a card instead of a player, write `{card}` immediately after the link
+
+The player accepts only official video URLs from those platforms. YouTube uses the privacy-enhanced `youtube-nocookie.com` host. Arbitrary pages and arbitrary iframes are not embedded.
+
+`npx garden embed URL` or `make embed URL="..."` prints one paste-ready canonical URL, and writes any title or summary to the terminal. It no longer emits a legacy `embed` fence.
+
+## 8. File Downloads and Previews
+
+To let readers download a file (a spec pack, a PDF, or sample code), use `<file>` or `<files>` inside `garden compose`. Put the files in the post's same-named directory, and write `src` relative to the Markdown file:
+
+```text
+content/posts/go-lock.md
+content/posts/go-lock/mutex-notes.pdf
+content/posts/go-lock/demo.zip
+```
+
+One file:
+
+````markdown
+```garden compose
+<file src="./go-lock/demo.zip" title="Sample code" note="Three lock examples you can run"/>
+```
+````
+
+A group of files:
+
+````markdown
+```garden compose
+<files title="References">
+  <file src="./go-lock/mutex-notes.pdf" note="A one-page mutex state machine"/>
+  <file src="./go-lock/readme.md"/>
+  <file src="https://oss.example.com/go-lock/trace.zip" title="Full trace"/>
+</files>
+```
+````
+
+| Attribute | Meaning |
+| :--- | :--- |
+| `src` | Required. Local files use a relative path; files in object storage use a full `https://` URL |
+| `title` | Optional card name; defaults to the file name |
+| `note` | Optional one-line description |
+
+You do not write the format or size. The build fills in a line such as `PDF · 204 KB`. A missing local file fails the build. Local Markdown, HTML, and PDF files can be previewed on the page: choose Preview to open the file on the right, or full screen on a phone.
+
+## 9. Footnotes
+
+Use GFM footnotes. Put the marker in the prose and the definition in its own paragraph, with matching names:
+
+```markdown
+This rule comes from a CommonMark derivative.[^1]
+
+[^1]: See [remark-gfm](https://github.com/remarkjs/remark-gfm).
+```
+
+Footnotes are collected at the end of the article.

package/docs/handbook/start.md

@@ -21,7 +21,7 @@ make dev
 
 `npx hd-garden init` 会把站点模板复制到 `my-blog` 目录，并写入 `.agents/skills/` 辅助技能文件（传入 `--locale en` 或 `--locale en_US` 时会生成英文版 `site.config.yaml`、`Makefile`、`README.md`，并安装 `.github/workflows/pages.yml`）。默认中文初始化不会自动执行 `npm install`，也不会自动创建 `.github/workflows/pages.yml`（GitHub Pages 工作流配置见 [发布到 GitHub Pages](/garden/deploy)）。
 
-首次运行 `make dev` 时，如果还没有 `node_modules`，`Makefile` 中的 `make prepare` 会先自动执行 `npm install`，随后运行 `npx garden dev`（其内部会先执行内容同步）并启动本地开发服务器，默认地址为 `http://localhost:3000`。
+首次运行 `make dev` 时，如果还没有 `node_modules`，`Makefile` 中的 `make prepare` 会先自动执行 `npm install`，随后运行 `npx garden dev`（其内部会先执行内容同步）并启动本地开发服务器。默认是 Node RSC 预览；需要 Cloudflare Worker 行为时用 `npx garden dev --worker`。
 
 ## 2. 站点目录结构
 

package/docs/handbook/workflow.md

@@ -104,8 +104,8 @@ Obsidian 插件这一轮不随包安装。
 
 ### 在编辑器里怎么用
 
-1. **插入想法。** VS Code / Cursor：macOS 用 `Cmd+Alt+I`，Windows / Linux 用 `Ctrl+Alt+I`，或命令「插入 Garden 块」。Typora：输入 `/` 后选 `/garden`（下一层列表每一项有一张小预览图），或命令「插入 Garden 块」直接打开组件列表（Windows / Linux 默认 `Ctrl+Alt+I`，macOS 请到「设置 → 快捷键」里自己录，因为 Option 会改写按键）。插入的是不带组件名的 `garden` 围栏，正文说明要写成哪种组件、写上哪些事实，交给 `garden-compose` skill 编译。
-2. **预览。** 打开 Markdown 预览（Typora 里光标离开围栏即可）。`ui` 块画成和博客一样的组件，`intent` 块显示成想法卡片。点滑杆、按钮不会跳回源码。
+1. **插入 Compose。** VS Code / Cursor：macOS 用 `Cmd+Alt+I`，Windows / Linux 用 `Ctrl+Alt+I`，或命令「插入 Garden 块」。Typora：输入 `/` 后选 `/garden`，在下一层图示列表里选一种（最后一项是「其他」；每一项有一张小预览图），或用命令「插入 Garden 块」直接打开这个列表（Windows / Linux 默认 `Ctrl+Alt+I`，macOS 请到「设置 → 快捷键」里自己录，因为 Option 会改写按键）。选中后会直接插入一个 `garden compose` 围栏，里面是针对该图示的说明草稿，交给 `garden-compose` skill 编译。不要再插入旧的 `ui` 或 `intent` 围栏。全部内置图示见[推荐图示](/garden/components/diagrams)。
+2. **预览。** 打开 Markdown 预览（Typora 里光标离开围栏即可）。已编译的 `garden compose` 画成和博客一样的组件；还没编译的白话围栏显示成想法卡片。点滑杆、按钮不会跳回源码。
 3. **看组件清单。** VS Code / Cursor 里用「查看组件清单」，点「用它开始」把配方插进当前稿件。终端里的同一份清单：
 
    ```bash

package/docs/handbook/writing.md

@@ -1,7 +1,7 @@
 ---
 title: 写文章
 navTitle: 写文章
-description: 长文的 Front Matter 字段、代码块对比、提示框、公式与流程图，以及配图、来源胶囊和链接卡片的入口。
+description: 长文的 Front Matter 字段、代码块对比、提示框、公式与流程图，以及配图、音视频、外链播放器、脚注、文件下载与链接卡片的入口。
 section: writing-and-reading
 order: 10
 ---
@@ -129,3 +129,84 @@ graph LR
   B --> C[生成搜索与静态资源]
   C --> D[页面渲染]
 ```
+
+## 6. 本地音频和视频
+
+长文 `content/posts/my-post.md` 的音视频放在同名目录 `content/posts/my-post/`。写在 Markdown 正文里，不要包进 Compose，也不要放进 Compose 的 `<html>` 内容岛。使用带 `controls` 的 `audio` 或 `video` 标签，`src` 填写相对路径，例如 `./my-post/clip.mp3` 或 `./my-post/clip.mp4`。对象存储里的文件写完整的 `https://` 地址。不要自动播放。
+
+构建会把本地附件复制到公开目录。大文件不要提交进 Git，更适合放对象存储。
+
+## 7. 嵌入 YouTube / Bilibili
+
+把可播放的视频链接单独占一行，前后留空行。页面会渲染成站内播放器，不自动播放，并保留到原站的链接：
+
+```markdown
+https://www.youtube.com/watch?v=VIDEO_ID
+
+https://www.bilibili.com/video/BV1xx411c7mD
+```
+
+也支持 `https://youtu.be/VIDEO_ID`、`/shorts/`、`/embed/`，以及 Bilibili 的 `av` 号和 `player.bilibili.com` 播放地址。多余的跟踪参数会被忽略；YouTube 链接里的开始时间（如 `?t=90` 或 `?t=1m30s`）会从那一秒起播。
+
+这些情况不会变成播放器：
+
+- 句子里的链接，或同一段里有多条链接
+- 代码块、行内代码里的地址
+- 不是单个视频的地址（播放列表、频道、专栏文章等）。单独一行时仍按[链接卡片](/garden/components/link-card)处理
+- 域名并不精确匹配 YouTube / Bilibili 的仿冒或无关地址
+- `b23.tv` 等需要跳转才能确定视频的短链。渲染时不会为了解析短链去访问网络；请先在浏览器打开，或运行 `npx garden embed <短链>`，把打印出的完整视频链接单独一行贴进文章
+- 希望显示卡片而不是播放器时，在链接后紧跟 `{card}`
+
+播放器只接受上述平台的官方视频地址，YouTube 使用隐私增强域名 `youtube-nocookie.com`，不会嵌入任意网页或任意 iframe。
+
+`npx garden embed URL` 或 `make embed URL="..."` 会打印一行可直接粘贴的规范化地址，标题等说明写在终端里，不再生成旧的 `embed` 围栏。
+
+## 8. 文件下载与预览
+
+想让读者下载一份文件（规格包、PDF、示例代码），在 `garden compose` 里用 `<file>` 或 `<files>`。文件放在这篇稿的同名目录里，`src` 相对这篇 Markdown 写：
+
+```text
+content/posts/go-lock.md
+content/posts/go-lock/mutex-notes.pdf
+content/posts/go-lock/demo.zip
+```
+
+一个文件：
+
+````markdown
+```garden compose
+<file src="./go-lock/demo.zip" title="示例代码" note="三个可以直接运行的加锁例子"/>
+```
+````
+
+一组文件：
+
+````markdown
+```garden compose
+<files title="参考资料">
+  <file src="./go-lock/mutex-notes.pdf" note="互斥锁的状态机，一页纸"/>
+  <file src="./go-lock/readme.md"/>
+  <file src="https://oss.example.com/go-lock/trace.zip" title="完整 trace"/>
+</files>
+```
+````
+
+| 属性 | 说明 |
+| :--- | :--- |
+| `src` | 必填。本地文件写相对路径；对象存储里的文件写完整的 `https://` 地址 |
+| `title` | 可选，卡片上的名字，默认是文件名 |
+| `note` | 可选，一句话说明里面有什么 |
+
+格式和大小不用手写，构建时会算出来，显示成「PDF · 204 KB」这样的一行。找不到本地文件时，构建会失败。本地的 Markdown、HTML 和 PDF 可以在页面里预览：点「预览」，文件在右侧打开，手机上占满全屏。
+
+## 9. 脚注
+
+使用 GFM 脚注。标记写在正文里，定义单独成段，名称要对应：
+
+```markdown
+这条规则来自 CommonMark 的衍生语法。[^1]
+
+[^1]: 详见 [remark-gfm](https://github.com/remarkjs/remark-gfm)。
+```
+
+脚注会集中出现在文章末尾。