hd-garden 0.6.1 → 0.7.0

package/app/garden/page.tsx

@@ -1,148 +1,81 @@
-import { ArrowRight, ArrowUpRight, GithubLogo } from "@phosphor-icons/react/ssr";
-import { GardenAdminGuide } from "../components/GardenAdminGuide";
-import { GardenContentGuide } from "../components/GardenContentGuide";
+import Link from "next/link";
+import { ArrowRight } from "@phosphor-icons/react/ssr";
+import { ArticleMeasure } from "../components/ArticleMeasure";
+import { ArticleReferences } from "../components/ArticleReferences";
+import { ArticleTitle } from "../components/ArticleTitle";
+import { GardenDocsNav } from "../components/GardenDocsNav";
 import { GardenMediaGuide } from "../components/GardenMediaGuide";
-import { PageIntro } from "../components/PageIntro";
-import { siteConfig } from "../site.config";
+import { MarkdownArticle } from "../components/MarkdownArticle";
+import { TableOfContents } from "../components/TableOfContents";
+import {
+  extractHeadings,
+  gardenDocHref,
+  gardenDocs,
+  gardenIndexDoc,
+} from "../lib/content";
+import {
+  orderedHandbookDocs,
+  toHandbookNavItems,
+} from "../lib/garden-docs-meta";
 import { pageAlternates } from "../lib/page-alternates";
+import { siteConfig } from "../site.config";
 
 export const metadata = {
-  title: "Garden",
-  description: "用 Markdown 写文章。推送之后，页面、搜索和 RSS 一起更新。",
+  title: "Garden 使用说明",
+  description:
+    "用 Markdown 写文章、随想与专栏。自动处理标题断行、宽图宽表展开、代码对比与 9 个内置组件。",
   alternates: pageAlternates("/garden"),
 };
 
