hd-garden 0.7.0 → 0.8.0

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

@@ -0,0 +1,34 @@
+---
+title: File Download & Preview (file)
+navTitle: file
+description: Attach one or more files with automatic format and size badges, download links, and inline preview.
+section: components
+order: 39
+badge: file
+---
+
+Write "use `file` to attach a pre-publish checklist that readers can preview inline or download" inside a `garden` idea block, and the Agent generates the `garden file` block below via the `garden-ui` skill (hand-written syntax follows).
+
+```garden file
+src: ./file/checklist.md
+title: Pre-publish Checklist
+note: Sample Markdown attachment; click Preview to read inline or Download to save the file
+```
+
+````markdown
+```garden file
+src: ./file/checklist.md
+title: Pre-publish Checklist
+note: Sample Markdown attachment; click Preview to read inline or Download to save the file
+```
+````
+
+- **Use when**: Attaching config files, datasets, PDFs, images, or Markdown documents for readers to download or preview inline (use `files` for multiple attachments).
+- **Skip when**: Showing a regular illustration in the middle of an article; use standard Markdown image syntax `![]()` instead.
+
+| Field | Required | Type | Description |
+| :--- | :--- | :--- | :--- |
+| `src` | Required for single file | path or URL | Relative path (must stay inside the content root), `/public` path, or `https://` URL |
+| `title` | No | string | Display title (defaults to filename; serves as the group heading when using `files`) |
+| `note` | No | string | Short note shown below the filename |
+| `files` | Required for multi-file | `{ src, title?, note? }[]` | List of multiple attachments (mutually exclusive with top-level `src`) |

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

@@ -0,0 +1,69 @@
+---
+title: Embedded Web Snippet (html)
+navTitle: html
+description: Run a self-contained HTML, CSS, and JavaScript demo inside a sandboxed iframe.
+section: components
+order: 37
+badge: html
+---
+
+Write "use `html` to embed a small widget that counts characters as the reader types" inside a `garden` idea block, and the Agent generates the `garden html` block below via the `garden-ui` skill (hand-written syntax follows).
+
+```garden html
+title: Character Count Widget
+height: 156
+code: |
+  <!doctype html>
+  <html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <style>
+      body { margin: 0; padding: 16px 18px; font: 14px/1.6 system-ui, sans-serif; color: #1b1a18; background: #faf9f5; }
+      input { width: 100%; box-sizing: border-box; padding: 8px 10px; border: 1px solid #d5d1c8; border-radius: 6px; font: inherit; background: #fff; color: #1b1a18; }
+      .meta { margin-top: 10px; color: #6e6b64; font-variant-numeric: tabular-nums; }
+      strong { color: #1b1a18; }
+    </style>
+  </head>
+  <body>
+    <input id="txt" value="Keep your posts in a Git repository and push to deploy." aria-label="Sample text input" />
+    <div class="meta">Characters: <strong id="count">55</strong></div>
+    <script>
+      const input = document.getElementById("txt");
+      const count = document.getElementById("count");
+      input.addEventListener("input", () => { count.textContent = String(input.value.length); });
+    </script>
+  </body>
+  </html>
+```
+
+````markdown
+```garden html
+title: Character Count Widget
+height: 156
+code: |
+  <!doctype html>
+  <html lang="en">
+  <head><meta charset="utf-8" /></head>
+  <body>
+    <input id="txt" value="Keep your posts in a Git repository and push to deploy." />
+    <div>Characters: <strong id="count">55</strong></div>
+    <script>
+      const input = document.getElementById("txt");
+      const count = document.getElementById("count");
+      input.addEventListener("input", () => { count.textContent = String(input.value.length); });
+    </script>
+  </body>
+  </html>
+```
+````
+
+- **Use when**: Running custom DOM scripts, Canvas drawings, or self-contained HTML snippets (either inline via `code` or loaded from a sibling `.html` file via `src`).
+- **Skip when**: You only need sliders wired to a formula (use [`interactive`](/garden/en/components/interactive)) or a diagram with clickable regions (use [`figure`](/garden/en/components/figure)).
+
+| Field | Required | Type | Description |
+| :--- | :--- | :--- | :--- |
+| `src` | Either this or `code` | relative path | Path to a `.html` file in the same directory or sibling asset directory |
+| `code` | Either this or `src` | multiline string | Inline HTML markup (alias `html` is also accepted) |
+| `title` | Recommended | string | Header bar title and accessible `iframe` title |
+| `height` | No | number | Initial height in pixels (defaults to `260`; resizes to fit content after load) |
+| `caption` | No | string | Caption shown below the frame |

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

