hd-garden 0.7.0 → 0.8.0

package/app/garden/[...slug]/page.tsx

@@ -1,33 +1,9 @@
-import Link from "next/link";
-import type { Metadata } from "next";
 import { notFound } from "next/navigation";
-import { ArrowLeft, ArrowRight } from "@phosphor-icons/react/ssr";
-import {
-  extractHeadings,
-  findGardenDoc,
-  gardenDocHref,
-  gardenDocs,
-} from "../../lib/content";
-import { FEED_ALTERNATES } from "../../lib/page-alternates";
-import { absoluteUrl, getSiteUrl } from "../../lib/site";
-import { siteHref } from "../../lib/site-href";
-import { ArticleMeasure } from "../../components/ArticleMeasure";
-import { ArticleReferences } from "../../components/ArticleReferences";
-import { ArticleTitle } from "../../components/ArticleTitle";
-import { MarkdownArticle } from "../../components/MarkdownArticle";
-import { TableOfContents } from "../../components/TableOfContents";
-import { GardenDocsNav } from "../../components/GardenDocsNav";
-import {
-  COMPONENT_BADGE,
-  HANDBOOK_SECTIONS,
-  orderedHandbookDocs,
-  toHandbookNavItems,
-} from "../../lib/garden-docs-meta";
-import {
-  isStaticPlaceholder,
-  STATIC_PLACEHOLDER,
-  staticParams,
-} from "../../../ui/garden/static-params.mjs";
+import { HandbookDoc, handbookDocMetadata } from "../../components/HandbookView";
+import { gardenDocs } from "../../lib/content";
+import { isStaticPlaceholder, STATIC_PLACEHOLDER, staticParams } from "../../../ui/garden/static-params.mjs";
+
+const find = (slug: string[]) => gardenDocs.find((doc) => doc.path === slug.join("/"));
 
 export function generateStaticParams() {
   return staticParams(
@@ -36,113 +12,17 @@ export function generateStaticParams() {
   );
 }
 
-export async function generateMetadata({
-  params,
-}: {
-  params: Promise<{ slug: string[] }>;
-}) {
+export async function generateMetadata({ params }: { params: Promise<{ slug: string[] }> }) {
   const { slug } = await params;
-  const doc = findGardenDoc(slug.join("/"));
-  if (!doc) return {};
-  const baseUrl = await getSiteUrl();
-  const pathname = gardenDocHref(doc);
-  return {
-    title: `${doc.title} · Garden 使用说明`,
-    description: doc.description,
-    alternates: { canonical: pathname, types: FEED_ALTERNATES },
-    openGraph: {
-      type: "article",
-      url: absoluteUrl(pathname, baseUrl),
-      title: `${doc.title} · Garden 使用说明`,
-      description: doc.description,
-    },
-  } satisfies Metadata;
+  return handbookDocMetadata("zh", find(slug));
 }
 
-export default async function GardenDocPage({
-  params,
-}: {
-  params: Promise<{ slug: string[] }>;
-}) {
+export default async function GardenDocPage({ params }: { params: Promise<{ slug: string[] }> }) {
   const { slug } = await params;
-  const doc = findGardenDoc(slug.join("/"));
+  const doc = find(slug);
   if (!doc) {
     if (isStaticPlaceholder(slug)) return null;
     notFound();
   }
-
-  const ordered = orderedHandbookDocs(gardenDocs);
-  const navItems = toHandbookNavItems(gardenDocs);
-  const index = ordered.findIndex((item) => item.path === doc.path);
-  const prev = index > 0 ? ordered[index - 1] : null;
-  const next = index >= 0 && index < ordered.length - 1 ? ordered[index + 1] : null;
-  const headings = extractHeadings(doc.content);
-  const sectionMeta = HANDBOOK_SECTIONS.find((sec) => sec.id === doc.section);
-  const componentBadge = COMPONENT_BADGE[doc.path];
-
-  return (
-    <main className="column-reading-page garden-doc-page">
-      <GardenDocsNav docs={navItems} currentPath={doc.path} />
-
-      <article className="article-column garden-doc-article h-entry">
-        <header className="gdoc-article-head">
-          <div className="gdoc-eyebrow">
-            <Link href={siteHref("/garden")} className="gdoc-eyebrow-root">
-              Garden 使用说明
-            </Link>
-            <span aria-hidden="true">/</span>
-            <span>{sectionMeta?.title ?? doc.sectionTitle ?? "指南"}</span>
-            {componentBadge ? (
-              <>
-                <code className="gdoc-eyebrow-fence">{`garden ${componentBadge}`}</code>
-              </>
-            ) : null}
-          </div>
-          <ArticleTitle title={doc.title} />
-          {doc.description ? (
-            <p className="gdoc-article-deck p-summary">{doc.description}</p>
-          ) : null}
-        </header>
-
-        <ArticleMeasure />
-
-        <div className="e-content">
-          <MarkdownArticle content={doc.content} />
-        </div>
-
-        <ArticleReferences references={doc.references} />
-
-        <nav className="gdoc-pager" aria-label="说明书上下篇导航">
-          {prev ? (
-            <Link href={gardenDocHref(prev)} className="gdoc-pager-card is-prev">
-              <span className="gdoc-pager-dir">
-                <ArrowLeft size={14} aria-hidden="true" />
-                上一篇
-              </span>
-              <strong>{prev.title}</strong>
-            </Link>
-          ) : (
-            <Link href={siteHref("/garden")} className="gdoc-pager-card is-prev">
-              <span className="gdoc-pager-dir">
-                <ArrowLeft size={14} aria-hidden="true" />
-                返回总览
-              </span>
-              <strong>Garden 使用说明首页</strong>
-            </Link>
-          )}
-          {next ? (
-            <Link href={gardenDocHref(next)} className="gdoc-pager-card is-next">
-              <span className="gdoc-pager-dir">
-                下一篇
-                <ArrowRight size={14} aria-hidden="true" />
-              </span>
-              <strong>{next.title}</strong>
-            </Link>
-          ) : null}
-        </nav>
-      </article>
-
-      <TableOfContents headings={headings} label="本页目录" />
-    </main>
-  );
+  return <HandbookDoc lang="zh" doc={doc} />;
 }

package/app/garden/en/[...slug]/page.tsx

@@ -0,0 +1,28 @@
+import { notFound } from "next/navigation";
+import { HandbookDoc, handbookDocMetadata } from "../../../components/HandbookView";
+import { gardenDocsEn } from "../../../lib/content";
+import { isStaticPlaceholder, STATIC_PLACEHOLDER, staticParams } from "../../../../ui/garden/static-params.mjs";
+
+const find = (slug: string[]) => gardenDocsEn.find((doc) => doc.path === slug.join("/"));
+
+export function generateStaticParams() {
+  return staticParams(
+    gardenDocsEn.map((doc) => ({ slug: doc.path.split("/") })),
+    { slug: [STATIC_PLACEHOLDER] },
+  );
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string[] }> }) {
+  const { slug } = await params;
+  return handbookDocMetadata("en", find(slug));
+}
+
+export default async function GardenEnDocPage({ params }: { params: Promise<{ slug: string[] }> }) {
+  const { slug } = await params;
+  const doc = find(slug);
+  if (!doc) {
+    if (isStaticPlaceholder(slug)) return null;
+    notFound();
+  }
+  return <HandbookDoc lang="en" doc={doc} />;
+}

package/app/garden/en/page.tsx

@@ -0,0 +1,16 @@
+import { notFound } from "next/navigation";
+import { HandbookOverview, handbookLanguages } from "../../components/HandbookView";
+import { pageAlternates } from "../../lib/page-alternates";
+import { HANDBOOK_UI } from "../../lib/garden-docs-meta";
+import { gardenIndexDocEn } from "../../lib/content";
+
+export const metadata = {
+  title: HANDBOOK_UI.en.name,
+  description: gardenIndexDocEn?.description ?? "",
+  alternates: pageAlternates("/garden/en", handbookLanguages("en", "index")),
+};
+
+export default function GardenEnPage() {
+  if (!gardenIndexDocEn) notFound();
+  return <HandbookOverview lang="en" />;
+}

package/app/garden/page.tsx

@@ -1,81 +1,14 @@
-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 { 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 { HandbookOverview, handbookLanguages } from "../components/HandbookView";
 import { pageAlternates } from "../lib/page-alternates";
-import { siteConfig } from "../site.config";
+import { HANDBOOK_UI } from "../lib/garden-docs-meta";
+import { gardenIndexDoc } from "../lib/content";
 
 export const metadata = {
-  title: "Garden 使用说明",
-  description:
-    "用 Markdown 写文章、随想与专栏。自动处理标题断行、宽图宽表展开、代码对比与 9 个内置组件。",
-  alternates: pageAlternates("/garden"),
+  title: HANDBOOK_UI.zh.name,
+  description: gardenIndexDoc?.description ?? "",
+  alternates: pageAlternates("/garden", handbookLanguages("zh", "index")),
 };
 
 export default function GardenPage() {
-  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;
-
-  return (
-    <main className="column-reading-page garden-doc-page">
-      <GardenDocsNav docs={navItems} currentPath="" />
-
-      <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>
-
-        <ArticleMeasure />
-
-        <div className="e-content">
-          <MarkdownArticle content={content} />
-        </div>
-
-        <ArticleReferences references={gardenIndexDoc?.references} />
-
-        {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>
-
-      <TableOfContents headings={headings} label="本页目录" />
-    </main>
-  );
+  return <HandbookOverview lang="zh" />;
 }

package/app/garden-modules.d.ts

@@ -60,9 +60,12 @@ declare module "@garden/generated-content" {
     references?: { title: string; url?: string; domain?: string }[];
     sourcePath: string;
     content: string;
+    lang?: "zh" | "en";
   };
   export const gardenDocs: GardenDocEntry[];
   export const gardenIndexDoc: GardenDocEntry | null;
+  export const gardenDocsEn: GardenDocEntry[];
+  export const gardenIndexDocEn: GardenDocEntry | null;
   export const a2WordCounts: Record<string, number>;
   export type LinkCardMeta = {
     title: string;

package/app/layout.tsx

@@ -13,6 +13,7 @@ import {
 import { githubUrl, siteConfig } from "./site.config";
 import { brand } from "@garden/site-config";
 import { FEED_ALTERNATES } from "./lib/page-alternates";
+import { htmlLang, siteLang } from "./lib/i18n";
 
 export async function generateMetadata(): Promise<Metadata> {
   const siteUrl = await getSiteUrl();
@@ -75,7 +76,7 @@ export default function RootLayout({
     "https://plausible.io/js/script.js";
 
   return (
-    <html lang="zh-CN" suppressHydrationWarning>
+    <html lang={htmlLang(siteLang)} suppressHydrationWarning>
       <head>
         <script
           dangerouslySetInnerHTML={{
@@ -93,9 +94,6 @@ export default function RootLayout({
         )}
       </head>
       <body>
-        <a className="skip-link" href="#main-content">
-          跳到正文
-        </a>
         <SiteChrome>{children}</SiteChrome>
       </body>
     </html>

package/app/lib/content.ts

@@ -3,6 +3,8 @@ import {
   columns,
   gardenDocs,
   gardenIndexDoc,
+  gardenDocsEn,
+  gardenIndexDocEn,
   posts,
   thoughts,
   type ContentEntry,
@@ -19,8 +21,9 @@ import { unified } from "unified";
 import { visit } from "unist-util-visit";
 import { articleUsesHeadingNumbers, autoNumbersHeadings, splitHeadingNumber } from "./heading-number";
 import { siteHref } from "./site-href";
+import { ui } from "./i18n";
 
-export { columns, gardenDocs, gardenIndexDoc, posts, thoughts };
+export { columns, gardenDocs, gardenDocsEn, gardenIndexDoc, gardenIndexDocEn, posts, thoughts };
 export type { ContentEntry, GardenDocEntry, MediaItem };
 
 export const postHref = (post: Pick<ContentEntry, "path">) => siteHref(`/blog/${post.path}`);
@@ -45,7 +48,7 @@ export const formatDate = (value: string, withTime = false) => {
   const canonical = canonicalSiteDate(value) ?? value;
   const date = new Date(canonical);
   if (Number.isNaN(date.getTime())) return value;
-  return new Intl.DateTimeFormat("zh-CN", {
+  return new Intl.DateTimeFormat(ui().dateLocale, {
     timeZone: "Asia/Shanghai",
     year: "numeric",
     month: "2-digit",
@@ -135,6 +138,13 @@ export const findThought = (slug: string): ContentEntry | undefined =>
 export const findGardenDoc = (path: string): GardenDocEntry | undefined =>
   gardenDocs.find((doc) => doc.path === path);
 
+/** Handbook pages and the overview of one language. */
+export const handbookDocs = (lang: "zh" | "en") => (lang === "en" ? gardenDocsEn : gardenDocs);
+export const handbookIndexDoc = (lang: "zh" | "en") => (lang === "en" ? gardenIndexDocEn : gardenIndexDoc);
+/** Whether a handbook page (or "index") exists in a language. */
+export const hasHandbookPage = (lang: "zh" | "en", path: string) =>
+  path === "index" || path === "" ? Boolean(handbookIndexDoc(lang)) : handbookDocs(lang).some((doc) => doc.path === path);
+
 export const findColumnEntry = (
   column: string,
   path: string,

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

@@ -4,19 +4,72 @@ export type GardenDocNavItem = {
   description?: string;
   section?: string;
   order?: number;
+  navTitle?: string;
 };
 
+export type HandbookLang = "zh" | "en";
+
 export type HandbookSectionMeta = {
   id: string;
   title: string;
-  note?: string;
+  /** English sidebar group heading; falls back to the Chinese one until translated. */
+  titleEn?: string;
 };
 
+/** Where each language of the handbook lives. English mirrors the Chinese paths. */
+export const handbookBase = (lang: HandbookLang) => (lang === "en" ? "/garden/en" : "/garden");
+export const handbookPath = (lang: HandbookLang, docPath = "") =>
+  docPath && docPath !== "index" ? `${handbookBase(lang)}/${docPath}` : handbookBase(lang);
+export const sectionTitle = (section: HandbookSectionMeta | undefined, lang: HandbookLang) =>
+  section ? (lang === "en" ? section.titleEn ?? section.title : section.title) : undefined;
+/** The handbook remembers the reader's choice under this localStorage key. */
+export const HANDBOOK_LANG_KEY = "garden-handbook-lang";
+
+/** Handbook chrome labels. Page text lives in docs/handbook and docs/handbook/en. */
+export const HANDBOOK_UI = {
+  zh: {
+    name: "Garden 使用说明",
+    overview: "总览",
+    overviewHint: "总览与快速入口",
+    guide: "指南",
+    pager: "说明书上下篇导航",
+    prev: "上一篇",
+    next: "下一篇",
+    backToOverview: "返回总览",
+    overviewDocTitle: "Garden 使用说明首页",
+    toc: "本页目录",
+    sidebar: "Garden 使用说明目录",
+    chapters: "章节导航",
+    closeSidebar: "关闭说明目录",
+    openSidebar: "打开说明目录",
+    sidebarShort: "说明目录",
+    mobileBar: "说明书目录栏",
+  },
+  en: {
+    name: "Garden Handbook",
+    overview: "Overview",
+    overviewHint: "Overview and quick links",
+    guide: "Guide",
+    pager: "Handbook pages",
+    prev: "Previous",
+    next: "Next",
+    backToOverview: "Back to overview",
+    overviewDocTitle: "Garden Handbook home",
+    toc: "On this page",
+    sidebar: "Garden Handbook contents",
+    chapters: "Chapters",
+    closeSidebar: "Close contents",
+    openSidebar: "Open contents",
+    sidebarShort: "Contents",
+    mobileBar: "Handbook contents bar",
+  },
+} as const;
+
 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: "语法检查与编辑器片段" },
+  { id: "getting-started", title: "快速上手", titleEn: "Getting Started" },
+  { id: "writing-and-reading", title: "写作与排版", titleEn: "Writing & Layout" },
+  { id: "components", title: "内置组件", titleEn: "Built-in Components" },
+  { id: "workflow", title: "检查与补全", titleEn: "Checks & Shortcuts" },
 ];
 
 export const COMPONENT_BADGE: Record<string, string> = {
@@ -33,6 +86,7 @@ export const COMPONENT_BADGE: Record<string, string> = {
 
 export const NAV_SHORT_TITLE: Record<string, string> = {
   start: "快速开始",
+  "ai-writing": "用 AI 写作",
   config: "站点与专栏配置",
   deploy: "发布到 GitHub Pages",
   writing: "写文章与随想",
@@ -79,5 +133,6 @@ export function toHandbookNavItems(docs: GardenDocNavItem[]): GardenDocNavItem[]
     description: doc.description,
     section: doc.section,
     order: doc.order,
+    ...(doc.navTitle ? { navTitle: doc.navTitle } : {}),
   }));
 }

package/app/lib/handbook-path.ts

@@ -0,0 +1,11 @@
+/**
+ * The same handbook page in the other language, worked out from the address
+ * in the browser so a basePath (/repo/garden/...) stays in front.
+ * /garden/x/ ⇄ /garden/en/x/. Returns null outside the handbook.
+ */
+export function swapHandbookLang(pathname: string, target: "zh" | "en"): string | null {
+  const match = /^(.*?\/garden)(\/en)?(\/.*)?$/u.exec(pathname);
+  if (!match) return null;
+  const rest = match[3] ?? "/";
+  return target === "en" ? `${match[1]}/en${rest}` : `${match[1]}${rest}`;
+}