hd-garden 0.8.0 → 0.8.2

package/app/lib/a2-meta.ts

@@ -1,4 +1,7 @@
 const shanghaiOffsetMs = 8 * 60 * 60 * 1000;
+const EN_MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
+
+export type DateLang = "zh" | "en";
 
 function shanghaiDate(value: string) {
   const date = new Date(value);
@@ -6,23 +9,43 @@ function shanghaiDate(value: string) {
   return new Date(date.getTime() + shanghaiOffsetMs);
 }
 
-/** Calendar date in Asia/Shanghai, the zone the demo uses for 「2026 年 9 月 18 日」. */
-export function demoDateLabel(value: string) {
+/** Calendar date in Asia/Shanghai, formatted for the active site language. */
+export function demoDateLabel(value: string, lang: DateLang = "zh") {
   const date = shanghaiDate(value);
   if (!date) return value;
+  if (lang === "en") {
+    return `${EN_MONTHS[date.getUTCMonth()]} ${date.getUTCDate()}, ${date.getUTCFullYear()}`;
+  }
   return `${date.getUTCFullYear()} 年 ${date.getUTCMonth() + 1} 月 ${date.getUTCDate()} 日`;
 }
 
 /** Home list label. The current Shanghai year drops the year so the column stays narrow. */
-export function homeListDate(value: string, now = new Date()) {
+export function homeListDate(value: string, now = new Date(), lang: "zh" | "en" = "zh") {
   const date = shanghaiDate(value);
   if (!date) return value;
   const today = shanghaiDate(now.toISOString());
+  const sameYear = Boolean(today && date.getUTCFullYear() === today.getUTCFullYear());
+  if (lang === "en") {
+    return new Intl.DateTimeFormat("en-US", {
+      timeZone: "UTC",
+      month: "short",
+      day: "numeric",
+      ...(sameYear ? {} : { year: "numeric" }),
+    }).format(date);
+  }
   const monthDay = `${date.getUTCMonth() + 1} 月 ${date.getUTCDate()} 日`;
   if (today && date.getUTCFullYear() === today.getUTCFullYear()) return monthDay;
   return `${date.getUTCFullYear()} 年 ${monthDay}`;
 }
 
+/** Full list date: 「2025 年 7 月 21 日」 or "Jul 21, 2025". */
+export function fullListDate(value: string, lang: "zh" | "en" = "zh") {
+  if (lang !== "en") return demoDateLabel(value);
+  const date = shanghaiDate(value);
+  if (!date) return value;
+  return new Intl.DateTimeFormat("en-US", { timeZone: "UTC", year: "numeric", month: "short", day: "numeric" }).format(date);
+}
+
 export function demoDateTime(value: string) {
   const date = shanghaiDate(value);
   if (!date) return value.slice(0, 10);

package/app/lib/content.ts

@@ -21,7 +21,7 @@ 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";
+import { siteLang, ui } from "./i18n";
 
 export { columns, gardenDocs, gardenDocsEn, gardenIndexDoc, gardenIndexDocEn, posts, thoughts };
 export type { ContentEntry, GardenDocEntry, MediaItem };
@@ -44,7 +44,7 @@ export const columnIndexHref = (slug: string) => siteHref(`/columns/#${slug}`);
 export const thoughtHref = (slug: string) => siteHref(`/thoughts/${slug}`);
 
 export const formatDate = (value: string, withTime = false) => {
-  if (!withTime) return demoDateLabel(value);
+  if (!withTime) return demoDateLabel(value, siteLang);
   const canonical = canonicalSiteDate(value) ?? value;
   const date = new Date(canonical);
   if (Number.isNaN(date.getTime())) return value;

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

@@ -70,8 +70,13 @@ export const HANDBOOK_SECTIONS: HandbookSectionMeta[] = [
   { id: "writing-and-reading", title: "写作与排版", titleEn: "Writing & Layout" },
   { id: "components", title: "内置组件", titleEn: "Built-in Components" },
   { id: "workflow", title: "检查与补全", titleEn: "Checks & Shortcuts" },
+  { id: "reference", title: "组件参考", titleEn: "Component reference" },
 ];
 
+/** Component reference pages: one per component, all fields and error codes. */
+export const REFERENCE_SECTION = "reference";
+export const isReferencePath = (docPath: string) => docPath === REFERENCE_SECTION || docPath.startsWith(`${REFERENCE_SECTION}/`);
+
 export const COMPONENT_BADGE: Record<string, string> = {
   "components/card": "card",
   "components/stat": "stat",
@@ -82,6 +87,21 @@ export const COMPONENT_BADGE: Record<string, string> = {
   "components/html": "html",
   "components/interactive": "interactive",
   "components/file": "file",
+  "components/relations": "relations",
+  "components/list": "list",
+  "components/choice": "choice",
+  "reference/card": "card",
+  "reference/stat": "stat",
+  "reference/compare": "compare",
+  "reference/timeline": "timeline",
+  "reference/chart": "chart",
+  "reference/figure": "figure",
+  "reference/html": "html",
+  "reference/interactive": "interactive",
+  "reference/file": "file",
+  "reference/relations": "relations",
+  "reference/list": "list",
+  "reference/choice": "choice",
 };
 
 export const NAV_SHORT_TITLE: Record<string, string> = {
@@ -101,7 +121,11 @@ export const NAV_SHORT_TITLE: Record<string, string> = {
   "components/html": "嵌入网页片段",
   "components/interactive": "可调公式与参数",
   "components/file": "文件下载与预览",
+  "components/relations": "关系图",
+  "components/list": "图标列表",
+  "components/choice": "选择卡",
   workflow: "语法检查与快捷输入",
+  reference: "总览",
 };
 
 export function groupHandbookDocs<T extends GardenDocNavItem>(docs: T[]) {

package/app/lib/github-id.mjs

@@ -0,0 +1,8 @@
+/** The template placeholder written by `garden init`; not a real GitHub account. */
+export const GITHUB_ID_PLACEHOLDER = "your-github-id";
+
+/** True when the configured GitHub id is a real account worth calling the GitHub API for. */
+export function hasRealGithubId(id) {
+  const value = String(id ?? "").trim();
+  return value !== "" && value.toLowerCase() !== GITHUB_ID_PLACEHOLDER;
+}

package/app/lib/handbook-switch.mjs

@@ -0,0 +1,12 @@
+/** Handbook page language from its path: /garden/en/... is English, the rest of /garden/ is Chinese. */
+export const handbookPageLang = (pathname) => (/\/garden\/en(\/|$)/u.test(String(pathname ?? "")) ? "en" : "zh");
+
+/** The 中 / EN switch always offers the other language: Chinese pages offer English, English pages offer Chinese. */
+export const handbookSwitchTarget = (pageLang) => (pageLang === "en" ? "zh" : "en");
+
+/** aria-label of the live link. */
+export const handbookSwitchLabel = (pageLang) => (handbookSwitchTarget(pageLang) === "en" ? "Read in English" : "Switch to Chinese");
+
+/** Tooltip while there is no counterpart link (built HTML, before hydration). */
+export const handbookSwitchTitle = (pageLang, siteLang) =>
+  pageLang === "en" ? "No Chinese version of this page yet" : siteLang === "en" ? "No English version of this page yet" : "这一页还没有英文版";

package/app/lib/i18n.ts

@@ -1,4 +1,9 @@
+import { siteLinks } from "@garden/site-config";
 import { siteConfig } from "../site.config";
+import {
+  inAppPath as resolveInAppPath,
+  isHandbookPath as resolveIsHandbookPath,
+} from "../../ui/garden/html-lang.mjs";
 
 /**
  * Framework chrome strings. The site language is chosen at build time with
@@ -7,12 +12,30 @@ import { siteConfig } from "../site.config";
  * their own language explicitly.
  */
 export type UiLang = "zh" | "en";
+export type SiteLang = UiLang;
 
 export const langOf = (locale: string | undefined): UiLang => (/^en/i.test(locale ?? "") ? "en" : "zh");
 export const siteLang: UiLang = langOf(siteConfig.locale);
 export const htmlLang = (lang: UiLang) => (lang === "en" ? "en" : "zh-CN");
 
 const zh = {
+  homeAbout: "关于我",
+  homeRss: "RSS 订阅",
+  homeLatest: "最新文章",
+  homeRecent: "最近更新",
+  homeAllPosts: (n: number) => `全部 ${n} 篇`,
+  homePinned: "置顶",
+  homeColumns: "专栏",
+  homeAllColumns: "全部专栏",
+  columnCount: (n: number, status: string) => `${n} 篇，${status}`,
+  columnDefault: "持续更新",
+  columnOngoing: "连载中",
+  columnCompleted: "已完结",
+  columnReadingList: (n: number, status: string) => `阅读清单，${n} 篇，${status}`,
+  columnSideCount: (n: number, status: string) => `${n} 篇 · ${status}`,
+  columnCoverAlt: (title: string | undefined) => `${title} 封面`,
+  columnFallbackDesc: "按顺序组织的专题文章系列。",
+  columnNewestFirst: (title: string | undefined) => `${title}，从新到旧`,
   toc: "本篇目录",
   tocShort: "目录",
   tocPage: "本页目录",
@@ -57,6 +80,8 @@ const zh = {
   fullscreen: "全屏",
   exitFullscreen: "退出全屏",
   chart: "图表",
+  relations: "关系图",
+  relationsLegend: "连线说明",
   dataTable: "查看数据表",
   item: "项目",
   value: "数值",
@@ -107,9 +132,193 @@ const zh = {
   escToClose: "关闭",
   noResults: (q: string) => (q ? `没有找到和「${q}」相关的文章` : "还没有可以搜索的内容"),
   navLabels: { "/blog/": "文章", "/thoughts/": "随想", "/columns/": "专栏", "/tags/": "标签", "/about/": "关于" } as Record<string, string>,
+  // Home page
+  homeLatestBadge: "最新文章",
+  homeRecentHeading: "最近更新",
+  homeAllPostsCount: (n: number) => `全部 ${n} 篇`,
+  homePinnedHeading: "置顶",
+  homeColumnsHeading: "专栏",
+  homeColumnCountStatus: (count: number, status: string) => `${count} 篇，${status}`,
+  columnDefaultStatus: "持续更新",
+  // Blog archive
+  blogHeading: "文章",
+  blogDeck: (n: number) => `阶段性的完整沉淀，关于工程、架构与技术思考。共 ${n} 篇，按年份归档。`,
+  unknownYear: "未知",
+  tagFilterLabel: "按标签筛选",
+  tagCollapse: "收起",
+  tagExpandAll: (n: number) => `展开全部 ${n} 个标签`,
+  tagClear: "清除",
+  densityLabel: "列表密度",
+  densityDetailed: "摘要",
+  densityCompact: "紧凑",
+  yearPostCount: (n: number) => `${n} 篇`,
+  pinnedBadge: "置顶",
+  tagEmptyMatch: "没有同时带这些标签的文章。",
+  tagDropLast: (tag: string) => `去掉「${tag}」`,
+  browseAllPosts: "看全部文章",
+  railJumpByYear: "按年份跳转",
+  railByYear: "按年份",
+  railColumns: "专栏",
+  // Post & column entry pages
+  permalinkLabel: (title: string) => `${title} 永久链接`,
+  updatedOn: (date: string) => `更新于 ${date}`,
+  originalLink: "原文 ↗",
+  coverLabel: (title: string) => `${title} 封面`,
+  referencesHeading: "参考",
+  articleTagsLabel: "标签",
+  allColumnsBack: "所有专栏",
+  seriesEyebrow: "主题专栏",
+  seriesCountStatus: (count: number, status: string) => `${count} 篇 · ${status}`,
+  // Columns index
+  columnsFallbackTitle: "专栏",
+  columnsMeta: (count: number, status: string) => `阅读清单，${count} 篇，${status}`,
+  columnsFallbackDesc: "按顺序组织的专题文章系列。",
+  columnsOrderLabel: (title: string) => `${title}，从新到旧`,
+  // Tags page
+  tagsTitle: "标签",
+  tagsDescription: "全部标签。",
+  tagsDeck: (n: number) => `${n} 个标签，按文章数排序。点一个标签，查看带这个标签的文章。`,
+  tagsIndexLabel: "全部标签",
+  tagsEmpty: "还没有标签。",
+  // Thoughts
+  thoughtsEyebrow: "THOUGHTS / 随想",
+  backToThoughts: "返回随想",
+  thoughtMixedLabel: (n: number) => `混合记录 · ${n} 个附件`,
+  thoughtImageLabel: "一张照片",
+  thoughtAudioLabel: "一段声音",
+  thoughtVideoLabel: "一段影像",
+  thoughtLinkLabel: "一个链接",
+  thoughtTextLabel: "随想",
+  thoughtGalleryLabel: (n: number) => `${n} 张照片`,
+  thoughtPhotoAlt: (title: string, idx: number) => `${title} · 照片 ${idx}`,
+  thoughtNowPlaying: (title: string) => `当前播放 · ${title}`,
+  audioFallback: "你的浏览器不支持音频播放。",
+  thoughtPermalinkShort: "永久链接",
+  // About & GitHub profile
+  aboutEyebrow: "关于",
+  aboutFallbackHeading: "关于",
+  aboutFallbackParagraphs: [
+    "一名工程师。平时写代码，也把想清楚的问题记下来。",
+    "这里放文章、随想和专栏。",
+  ] as string[],
+  aboutFocusHeading: "现在关注",
+  aboutFallbackFocus: ["软件", "笔记", "日常"] as string[],
+  aboutFallbackCta: "浏览博文",
+  githubProfileAria: "GitHub 资料",
+  githubAvatarAlt: (login: string) => `${login} 的 GitHub 头像`,
+  githubOverviewPrefix: "GitHub 公开资料",
+  githubSyncSynced: "本次访问已同步",
+  githubSyncSnapshot: "暂用发布时快照",
+  githubSyncSyncing: "正在同步当前资料",
+  githubViewProfile: "查看 GitHub",
+  githubMetricRepos: "公开仓库",
+  githubMetricCommits: "近 30 天 commits",
+  githubPinnedEyebrow: "PINNED / 置顶仓库",
+  githubPinnedHeading: "正在做的项目",
+  githubPinnedFallbackDesc: "查看这个公开仓库的代码与最近更新。",
+  githubPinnedEmpty: "配置 GitHub Token 或 author.githubPinned 后，这里会展示置顶仓库。",
+  githubContribEyebrow: "CONTRIBUTIONS / 贡献",
+  githubContribHeading: "过去一年的公开贡献",
+  githubContribCount: (n: number) => `${n} 次贡献`,
+  githubContribNeedToken: "需要 GitHub Token",
+  githubContribAria: (n: number) => `过去一年 ${n} 次公开贡献`,
+  githubContribDayTitle: (date: string, n: number) => `${date} · ${n} 次贡献`,
+  githubContribDayAria: (date: string, n: number) => `${date}，${n} 次贡献`,
+  githubContribEmpty: "正式发布时会使用工作流的只读令牌生成贡献热点图。",
+  githubActivityEyebrow: "CONTRIBUTION ACTIVITY / 最近活动",
+  githubActivityHeading: "最近在 GitHub 上做了什么",
+  githubActivityEmpty: "GitHub 暂时没有返回最近的公开贡献活动。",
+  githubEventPush: "推送了代码",
+  githubEventPrClosed: "完成了 Pull Request",
+  githubEventPrOpen: "提交了 Pull Request",
+  githubEventIssueClosed: "关闭了 Issue",
+  githubEventIssueOpen: "参与了 Issue",
+  githubEventCreateRepo: "创建了仓库",
+  githubEventCreateTag: "创建了标签",
+  githubEventCreateBranch: "创建了分支",
+  githubEventRelease: "发布了新版本",
+  // Comments & Webmentions
+  commentsSummaryReady: "评论由 GitHub Discussions 保存和管理。",
+  commentsSummaryUnconfigured: "评论还没开放。配好下面四项后，这里才会出现评论框。",
+  commentsGiscusGuideUrl: "https://giscus.app/zh-CN",
+  commentsSetupBefore: "打开",
+  commentsSetupMiddle: "，安装到一个已开启 Discussions 的公开仓库，把仓库、仓库 ID、分类、分类 ID 写入 ",
+  commentsSetupAnd: " 和 GitHub Actions Variables：",
+  commentsSetupJoin: "、",
+  commentsSetupEnd: "。",
+  giscusLang: "zh-CN",
+  webmentionIdleNote: "接收与展示代码已经就绪，注册正式域名后即可开始收集回应。",
+  webmentionLoading: "正在读取开放网络回应…",
+  webmentionUnavailable: "暂时无法读取回应，稍后会自动恢复。",
+  webmentionEmpty: "还没有站外回应。任何链接到这篇文章的网站都可以向它发送 Webmention。",
+  webmentionReactionCount: (n: number) => `${n} 个喜欢、转发或收藏`,
+  webmentionRespondersLabel: "回应者",
+  webmentionViewResponse: "查看站外回应",
+  webmentionAuthorFallback: "开放网络访客",
+  webmentionViewOriginal: "查看原文",
+  // Empty states, embeds, widgets, UI blocks
+  emptyPostsEyebrow: "暂无博文",
+  emptyPostsTitle: "暂无博文。",
+  emptyPostsDesc: "文章会按时间排在这里。",
+  emptyPostsCta: "返回首页",
+  emptyThoughtsEyebrow: "暂无随想",
+  emptyThoughtsTitle: "暂无随想。",
+  emptyThoughtsDesc: "短笔记和链接会在这里。",
+  emptyThoughtsCta: "先读博文",
+  emptyColumnsEyebrow: "暂无专栏",
+  emptyColumnsTitle: "暂无专栏。",
+  emptyColumnsDesc: "一组文章会按顺序列在这里。",
+  emptyColumnsCta: "浏览全部博文",
+  embedProviderWechat: "微信公众号",
+  embedProviderWeb: "网页摘要",
+  embedParseError: "无法解析这个嵌入块，请检查 URL 与 YAML 格式。",
+  embedFrameTitle: (label: string) => `${label} 嵌入内容`,
+  embedOpenOriginal: "在原网站打开",
+  embedFallbackTitle: "打开这条外部内容",
+  embedFallbackNoScript: "平台不提供稳定的无脚本嵌入，Garden 会保留清晰、可访问的原文入口。",
+  embedFallbackWeb: "查看原网页中的完整内容与上下文。",
+  widgetParseError: "无法解析这个嵌入块。请在与 Markdown 同名的目录里放一份 .html 或 .pdf，并在围栏中写 src 与 caption。",
+  widgetOpenPage: "打开页面",
+  widgetOpenPdf: "打开 PDF",
+  widgetPageKind: "页面",
+  widgetCollapse: "收起",
+  widgetExpand: "展开",
+  uiBlockCorrupt: "这块交互的数据损坏了，请重新运行 garden sync。",
+  // Admin static notice & metadata
+  staticAdminHeading: "后台在另一个地址。",
+  staticAdminBody: "公开博客上看不到这一页。写随想和改交互，去单独部署的后台。",
+  staticAdminRootBody: "这个页面是公开博客。写随想、上传和转发，去后台。",
+  staticAdminOpen: "打开后台",
+  staticAdminNoUrl: "还没有填写后台地址。",
+  staticAdminBack: "返回公开博客",
+  adminTitleMain: "内容管理",
+  adminTitleUi: "写作台",
+  adminTitleBlocks: "交互块",
+  adminTitleCatalog: "组件清单",
+  adminTitleEvals: "模型自检",
+  adminTitlePreview: "草稿预览",
+  a2IndexTitle: "A2 对照",
+  a2IndexDeck: "对照参考文章的版式。正文没有改字。",
 };
 
 const en: typeof zh = {
+  homeAbout: "About",
+  homeRss: "RSS",
+  homeLatest: "Latest",
+  homeRecent: "Recent posts",
+  homeAllPosts: (n: number) => `All ${n} ${n === 1 ? "post" : "posts"}`,
+  homePinned: "Pinned",
+  homeColumns: "Columns",
+  homeAllColumns: "All columns",
+  columnCount: (n: number, status: string) => `${n} ${n === 1 ? "post" : "posts"} · ${status}`,
+  columnDefault: "Active",
+  columnOngoing: "Ongoing",
+  columnCompleted: "Completed",
+  columnReadingList: (n: number, status: string) => `Reading list · ${n} ${n === 1 ? "post" : "posts"} · ${status}`,
+  columnSideCount: (n: number, status: string) => `${n} ${n === 1 ? "post" : "posts"} · ${status}`,
+  columnCoverAlt: (title: string | undefined) => `${title} cover`,
+  columnFallbackDesc: "A series of posts in reading order.",
+  columnNewestFirst: (title: string | undefined) => `${title}, newest first`,
   toc: "Contents",
   tocShort: "Contents",
   tocPage: "On this page",
@@ -154,6 +363,8 @@ const en: typeof zh = {
   fullscreen: "Full screen",
   exitFullscreen: "Exit full screen",
   chart: "Chart",
+  relations: "Relationship diagram",
+  relationsLegend: "Link labels",
   dataTable: "Show data table",
   item: "Item",
   value: "Value",
@@ -204,19 +415,207 @@ const en: typeof zh = {
   escToClose: "to close",
   noResults: (q: string) => (q ? `No posts match “${q}”` : "Nothing to search yet"),
   navLabels: { "/blog/": "Posts", "/thoughts/": "Thoughts", "/columns/": "Columns", "/tags/": "Tags", "/about/": "About" },
+  // Home page
+  homeLatestBadge: "Latest post",
+  homeRecentHeading: "Recent updates",
+  homeAllPostsCount: (n: number) => `All ${n} ${n === 1 ? "post" : "posts"}`,
+  homePinnedHeading: "Pinned",
+  homeColumnsHeading: "Columns",
+  homeColumnCountStatus: (count: number, status: string) => `${count} ${count === 1 ? "post" : "posts"}, ${status}`,
+  columnDefaultStatus: "Ongoing",
+  // Blog archive
+  blogHeading: "Posts",
+  blogDeck: (n: number) => `Essays on engineering, architecture, and systems thinking. ${n} ${n === 1 ? "post" : "posts"}, archived by year.`,
+  unknownYear: "Unknown",
+  tagFilterLabel: "Filter by tag",
+  tagCollapse: "Show less",
+  tagExpandAll: (n: number) => `Show all ${n} tags`,
+  tagClear: "Clear",
+  densityLabel: "List density",
+  densityDetailed: "Detailed",
+  densityCompact: "Compact",
+  yearPostCount: (n: number) => `${n} ${n === 1 ? "post" : "posts"}`,
+  pinnedBadge: "Pinned",
+  tagEmptyMatch: "No posts match all of the selected tags.",
+  tagDropLast: (tag: string) => `Remove “${tag}”`,
+  browseAllPosts: "All posts",
+  railJumpByYear: "Jump by year",
+  railByYear: "By year",
+  railColumns: "Columns",
+  // Post & column entry pages
+  permalinkLabel: (title: string) => `Permanent link to ${title}`,
+  updatedOn: (date: string) => `Updated ${date}`,
+  originalLink: "Original ↗",
+  coverLabel: (title: string) => `${title} cover`,
+  referencesHeading: "References",
+  articleTagsLabel: "Tags",
+  allColumnsBack: "All columns",
+  seriesEyebrow: "Column",
+  seriesCountStatus: (count: number, status: string) => `${count} ${count === 1 ? "post" : "posts"} · ${status}`,
+  // Columns index
+  columnsFallbackTitle: "Columns",
+  columnsMeta: (count: number, status: string) => `Reading list · ${count} ${count === 1 ? "post" : "posts"} · ${status}`,
+  columnsFallbackDesc: "A series of posts organized in reading order.",
+  columnsOrderLabel: (title: string) => `${title}, newest to oldest`,
+  // Tags page
+  tagsTitle: "Tags",
+  tagsDescription: "All tags.",
+  tagsDeck: (n: number) => `${n} ${n === 1 ? "tag" : "tags"}, ordered by post count. Pick a tag to view matching posts.`,
+  tagsIndexLabel: "All tags",
+  tagsEmpty: "No tags yet.",
+  // Thoughts
+  thoughtsEyebrow: "THOUGHTS",
+  backToThoughts: "Back to thoughts",
+  thoughtMixedLabel: (n: number) => `Mixed note · ${n} ${n === 1 ? "attachment" : "attachments"}`,
+  thoughtImageLabel: "Photo",
+  thoughtAudioLabel: "Audio",
+  thoughtVideoLabel: "Video",
+  thoughtLinkLabel: "Link",
+  thoughtTextLabel: "Thought",
+  thoughtGalleryLabel: (n: number) => `${n} ${n === 1 ? "photo" : "photos"}`,
+  thoughtPhotoAlt: (title: string, idx: number) => `${title} · photo ${idx}`,
+  thoughtNowPlaying: (title: string) => `Now playing · ${title}`,
+  audioFallback: "Your browser does not support audio playback.",
+  thoughtPermalinkShort: "Permalink",
+  // About & GitHub profile
+  aboutEyebrow: "About",
+  aboutFallbackHeading: "About",
+  aboutFallbackParagraphs: [
+    "An engineer who writes code and writes down problems once they are clear.",
+    "This site holds posts, thoughts, and columns.",
+  ],
+  aboutFocusHeading: "Current focus",
+  aboutFallbackFocus: ["Software", "Notes", "Daily work"],
+  aboutFallbackCta: "Browse posts",
+  githubProfileAria: "GitHub profile",
+  githubAvatarAlt: (login: string) => `${login}'s GitHub avatar`,
+  githubOverviewPrefix: "GitHub public profile",
+  githubSyncSynced: "Synced on this visit",
+  githubSyncSnapshot: "Using build snapshot",
+  githubSyncSyncing: "Syncing live profile",
+  githubViewProfile: "View GitHub",
+  githubMetricRepos: "Public repos",
+  githubMetricCommits: "Commits (30d)",
+  githubPinnedEyebrow: "PINNED",
+  githubPinnedHeading: "Pinned repositories",
+  githubPinnedFallbackDesc: "View code and recent updates in this public repository.",
+  githubPinnedEmpty: "Configure a GitHub Token or author.githubPinned to show pinned repositories here.",
+  githubContribEyebrow: "CONTRIBUTIONS",
+  githubContribHeading: "Public contributions in the past year",
+  githubContribCount: (n: number) => `${n} ${n === 1 ? "contribution" : "contributions"}`,
+  githubContribNeedToken: "GitHub Token required",
+  githubContribAria: (n: number) => `${n} public ${n === 1 ? "contribution" : "contributions"} in the past year`,
+  githubContribDayTitle: (date: string, n: number) => `${date} · ${n} ${n === 1 ? "contribution" : "contributions"}`,
+  githubContribDayAria: (date: string, n: number) => `${date}, ${n} ${n === 1 ? "contribution" : "contributions"}`,
+  githubContribEmpty: "Production builds use the workflow's read-only token to generate the contribution heatmap.",
+  githubActivityEyebrow: "CONTRIBUTION ACTIVITY",
+  githubActivityHeading: "Recent activity on GitHub",
+  githubActivityEmpty: "No recent public GitHub activity returned right now.",
+  githubEventPush: "Pushed commits",
+  githubEventPrClosed: "Completed a Pull Request",
+  githubEventPrOpen: "Opened a Pull Request",
+  githubEventIssueClosed: "Closed an Issue",
+  githubEventIssueOpen: "Participated in an Issue",
+  githubEventCreateRepo: "Created a repository",
+  githubEventCreateTag: "Created a tag",
+  githubEventCreateBranch: "Created a branch",
+  githubEventRelease: "Published a release",
+  // Comments & Webmentions
+  commentsSummaryReady: "Comments are stored and managed via GitHub Discussions.",
+  commentsSummaryUnconfigured: "Comments are not enabled yet. Configure the four variables below to show the comment box.",
+  commentsGiscusGuideUrl: "https://giscus.app",
+  commentsSetupBefore: "Open",
+  commentsSetupMiddle: ", install it on a public repository with Discussions enabled, and add the repository, repository ID, category, and category ID to ",
+  commentsSetupAnd: " and GitHub Actions Variables: ",
+  commentsSetupJoin: ", ",
+  commentsSetupEnd: ".",
+  giscusLang: "en",
+  webmentionIdleNote: "Webmention receiving and display are ready; responses will appear once a custom domain is connected.",
+  webmentionLoading: "Loading responses from the open web…",
+  webmentionUnavailable: "Responses are temporarily unavailable. Please try again later.",
+  webmentionEmpty: "No external responses yet. Any site linking to this post can send a Webmention.",
+  webmentionReactionCount: (n: number) => `${n} ${n === 1 ? "like, repost, or bookmark" : "likes, reposts, or bookmarks"}`,
+  webmentionRespondersLabel: "Responders",
+  webmentionViewResponse: "View external response",
+  webmentionAuthorFallback: "Open web reader",
+  webmentionViewOriginal: "View original",
+  // Empty states, embeds, widgets, UI blocks
+  emptyPostsEyebrow: "No posts yet",
+  emptyPostsTitle: "No posts yet.",
+  emptyPostsDesc: "Published posts will appear here in chronological order.",
+  emptyPostsCta: "Back to home",
+  emptyThoughtsEyebrow: "No thoughts yet",
+  emptyThoughtsTitle: "No thoughts yet.",
+  emptyThoughtsDesc: "Short notes and links will appear here.",
+  emptyThoughtsCta: "Browse posts",
+  emptyColumnsEyebrow: "No columns yet",
+  emptyColumnsTitle: "No columns yet.",
+  emptyColumnsDesc: "Curated post series will appear here in reading order.",
+  emptyColumnsCta: "Browse all posts",
+  embedProviderWechat: "WeChat Official Account",
+  embedProviderWeb: "Web excerpt",
+  embedParseError: "Could not parse this embed block. Please check the URL and YAML syntax.",
+  embedFrameTitle: (label: string) => `${label} embedded content`,
+  embedOpenOriginal: "Open original",
+  embedFallbackTitle: "Open external content",
+  embedFallbackNoScript: "This platform does not provide a stable script-free embed; Garden keeps a clean link to the original post.",
+  embedFallbackWeb: "Read the full page and context on the original site.",
+  widgetParseError: "Could not parse this widget block. Place a .html or .pdf file in the folder matching the Markdown file name, and specify src and caption.",
+  widgetOpenPage: "Open page",
+  widgetOpenPdf: "Open PDF",
+  widgetPageKind: "Page",
+  widgetCollapse: "Collapse",
+  widgetExpand: "Expand",
+  uiBlockCorrupt: "This interactive block's payload is corrupted. Please re-run garden sync.",
+  // Admin static notice & metadata
+  staticAdminHeading: "Admin lives at a separate address.",
+  staticAdminBody: "This page is not available on the public blog. Use your separately deployed admin instance to post thoughts or edit interactive blocks.",
+  staticAdminRootBody: "This is the public blog. Use the admin site to post thoughts, upload media, and share.",
+  staticAdminOpen: "Open admin",
+  staticAdminNoUrl: "No admin URL configured yet.",
+  staticAdminBack: "Back to public blog",
+  adminTitleMain: "Content Studio",
+  adminTitleUi: "Writing Studio",
+  adminTitleBlocks: "Interactive Blocks",
+  adminTitleCatalog: "Component Catalog",
+  adminTitleEvals: "Model Evals",
+  adminTitlePreview: "Draft Preview",
+  a2IndexTitle: "A2 Parity",
+  a2IndexDeck: "Layout comparison against reference articles. Body text is unchanged.",
 };
 
 export const UI_STRINGS = { zh, en } as const;
 export const ui = (lang: UiLang = siteLang) => UI_STRINGS[lang];
 
+/**
+ * Normalize a browser or router pathname to the in-app path (stripping a
+ * configured basePath or a leading deployment prefix before /garden).
+ */
+export function inAppPath(pathname: string | null | undefined): string {
+  return resolveInAppPath(pathname, siteLinks?.basePath);
+}
+
+export function isHandbookPath(pathname: string | null | undefined): boolean {
+  return resolveIsHandbookPath(pathname, siteLinks?.basePath);
+}
+
 /**
  * Chrome language for a route. The handbook follows its own URL (/garden/en/
  * is English, the rest of /garden/ is Chinese); every other page uses the site
  * language. `pathname` is the in-app path (no basePath), as usePathname gives.
  */
 export function routeLang(pathname: string | null | undefined): UiLang {
-  const path = pathname || "/";
+  const path = inAppPath(pathname);
   if (/^\/garden\/en(\/|$)/u.test(path)) return "en";
-  if (/^\/garden(\/|$)/u.test(path)) return "zh";
+  if (/^\/garden(\/|$)/u.test(path)) return siteLang === "en" ? "en" : "zh";
   return siteLang;
 }
+
+/** Label for a column status: the enum values are localized, any other author text is shown as written. */
+export const columnStatusLabel = (status: string | undefined, lang: UiLang = siteLang) => {
+  const t = ui(lang);
+  if (!status || status === "default") return t.columnDefault;
+  if (status === "ongoing") return t.columnOngoing;
+  if (status === "completed") return t.columnCompleted;
+  return status;
+};

package/app/lib/rehype-field-tables.mjs

@@ -0,0 +1,47 @@
+/**
+ * Handbook field tables (first header "字段"/"Field" plus a "是否必填"/"Required"
+ * column): tag the table, mark the Required column, and give every body cell its
+ * column name, so narrow screens can show each row as a small card.
+ */
+import { toString } from "hast-util-to-string";
+import { visit } from "unist-util-visit";
+
+// "字段", "字段或标签", "Field", "Field or Tag"…
+const FIELD = /^(字段|field\b)/iu;
+const REQUIRED = new Set(["是否必填", "required"]);
+
+const cells = (row) => (row?.children ?? []).filter((node) => node.type === "element" && (node.tagName === "th" || node.tagName === "td"));
+const rows = (node) => {
+  const out = [];
+  visit(node, "element", (child) => { if (child.tagName === "tr") out.push(child); });
+  return out;
+};
+const addClass = (node, name) => {
+  const props = (node.properties ??= {});
+  const list = Array.isArray(props.className) ? props.className : props.className ? [String(props.className)] : [];
+  if (!list.includes(name)) props.className = [...list, name];
+};
+
+export function isFieldTableHeader(labels) {
+  return labels.length >= 3 && FIELD.test(labels[0].trim()) && labels.some((label) => REQUIRED.has(label.trim().toLowerCase()));
+}
+
+export function rehypeFieldTables() {
+  return (tree) => {
+    visit(tree, "element", (table) => {
+      if (table.tagName !== "table") return;
+      const [head, ...body] = rows(table);
+      const labels = cells(head).map((cell) => toString(cell).trim());
+      if (!isFieldTableHeader(labels)) return;
+      addClass(table, "field-table");
+      const required = labels.findIndex((label) => REQUIRED.has(label.toLowerCase()));
+      cells(head).forEach((cell, i) => { if (i === required) addClass(cell, "ft-req"); });
+      for (const row of body) {
+        cells(row).forEach((cell, i) => {
+          cell.properties = { ...(cell.properties ?? {}), dataLabel: labels[i] ?? "" };
+          if (i === required) addClass(cell, "ft-req");
+        });
+      }
+    });
+  };
+}