@@ -0,0 +1,67 @@
+---
+title: Interactive Formula & Parameters (interactive)
+navTitle: interactive
+description: Let readers drag sliders or switches to recalculate formulas and charts in real time.
+section: components
+order: 38
+badge: interactive
+---
+
+Write "let readers drag word count, reading speed, and image count sliders to see how estimated reading time changes" inside a `garden` idea block, and the Agent generates the `garden interactive` block below via the `garden-ui` skill (hand-written syntax follows).
+
+```garden interactive #reading-time
+caption: "Example: estimate reading time from word count, reading speed, and image count. Numbers are illustrative only."
+---
+<State words={6000} speed={400} images={8} />
+<Let textMinutes={round(words / speed)} />
+<Let imageMinutes={round(images * 12 / 60)} />
+<Let parts={[{ part: "Prose", minutes: textMinutes }, { part: "Images", minutes: imageMinutes }]} />
+
+<Slider bind="words" label="Word count" min={1000} max={20000} step={500} unit="words" />
+<Slider bind="speed" label="Reading speed" min={200} max={800} step={50} unit="wpm" />
+<Slider bind="images" label="Image count" min={0} max={30} step={1} unit="images" />
+
+<Stat label="Example: estimated reading time" value={textMinutes + imageMinutes} unit="min" hint="Counting 12 seconds per image" />
+<Chart data={parts} x={part} yLabel="min">
+  <Bar y={minutes} label="Example" />
+</Chart>
+```
+
+````markdown
+```garden interactive #reading-time
+caption: "Example: estimate reading time from word count, reading speed, and image count. Numbers are illustrative only."
+---
+<State words={6000} speed={400} images={8} />
+<Let textMinutes={round(words / speed)} />
+<Let imageMinutes={round(images * 12 / 60)} />
+<Let parts={[{ part: "Prose", minutes: textMinutes }, { part: "Images", minutes: imageMinutes }]} />
+
+<Slider bind="words" label="Word count" min={1000} max={20000} step={500} unit="words" />
+<Slider bind="speed" label="Reading speed" min={200} max={800} step={50} unit="wpm" />
+<Slider bind="images" label="Image count" min={0} max={30} step={1} unit="images" />
+
+<Stat label="Example: estimated reading time" value={textMinutes + imageMinutes} unit="min" hint="Counting 12 seconds per image" />
+<Chart data={parts} x={part} yLabel="min">
+  <Bar y={minutes} label="Example" />
+</Chart>
+```
+````
+
+- **Use when**: Explaining a multi-variable formula, capacity estimate, or parameter tradeoff where dragging a slider reveals how the output responds.
+- **Skip when**: A block has only `<Steps>` without any state or input control (fails with `steps-prose`), or every `<Let>` is a single multiplication like `a * b` (fails with `interactive-trivial`). Write plain prose in both cases.
+
+Metadata goes above `---`, and declarative tags go below it:
+
+| Field or Tag | Required | Description |
+| :--- | :--- | :--- |
+| `#reading-time` | Recommended | Block identifier on the fence line (lowercase letters, digits, and hyphens) |
+| `caption` | Yes | One sentence explaining what the reader can observe |
+| `intent` | No | The original natural-language prompt this block was compiled from |
+| `expect` | No | Array of `{ given: {...}, name: expectedValue }` assertions checked by `garden ui check` |
+| `<State />` | Yes | Declares mutable state variables and their initial values, e.g. `<State words={6000} />` |
+| `<Let />` | No | Computes derived values or data arrays from state |
+| `<Slider />` / `<Choice />` / `<Toggle />` | Yes | Input controls bound to a state variable via `bind`; `Slider` requires `label`, `min`, and `max` |
+| `<Stat />` | No | Displays a highlighted computed value; requires `label` and `value` |
+| `<Chart />` | No | Plots a function curve with `sweep` or a bar/line chart with `data` and `<Bar>` / `<Line>` |
+
+Run `npx garden ui catalog` to inspect the full tag and attribute reference in `.garden/ui-catalog.html`.

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

