hd-garden 0.3.13 → 0.4.0

package/scripts/check-post.mjs

@@ -5,6 +5,7 @@ import { parse as parseYaml } from "yaml";
 import { canonicalSiteDate } from "./site-date.mjs";
 import { gardenSiteRoot } from "./garden-paths.mjs";
 import { checkUiBlock } from "../ui/core/validate.mjs";
+import { checkGardenMarkdown } from "../ui/garden/check.mjs";
 
 const siteRoot = gardenSiteRoot();
 const calloutTypes = new Set([
@@ -18,7 +19,7 @@ const calloutTypes = new Set([
   "DANGER",
   "FAILURE",
 ]);
-const authorDate = /^(?:\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})$/u;
+const authorDate = /^(?:\d{4}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?)$/u;
 const matterOptions = {
   engines: {
     yaml: {
@@ -202,7 +203,7 @@ const checkUi = (errors, warnings, body, markdownPath, sourcePath, line) => {
 
 const scanBody = (errors, content, markdownPath, sourcePath, { warnings = [], draft = false } = {}) => {
   let fence = null;
-  let previousDepth = 1;
+  let previousDepth = 2;
   const lines = content.split(/\r?\n/u);
   lines.forEach((line, index) => {
     const lineNumber = index + 1;
@@ -277,8 +278,11 @@ const checkFile = (filePath) => {
   if (data.slug !== undefined) {
     error(errors, "unexpected-slug", 1, `${sourcePath}: 不要写 slug，文件名就是标识`);
   }
-  if (typeof data.date !== "string" || !authorDate.test(data.date.trim()) || !canonicalSiteDate(data.date)) {
-    error(errors, "date-format", 1, `${sourcePath}: date 必须是 2026-09-18 或 2026-09-18 14:39:00`);
+  const dateText = data.date instanceof Date
+    ? (Number.isNaN(data.date.getTime()) ? "" : data.date.toISOString())
+    : typeof data.date === "string" ? data.date.trim() : "";
+  if (!authorDate.test(dateText) || !canonicalSiteDate(data.date)) {
+    error(errors, "date-format", 1, `${sourcePath}: date 必须是 2026-09-18、2026-09-18 14:39:00，或带时区的 ISO 时间`);
   }
   if (typeof data.cover === "string" && data.cover.trim() && !isExternalAsset(data.cover.trim())) {
     const coverPath = path.join(siteRoot, "content", "covers", data.cover.trim());
@@ -289,6 +293,16 @@ const checkFile = (filePath) => {
   checkReferences(data, sourcePath, errors);
   const draft = data.draft === true || (typeof data.publishAt === "string" && Date.parse(canonicalSiteDate(data.publishAt) ?? "") > Date.now());
   scanBody(errors, parsed.content, absolute, sourcePath, { warnings, draft });
+  const raw = fs.readFileSync(absolute, "utf8");
+  const titleLine = Math.max(1, raw.split(/\r?\n/u).findIndex((line) => /^title:/u.test(line)) + 1);
+  for (const item of checkGardenMarkdown(raw, {
+    draft,
+    title: typeof data.title === "string" ? data.title : "",
+    titleLine,
+  })) {
+    const target = item.severity === "warning" ? warnings : errors;
+    target.push({ code: item.code, line: item.line, message: `${sourcePath}: ${item.message} 建议：${item.suggestion}` });
+  }
   return { file: sourcePath, errors, warnings };
 };
 

package/scripts/new-post.mjs

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { lstat, mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { formatAuthorDate } from "./site-date.mjs";
+import { cheatSheet } from "../ui/garden/catalog.mjs";
 
 const root = path.resolve(process.env.GARDEN_SITE || process.cwd());
 const option = (name) => (process.env[`GARDEN_NEW_${name}`] ?? "").trim();
@@ -51,6 +52,8 @@ async function main() {
     "",
     "从这里开始写正文。",
     "",
+    cheatSheet(),
+    "",
   ].join("\n");
   try {
     await writeFile(destination, markdown, { flag: "wx" });

package/site.config.yaml

@@ -1,4 +1,4 @@
-name: Garden
+name: Hedon Garden
 tagline: 写作 · 构建 · 保持好奇
 description: 一个可 fork、可长期维护的 Markdown 个人博客系统。
 locale: zh_CN

package/templates/garden-blocks.md

@@ -0,0 +1,128 @@
+# Garden 块模板
+
+从这里复制。触发词和 VS Code 片段、macOS 文本替换是同一份目录生成的。
+
+## 想法 · 想法
+
+还不确定用哪个组件时，写一句想让读者看出什么。
+
+不该用：发布前必须编译掉。草稿里可以留着。
+
+```garden
+让读者……；想让读者看出……
+```
+
+## card · 资源卡
+
+一篇论文、一个仓库或一本书，读者需要标题、链接和一句说明。
+
+不该用：正文里已经有这句话时，不要再包一张卡。
+
+```garden card
+url: https://arxiv.org/abs/2309.06180
+title: PagedAttention
+description: vLLM 的分页 KV 管理。
+```
+
+## stat · 指标
+
+一个短指标：标签、数字、可选的一句说明和来源。
+
+不该用：数字需要读者自己代入参数时，写成想法，不要做静态指标。
+
+```garden stat
+items:
+  - label: Llama-2-13B · 4K 上下文
+    value: 3.2
+    unit: GiB
+    source: https://arxiv.org/abs/2309.06180
+```
+
+## compare · 对比
+
+两三件东西并排，每格大约 60 字以内。
+
+不该用：任何一格超过约 60 字时，用原文的列表，不要并排。
+
+```garden compare
+items:
+  - title: 自旋锁
+    text: 临界区极短时忙等，不进入休眠。
+  - title: 互斥锁
+    text: 争用久就休眠，避免空转占满 CPU。
+```
+
+## timeline · 时间线
+
+版本演进或一段历史，每条有日期和一句说明。
+
+不该用：没有时间顺序时，用普通列表。
+
+```garden timeline
+items:
+  - date: 2015
+    title: 并发标记
+    text: 暂停时间降下来。
+  - date: 2017
+    title: 栈重扫移出 STW
+    text: 停顿通常低于 100 微秒。
+  - date: 2022
+    title: 软内存上限
+    text: 运行时可以设 GOMEMLIMIT。
+```
+
+## chart · 图表
+
+一组已经算好的数字，读者不需要拧参数。
+
+不该用：数字会随读者的选择变化时，写成想法，编译成 interactive。
+
+```garden chart
+type: bar
+title: 示例延迟
+x: 方案
+series:
+  - name: 延迟
+    data: [120, 85]
+unit: ms
+```
+
+## figure · 结构图
+
+一张结构图，读者点一个部分就看到对应的一句说明。
+
+不该用：作者已经用 mermaid 画了整张流程时，保留 mermaid，不要拆开重画。
+
+```garden figure
+image: ./figure.svg
+parts:
+  - name: 全部
+    text: 整张图。
+  - name: 标记
+    text: 这一步只做标记。
+```
+
+## html · 自定义 HTML
+
+目录里的组件画不出来的示意图或小工具，写在同名目录的 HTML 里。
+
+不该用：能用 card、chart、figure 或正文说清时，不要写 HTML。
+
+```garden html
+src: ./demo.html
+title: 示意图
+```
+
+## interactive · 交互
+
+读者需要拧参数或翻状态才能看懂，由想法编译而来。
+
+不该用：一次乘法、把散文切成步骤，都不要做成交互。
+
+```garden interactive #kv-memory
+caption: 显存与 batch、序列长度都成正比。
+intent: |
+  让读者拧 batch，看 KV 显存。
+---
+<State batch={1} />
+```

package/templates/garden-snippets.plist

@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<array>
+  <dict>
+    <key>phrase</key>
+    <string>```garden
+让读者……；想让读者看出……
+```</string>
+    <key>shortcut</key>
+    <string>;garden想法</string>
+  </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden
+让读者……；想让读者看出……
+```</string>
+    <key>shortcut</key>
+    <string>;gidea</string>
+  </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden card
+url: https://arxiv.org/abs/2309.06180
+title: PagedAttention
+description: vLLM 的分页 KV 管理。
+```</string>
+    <key>shortcut</key>
+    <string>;gcard</string>
+  </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden stat
+items:
+  - label: Llama-2-13B · 4K 上下文
+    value: 3.2
+    unit: GiB
+    source: https://arxiv.org/abs/2309.06180
+```</string>
+    <key>shortcut</key>
+    <string>;gstat</string>
+  </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden compare
+items:
+  - title: 自旋锁
+    text: 临界区极短时忙等，不进入休眠。
+  - title: 互斥锁
+    text: 争用久就休眠，避免空转占满 CPU。
+```</string>
+    <key>shortcut</key>
+    <string>;gcompare</string>
+  </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden timeline
+items:
+  - date: 2015
+    title: 并发标记
+    text: 暂停时间降下来。
+  - date: 2017
+    title: 栈重扫移出 STW
+    text: 停顿通常低于 100 微秒。
+  - date: 2022
+    title: 软内存上限
+    text: 运行时可以设 GOMEMLIMIT。
+```</string>
+    <key>shortcut</key>
+    <string>;gtimeline</string>
+  </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden chart
+type: bar
+title: 示例延迟
+x: 方案
+series:
+  - name: 延迟
+    data: [120, 85]
+unit: ms
+```</string>
+    <key>shortcut</key>
+    <string>;gchart</string>
+  </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden figure
+image: ./figure.svg
+parts:
+  - name: 全部
+    text: 整张图。
+  - name: 标记
+    text: 这一步只做标记。
+```</string>
+    <key>shortcut</key>
+    <string>;gfigure</string>
+  </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden html
+src: ./demo.html
+title: 示意图
+```</string>
+    <key>shortcut</key>
+    <string>;ghtml</string>
+  </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden interactive #kv-memory
+caption: 显存与 batch、序列长度都成正比。
+intent: |
+  让读者拧 batch，看 KV 显存。
+---
+&lt;State batch={1} /&gt;
+```</string>
+    <key>shortcut</key>
+    <string>;ginteractive</string>
+  </dict>
+</array>
+</plist>

package/ui/garden/catalog.mjs

@@ -0,0 +1,196 @@
+/**
+ * Author-facing Garden blocks. One catalog feeds the parser, checker,
+ * snippets, Typora templates and the component list.
+ * Names describe what the reader sees. English only.
+ */
+
+export const GARDEN_NAMES = ["card", "stat", "compare", "timeline", "chart", "figure", "html", "interactive"];
+
+export const LEGACY_FENCES = {
+  embed: { name: "card", suggestion: "`embed` 已改为 `garden card`" },
+  widget: { name: "html", suggestion: "`widget` 已改为 `garden html`" },
+  intent: { name: "", suggestion: "`intent` 已改为 `garden`（想法，发布前编译）" },
+  ui: { name: "interactive", suggestion: "`ui` 已改为 `garden interactive`" },
+  "ui-error": { name: "interactive", suggestion: "`ui` 已改为 `garden interactive`" },
+};
+
+export const CATALOG = {
+  card: {
+    label: "资源卡",
+    when: "一篇论文、一个仓库或一本书，读者需要标题、链接和一句说明。",
+    whenNot: "正文里已经有这句话时，不要再包一张卡。",
+    keys: ["url", "title", "description", "image", "alt", "points", "meta", "text", "source", "site", "items"],
+    example: `\`\`\`garden card
+url: https://arxiv.org/abs/2309.06180
+title: PagedAttention
+description: vLLM 的分页 KV 管理。
+\`\`\``,
+    triggers: ["gcard"],
+  },
+  stat: {
+    label: "指标",
+    when: "一个短指标：标签、数字、可选的一句说明和来源。",
+    whenNot: "数字需要读者自己代入参数时，写成想法，不要做静态指标。",
+    keys: ["items", "label", "value", "unit", "caption", "source", "text"],
+    example: `\`\`\`garden stat
+items:
+  - label: Llama-2-13B · 4K 上下文
+    value: 3.2
+    unit: GiB
+    source: https://arxiv.org/abs/2309.06180
+\`\`\``,
+    triggers: ["gstat"],
+  },
+  compare: {
+    label: "对比",
+    when: "两三件东西并排，每格大约 60 字以内。",
+    whenNot: "任何一格超过约 60 字时，用原文的列表，不要并排。",
+    keys: ["items"],
+    itemKeys: ["title", "text"],
+    example: `\`\`\`garden compare
+items:
+  - title: 自旋锁
+    text: 临界区极短时忙等，不进入休眠。
+  - title: 互斥锁
+    text: 争用久就休眠，避免空转占满 CPU。
+\`\`\``,
+    triggers: ["gcompare"],
+  },
+  timeline: {
+    label: "时间线",
+    when: "版本演进或一段历史，每条有日期和一句说明。",
+    whenNot: "没有时间顺序时，用普通列表。",
+    keys: ["title", "items"],
+    itemKeys: ["date", "title", "text", "source"],
+    example: `\`\`\`garden timeline
+items:
+  - date: 2015
+    title: 并发标记
+    text: 暂停时间降下来。
+  - date: 2017
+    title: 栈重扫移出 STW
+    text: 停顿通常低于 100 微秒。
+  - date: 2022
+    title: 软内存上限
+    text: 运行时可以设 GOMEMLIMIT。
+\`\`\``,
+    triggers: ["gtimeline"],
+  },
+  chart: {
+    label: "图表",
+    when: "一组已经算好的数字，读者不需要拧参数。",
+    whenNot: "数字会随读者的选择变化时，写成想法，编译成 interactive。",
+    keys: ["type", "title", "x", "series", "data", "unit", "caption", "xLabel", "yLabel"],
+    example: `\`\`\`garden chart
+type: bar
+title: 示例延迟
+x: 方案
+series:
+  - name: 延迟
+    data: [120, 85]
+unit: ms
+\`\`\``,
+    triggers: ["gchart"],
+  },
+  figure: {
+    label: "结构图",
+    when: "一张结构图，读者点一个部分就看到对应的一句说明。",
+    whenNot: "作者已经用 mermaid 画了整张流程时，保留 mermaid，不要拆开重画。",
+    keys: ["image", "alt", "mermaid", "svg", "parts", "caption"],
+    example: `\`\`\`garden figure
+image: ./figure.svg
+parts:
+  - name: 全部
+    text: 整张图。
+  - name: 标记
+    text: 这一步只做标记。
+\`\`\``,
+    triggers: ["gfigure"],
+  },
+  html: {
+    label: "自定义 HTML",
+    when: "目录里的组件画不出来的示意图或小工具，写在同名目录的 HTML 里。",
+    whenNot: "能用 card、chart、figure 或正文说清时，不要写 HTML。",
+    keys: ["src", "code", "title", "height"],
+    example: `\`\`\`garden html
+src: ./demo.html
+title: 示意图
+\`\`\``,
+    triggers: ["ghtml"],
+  },
+  interactive: {
+    label: "交互",
+    when: "读者需要拧参数或翻状态才能看懂，由想法编译而来。",
+    whenNot: "一次乘法、把散文切成步骤，都不要做成交互。",
+    keys: ["id", "caption", "intent", "expect"],
+    example: `\`\`\`garden interactive #kv-memory
+caption: 显存与 batch、序列长度都成正比。
+intent: |
+  让读者拧 batch，看 KV 显存。
+---
+<State batch={1} />
+\`\`\``,
+    triggers: ["ginteractive"],
+  },
+};
+
+export const IDEA = {
+  label: "想法",
+  when: "还不确定用哪个组件时，写一句想让读者看出什么。",
+  whenNot: "发布前必须编译掉。草稿里可以留着。",
+  example: `\`\`\`garden
+让读者……；想让读者看出……
+\`\`\``,
+  triggers: ["garden想法", "gidea"],
+};
+
+export function legacyOf(lang) {
+  const key = String(lang || "").toLowerCase();
+  if (LEGACY_FENCES[key]) return { lang: key, ...LEGACY_FENCES[key] };
+  if (key.startsWith("garden:")) {
+    const name = key.slice("garden:".length);
+    return { lang: key, name, suggestion: `\`${key}\` 已改为 \`garden ${name}\`` };
+  }
+  return null;
+}
+
+export function knownName(name) {
+  return GARDEN_NAMES.includes(name);
+}
+
+function distance(left, right) {
+  const a = [...left];
+  const b = [...right];
+  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i += 1) {
+    let previous = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const next = a[i - 1] === b[j - 1] ? row[j - 1] : Math.min(row[j - 1], row[j], previous) + 1;
+      row[j - 1] = previous;
+      previous = next;
+    }
+    row[b.length] = previous;
+  }
+  return row[b.length];
+}
+
+export function suggestName(name) {
+  let best = null;
+  let score = 3;
+  for (const known of GARDEN_NAMES) {
+    const gap = distance(String(name || ""), known);
+    if (gap < score) {
+      score = gap;
+      best = known;
+    }
+  }
+  return best;
+}
+
+export function cheatSheet() {
+  const blocks = [
+    IDEA.example,
+    ...GARDEN_NAMES.map((name) => CATALOG[name].example),
+  ];
+  return ["<!-- 组件速查。复制需要的一块，删掉这段注释。", ...blocks.flatMap((example) => ["", example]), "-->"].join("\n");
+}

package/ui/garden/check.mjs

@@ -0,0 +1,103 @@
+import { CATALOG, suggestName } from "./catalog.mjs";
+import { isProseSteps, isTrivialInteractive } from "./enhance.mjs";
+import { blanksBetween, classifyFence, isFullCodeFence, scanFences } from "./parse.mjs";
+import { splitTitle } from "./title.mjs";
+
+const COMPARE_LIMIT = 60;
+
+function cellText(item) {
+  if (!item || typeof item !== "object") return "";
+  const parts = [];
+  if (typeof item.text === "string") parts.push(item.text);
+  if (Array.isArray(item.text)) parts.push(...item.text.map(String));
+  for (const [key, value] of Object.entries(item)) {
+    if (key === "title" || key === "text") continue;
+    if (typeof value === "string") parts.push(value);
+  }
+  return parts.join("");
+}
+
+function compareTooLong(props) {
+  const items = Array.isArray(props?.items) ? props.items : [];
+  return items.some((item) => [...cellText(item).trim()].length > COMPARE_LIMIT);
+}
+
+/**
+ * Diagnostics for one Markdown file.
+ * `line` is a 1-based line in `markdown` (front matter included when `title` is passed with `titleLine`).
+ */
+export function checkGardenMarkdown(markdown, { draft = false, title = "", titleLine = 1 } = {}) {
+  const diagnostics = [];
+  const push = (line, code, message, suggestion, severity = "error") => {
+    diagnostics.push({ line, code, message, suggestion, severity });
+  };
+
+  if (title) {
+    const split = splitTitle(title);
+    // Titles stay exactly as written. splitTitle already keeps one line when it cannot split.
+    if (split.issue === "multiple") {
+      push(titleLine, "title-split", "标题里有不止一个分隔符，无法分成正好两行。", "只留一个 丨、｜ 或 \" | \"。", "warning");
+    } else if (split.issue === "empty") {
+      push(titleLine, "title-split", "分隔符两侧都要有文字。", "写成「主题丨副题」。", "warning");
+    }
+  }
+
+  const fences = scanFences(markdown);
+  fences.forEach((fence, index) => {
+    const kind = classifyFence(fence);
+    if (kind.kind === "legacy") {
+      push(fence.line, "legacy-fence", kind.suggestion, kind.suggestion);
+      return;
+    }
+    if (kind.kind === "diff") {
+      const previous = fences[index - 1];
+      const previousKind = previous ? classifyFence(previous) : null;
+      const adjacent = previous && blanksBetween(markdown, previous.endLine, fence.line) && isFullCodeFence(previousKind);
+      if (!adjacent) {
+        push(fence.line, "diff-orphan", "这段 diff 前面没有紧挨着的完整代码块。", "先放完整代码，下一围栏再写它的 diff。");
+      }
+      return;
+    }
+    if (kind.kind !== "garden" || !kind.block) return;
+    const block = kind.block;
+    if (block.legacy) {
+      const suggestion = `\`${block.legacyLang}\` 已改为 \`garden ${block.name}\``;
+      push(fence.line, "legacy-fence", suggestion, suggestion);
+    }
+    if (!block.name) {
+      if (!draft) {
+        push(fence.line, "garden-idea", "非草稿里还有未编译的想法。", "编译成 `garden interactive`，或把这句话写回正文。");
+      }
+      return;
+    }
+    if (block.error?.code === "garden-name") {
+      const guess = suggestName(block.name);
+      const suggestion = guess ? `你是不是想用 ${guess}` : `可用的名字：${Object.keys(CATALOG).join("、")}`;
+      push(fence.line, "garden-name", block.error.message, suggestion);
+      return;
+    }
+    if (block.error?.code === "garden-yaml") {
+      const allowed = block.error.allowed ?? CATALOG[block.name]?.keys ?? [];
+      push(fence.line, "garden-yaml", block.error.message, allowed.length ? `可用的键：${allowed.join("、")}` : "检查缩进和冒号。");
+      return;
+    }
+    if (block.name === "compare" && compareTooLong(block.props)) {
+      push(fence.line, "compare-long", "对比格超过约 60 字。", "这一格改回原文的列表或段落。");
+    }
+    if (block.name === "interactive") {
+      const source = `${fence.body}\n${block.children}`;
+      if (isTrivialInteractive(source)) {
+        push(fence.line, "interactive-trivial", "只有一次乘法，却做成了交互。", "把这句算式留在正文里。");
+      }
+      if (isProseSteps(source)) {
+        push(fence.line, "steps-prose", "步骤只是散文。", "连续的段落不要拆成步骤；有状态变化时才用 interactive。");
+      }
+    }
+  });
+  return diagnostics;
+}
+
+export function formatDiagnostic(file, diagnostic) {
+  const where = file ? `${file}:${diagnostic.line}` : String(diagnostic.line);
+  return `${where} ${diagnostic.code} ${diagnostic.message} 建议：${diagnostic.suggestion}`;
+}