hd-garden 0.6.1 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/skills/garden-ui/SKILL.md +26 -19
- package/README.en.md +57 -0
- package/README.md +31 -46
- package/app/admin/preview/[...path]/page.tsx +1 -1
- package/app/blog/[...path]/page.tsx +11 -3
- package/app/columns/[column]/[...path]/page.tsx +12 -14
- package/app/components/ArticleMeasure.tsx +39 -4
- package/app/components/ArticlePager.tsx +32 -0
- package/app/components/Comments.tsx +2 -1
- package/app/components/FeedMore.tsx +70 -0
- package/app/components/GardenDocsNav.tsx +189 -0
- package/app/components/HandbookLangRedirect.tsx +30 -0
- package/app/components/HandbookLangSwitch.tsx +49 -0
- package/app/components/HandbookView.tsx +187 -0
- package/app/components/MarkdownArticle.tsx +15 -8
- package/app/components/MarkdownImage.tsx +6 -4
- package/app/components/SiteChrome.tsx +11 -2
- package/app/components/SiteFooter.tsx +12 -3
- package/app/components/SiteHeader.tsx +27 -23
- package/app/components/TableOfContents.tsx +15 -9
- package/app/components/ThoughtFeed.tsx +41 -0
- package/app/components/UiLang.tsx +18 -0
- package/app/components/Webmentions.tsx +3 -2
- package/app/components/garden/FilePreview.tsx +13 -11
- package/app/components/garden/GardenBlock.tsx +3 -1
- package/app/components/garden/GardenFile.tsx +9 -7
- package/app/components/garden/blocks.tsx +34 -24
- package/app/components/garden/chrome.tsx +20 -13
- package/app/garden/[...slug]/page.tsx +28 -0
- package/app/garden/en/[...slug]/page.tsx +28 -0
- package/app/garden/en/page.tsx +16 -0
- package/app/garden/page.tsx +7 -141
- package/app/garden-modules.d.ts +18 -0
- package/app/globals.css +10 -10
- package/app/layout.tsx +2 -4
- package/app/lib/content.ts +27 -11
- package/app/lib/garden-docs-meta.ts +138 -0
- package/app/lib/handbook-path.ts +11 -0
- package/app/lib/heading-number.ts +13 -0
- package/app/lib/i18n.ts +222 -0
- package/app/lib/page-alternates.ts +2 -2
- package/app/not-found.tsx +5 -3
- package/app/site.config.ts +1 -1
- package/app/styles/a2.css +613 -13
- package/app/styles/shell.css +6 -0
- package/app/thoughts/page/[n]/page.tsx +44 -0
- package/app/thoughts/page.tsx +2 -6
- package/bin/garden.mjs +4 -0
- package/docs/handbook/ai-writing.md +99 -0
- package/docs/handbook/assets/reading-layout.svg +26 -0
- package/docs/handbook/components/card.md +46 -0
- package/docs/handbook/components/chart.md +54 -0
- package/docs/handbook/components/compare.md +38 -0
- package/docs/handbook/components/figure.md +72 -0
- package/docs/handbook/components/file/checklist.md +17 -0
- package/docs/handbook/components/file.md +34 -0
- package/docs/handbook/components/html.md +69 -0
- package/docs/handbook/components/interactive.md +67 -0
- package/docs/handbook/components/stat.md +57 -0
- package/docs/handbook/components/timeline.md +52 -0
- package/docs/handbook/components.md +30 -0
- package/docs/handbook/config.md +125 -0
- package/docs/handbook/deploy.md +273 -0
- package/docs/handbook/design.md +81 -0
- package/docs/handbook/en/ai-writing.md +99 -0
- package/docs/handbook/en/components/card.md +46 -0
- package/docs/handbook/en/components/chart.md +54 -0
- package/docs/handbook/en/components/compare.md +38 -0
- package/docs/handbook/en/components/figure.md +72 -0
- package/docs/handbook/en/components/file/checklist.md +17 -0
- package/docs/handbook/en/components/file.md +34 -0
- package/docs/handbook/en/components/html.md +69 -0
- package/docs/handbook/en/components/interactive.md +67 -0
- package/docs/handbook/en/components/stat.md +57 -0
- package/docs/handbook/en/components/timeline.md +52 -0
- package/docs/handbook/en/components.md +30 -0
- package/docs/handbook/en/config.md +125 -0
- package/docs/handbook/en/deploy.md +273 -0
- package/docs/handbook/en/design.md +81 -0
- package/docs/handbook/en/index.md +192 -0
- package/docs/handbook/en/start.md +92 -0
- package/docs/handbook/en/workflow.md +81 -0
- package/docs/handbook/en/writing.md +156 -0
- package/docs/handbook/index.md +187 -0
- package/docs/handbook/start.md +92 -0
- package/docs/handbook/workflow.md +81 -0
- package/docs/handbook/writing.md +156 -0
- package/package.json +2 -1
- package/scripts/build-content.mjs +144 -15
- package/scripts/handbook-allowlist.mjs +68 -0
- package/scripts/handbook-facts.mjs +1138 -0
- package/scripts/html-lang.mjs +36 -0
- package/scripts/static-404.mjs +25 -0
- package/scripts/ui-cli.mjs +14 -8
- package/site.config.yaml +2 -2
- package/templates/garden-blocks.md +1 -1
- package/templates/site/package.json +1 -3
- package/templates/site/site.config.yaml +2 -0
- package/ui/core/apply.mjs +22 -4
- package/ui/core/cli-locale.mjs +67 -0
- package/ui/core/fence.mjs +18 -3
- package/ui/core/fix-prompt.mjs +18 -15
- package/ui/core/garden-fence.mjs +64 -0
- package/ui/core/scan.mjs +19 -3
- package/ui/garden/adjacent.mjs +21 -0
- package/ui/garden/catalog.mjs +1 -1
- package/ui/garden/check.mjs +6 -0
- package/ui/garden/html-lang.mjs +16 -0
- package/ui/garden/paging.mjs +30 -0
- package/ui/preview/dist/garden-ui.css +9 -9
- package/ui/preview/dist/garden-ui.esm.js +169 -169
- package/ui/preview/dist/garden-ui.iife.js +169 -169
- package/ui/react/components/chart.tsx +7 -4
- package/ui/react/components/display.tsx +6 -3
- package/ui/react/components/inputs.tsx +6 -3
- package/ui/react/components/layout.tsx +6 -4
- package/ui/react/components/media.tsx +7 -4
- package/ui/react/components/sandbox.tsx +3 -1
- package/ui/react/index.tsx +11 -7
- package/ui/react/lang.tsx +85 -0
- package/ui/react/runtime.tsx +3 -1
- package/ui/react/ui.css +9 -9
- package/worker/index.ts +8 -1
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { notFound } from "next/navigation";
|
|
2
|
+
import { PageIntro } from "../../../components/PageIntro";
|
|
3
|
+
import { ThoughtFeed, thoughtsPageCount, thoughtsPageSize } from "../../../components/ThoughtFeed";
|
|
4
|
+
import { getPublishedThoughts } from "../../../lib/public-thoughts";
|
|
5
|
+
import { ui } from "../../../lib/i18n";
|
|
6
|
+
import { pageAlternates } from "../../../lib/page-alternates";
|
|
7
|
+
import { siteConfig } from "../../../site.config";
|
|
8
|
+
import { extraPages, pagePath } from "../../../../ui/garden/paging.mjs";
|
|
9
|
+
import { isStaticPlaceholder, STATIC_PLACEHOLDER, staticParams } from "../../../../ui/garden/static-params.mjs";
|
|
10
|
+
|
|
11
|
+
export function generateStaticParams() {
|
|
12
|
+
return staticParams(
|
|
13
|
+
extraPages(getPublishedThoughts().length, thoughtsPageSize()).map((page: number) => ({ n: String(page) })),
|
|
14
|
+
{ n: STATIC_PLACEHOLDER },
|
|
15
|
+
);
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
const pageNumber = (value: string) => (/^\d+$/u.test(value) ? Number(value) : NaN);
|
|
19
|
+
|
|
20
|
+
export async function generateMetadata({ params }: { params: Promise<{ n: string }> }) {
|
|
21
|
+
const { n } = await params;
|
|
22
|
+
const page = pageNumber(n);
|
|
23
|
+
if (!(page >= 2 && page <= thoughtsPageCount())) return {};
|
|
24
|
+
return {
|
|
25
|
+
title: `${siteConfig.pages.thoughts.title} · ${ui().pageOf(page, thoughtsPageCount())}`,
|
|
26
|
+
description: siteConfig.pages.thoughts.subtitle || siteConfig.description,
|
|
27
|
+
alternates: pageAlternates(pagePath("/thoughts", page)),
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export default async function ThoughtsPage({ params }: { params: Promise<{ n: string }> }) {
|
|
32
|
+
const { n } = await params;
|
|
33
|
+
const page = pageNumber(n);
|
|
34
|
+
if (!(page >= 2 && page <= thoughtsPageCount())) {
|
|
35
|
+
if (isStaticPlaceholder(n)) return null;
|
|
36
|
+
notFound();
|
|
37
|
+
}
|
|
38
|
+
return (
|
|
39
|
+
<main className="page-shell thoughts-page">
|
|
40
|
+
<PageIntro eyebrow="THOUGHTS / 随想" title={siteConfig.pages.thoughts.title} subtitle={siteConfig.pages.thoughts.subtitle} />
|
|
41
|
+
<ThoughtFeed page={page} />
|
|
42
|
+
</main>
|
|
43
|
+
);
|
|
44
|
+
}
|
package/app/thoughts/page.tsx
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { getPublishedThoughts } from "../lib/public-thoughts";
|
|
2
|
-
import {
|
|
2
|
+
import { ThoughtFeed } from "../components/ThoughtFeed";
|
|
3
3
|
import { ContentEmptyState } from "../components/ContentEmptyState";
|
|
4
4
|
import { PageIntro } from "../components/PageIntro";
|
|
5
5
|
import { siteConfig, siteDocumentTitle } from "../site.config";
|
|
@@ -22,11 +22,7 @@ export default function ThoughtsPage() {
|
|
|
22
22
|
subtitle={siteConfig.pages.thoughts.subtitle}
|
|
23
23
|
/>
|
|
24
24
|
{thoughts.length > 0 ? (
|
|
25
|
-
<
|
|
26
|
-
{thoughts.map((thought) => (
|
|
27
|
-
<ThoughtCard key={thought.slug} thought={thought} />
|
|
28
|
-
))}
|
|
29
|
-
</div>
|
|
25
|
+
<ThoughtFeed page={1} />
|
|
30
26
|
) : (
|
|
31
27
|
<ContentEmptyState kind="thoughts" />
|
|
32
28
|
)}
|
package/bin/garden.mjs
CHANGED
|
@@ -398,6 +398,10 @@ switch (command) {
|
|
|
398
398
|
// What the export wrote for empty dynamic routes (ui/garden/static-params.mjs).
|
|
399
399
|
runNode("scripts/static-placeholders.mjs");
|
|
400
400
|
runNode("scripts/redirects.mjs");
|
|
401
|
+
// <html lang="en"> on the English handbook pages.
|
|
402
|
+
runNode("scripts/html-lang.mjs");
|
|
403
|
+
// 404.html also under basePath when the host serves that folder alone.
|
|
404
|
+
runNode("scripts/static-404.mjs");
|
|
401
405
|
}
|
|
402
406
|
break;
|
|
403
407
|
case "links":
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 用 AI 写作
|
|
3
|
+
navTitle: 用 AI 写作
|
|
4
|
+
description: 用一句话描述想要的组件,交给 Agent 生成;提交前由同一个脚本检查,失败时打印可粘贴给 AI 的修复提示词。
|
|
5
|
+
section: getting-started
|
|
6
|
+
order: 2
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
在 Garden 里写图表、指标或交互组件不用记标签语法。你在正文写一句自然语言想法,Agent 按站点里的 skill 把它编译成组件,提交时再由同一套命令检查。
|
|
10
|
+
|
|
11
|
+
> [!IMPORTANT] 人和 Agent 用同一套工具
|
|
12
|
+
> Agent 找块用 `npx garden ui scan`,写回用 `npx garden ui apply`,自查用 `npx garden ui check`;作者提交时 pre-commit 钩子运行的也是 `npx garden ui check`。检查失败时打印的提示词,就是发给 Agent 的下一步指令。
|
|
13
|
+
|
|
14
|
+
## 1. 写一句想法
|
|
15
|
+
|
|
16
|
+
在想放组件的位置写一个不带名字的 `garden` 围栏,只写想让读者做什么、看到什么,不用写组件名:
|
|
17
|
+
|
|
18
|
+
````markdown
|
|
19
|
+
```garden
|
|
20
|
+
让读者拖动每天写的字数和每周写几天,看写完一篇 8000 字的长文要几周。
|
|
21
|
+
```
|
|
22
|
+
````
|
|
23
|
+
|
|
24
|
+
草稿(`draft: true`)里可以保留未编译的想法;非草稿文章里还有未编译的想法时,`npx garden ui check` 和 `npx garden check` 都会报 `garden-idea` 错误。Agent 会根据内容把想法编译成 `garden interactive`、`card`、`stat`、`compare` 等内置组件,或者在一段话就能说清时直接写回普通段落。
|
|
25
|
+
|
|
26
|
+
## 2. 随包安装的三个 skill
|
|
27
|
+
|
|
28
|
+
三个 skill 存放在站点根目录的 `.agents/skills/` 下。`npx hd-garden init` 建站时会自动安装,首次运行 `npx garden sync` 或 `npx garden dev` 时会补齐缺失的 skill,运行 `npx garden skill` 可手动重装。
|
|
29
|
+
|
|
30
|
+
| Skill 名称 | 触发话术示例 | 执行操作 |
|
|
31
|
+
| :--- | :--- | :--- |
|
|
32
|
+
| `garden-ui` | 「编译这篇:content/posts/writing-pace.md」「重编译 writing-pace」或直接粘贴修复提示词 | 扫描 `uncompiled`、`stale`、`error` 状态的块,按规则生成组件并用 `npx garden ui apply` 写回;说「这篇哪里适合交互」则进入只读建议模式,最多挑出 5 处可直接粘贴的想法草稿 |
|
|
33
|
+
| `garden-interactive-chart` | 组件目录表达不了的画布动画或模拟 | 在文章同名目录下编写独立 `.html` 文件,正文中只用 `garden html` 围栏嵌入 |
|
|
34
|
+
| `garden-post-review` | 「审稿:content/posts/writing-pace.md」 | 先修 `npx garden check` 报出的结构错误,再按图表规范修交互块,最后通读全文只给修改建议而不改稿 |
|
|
35
|
+
|
|
36
|
+
## 3. `garden ui` 子命令与整篇检查
|
|
37
|
+
|
|
38
|
+
`garden ui` 下的子命令供作者和 Agent 共用;想法块没有 `id` 时,`npx garden ui apply` 用 `npx garden ui scan` 输出的 `--intent-hash`(或行号 `--at`)定位。
|
|
39
|
+
|
|
40
|
+
| 命令 | 作者何时使用 | Agent 何时使用 |
|
|
41
|
+
| :--- | :--- | :--- |
|
|
42
|
+
| `npx garden ui scan <稿件.md>` | 查看文内有哪些待编译或报错的块 | 第一步:读取每块的 `status`、`startLine`、`hash` 和 `intentHash` |
|
|
43
|
+
| `npx garden ui prompt [--studio]` | 查看组件目录、设计规则与配方示例 | 编写组件前必读,只使用目录里存在的组件与属性 |
|
|
44
|
+
| `npx garden ui schema` | 查看组件目录的 JSON 定义 | 需要结构化读取组件属性约束时调用 |
|
|
45
|
+
| `npx garden ui apply <稿件.md> --id <id>` | 日常手写一般不用 | 按 `--id`、`--intent-hash` 或 `--at` 替换单个围栏,围栏外逐字节不变 |
|
|
46
|
+
| `npx garden ui check <稿件.md>` | 提交前钩子自动运行(也可传 `--staged` 或 `--all`) | 写回后自查,直到退出码为 `0` |
|
|
47
|
+
| `npx garden ui catalog [--out 文件] [--no-open]` | 在 `.garden/ui-catalog.html` 生成离线组件清单并在浏览器查看 | 一般不用 |
|
|
48
|
+
| `npx garden check <稿件.md>` | 单独检查一篇文章的标题、图片与全部围栏 | 全部块写回后的收尾检查,确认输出 JSON 的 `ok` 为 `true` |
|
|
49
|
+
|
|
50
|
+
## 4. 提交前检查与修复提示词
|
|
51
|
+
|
|
52
|
+
首次运行 `npx garden sync` 或 `npx garden dev` 时,Garden 会在 `.git/hooks/pre-commit` 写入 `exec npx --no-install garden ui check --staged --quiet`(若已有其他钩子则不覆盖,只提示需添加的命令)。`--staged` 直接通过 `git show :<路径>` 读取暂存区内容,失败时输出文件行号、诊断码和一段修复提示词:
|
|
53
|
+
|
|
54
|
+
```console
|
|
55
|
+
content/posts/writing-pace.md:9 - garden-idea 还有没编译的想法
|
|
56
|
+
|
|
57
|
+
──────────────────────── 发给 AI 的修复提示词 ────────────────────────
|
|
58
|
+
请处理下面 Garden 博文里列出的块:没编译的想法要编译,有错误的交互块要修好。
|
|
59
|
+
……
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
- 提示词同时写入 `.garden/ui-fix-prompt.md`,系统有 `pbcopy`、`wl-copy`、`xclip`、`xsel` 或 `clip` 时自动复制到剪贴板;传入 `--no-copy` 或设置 `GARDEN_UI_NO_COPY=1` 可关闭自动复制。
|
|
63
|
+
- 需要把提示词发给无法读取本地仓库的网页端聊天窗口时,运行 `npx garden ui check <稿件.md> --standalone`,提示词末尾会附上完整的 `npx garden ui prompt` 组件规则(单次最多附 10 个问题块的原文)。
|
|
64
|
+
- 交互块里写错标签名(如把 `<Slider>` 写成 `<Slidr>`)也会报 `ui-component` 并指到具体行号;确实要先带病提交时可用 `git commit --no-verify`。
|
|
65
|
+
- 需要重装钩子时运行 `npx garden hooks`(加 `--force` 覆盖已有钩子);不想自动安装钩子时设置 `GARDEN_SKIP_HOOKS=1`。
|
|
66
|
+
|
|
67
|
+
## 5. 用一句话生成代码对比
|
|
68
|
+
|
|
69
|
+
在改好的完整代码块正下方放一个 `garden` 想法块,用一句话写出它和上一版相比改了什么:
|
|
70
|
+
|
|
71
|
+
````markdown
|
|
72
|
+
```yaml
|
|
73
|
+
pages:
|
|
74
|
+
garden:
|
|
75
|
+
title: "用 Markdown 写丨推送之后网站自己更新"
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
```garden
|
|
79
|
+
和上一版比:标题原来用句号和换行分两行,现在改成用「丨」分行。
|
|
80
|
+
```
|
|
81
|
+
````
|
|
82
|
+
|
|
83
|
+
Agent 按 `garden-ui` skill 会把这个想法块替换成一段紧挨着完整代码的 `diff` 围栏。页面渲染时会把完整代码和 `diff` 合成一个带「代码 / 对比上一版」切换按钮的代码框,手写 `diff` 的规则见 [写文章与随想](/garden/writing)。
|
|
84
|
+
|
|
85
|
+
## 6. 不使用 Agent 时的快捷输入
|
|
86
|
+
|
|
87
|
+
不借助 AI 手写组件时,可以直接使用包内自带的模板与代码片段:
|
|
88
|
+
|
|
89
|
+
- `make new` 创建的草稿底部自带一段 `<!-- 组件速查 ... -->` 注释,包含想法块和 9 个组件的示例,写完可直接删掉。
|
|
90
|
+
- `templates/garden-blocks.md` 汇总了想法块与 9 个组件的适用场景(`when` / `whenNot`)和可复制示例;macOS 与 Typora / Alfred 用户可导入 `templates/garden-snippets.plist`,输入 `;gidea`(或 `;garden想法`)、`;gcard`、`;gstat`、`;gcompare`、`;gtimeline`、`;gchart`、`;gfigure`、`;ghtml`、`;ginteractive`、`;gfile` 即可展开对应围栏。
|
|
91
|
+
- 引擎仓库的 `editors/vscode`、`editors/typora` 与 `editors/obsidian` 目录提供了对应的编辑器片段与插件支持,运行 `npx garden ui catalog` 则可在本地生成 `.garden/ui-catalog.html` 离线组件画廊。
|
|
92
|
+
|
|
93
|
+
## 7. 可选的独立管理后台
|
|
94
|
+
|
|
95
|
+
Garden 引擎仓库内置了可选的 `/admin` 管理后台(位于 `app/admin` 与 `worker/`),可通过 `npm run admin:local`、`npm run admin:cloudflare` 或 Docker 单独部署。配置环境变量后,后台提供以下网页端功能:
|
|
96
|
+
|
|
97
|
+
- 通过 GitHub OAuth 登录(仅允许 `ADMIN_GITHUB_LOGINS` 白名单中的用户),在网页端编写随想并用 `CONTENT_GITHUB_TOKEN` 直接提交为 `content/thoughts/*.md`,图片与音视频通过十分钟有效的 Post Policy 直传阿里云 OSS。
|
|
98
|
+
- 在 `/admin/ui/blocks` 查看仓库内全部稿件(含草稿)的交互块状态,一键复制与命令行钩子相同的修复提示词。
|
|
99
|
+
- 在 `/admin/ui` 组件工作台用自然语言试写或手改组件(配置 `UI_MODEL_BASE_URL`、`UI_MODEL_API_KEY`、`UI_MODEL_NAME`),在 `/admin/ui/catalog` 浏览组件清单,在 `/admin/preview/<路径>` 预览未发布草稿,以及在 `/admin/ui/evals` 运行模型自检。
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="2080" height="560" viewBox="0 0 1040 280" fill="none" font-family="-apple-system, BlinkMacSystemFont, 'PingFang SC', 'Noto Sans SC', sans-serif">
|
|
2
|
+
<!-- Outer 1340px wide-table boundary -->
|
|
3
|
+
<rect x="20" y="20" width="1000" height="240" rx="14" stroke="#6e6b64" stroke-width="1.5" stroke-dasharray="6 5" />
|
|
4
|
+
<text x="44" y="48" fill="#4a4844" font-size="13" font-weight="600">多列表格外扩区 · 文章页上限 1340px(单侧最多外扩 300px)</text>
|
|
5
|
+
<text x="996" y="48" text-anchor="end" fill="#6e6b64" font-size="12" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">max 1340px</text>
|
|
6
|
+
|
|
7
|
+
<!-- Middle 1040px wide-figure boundary -->
|
|
8
|
+
<rect x="110" y="66" width="820" height="174" rx="12" stroke="#2d2c29" stroke-width="1.5" stroke-dasharray="4 4" />
|
|
9
|
+
<text x="132" y="92" fill="#2d2c29" font-size="13" font-weight="600">宽幅配图外扩区 · 文章页上限 1040px(截图按像素宽度的一半显示,超过 740px 才外扩)</text>
|
|
10
|
+
<text x="908" y="92" text-anchor="end" fill="#6e6b64" font-size="12" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">max 1040px</text>
|
|
11
|
+
|
|
12
|
+
<!-- Inner 740px reading column -->
|
|
13
|
+
<rect x="215" y="110" width="610" height="110" rx="10" fill="#f0eee6" fill-opacity="0.72" stroke="#1b1a18" stroke-width="2" />
|
|
14
|
+
<text x="520" y="146" text-anchor="middle" fill="#1b1a18" font-size="16" font-weight="700">正文阅读列 · 740px(var(--col))</text>
|
|
15
|
+
<text x="520" y="172" text-anchor="middle" fill="#2d2c29" font-size="13">段落、列表、引用、代码块与公式默认收敛在此列内</text>
|
|
16
|
+
<text x="520" y="196" text-anchor="middle" fill="#6e6b64" font-size="12" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">暗色模式透明底配图自动补 var(--image-backing) #faf9f5 暖白底</text>
|
|
17
|
+
|
|
18
|
+
<!-- Left & right expansion arrows -->
|
|
19
|
+
<path d="M210 165 H118" stroke="#2d2c29" stroke-width="1.5" />
|
|
20
|
+
<path d="M124 160 L116 165 L124 170" stroke="#2d2c29" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" />
|
|
21
|
+
<text x="164" y="156" text-anchor="middle" fill="#4a4844" font-size="11" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">≤ 150px</text>
|
|
22
|
+
|
|
23
|
+
<path d="M830 165 H922" stroke="#2d2c29" stroke-width="1.5" />
|
|
24
|
+
<path d="M916 160 L924 165 L916 170" stroke="#2d2c29" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" />
|
|
25
|
+
<text x="876" y="156" text-anchor="middle" fill="#4a4844" font-size="11" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">≤ 150px</text>
|
|
26
|
+
</svg>
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 知识卡片(card)
|
|
3
|
+
navTitle: 知识卡片
|
|
4
|
+
description: 把论文、项目或模块说明整理成带元数据与编号要点的卡片。
|
|
5
|
+
section: components
|
|
6
|
+
order: 31
|
|
7
|
+
badge: card
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
在 `garden` 想法块里写一句「放一张 `card` 介绍 SQLite 的 WAL 文档,带标题、链接和三条要点」,Agent 会按 `garden-ui` skill 生成下面的 `garden card`(手写格式附后)。
|
|
11
|
+
|
|
12
|
+
```garden card
|
|
13
|
+
title: SQLite WAL 写入模式
|
|
14
|
+
url: https://www.sqlite.org/wal.html
|
|
15
|
+
meta: 文档说明 · sqlite.org
|
|
16
|
+
description: 把修改先顺序追加到预写日志,读操作继续访问原数据库页,减少读写互斥等待。
|
|
17
|
+
points:
|
|
18
|
+
- 写入只追加到 `-wal` 文件末尾,不需要在事务提交时原地覆盖数据页。
|
|
19
|
+
- 读事务记录当前末尾偏移量即可看到一致快照,不会阻塞并发写入。
|
|
20
|
+
- 后台 Checkpoint 按阈值将日志页分批写回主库文件。
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
````markdown
|
|
24
|
+
```garden card
|
|
25
|
+
title: SQLite WAL 写入模式
|
|
26
|
+
url: https://www.sqlite.org/wal.html
|
|
27
|
+
meta: 文档说明 · sqlite.org
|
|
28
|
+
description: 把修改先顺序追加到预写日志,读操作继续访问原数据库页,减少读写互斥等待。
|
|
29
|
+
points:
|
|
30
|
+
- 写入只追加到 `-wal` 文件末尾,不需要在事务提交时原地覆盖数据页。
|
|
31
|
+
- 读事务记录当前末尾偏移量即可看到一致快照,不会阻塞并发写入。
|
|
32
|
+
- 后台 Checkpoint 按阈值将日志页分批写回主库文件。
|
|
33
|
+
```
|
|
34
|
+
````
|
|
35
|
+
|
|
36
|
+
- **用**:介绍一篇论文、一个开源项目或某个子系统,需要带出来源链接和 2~4 条关键要点时。
|
|
37
|
+
- **别用**:只有一两句普通说明时直接写正文段落或链接卡片(`{card}`),不要套一层 `card`。
|
|
38
|
+
|
|
39
|
+
| 字段 | 必填 | 类型 | 说明 |
|
|
40
|
+
| :--- | :--- | :--- | :--- |
|
|
41
|
+
| `title` | 建议 | 字符串 | 卡片标题 |
|
|
42
|
+
| `url` | 否 | 完整链接 | 标题旁显示的外部链接(渲染为 `来源 ↗`) |
|
|
43
|
+
| `meta` | 否 | 字符串 | 标题下方的副标题或元信息说明 |
|
|
44
|
+
| `description` | 与 `points` 二选一 | 字符串 | 卡片主说明段落(支持行内加粗与代码) |
|
|
45
|
+
| `points` | 与 `description` 二选一 | 字符串数组 | 下方带编号的要点列表 |
|
|
46
|
+
| `source` | 否 | 字符串或 `{ title, url }` | 右下角出处角标 |
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 条形图表(chart)
|
|
3
|
+
navTitle: 条形图表
|
|
4
|
+
description: 用 YAML 数据直接生成比例条形图,下方自带可展开的数据表格。
|
|
5
|
+
section: components
|
|
6
|
+
order: 35
|
|
7
|
+
badge: chart
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
在 `garden` 想法块里写一句「用 `chart` 画条形图比较正文列、宽图区和宽表区的宽度上限」,Agent 会按 `garden-ui` skill 生成下面的 `garden chart`(手写格式附后)。
|
|
11
|
+
|
|
12
|
+
```garden chart
|
|
13
|
+
title: 三种版面区域的宽度上限
|
|
14
|
+
xLabel: 版面区域
|
|
15
|
+
yLabel: 最大宽度
|
|
16
|
+
unit: px
|
|
17
|
+
data:
|
|
18
|
+
- x: 普通正文列
|
|
19
|
+
y: 740
|
|
20
|
+
- x: 宽幅配图区
|
|
21
|
+
y: 1040
|
|
22
|
+
- x: 多列宽表格
|
|
23
|
+
y: 1340
|
|
24
|
+
caption: 点击「查看数据表」可展开完整数值表格。
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
````markdown
|
|
28
|
+
```garden chart
|
|
29
|
+
title: 三种版面区域的宽度上限
|
|
30
|
+
xLabel: 版面区域
|
|
31
|
+
yLabel: 最大宽度
|
|
32
|
+
unit: px
|
|
33
|
+
data:
|
|
34
|
+
- x: 普通正文列
|
|
35
|
+
y: 740
|
|
36
|
+
- x: 宽幅配图区
|
|
37
|
+
y: 1040
|
|
38
|
+
- x: 多列宽表格
|
|
39
|
+
y: 1340
|
|
40
|
+
caption: 点击「查看数据表」可展开完整数值表格。
|
|
41
|
+
```
|
|
42
|
+
````
|
|
43
|
+
|
|
44
|
+
- **用**:对比 2~8 组同量纲数值的长短比例时。
|
|
45
|
+
- **别用**:已经在同一个小节里放了同组数字的 Markdown 表格时不要再画一张 `chart`(图表底部已自带可展开的数据表)。
|
|
46
|
+
|
|
47
|
+
| 字段 | 必填 | 类型 | 说明 |
|
|
48
|
+
| :--- | :--- | :--- | :--- |
|
|
49
|
+
| `title` | 建议 | 字符串 | 图表标题 |
|
|
50
|
+
| `data` | 是 | `{ x, y, label? }[]`(至少 2 项) | 数据行列表,`x` 为名称,`y` 为数值 |
|
|
51
|
+
| `unit` | 否 | 字符串 | 数值后缀单位(当数据项未单独指定 `label` 时自动拼接) |
|
|
52
|
+
| `xLabel` | 否 | 字符串 | 展开数据表第一列的表头名称(默认 `项目`) |
|
|
53
|
+
| `yLabel` | 否 | 字符串 | 展开数据表第二列的表头名称(默认 `数值`) |
|
|
54
|
+
| `caption` | 否 | 字符串 | 图表底部的图注说明 |
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 并排对比(compare)
|
|
3
|
+
navTitle: 并排对比
|
|
4
|
+
description: 把两到三种方案左右并列,对比各自的取舍与属性。
|
|
5
|
+
section: components
|
|
6
|
+
order: 33
|
|
7
|
+
badge: compare
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
在 `garden` 想法块里写一句「用 `compare` 并排比较用一句话描述代码改动和手写 diff 两种做法」,Agent 会按 `garden-ui` skill 生成下面的 `garden compare`(手写格式附后)。
|
|
11
|
+
|
|
12
|
+
```garden compare
|
|
13
|
+
items:
|
|
14
|
+
- title: 写一句话说明改了什么
|
|
15
|
+
text: 想法块紧跟在完整代码下面,garden-ui 把它换成 diff,页面合成「代码 / 对比上一版」。
|
|
16
|
+
- title: 手写 diff
|
|
17
|
+
text: 完整代码下面紧跟一段 diff;前面没有完整代码时,garden check 报 diff-orphan。
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
````markdown
|
|
21
|
+
```garden compare
|
|
22
|
+
items:
|
|
23
|
+
- title: 写一句话说明改了什么
|
|
24
|
+
text: 想法块紧跟在完整代码下面,garden-ui 把它换成 diff,页面合成「代码 / 对比上一版」。
|
|
25
|
+
- title: 手写 diff
|
|
26
|
+
text: 完整代码下面紧跟一段 diff;前面没有完整代码时,garden check 报 diff-orphan。
|
|
27
|
+
```
|
|
28
|
+
````
|
|
29
|
+
|
|
30
|
+
- **用**:并排对比 2~3 种方案、配置方式或改动前后的行为差异时(每格文字控制在 60 字以内)。
|
|
31
|
+
- **别用**:对比项超过 3 个或需要横向对齐多个参数维度时,直接用 Markdown 表格。
|
|
32
|
+
|
|
33
|
+
| 字段 | 必填 | 类型 | 说明 |
|
|
34
|
+
| :--- | :--- | :--- | :--- |
|
|
35
|
+
| `items` | 是 | 数组(至少 2 项) | 对比项列表;每项也可简写为 `"标题:说明"` 单行字符串 |
|
|
36
|
+
| `items[].title` | 建议 | 字符串 | 该对比列的标题 |
|
|
37
|
+
| `items[].text` | 建议 | 字符串或字符串数组 | 该对比列的正文说明 |
|
|
38
|
+
| `items[].<自定义键>` | 否 | 字符串或数字 | 除 `title` / `text` 外的附加键值会渲染在卡片底部的属性标签行 |
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 分区结构图(figure)
|
|
3
|
+
navTitle: 分区结构图
|
|
4
|
+
description: 为 SVG 结构图加上分区高亮按钮,点击切换对应区域与文字说明。
|
|
5
|
+
section: components
|
|
6
|
+
order: 36
|
|
7
|
+
badge: figure
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
在 `garden` 想法块里写一句「用 `figure` 画一张静态发布流程的结构图,点到哪一步就高亮并显示那一步的说明」,Agent 会按 `garden-ui` skill 生成下面的 `garden figure`(手写格式附后)。
|
|
11
|
+
|
|
12
|
+
```garden figure
|
|
13
|
+
caption: 点击上方按钮切换高亮各步骤
|
|
14
|
+
svg: |
|
|
15
|
+
<svg viewBox="0 0 680 110" xmlns="http://www.w3.org/2000/svg" font-family="var(--sans)">
|
|
16
|
+
<rect data-p="sync" x="12" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
|
|
17
|
+
<text data-p="sync" x="110" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">1. garden sync</text>
|
|
18
|
+
<text data-p="sync" x="110" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">解析 Markdown 与图片尺寸</text>
|
|
19
|
+
<path d="M214 55 H236" stroke="var(--muted)" stroke-width="1.5"/>
|
|
20
|
+
<rect data-p="build" x="242" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
|
|
21
|
+
<text data-p="build" x="340" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">2. garden build</text>
|
|
22
|
+
<text data-p="build" x="340" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">生成静态页面与搜索索引</text>
|
|
23
|
+
<path d="M444 55 H466" stroke="var(--muted)" stroke-width="1.5"/>
|
|
24
|
+
<rect data-p="validate" x="472" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
|
|
25
|
+
<text data-p="validate" x="570" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">3. pages:validate</text>
|
|
26
|
+
<text data-p="validate" x="570" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">检查 index.html 与禁用文件</text>
|
|
27
|
+
</svg>
|
|
28
|
+
parts:
|
|
29
|
+
- id: sync
|
|
30
|
+
label: 1. 同步内容
|
|
31
|
+
text: 扫描 `content/` 与 `docs/handbook/`,复制随文附件并生成 `.garden/generated-content.ts`。
|
|
32
|
+
- id: build
|
|
33
|
+
label: 2. 构建页面
|
|
34
|
+
text: 根据 `STATIC_EXPORT=1` 预渲染所有页面路由,输出 RSS、sitemap 与全文搜索文件。
|
|
35
|
+
- id: validate
|
|
36
|
+
label: 3. 导出校验
|
|
37
|
+
text: 运行 pages:validate,确认导出目录里有 `index.html`,且没有 `.env`、源码目录、`.map` 或 `.md` 文件和软链接。
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
````markdown
|
|
41
|
+
```garden figure
|
|
42
|
+
caption: 点击上方按钮切换高亮各步骤
|
|
43
|
+
svg: |
|
|
44
|
+
<svg viewBox="0 0 680 110" xmlns="http://www.w3.org/2000/svg" font-family="var(--sans)">
|
|
45
|
+
<rect data-p="sync" x="12" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
|
|
46
|
+
<text data-p="sync" x="110" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">1. garden sync</text>
|
|
47
|
+
<text data-p="sync" x="110" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">解析 Markdown 与图片尺寸</text>
|
|
48
|
+
<rect data-p="build" x="242" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
|
|
49
|
+
<rect data-p="validate" x="472" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
|
|
50
|
+
</svg>
|
|
51
|
+
parts:
|
|
52
|
+
- id: sync
|
|
53
|
+
label: 1. 同步内容
|
|
54
|
+
text: 扫描 `content/` 与 `docs/handbook/`,复制随文附件并生成 `.garden/generated-content.ts`。
|
|
55
|
+
- id: build
|
|
56
|
+
label: 2. 构建页面
|
|
57
|
+
text: 根据 `STATIC_EXPORT=1` 预渲染所有页面路由,输出 RSS、sitemap 与全文搜索文件。
|
|
58
|
+
- id: validate
|
|
59
|
+
label: 3. 导出校验
|
|
60
|
+
text: 运行 pages:validate,确认导出目录里有 `index.html`,且没有 `.env`、源码目录、`.map` 或 `.md` 文件和软链接。
|
|
61
|
+
```
|
|
62
|
+
````
|
|
63
|
+
|
|
64
|
+
- **用**:展示模块架构或数据流向,需要读者点击按钮逐块查看对应区域职责时(SVG 内优先使用 `var(--well)`、`var(--ink)`、`var(--muted)` 等主题变量以兼容深色模式)。
|
|
65
|
+
- **别用**:不需要分区点击说明的普通流程图或截图,直接用标准 Markdown 图片或 `mermaid` 代码块。
|
|
66
|
+
|
|
67
|
+
| 字段 | 必填 | 类型 | 说明 |
|
|
68
|
+
| :--- | :--- | :--- | :--- |
|
|
69
|
+
| `svg` | 与 `image` 二选一 | 多行字符串 | 内联 `<svg>` 源码;在需要高亮的分组上标注 `data-p="<id>"` |
|
|
70
|
+
| `image` | 与 `svg` 二选一 | 路径字符串 | 普通图片路径(可写成 `{ src, alt }`) |
|
|
71
|
+
| `parts` | 否 | `{ id, label, text }[]` | 顶部分区切换按钮及底部对应的说明文字 |
|
|
72
|
+
| `caption` | 否 | 字符串 | 图框下方的图注说明 |
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# 站点发布前检查清单
|
|
2
|
+
|
|
3
|
+
在运行 `make update` 推送更新前,可以核对以下几项:
|
|
4
|
+
|
|
5
|
+
## 1. 文章 Front Matter 与路径
|
|
6
|
+
|
|
7
|
+
- [x] `title`、`date`、`description` 均已填写,文件名只用小写字母、数字和连字符
|
|
8
|
+
- [x] 本地图片与随文附件放在文章同名目录下,使用 `./<slug>/file.ext` 相对路径引用
|
|
9
|
+
- [x] 正式发布的文章已去掉 `draft: true`
|
|
10
|
+
|
|
11
|
+
## 2. 本地校验命令
|
|
12
|
+
|
|
13
|
+
| 命令 | 检查内容 |
|
|
14
|
+
| :--- | :--- |
|
|
15
|
+
| `npx garden check content/posts/<slug>.md` | 检查单篇文章的组件字段、代码对比与图片附件路径 |
|
|
16
|
+
| `make check` | 运行 `npx garden sync && npx garden build` 校验全站构建 |
|
|
17
|
+
| `CONTENT_INCLUDE_DRAFTS=1 make dev` | 在本地连同草稿和定时文章一起预览 |
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 文件下载与预览(file)
|
|
3
|
+
navTitle: 文件下载与预览
|
|
4
|
+
description: 提供单个或一组附件下载,自动显示格式与大小,支持在页内展开预览。
|
|
5
|
+
section: components
|
|
6
|
+
order: 39
|
|
7
|
+
badge: file
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
在 `garden` 想法块里写一句「用 `file` 给读者一份可以下载和页内预览的发布前检查清单」,Agent 会按 `garden-ui` skill 生成下面的 `garden file`(手写格式附后)。
|
|
11
|
+
|
|
12
|
+
```garden file
|
|
13
|
+
src: ./file/checklist.md
|
|
14
|
+
title: 发布前检查清单
|
|
15
|
+
note: Markdown 附件示例,可点击「预览」在当前页展开阅读,或直接下载原文件
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
````markdown
|
|
19
|
+
```garden file
|
|
20
|
+
src: ./file/checklist.md
|
|
21
|
+
title: 发布前检查清单
|
|
22
|
+
note: Markdown 附件示例,可点击「预览」在当前页展开阅读,或直接下载原文件
|
|
23
|
+
```
|
|
24
|
+
````
|
|
25
|
+
|
|
26
|
+
- **用**:随文章提供配置文件、数据表、PDF、图片或 Markdown 附件供读者下载与页内预览时(多文件可用 `files` 数组)。
|
|
27
|
+
- **别用**:正文里本来就要直接展示的配图用标准 Markdown 图片语法 `![]()`,不要放进 `file` 组件。
|
|
28
|
+
|
|
29
|
+
| 字段 | 必填 | 类型 | 说明 |
|
|
30
|
+
| :--- | :--- | :--- | :--- |
|
|
31
|
+
| `src` | 单文件必填 | 路径或完整链接 | 相对当前 Markdown 文件的本地路径(不得越出 `content/`)、`/public` 路径或 `https://` 链接 |
|
|
32
|
+
| `title` | 否 | 字符串 | 显示的文件标题(默认取文件名;多文件模式下作为分组标题) |
|
|
33
|
+
| `note` | 否 | 字符串 | 文件名下方的简短说明 |
|
|
34
|
+
| `files` | 多文件必填 | `{ src, title?, note? }[]` | 一次列出多个文件时使用(与顶层 `src` 二选一) |
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 嵌入网页片段(html)
|
|
3
|
+
navTitle: 嵌入网页片段
|
|
4
|
+
description: 在沙盒 iframe 中运行独立的 HTML、CSS 与 JavaScript 演示片段。
|
|
5
|
+
section: components
|
|
6
|
+
order: 37
|
|
7
|
+
badge: html
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
在 `garden` 想法块里写一句「用 `html` 嵌一个小工具,输入文字就实时算出字符数」,Agent 会按 `garden-ui` skill 生成下面的 `garden html`(手写格式附后)。
|
|
11
|
+
|
|
12
|
+
```garden html
|
|
13
|
+
title: 字符长度与预计阅读耗时小工具
|
|
14
|
+
height: 156
|
|
15
|
+
code: |
|
|
16
|
+
<!doctype html>
|
|
17
|
+
<html lang="zh-CN">
|
|
18
|
+
<head>
|
|
19
|
+
<meta charset="utf-8" />
|
|
20
|
+
<style>
|
|
21
|
+
body { margin: 0; padding: 16px 18px; font: 14px/1.6 system-ui, sans-serif; color: #1b1a18; background: #faf9f5; }
|
|
22
|
+
input { width: 100%; box-sizing: border-box; padding: 8px 10px; border: 1px solid #d5d1c8; border-radius: 6px; font: inherit; background: #fff; color: #1b1a18; }
|
|
23
|
+
.meta { margin-top: 10px; color: #6e6b64; font-variant-numeric: tabular-nums; }
|
|
24
|
+
strong { color: #1b1a18; }
|
|
25
|
+
</style>
|
|
26
|
+
</head>
|
|
27
|
+
<body>
|
|
28
|
+
<input id="txt" value="把文章放在自己的 Git 仓库里,推送后自动构建。" aria-label="输入示例文本" />
|
|
29
|
+
<div class="meta">当前字符数:<strong id="count">23</strong> 字</div>
|
|
30
|
+
<script>
|
|
31
|
+
const input = document.getElementById("txt");
|
|
32
|
+
const count = document.getElementById("count");
|
|
33
|
+
input.addEventListener("input", () => { count.textContent = String(input.value.length); });
|
|
34
|
+
</script>
|
|
35
|
+
</body>
|
|
36
|
+
</html>
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
````markdown
|
|
40
|
+
```garden html
|
|
41
|
+
title: 字符长度与预计阅读耗时小工具
|
|
42
|
+
height: 156
|
|
43
|
+
code: |
|
|
44
|
+
<!doctype html>
|
|
45
|
+
<html lang="zh-CN">
|
|
46
|
+
<head><meta charset="utf-8" /></head>
|
|
47
|
+
<body>
|
|
48
|
+
<input id="txt" value="把文章放在自己的 Git 仓库里,推送后自动构建。" />
|
|
49
|
+
<div>当前字符数:<strong id="count">23</strong> 字</div>
|
|
50
|
+
<script>
|
|
51
|
+
const input = document.getElementById("txt");
|
|
52
|
+
const count = document.getElementById("count");
|
|
53
|
+
input.addEventListener("input", () => { count.textContent = String(input.value.length); });
|
|
54
|
+
</script>
|
|
55
|
+
</body>
|
|
56
|
+
</html>
|
|
57
|
+
```
|
|
58
|
+
````
|
|
59
|
+
|
|
60
|
+
- **用**:需要运行自定义 DOM 脚本、Canvas 绘图或独立 HTML 页面片段时(支持 `code` 内联或 `src` 引用文章同名目录下的 `.html` 文件)。
|
|
61
|
+
- **别用**:只需要滑杆调参数算公式时用 [`interactive`](/garden/components/interactive);静态结构图用 [`figure`](/garden/components/figure)。
|
|
62
|
+
|
|
63
|
+
| 字段 | 必填 | 类型 | 说明 |
|
|
64
|
+
| :--- | :--- | :--- | :--- |
|
|
65
|
+
| `src` | 与 `code` 二选一 | 相对路径字符串 | 引用与当前 Markdown 同目录(或同名子目录)下的 `.html` 文件 |
|
|
66
|
+
| `code` | 与 `src` 二选一 | 多行字符串 | 直接内联编写的 HTML 源码(也可用别名 `html`) |
|
|
67
|
+
| `title` | 建议 | 字符串 | 卡片顶部栏标题及 `iframe` 的无障碍标题 |
|
|
68
|
+
| `height` | 否 | 数字 | 初始高度(像素,默认 `260`;加载后也会随内容高度自动调整) |
|
|
69
|
+
| `caption` | 否 | 字符串 | 底部的图注说明 |
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 可调公式与参数(interactive)
|
|
3
|
+
navTitle: 可调公式与参数
|
|
4
|
+
description: 提供滑杆或单选按钮,让读者调整变量并实时计算公式与图表结果。
|
|
5
|
+
section: components
|
|
6
|
+
order: 38
|
|
7
|
+
badge: interactive
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
在 `garden` 想法块里写一句「让读者拖动字数、阅读速度和配图数,看预计阅读时间怎么变」,Agent 会按 `garden-ui` skill 生成下面的 `garden interactive`(手写格式附后)。
|
|
11
|
+
|
|
12
|
+
```garden interactive #reading-time
|
|
13
|
+
caption: 示例:按字数、阅读速度和配图数估算一篇文章的阅读时间。数字只用来演示组件,不是统计结果。
|
|
14
|
+
---
|
|
15
|
+
<State words={6000} speed={400} images={8} />
|
|
16
|
+
<Let textMinutes={round(words / speed)} />
|
|
17
|
+
<Let imageMinutes={round(images * 12 / 60)} />
|
|
18
|
+
<Let parts={[{ part: "正文", minutes: textMinutes }, { part: "配图", minutes: imageMinutes }]} />
|
|
19
|
+
|
|
20
|
+
<Slider bind="words" label="正文字数" min={1000} max={20000} step={500} unit="字" />
|
|
21
|
+
<Slider bind="speed" label="阅读速度" min={200} max={800} step={50} unit="字/分钟" />
|
|
22
|
+
<Slider bind="images" label="配图数" min={0} max={30} step={1} unit="张" />
|
|
23
|
+
|
|
24
|
+
<Stat label="示例:预计阅读时间" value={textMinutes + imageMinutes} unit="分钟" hint="配图按每张 12 秒估算" />
|
|
25
|
+
<Chart data={parts} x={part} yLabel="分钟">
|
|
26
|
+
<Bar y={minutes} label="示例" />
|
|
27
|
+
</Chart>
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
````markdown
|
|
31
|
+
```garden interactive #reading-time
|
|
32
|
+
caption: 示例:按字数、阅读速度和配图数估算一篇文章的阅读时间。数字只用来演示组件,不是统计结果。
|
|
33
|
+
---
|
|
34
|
+
<State words={6000} speed={400} images={8} />
|
|
35
|
+
<Let textMinutes={round(words / speed)} />
|
|
36
|
+
<Let imageMinutes={round(images * 12 / 60)} />
|
|
37
|
+
<Let parts={[{ part: "正文", minutes: textMinutes }, { part: "配图", minutes: imageMinutes }]} />
|
|
38
|
+
|
|
39
|
+
<Slider bind="words" label="正文字数" min={1000} max={20000} step={500} unit="字" />
|
|
40
|
+
<Slider bind="speed" label="阅读速度" min={200} max={800} step={50} unit="字/分钟" />
|
|
41
|
+
<Slider bind="images" label="配图数" min={0} max={30} step={1} unit="张" />
|
|
42
|
+
|
|
43
|
+
<Stat label="示例:预计阅读时间" value={textMinutes + imageMinutes} unit="分钟" hint="配图按每张 12 秒估算" />
|
|
44
|
+
<Chart data={parts} x={part} yLabel="分钟">
|
|
45
|
+
<Bar y={minutes} label="示例" />
|
|
46
|
+
</Chart>
|
|
47
|
+
```
|
|
48
|
+
````
|
|
49
|
+
|
|
50
|
+
- **用**:解释带多个变量的数学关系、容量估算或参数权衡,需要读者拖动滑杆实时观察结果变化时。
|
|
51
|
+
- **别用**:只有 `<Steps>` 而没有任何状态或输入控件,会报 `steps-prose` 错误;所有 `<Let>` 都只是一次乘法(形如 `a * b`),会报 `interactive-trivial` 错误。遇到这两种情况,改用普通段落。
|
|
52
|
+
|
|
53
|
+
分隔线 `---` 上方是块头,下方是标签。常用的写法:
|
|
54
|
+
|
|
55
|
+
| 字段或标签 | 必填 | 说明 |
|
|
56
|
+
| :--- | :--- | :--- |
|
|
57
|
+
| `#reading-time` | 建议 | 写在围栏头,块的标识,只能用小写字母、数字和连字符 |
|
|
58
|
+
| `caption` | 是 | 一句话说明这块交互想让读者看到什么 |
|
|
59
|
+
| `intent` | 否 | 这块交互由哪句想法编译而来,写成文字 |
|
|
60
|
+
| `expect` | 否 | 数组,每条写成 `{ given: {...}, 名字: 期望值 }`,检查时会按给定状态算一遍 |
|
|
61
|
+
| `<State />` | 是 | 声明会变的量和默认值,例如 `<State words={6000} />` |
|
|
62
|
+
| `<Let />` | 否 | 由别的量算出来的值,也可以写数据数组 |
|
|
63
|
+
| `<Slider />` / `<Choice />` / `<Toggle />` | 是 | 输入控件,用 `bind` 绑定一个状态;`Slider` 必填 `label`、`min`、`max` |
|
|
64
|
+
| `<Stat />` | 否 | 显示一个醒目的数字,必填 `label` 与 `value` |
|
|
65
|
+
| `<Chart />` | 否 | 用 `sweep` 画函数曲线,或用 `data` 加 `<Bar>` / `<Line>` 画数据 |
|
|
66
|
+
|
|
67
|
+
全部标签和属性见 `npx garden ui catalog` 生成的组件目录。
|