@@ -0,0 +1,57 @@
+---
+title: Key Figures (stat)
+navTitle: stat
+description: Display 2 to 4 key numbers, units, and short captions side by side.
+section: components
+order: 32
+badge: stat
+---
+
+Write "use `stat` to list the width limits for the prose column, wide figures, and wide tables" inside a `garden` idea block, and the Agent generates the `garden stat` block below via the `garden-ui` skill (hand-written syntax follows).
+
+```garden stat
+items:
+  - label: Reading Column
+    value: "740"
+    unit: px
+    caption: Default prose column width
+  - label: Wide Figure Limit
+    value: "1040"
+    unit: px
+    caption: Extends up to 150px on each side
+  - label: Wide Table Limit
+    value: "1340"
+    unit: px
+    caption: Extends up to 300px on each side
+```
+
+````markdown
+```garden stat
+items:
+  - label: Reading Column
+    value: "740"
+    unit: px
+    caption: Default prose column width
+  - label: Wide Figure Limit
+    value: "1040"
+    unit: px
+    caption: Extends up to 150px on each side
+  - label: Wide Table Limit
+    value: "1340"
+    unit: px
+    caption: Extends up to 300px on each side
+```
+````
+
+- **Use when**: Pulling 2 to 4 core numbers, thresholds, or specs out of prose so readers can scan them side by side.
+- **Skip when**: You only have one number (keep it in prose) or you have multiple rows and columns (use a Markdown table).
+
+| Field | Required | Type | Description |
+| :--- | :--- | :--- | :--- |
+| `items` | No | object[] | Array of stat items; for a single stat you can place the fields at the top level |
+| `label` | Yes | string | Metric name shown above the number |
+| `value` | Yes | string or number | Primary figure rendered in large tabular type |
+| `unit` | No | string | Unit shown immediately to the right of `value` |
+| `caption` | No | string | Short note below the figure |
+| `text` | No | string | Additional explanatory text |
+| `source` | No | string or `{ title, url }` | Source attribution badge |

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

@@ -0,0 +1,52 @@
+---
+title: Step Timeline (timeline)
+navTitle: timeline
+description: Order release milestones, incident steps, or build stages along a vertical sequence.
+section: components
+order: 34
+badge: timeline
+---
+
+Write "use `timeline` to list the three stages of the static publishing pipeline in order" inside a `garden` idea block, and the Agent generates the `garden timeline` block below via the `garden-ui` skill (hand-written syntax follows).
+
+```garden timeline
+title: Static Publishing Pipeline Stages
+items:
+  - date: Step 1
+    title: Sync Content and Assets
+    text: Run `npx garden sync` to validate Front Matter, copy image attachments, and generate the search index and RSS feed.
+  - date: Step 2
+    title: Build Static Site Output
+    text: Run `STATIC_EXPORT=1 npx garden build` to prerender every route into `dist/client/`.
+  - date: Step 3
+    title: Validate Output and Deploy
+    text: Run `npm run pages:validate` to confirm `index.html` exists and no `.env`, source directories, `.map` or `.md` files, or symlinks were included, then publish to GitHub Pages.
+```
+
+````markdown
+```garden timeline
+title: Static Publishing Pipeline Stages
+items:
+  - date: Step 1
+    title: Sync Content and Assets
+    text: Run `npx garden sync` to validate Front Matter, copy image attachments, and generate the search index and RSS feed.
+  - date: Step 2
+    title: Build Static Site Output
+    text: Run `STATIC_EXPORT=1 npx garden build` to prerender every route into `dist/client/`.
+  - date: Step 3
+    title: Validate Output and Deploy
+    text: Run `npm run pages:validate` to confirm `index.html` exists and no `.env`, source directories, `.map` or `.md` files, or symlinks were included, then publish to GitHub Pages.
+```
+````
+
+- **Use when**: Walking through incident timestamps, evolution stages, or pipeline steps in chronological order (at least 2 items).
+- **Skip when**: Listing unordered points with no sequence; use a regular bullet list instead.
+
+| Field | Required | Type | Description |
+| :--- | :--- | :--- | :--- |
+| `title` | No | string | Heading above the timeline |
+| `items` | Yes | object[] (at least 2) | Ordered list of steps |
+| `items[].date` | No | string | Timestamp, stage label, or step number above the item title |
+| `items[].title` | Yes | string | Step heading |
+| `items[].text` | No | string | Detailed explanation for the step |
+| `items[].source` | No | string or `{ title, url }` | Source attribution badge |

package/docs/handbook/en/components.md