-const jumps = [
-  ["#write-post", "写文章"],
-  ["#write-thought", "随想"],
-  ["#make-column", "专栏"],
-  ["#setup", "跑起来"],
-  ["#media", "视频和链接"],
-  ["#admin", "后台"],
-];
-
-const setupSteps = [
-  {
-    title: "创建站点",
-    body: (
-      <>
-        运行 <code>npx hd-garden init my-blog</code>。目录里留下 <code>content/</code> 和 <code>site.config.yaml</code>。仓库名叫 <code>&lt;owner&gt;.github.io</code> 时，地址最直接。
-      </>
-    ),
-  },
-  {
-    title: "在本地看",
-    command: "make dev",
-    body: "第一次会安装依赖。然后打开终端里的地址。",
-  },
-  {
-    title: "换成你的内容",
-    files: [
-      ["site.config.yaml", "站名、作者、各页标题"],
-      ["content/posts/", "长文和附件"],
-      ["content/thoughts/", "随想"],
-      ["content/columns.yaml", "专栏和阅读顺序"],
-    ],
-  },
-  {
-    title: "发布",
-    command: "make update",
-    body: "先检查，再提交并推送。main 更新后，网站、搜索和 RSS 会一起更新。",
-  },
-];
-
 export default function GardenPage() {
-  return (
-    <main className="page-shell garden-page">
-      <PageIntro title={siteConfig.pages.garden.title} subtitle={siteConfig.pages.garden.subtitle}>
-        <p className="garden-lede">
-          文章放在你自己的仓库里。你改文件，网站跟着更新。
-        </p>
-        <div className="garden-actions">
-          <a
-            className="garden-primary-link"
-            href="https://github.com/hedon954/garden"
-            target="_blank"
-            rel="noreferrer"
-          >
-            <GithubLogo size={18} weight="fill" />
-            查看源码
-            <ArrowUpRight size={16} />
-          </a>
-          <a className="inline-cta" href="#setup">
-            在本地跑起来
-            <ArrowRight size={16} />
-          </a>
-        </div>
-      </PageIntro>
-
-      <nav className="garden-jumps" aria-label="本页">
-        {jumps.map(([href, label]) => (
-          <a key={href} href={href}>{label}</a>
-        ))}
-      </nav>
+  const navItems = toHandbookNavItems(gardenDocs);
+  const ordered = orderedHandbookDocs(gardenDocs);
+  const firstDoc = ordered[0] ?? null;
+  const content = gardenIndexDoc?.content ?? "";
+  const headings = extractHeadings(content);
+  const configuredTitle = siteConfig.pages.garden.title?.trim() || gardenIndexDoc?.title || "Garden 使用说明";
+  const configuredSubtitle = siteConfig.pages.garden.subtitle?.trim() || gardenIndexDoc?.description || "";
+  void GardenMediaGuide;
 
-      <GardenContentGuide />
+  return (
+    <main className="column-reading-page garden-doc-page">
+      <GardenDocsNav docs={navItems} currentPath="" />
 
-      <section className="garden-setup" id="setup" aria-labelledby="garden-setup-title">
-        <header className="garden-section-heading">
-          <h2 id="garden-setup-title">跑起来</h2>
-          <p>不需要数据库。换上你的名字和第一篇文章，推送即可。</p>
+      <article className="article-column garden-doc-article h-entry">
+        <header className="gdoc-article-head">
+          <div className="gdoc-eyebrow">
+            <span>Garden 使用说明</span>
+            <span aria-hidden="true">/</span>
+            <span>总览</span>
+          </div>
+          <ArticleTitle title={configuredTitle} />
+          {configuredSubtitle ? (
+            <p className="gdoc-article-deck p-summary">{configuredSubtitle}</p>
+          ) : null}
         </header>
 
-        <ol className="garden-steps">
-          {setupSteps.map((step, index) => (
-            <li key={step.title}>
-              <span>{index + 1}</span>
-              <div>
-                <h3>{step.title}</h3>
-                {"command" in step && step.command ? <pre><code>{step.command}</code></pre> : null}
-                {"files" in step && step.files ? (
-                  <dl>
-                    {step.files.map(([name, note]) => (
-                      <div key={name}>
-                        <dt>{name}</dt>
-                        <dd>{note}</dd>
-                      </div>
-                    ))}
-                  </dl>
-                ) : null}
-                {"body" in step && step.body ? <p>{step.body}</p> : null}
-              </div>
-            </li>
-          ))}
-        </ol>
+        <ArticleMeasure />
 
-        <div className="garden-setup-notes">
-          <p>
-            <strong>仓库可以是私有的。</strong>
-            公开仓库一种就够。想把草稿留在私有仓库时，用 <code>PAGES_REPOSITORY</code> 指向公开的页面仓库。两种都是 <code>make update</code>。
-          </p>
-          <p>
-            <strong>先看草稿。</strong>
-            <code>CONTENT_INCLUDE_DRAFTS=1 make dev</code> 会把草稿和还没到时间的文章也显示出来。
-          </p>
-          <p>
-            <strong>密钥不进仓库。</strong>
-            评论、统计和后台的密钥放在部署平台。
-          </p>
+        <div className="e-content">
+          <MarkdownArticle content={content} />
         </div>
-      </section>
 
-      <GardenMediaGuide />
+        <ArticleReferences references={gardenIndexDoc?.references} />
 
-      <section className="garden-after" aria-labelledby="garden-after-title">
-        <header className="garden-section-heading">
-          <h2 id="garden-after-title">推送之后</h2>
-        </header>
-        <p className="garden-after-lead">推送之后，网站公开更新。</p>
-        <div className="garden-after-copy">
-          <p>文章在你自己的仓库里。读者打开的是已经发布的页面。</p>
-          <p>一次更新会带上正文、目录、前后篇、搜索、RSS 和 sitemap。后台和评论都可以以后再加。</p>
-        </div>
-      </section>
+        {firstDoc ? (
+          <nav className="gdoc-pager" aria-label="说明书上下篇导航">
+            <Link href={gardenDocHref(firstDoc)} className="gdoc-pager-card is-next">
+              <span className="gdoc-pager-dir">
+                下一篇
+                <ArrowRight size={14} aria-hidden="true" />
+              </span>
+              <strong>{firstDoc.title}</strong>
+            </Link>
+          </nav>
+        ) : null}
+      </article>
 
-      <GardenAdminGuide />
+      <TableOfContents headings={headings} label="本页目录" />
     </main>
   );
 }

package/app/garden-modules.d.ts

@@ -48,6 +48,21 @@ declare module "@garden/generated-content" {
   export const posts: ContentEntry[];
   export const columns: ContentEntry[];
   export const thoughts: ContentEntry[];
+  export type GardenDocEntry = {
+    title: string;
+    slug: string;
+    path: string;
+    description?: string;
+    section?: string;
+    sectionTitle?: string;
+    order?: number;
+    readingTime?: string;
+    references?: { title: string; url?: string; domain?: string }[];
+    sourcePath: string;
+    content: string;
+  };
+  export const gardenDocs: GardenDocEntry[];
+  export const gardenIndexDoc: GardenDocEntry | null;
   export const a2WordCounts: Record<string, number>;
   export type LinkCardMeta = {
     title: string;

package/app/globals.css

@@ -4828,14 +4828,14 @@ html[data-theme="dark"] .search-footer {
 .garden-page,
 .admin-shell,
 .admin-access-page {
-  --garden-ink: #1d1d1f;
-  --garden-muted: #6e6e73;
-  --garden-stage: #f5f5f7;
-  --garden-link: #0071e3;
-  --garden-button: #1d1d1f;
-  --garden-button-text: #fff;
+  --garden-ink: var(--ink);
+  --garden-muted: var(--muted);
+  --garden-stage: var(--paper-deep);
+  --garden-link: var(--ink);
+  --garden-button: var(--ink);
+  --garden-button-text: var(--paper);
   color: var(--garden-ink);
-  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Noto Sans SC", sans-serif;
+  font-family: var(--sans);
 }
 
 :root[data-theme="dark"] .garden-page,
@@ -4844,9 +4844,9 @@ html[data-theme="dark"] .search-footer {
   --garden-ink: var(--ink);
   --garden-muted: var(--muted);
   --garden-stage: var(--paper-deep);
-  --garden-link: #8ab4f8;
-  --garden-button: #f5f5f7;
-  --garden-button-text: #1d1d1f;
+  --garden-link: var(--ink);
+  --garden-button: var(--ink);
+  --garden-button-text: var(--paper);
 }
 
 .garden-page pre,

package/app/lib/content.ts

@@ -1,9 +1,12 @@
 import { markdownPlugins } from "./markdown-plugins";
 import {
   columns,
+  gardenDocs,
+  gardenIndexDoc,
   posts,
   thoughts,
   type ContentEntry,
+  type GardenDocEntry,
   type MediaItem,
 } from "@garden/generated-content";
 import GithubSlugger from "github-slugger";
@@ -14,13 +17,14 @@ import { toString } from "mdast-util-to-string";
 import remarkParse from "remark-parse";
 import { unified } from "unified";
 import { visit } from "unist-util-visit";
-import { splitHeadingNumber } from "./heading-number";
+import { articleUsesHeadingNumbers, autoNumbersHeadings, splitHeadingNumber } from "./heading-number";
 import { siteHref } from "./site-href";
 
-export { columns, posts, thoughts };
-export type { ContentEntry, MediaItem };
+export { columns, gardenDocs, gardenIndexDoc, posts, thoughts };
+export type { ContentEntry, GardenDocEntry, MediaItem };
 
 export const postHref = (post: Pick<ContentEntry, "path">) => siteHref(`/blog/${post.path}`);
+export const gardenDocHref = (doc: Pick<GardenDocEntry, "path">) => siteHref(`/garden/${doc.path}`);
 export const columnEntryPath = (entry: Pick<ContentEntry, "column" | "path">) => {
   const prefix = entry.column ? `${entry.column}/` : "";
   return prefix && entry.path.startsWith(prefix) ? entry.path.slice(prefix.length) : entry.path;
@@ -51,10 +55,8 @@ export const formatDate = (value: string, withTime = false) => {
   }).format(date);
 };
 
-const NUMBERED_ARTICLE = /^#{2,3}[ \t]+\d/m;
-
 /** An article that already writes its own heading numbers is not auto-numbered. */
-export const articleUsesHeadingNumbers = (markdown: string) => NUMBERED_ARTICLE.test(markdown);
+export { articleUsesHeadingNumbers, autoNumbersHeadings };
 
 /**
  * Prototype render: an article with no `##` treats `###` as the top section.
@@ -76,11 +78,12 @@ export { splitHeadingNumber };
  * rehype-slug. Every heading depth advances the slugger so headings outside
  * the H2-H5 TOC range cannot shift the IDs shown in the directory.
  * `no` follows the prototype: keep an author-written number, otherwise
- * auto-number h2/h3 only when the article has no numbered headings.
+ * auto-number h2/h3 only when the article has no numbered headings and its
+ * front matter does not say `numbering: false`.
  */
-export const extractHeadings = (markdown: string) => {
+export const extractHeadings = (markdown: string, { numbering }: { numbering?: boolean } = {}) => {
   const slugger = new GithubSlugger();
-  const numbered = articleUsesHeadingNumbers(markdown);
+  const autoNumber = autoNumbersHeadings(markdown, numbering);
   const base = articleHeadingBase(markdown);
   const headings: Array<{ depth: number; text: string; id: string; no?: string }> = [];
   const tree = unified().use(remarkParse).use(markdownPlugins).parse(markdown);
@@ -101,7 +104,7 @@ export const extractHeadings = (markdown: string) => {
         text = split.text;
         if (level === 2) { h2 += 1; h3 = 0; }
         else h3 += 1;
-      } else if (!numbered) {
+      } else if (autoNumber) {
         if (level === 2) { h2 += 1; h3 = 0; no = String(h2); }
         else { h3 += 1; no = h2 ? `${h2}.${h3}` : String(h3); }
       }
@@ -129,6 +132,9 @@ export const findPost = (path: string): ContentEntry | undefined =>
 export const findThought = (slug: string): ContentEntry | undefined =>
   thoughts.find((thought) => thought.slug === slug);
 
+export const findGardenDoc = (path: string): GardenDocEntry | undefined =>
+  gardenDocs.find((doc) => doc.path === path);
+
 export const findColumnEntry = (
   column: string,
   path: string,

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

@@ -0,0 +1,83 @@
+export type GardenDocNavItem = {
+  path: string;
+  title: string;
+  description?: string;
+  section?: string;
+  order?: number;
+};
+
+export type HandbookSectionMeta = {
+  id: string;
+  title: string;
+  note?: string;
+};
+
+export const HANDBOOK_SECTIONS: HandbookSectionMeta[] = [
+  { id: "getting-started", title: "快速上手", note: "建站、配置与发布" },
+  { id: "writing-and-reading", title: "写作与排版", note: "Markdown 与阅读版面" },
+  { id: "components", title: "内置组件", note: "garden <name>" },
+  { id: "workflow", title: "检查与补全", note: "语法检查与编辑器片段" },
+];
+
+export const COMPONENT_BADGE: Record<string, string> = {
+  "components/card": "card",
+  "components/stat": "stat",
+  "components/compare": "compare",
+  "components/timeline": "timeline",
+  "components/chart": "chart",
+  "components/figure": "figure",
+  "components/html": "html",
+  "components/interactive": "interactive",
+  "components/file": "file",
+};
+
+export const NAV_SHORT_TITLE: Record<string, string> = {
+  start: "快速开始",
+  config: "站点与专栏配置",
+  deploy: "发布到 GitHub Pages",
+  writing: "写文章与随想",
+  design: "阅读排版是怎么工作的",
+  components: "组件总览",
+  "components/card": "知识卡片",
+  "components/stat": "数字指标",
+  "components/compare": "并排对比",
+  "components/timeline": "时间线",
+  "components/chart": "条形图表",
+  "components/figure": "分区结构图",
+  "components/html": "嵌入网页片段",
+  "components/interactive": "可调公式与参数",
+  "components/file": "文件下载与预览",
+  workflow: "语法检查与快捷输入",
+};
+
+export function groupHandbookDocs<T extends GardenDocNavItem>(docs: T[]) {
+  const bySection = new Map<string, T[]>();
+  for (const section of HANDBOOK_SECTIONS) {
+    bySection.set(section.id, []);
+  }
+  for (const doc of docs) {
+    const key = doc.section && bySection.has(doc.section) ? doc.section : "getting-started";
+    bySection.get(key)!.push(doc);
+  }
+  for (const list of bySection.values()) {
+    list.sort((a, b) => (a.order ?? 999) - (b.order ?? 999) || a.path.localeCompare(b.path));
+  }
+  return HANDBOOK_SECTIONS.map((section) => ({
+    ...section,
+    items: bySection.get(section.id) ?? [],
+  })).filter((section) => section.items.length > 0);
+}
+
+export function orderedHandbookDocs<T extends GardenDocNavItem>(docs: T[]): T[] {
+  return groupHandbookDocs(docs).flatMap((section) => section.items);
+}
+
+export function toHandbookNavItems(docs: GardenDocNavItem[]): GardenDocNavItem[] {
+  return orderedHandbookDocs(docs).map((doc) => ({
+    path: doc.path,
+    title: doc.title,
+    description: doc.description,
+    section: doc.section,
+    order: doc.order,
+  }));
+}

package/app/lib/heading-number.ts

@@ -7,3 +7,16 @@ export const splitHeadingNumber = (text: string) => {
   const match = /^(\d+(?:\.\d+)*\.?)[ \t]+([\s\S]+)$/u.exec(text.trim());
   return match ? { no: match[1], text: match[2] } : null;
 };
+
+const NUMBERED_ARTICLE = /^#{2,3}[ \t]+\d/m;
+
+/** True when the article writes its own section numbers (`## 2. …`). */
+export const articleUsesHeadingNumbers = (markdown: string) => NUMBERED_ARTICLE.test(markdown);
+
+/**
+ * Whether h2/h3 get automatic numbers. Off when the author writes numbers, or
+ * when the front matter says `numbering: false`. Author-written numbers are
+ * always kept.
+ */
+export const autoNumbersHeadings = (markdown: string, numbering?: boolean) =>
+  numbering !== false && !articleUsesHeadingNumbers(markdown);