@@ -0,0 +1,30 @@
+---
+title: Components Overview
+navTitle: Overview
+description: What each of the 9 built-in garden components is for, its fence name, and its required fields.
+section: components
+order: 30
+---
+
+You can describe any of these 9 components in a single sentence inside a `garden` idea block and let your Agent generate the block with the `garden-ui` skill (see [Writing with AI](/garden/en/ai-writing)). When writing by hand, open a ```` ```garden <name> ```` code block with the English component name (`card`, `stat`, `compare`, `timeline`, `chart`, `figure`, `html`, `interactive`, or `file`); parameters use YAML, while `interactive` takes declarative tags below `---`.
+
+## Component Quick Reference
+
+| Component | Code Fence | When to Use | Minimum Requirement |
+| :--- | :--- | :--- | :--- |
+| [card](/garden/en/components/card) | ```` ```garden card ```` | Summarize a paper, open-source project, or subsystem | Provide `description` or `points` |
+| [stat](/garden/en/components/stat) | ```` ```garden stat ```` | Place 2 to 4 key numbers and units side by side | Each item requires `label` and `value` |
+| [compare](/garden/en/components/compare) | ```` ```garden compare ```` | Compare 2 or 3 options or before/after tradeoffs side by side | At least 2 `items`, ~60 characters per cell |
+| [timeline](/garden/en/components/timeline) | ```` ```garden timeline ```` | Walk through debugging steps or release stages in order | At least 2 `items` |
+| [chart](/garden/en/components/chart) | ```` ```garden chart ```` | Plot proportional bars from YAML rows (includes an expandable table) | At least 2 rows in `data` |
+| [figure](/garden/en/components/figure) | ```` ```garden figure ```` | Highlight regions of an SVG or image diagram with step buttons | Either `svg` or `image` |
+| [html](/garden/en/components/html) | ```` ```garden html ```` | Run a self-contained HTML/JS demo in a sandboxed `iframe` | Either `src` or `code` |
+| [interactive](/garden/en/components/interactive) | ```` ```garden interactive ```` | Let readers drag sliders or switches to evaluate a non-trivial formula | Must include an input control and a formula beyond a single multiplication |
+| [file](/garden/en/components/file) | ```` ```garden file ```` | Offer local or remote attachments for download and inline preview | Either `src` or `files` |
+
+## Authoring Rules
+
+1. **Use standard Markdown first**: Write regular paragraphs, ordered lists, and comparison tables in plain Markdown, and reach for a `garden` fence only when a structured block makes the point easier to read.
+2. **Do not duplicate the same numbers**: A `chart` block already includes an expandable data table underneath, so do not put a second Markdown table with the same figures in the same section.
+3. **Inline formatting works inside fields**: Text fields such as `text`, `description`, `caption`, and `points` accept inline `**bold**`, `` `code` ``, and `<u>highlighter underline</u>`.
+4. **Preview every component locally**: Run `npx garden ui catalog` to generate `.garden/ui-catalog.html` and open it in your browser.

package/docs/handbook/en/config.md

@@ -0,0 +1,125 @@
+---
+title: Site & Column Config
+navTitle: Site & Column Config
+description: Configure site metadata, page headings, and brand icons in site.config.yaml, and organize series in content/columns.yaml.
+section: getting-started
+order: 3
+---
+
+Global site copy and appearance settings live in `site.config.yaml` at the repository root, while series definitions live in `content/columns.yaml`. Run `npx garden sync` (or `make dev`) after editing to apply changes.
+
+## 1. Full `site.config.yaml` Structure
+
+Here is the default `site.config.yaml` shipped with the site template:
+
+```yaml
+name: Garden
+tagline: 写作 · 记录 · 保持好奇
+description: 文章、随想和专栏。
+locale: zh_CN
+# 站点的公开地址。文章里指向这个地址的完整网址会按站内链接显示。
+# url: https://blog.example.com
+# 站点图标，不写时使用 Garden 自带的图标。
+# brand:
+#   logo: brand/logo.svg
+#   favicon: /favicon.svg
+#   appleTouchIcon: /apple-touch-icon.png
+
+author:
+  name: Your Name
+  github: your-github-id
+  githubBio: 一句自我介绍。
+  githubPinned: []
+
+pages:
+  home:
+    title: |-
+      记一些正在做的事，
+      和想清楚的问题。
+    subtitle: 软件、笔记，和偶尔的工作记录。
+  blog:
+    title: 博文
+    subtitle: 写完的长文。
+  thoughts:
+    title: 随想
+    subtitle: 短笔记、图片和链接。
+  columns:
+    title: 专栏
+    subtitle: 按顺序读的一组文章。
+  about:
+    title: 你好，我是 Your Name。
+    subtitle: 文章和笔记都在这里。
+    heading: 关于
+    paragraphs:
+      - 一名工程师。平时写代码，也把想清楚的问题记下来。
+      - 这里放文章、随想和专栏。
+    quote: ""
+    focus:
+      - 软件
+      - 笔记
+      - 日常
+    cta:
+      href: /blog
+      label: 浏览博文
+  garden:
+    title: "用 Markdown 写。\n推送之后，网站自己更新。"
+    subtitle: ""
+
+footer: 持续记录。
+```
+
+### Top-level and Author Fields
+
+| Field | Description |
+| :--- | :--- |
+| `name` | Site name shown in the top-left header, browser title suffix, and RSS feed title |
+| `tagline` | Site tagline |
+| `description` | Site summary used for the home page SEO description and RSS channel description |
+| `locale` | Language and region tag (`zh_CN` by default; setting `en_US` switches the site chrome to English at build time) |
+| `url` | Public root URL of the site (such as `https://blog.example.com`). Full URLs pointing to this address inside posts are treated as internal links |
+| `author.name` | Author name displayed in article metadata, the About page, and the footer |
+| `author.github` | GitHub username (without the full URL), used to link your GitHub profile and fetch public activity for the About page |
+| `author.githubBio` | Fallback bio used when the build environment has no `GITHUB_TOKEN` |
+| `author.githubPinned` | Fallback list of pinned repositories when `GITHUB_TOKEN` is not set locally |
+| `footer` | Short signature text in the footer |
+
+> [!NOTE] Note
+> Trailing slashes on internal URLs are not configured in `site.config.yaml`: static exports (`STATIC_EXPORT=1`) always enable trailing slashes, and server builds can enable them with `TRAILING_SLASH=1`.
+
+### `pages` Top-level Page Headings
+
+Each key under `pages` sets the header copy for a top-level route:
+
+- **`pages.home`, `pages.blog`, `pages.thoughts`, `pages.columns`, `pages.garden`**: Each accepts `title` and `subtitle`. On `/garden/`, the Chinese overview page reads `pages.garden.title` (splitting into two lines on ` | `) and `pages.garden.subtitle`.
+- **`pages.about`**: Alongside `title` and `subtitle`, supports `heading` (section heading), `paragraphs` (array of paragraphs), `quote` (pull quote), `focus` (array of topic tags), and `cta` (`{ href, label }` button).
+
+### `brand` Custom Icons and Redirects
+
+- **`brand.logo`**: SVG mark placed to the left of the site name in the header. Resolved relative to the site root (for example `brand/logo.svg`), sanitized and inlined at build time so it inherits `currentColor`. Set to `false` to hide the header mark.
+- **`brand.favicon` and `brand.appleTouchIcon`**: Paths served from `public/` (such as `/favicon.svg` and `/apple-touch-icon.png`); set `appleTouchIcon` to `false` to omit the tag.
+- **`redirects`**: Top-level map in `site.config.yaml` for moved posts (for example `"/2024/01/20/old-post/": "/blog/new-post/"`). The build emits redirect pages at the old paths and rewrites matching internal links inside post bodies to the new destination.
+
+## 2. Configuring Columns (`content/columns.yaml`)
+
+Columns group multiple posts from `content/posts/` into an ordered reading series. Edit `content/columns.yaml`:
+
+```yaml
+columns:
+  - slug: building-in-public
+    title: Building in Public
+    status: Ongoing
+    description: Notes from initial prototype to production release.
+    cover: windowsill-herbs.svg
+    posts:
+      - building-in-public/smallest-closed-loop
+      - building-in-public/ship-with-evidence
+```
+
+| Field | Required | Description |
+| :--- | :--- | :--- |
+| `slug` | Yes | Column identifier (lowercase letters, digits, and hyphens only), generating routes at `/columns/<slug>/<post>` |
+| `title` | Yes | Column title (also shown beside member posts on `/blog`) |
+| `description` | Yes | Column summary shown on `/columns` cards |
+| `status` | No | Status badge text |
+| `cover` | No | Cover image path relative to `content/covers/` |
+| `posts` | Yes | Ordered array of post paths relative to `content/posts/`, without the `.md` extension |