hd-garden 0.3.3 → 0.3.5

package/app/api/admin/thoughts/route.ts

@@ -4,6 +4,7 @@ import {
   listRepositoryThoughts,
 } from "../../../lib/github-content";
 import type { MediaItem } from "../../../lib/content";
+import { formatAuthorDate } from "../../../../scripts/site-date.mjs";
 
 type ThoughtPayload = {
   title?: unknown;
@@ -108,7 +109,7 @@ export async function POST(request: Request) {
       tags: parsed.value.tags,
       media: parsed.value.media,
       status: parsed.value.status,
-      date: new Date().toISOString(),
+      date: formatAuthorDate(),
     });
     return Response.json({ thought }, { status: 201 });
   } catch (error) {

package/app/blog/[...path]/page.tsx

@@ -9,6 +9,7 @@ import {
   postHref,
   posts,
 } from "../../lib/content";
+import { ArticleReferences } from "../../components/ArticleReferences";
 import { MarkdownArticle } from "../../components/MarkdownArticle";
 import { TableOfContents } from "../../components/TableOfContents";
 import { Comments } from "../../components/Comments";
@@ -48,7 +49,7 @@ export async function generateMetadata({
         ? new Date(post.updated).toISOString()
         : undefined,
       tags: post.tags,
-      images: post.cover ? [{ url: post.cover, alt: post.coverAlt }] : undefined,
+      images: post.cover ? [{ url: post.cover, alt: post.title }] : undefined,
     },
     twitter: {
       card: "summary_large_image",
@@ -92,7 +93,7 @@ export default async function PostPage({
             <img
               className="u-photo"
               src={post.cover}
-              alt={post.coverAlt ?? `${post.title} 封面`}
+              alt={`${post.title} 封面`}
             />
           </figure>
         )}
@@ -114,6 +115,7 @@ export default async function PostPage({
             <div className="e-content">
               <MarkdownArticle content={post.content} />
             </div>
+            <ArticleReferences references={post.references} />
             <div className="article-tags">
               {post.tags?.map((tag) => (
                 <span className="p-category" key={tag}>

package/app/columns/[column]/[...path]/page.tsx

@@ -10,6 +10,7 @@ import {
   columnHref,
   columnEntryPath,
 } from "../../../lib/content";
+import { ArticleReferences } from "../../../components/ArticleReferences";
 import { MarkdownArticle } from "../../../components/MarkdownArticle";
 import { TableOfContents } from "../../../components/TableOfContents";
 import { Comments } from "../../../components/Comments";
@@ -52,7 +53,7 @@ export async function generateMetadata({
         ? new Date(entry.updated).toISOString()
         : undefined,
       tags: entry.tags,
-      images: entry.cover ? [{ url: entry.cover, alt: entry.coverAlt }] : undefined,
+      images: entry.cover ? [{ url: entry.cover, alt: entry.title }] : undefined,
     },
     twitter: {
       card: "summary_large_image",
@@ -115,7 +116,7 @@ export default async function ColumnEntryPage({
             <img
               className="u-photo"
               src={entry.cover}
-              alt={entry.coverAlt ?? `${entry.title} 封面`}
+              alt={`${entry.title} 封面`}
             />
           </figure>
         )}
@@ -137,6 +138,7 @@ export default async function ColumnEntryPage({
         <div className="e-content">
           <MarkdownArticle content={entry.content} />
         </div>
+        <ArticleReferences references={entry.references} />
         {next && (
           <Link
             href={columnHref(next)}

package/app/components/AdminDashboard.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import Link from "next/link";
+import { formatAuthorDate } from "../../scripts/site-date.mjs";
 import { useMemo, useState } from "react";
 import {
   ArrowSquareOut,
@@ -239,7 +240,7 @@ export function AdminDashboard({
     setThoughts((current) =>
       current.map((thought) =>
         thought.id === id
-          ? { ...thought, status, date: status === "published" ? new Date().toISOString() : thought.date }
+          ? { ...thought, status, date: status === "published" ? formatAuthorDate() : thought.date }
           : thought,
       ),
     );

package/app/components/ArticleReferences.tsx

@@ -0,0 +1,47 @@
+type ReferenceItem = {
+  title: string;
+  url?: string;
+};
+
+export function ArticleReferences({
+  references,
+}: {
+  references?: ReferenceItem[];
+}) {
+  if (!references?.length) return null;
+
+  return (
+    <section className="article-references" aria-labelledby="article-references-heading">
+      <p id="article-references-heading">参考</p>
+      <table>
+        <tbody>
+          {references.map((item, index) => {
+            const number = index + 1;
+            return (
+              <tr key={index}>
+                <td>
+                  {item.url ? (
+                    <a href={item.url} tabIndex={-1} aria-hidden="true">
+                      {number}
+                    </a>
+                  ) : (
+                    <span>{number}</span>
+                  )}
+                </td>
+                <td>
+                  {item.url ? (
+                    <a href={item.url} rel="noreferrer">
+                      <span>{item.title}</span>
+                    </a>
+                  ) : (
+                    <span>{item.title}</span>
+                  )}
+                </td>
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </section>
+  );
+}

package/app/components/BlogArchive.tsx

@@ -69,7 +69,7 @@ export function BlogArchive() {
                 <img
                   className="archive-cover"
                   src={post.cover}
-                  alt={post.coverAlt ?? `${post.title} 封面`}
+                  alt={`${post.title} 封面`}
                   loading="lazy"
                 />
               )}

package/app/components/GardenContentGuide.tsx

@@ -26,13 +26,12 @@ function SourcePanel({ path, source, language }: SourcePanelProps) {
 
 const postSource = `---
 title: 我的第一篇文章
-slug: first-post
-date: 2026-08-03T09:00:00+08:00
+date: 2026-08-03 09:00:00
 description: 这篇文章记录我为什么重新开始写博客。
 topic: 写作
 tags: [Markdown, 博客]
 pinned: false
-cover: ./assets/cover.jpg
+cover: writing/first-post.jpg
 ---
 
 正文从这里开始。
@@ -43,8 +42,7 @@ cover: ./assets/cover.jpg
 
 const thoughtSource = `---
 title: 雨后的散步
-slug: walk-after-rain
-date: 2026-08-03T18:30:00+08:00
+date: 2026-08-03 18:30:00
 tags: [生活]
 media:
   - type: image
@@ -121,9 +119,9 @@ const guides: Guide[] = [
       "随想适合记录几句话、一个链接或一组多媒体。它同样保存在 Git 仓库中，只需要更少的字段，也可以通过可选管理后台发布。",
     steps: [
       <>
-        直接创建 <code>content/thoughts/&lt;slug&gt;.md</code>，或者在管理后台填写内容。
+        直接创建 <code>content/thoughts/&lt;文件名&gt;.md</code>，或者在管理后台填写内容。
       </>,
-      <>填写标题、唯一 slug 和日期；需要暂存时加入草稿状态。</>,
+      <>文件名就是地址。front matter 填写标题和日期；需要暂存时加入草稿状态。</>,
       <>
         在 <code>media</code> 中按顺序添加图片、音频、视频或外部链接。
       </>,

package/app/garden-modules.d.ts

@@ -20,6 +20,7 @@ declare module "@garden/generated-content" {
     draft?: boolean;
     topic?: string;
     tags?: string[];
+    references?: { title: string; url?: string }[];
     pinned?: boolean;
     readingTime?: string;
     kind: "post" | "column" | "thought";
@@ -33,7 +34,6 @@ declare module "@garden/generated-content" {
     columnCoverAlt?: string;
     order?: number;
     cover?: string;
-    coverAlt?: string;
     mediaType?: "image" | "audio" | "video" | "link" | "text";
     media?: string | MediaItem[];
     mediaAlt?: string;

package/app/globals.css

@@ -2802,6 +2802,72 @@ button {
   color: #7f8790;
 }
 
+.article-references {
+  margin-top: 64px;
+}
+
+.article-references > p {
+  margin: 0 0 14px;
+  color: var(--accent);
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.article-references table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 12px;
+}
+
+.article-references td {
+  padding: 0;
+  border: 1px solid var(--line);
+  color: var(--ink-soft);
+  text-align: left;
+  overflow-wrap: anywhere;
+}
+
+.article-references td:first-child {
+  width: 1%;
+  color: var(--accent);
+  font-variant-numeric: tabular-nums;
+  text-align: right;
+  white-space: nowrap;
+}
+
+.article-references td a,
+.article-references td > span {
+  display: block;
+  padding: 11px 13px;
+}
+
+.article-references td:first-child a,
+.article-references td:first-child > span {
+  padding-right: 8px;
+  color: var(--accent);
+  text-decoration: none;
+}
+
+.article-references td a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.article-references td a span {
+  text-decoration: underline;
+  text-decoration-color: var(--accent);
+  text-underline-offset: 4px;
+}
+
+.article-references td a:hover span {
+  color: var(--accent);
+}
+
+.article-references + .article-tags,
+.article-references + .next-entry {
+  margin-top: 36px;
+}
+
 .article-tags {
   display: flex;
   flex-wrap: wrap;

package/app/lib/content.ts

@@ -7,6 +7,7 @@ import {
   type MediaItem,
 } from "@garden/generated-content";
 import GithubSlugger from "github-slugger";
+import { canonicalSiteDate } from "../../scripts/site-date.mjs";
 import { toString } from "mdast-util-to-string";
 import remarkParse from "remark-parse";
 import { unified } from "unified";
@@ -23,13 +24,18 @@ export const columnEntryPath = (entry: Pick<ContentEntry, "column" | "path">) =>
 export const columnHref = (entry: Pick<ContentEntry, "column" | "path">) =>
   `/columns/${entry.column}/${columnEntryPath(entry)}`;
 
-export const formatDate = (value: string, withTime = false) =>
-  new Intl.DateTimeFormat("zh-CN", {
+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", {
+    timeZone: "Asia/Shanghai",
     year: "numeric",
     month: "2-digit",
     day: "2-digit",
     ...(withTime ? { hour: "2-digit", minute: "2-digit" } : {}),
-  }).format(new Date(value));
+  }).format(date);
+};
 
 /**
  * Parses the same Markdown heading text that ReactMarkdown sends to

package/app/lib/generated-content.ts

@@ -1,4 +1,4 @@
-// Generated by scripts/build-content.mjs. Edit files in content/ instead.
+// Generated by garden sync. Edit files in content/ instead.
 export type MediaItem = {
   type: "image" | "audio" | "video" | "link";
   src: string;
@@ -33,7 +33,6 @@ export type ContentEntry = {
   columnCoverAlt?: string;
   order?: number;
   cover?: string;
-  coverAlt?: string;
   mediaType?: "image" | "audio" | "video" | "link" | "text";
   media?: string | MediaItem[];
   mediaAlt?: string;
@@ -42,11 +41,10 @@ export type ContentEntry = {
   linkDescription?: string;
 };
 
-export const contentHash = "d29583878502";
+export const contentHash = "86dad25b6dba";
 export const posts = [
   {
     "title": "Markdown 复杂语法实验场",
-    "slug": "markdown-lab",
     "description": "用一篇真实文章验证 Typora 常用语法、数学公式、Mermaid、脚注、表格与原生 HTML。",
     "date": "2026-07-25T00:00:00.000Z",
     "topic": "写作系统",
@@ -59,7 +57,7 @@ export const posts = [
     "pinned": false,
     "readingTime": "10 分钟",
     "cover": "https://images.unsplash.com/photo-1761414500824-e280de5a1b37?auto=format&fit=crop&w=1600&q=84",
-    "coverAlt": "彩色阳台构成的现代建筑立面",
+    "slug": "markdown-lab",
     "path": "markdown-lab",
     "kind": "post",
     "draft": false,
@@ -68,7 +66,6 @@ export const posts = [
   },
   {
     "title": "注意力也是一种界面",
-    "slug": "attention-is-an-interface",
     "description": "当工具越来越聪明，真正稀缺的不是功能，而是我们把注意力放在哪里。",
     "date": "2026-07-21T00:00:00.000Z",
     "updated": "2026-07-23T00:00:00.000Z",
@@ -80,7 +77,7 @@ export const posts = [
     "pinned": true,
     "readingTime": "6 分钟",
     "cover": "https://images.unsplash.com/photo-1630234674857-527eb5534837?auto=format&fit=crop&w=1600&q=84",
-    "coverAlt": "彩色几何建筑立面",
+    "slug": "attention-is-an-interface",
     "path": "attention-is-an-interface",
     "kind": "post",
     "draft": false,
@@ -89,7 +86,6 @@ export const posts = [
   },
   {
     "title": "03 · 带着证据发布",
-    "slug": "ship-with-evidence",
     "description": "“我改完了”不是完成，“用户可以确认它好了”才是。",
     "date": "2026-07-18T00:00:00.000Z",
     "topic": "独立开发",
@@ -98,6 +94,7 @@ export const posts = [
       "发布"
     ],
     "readingTime": "5 分钟",
+    "slug": "ship-with-evidence",
     "path": "building-in-public/ship-with-evidence",
     "kind": "post",
     "draft": false,
@@ -106,7 +103,6 @@ export const posts = [
   },
   {
     "title": "我为什么重新选择本地写作",
-    "slug": "local-first-writing",
     "description": "Markdown 文件、可迁移的媒体资源，以及不被平台锁住的长期写作。",
     "date": "2026-07-12T00:00:00.000Z",
     "topic": "写作系统",
@@ -117,7 +113,7 @@ export const posts = [
     "pinned": true,
     "readingTime": "5 分钟",
     "cover": "https://images.unsplash.com/photo-1501525771695-688643efeea4?auto=format&fit=crop&w=1600&q=84",
-    "coverAlt": "木桌上的笔记本与钢笔",
+    "slug": "local-first-writing",
     "path": "local-first-writing",
     "kind": "post",
     "draft": false,
@@ -126,7 +122,6 @@ export const posts = [
   },
   {
     "title": "02 · 让状态变得可靠",
-    "slug": "stable-state",
     "description": "状态设计的关键，是明确谁拥有事实。",
     "date": "2026-07-10T00:00:00.000Z",
     "topic": "独立开发",
@@ -134,6 +129,7 @@ export const posts = [
       "状态管理"
     ],
     "readingTime": "6 分钟",
+    "slug": "stable-state",
     "path": "building-in-public/stable-state",
     "kind": "post",
     "draft": false,
@@ -142,7 +138,6 @@ export const posts = [
   },
   {
     "title": "01 · 从最小闭环开始",
-    "slug": "smallest-closed-loop",
     "description": "先让最重要的一条路径真正跑通。",
     "date": "2026-07-04T00:00:00.000Z",
     "topic": "独立开发",
@@ -151,6 +146,7 @@ export const posts = [
       "工程"
     ],
     "readingTime": "7 分钟",
+    "slug": "smallest-closed-loop",
     "path": "building-in-public/smallest-closed-loop",
     "kind": "post",
     "draft": false,
@@ -159,7 +155,6 @@ export const posts = [
   },
   {
     "title": "做一个 PDF 阅读器之后，我重新理解了「位置」",
-    "slug": "building-a-pdf-reader",
     "description": "阅读位置不是页码，而是一段连续体验的锚点。",
     "date": "2026-06-28T00:00:00.000Z",
     "topic": "构建手记",
@@ -170,7 +165,7 @@ export const posts = [
     "pinned": false,
     "readingTime": "8 分钟",
     "cover": "https://images.unsplash.com/photo-1623276527153-fa38c1616b05?auto=format&fit=crop&w=1600&q=84",
-    "coverAlt": "桌上的平板电脑、笔记本电脑与咖啡",
+    "slug": "building-a-pdf-reader",
     "path": "building-a-pdf-reader",
     "kind": "post",
     "draft": false,
@@ -179,7 +174,6 @@ export const posts = [
   },
   {
     "title": "从逐词生成理解 KV Cache",
-    "slug": "understand-kv-cache",
     "description": "不从公式开始，而是从模型下一次到底重复算了什么开始。",
     "date": "2026-06-09T00:00:00.000Z",
     "topic": "AI 学习",
@@ -190,7 +184,7 @@ export const posts = [
     "pinned": false,
     "readingTime": "9 分钟",
     "cover": "https://images.unsplash.com/photo-1518770660439-4636190af475?auto=format&fit=crop&w=1600&q=84",
-    "coverAlt": "近距离拍摄的电子电路板",
+    "slug": "understand-kv-cache",
     "path": "understand-kv-cache",
     "kind": "post",
     "draft": false,
@@ -201,7 +195,6 @@ export const posts = [
 export const columns = [
   {
     "title": "01 · 从最小闭环开始",
-    "slug": "smallest-closed-loop",
     "description": "先让最重要的一条路径真正跑通。",
     "date": "2026-07-04T00:00:00.000Z",
     "topic": "独立开发",
@@ -210,6 +203,7 @@ export const columns = [
       "工程"
     ],
     "readingTime": "7 分钟",
+    "slug": "smallest-closed-loop",
     "path": "building-in-public/smallest-closed-loop",
     "kind": "column",
     "draft": false,
@@ -223,7 +217,6 @@ export const columns = [
   },
   {
     "title": "02 · 让状态变得可靠",
-    "slug": "stable-state",
     "description": "状态设计的关键，是明确谁拥有事实。",
     "date": "2026-07-10T00:00:00.000Z",
     "topic": "独立开发",
@@ -231,6 +224,7 @@ export const columns = [
       "状态管理"
     ],
     "readingTime": "6 分钟",
+    "slug": "stable-state",
     "path": "building-in-public/stable-state",
     "kind": "column",
     "draft": false,
@@ -244,7 +238,6 @@ export const columns = [
   },
   {
     "title": "03 · 带着证据发布",
-    "slug": "ship-with-evidence",
     "description": "“我改完了”不是完成，“用户可以确认它好了”才是。",
     "date": "2026-07-18T00:00:00.000Z",
     "topic": "独立开发",
@@ -253,6 +246,7 @@ export const columns = [
       "发布"
     ],
     "readingTime": "5 分钟",
+    "slug": "ship-with-evidence",
     "path": "building-in-public/ship-with-evidence",
     "kind": "column",
     "draft": false,
@@ -268,7 +262,6 @@ export const columns = [
 export const thoughts = [
   {
     "title": "雨后的城市",
-    "slug": "rainy-night",
     "date": "2026-07-24T14:36:00.000Z",
     "tags": [
       "摄影"
@@ -307,6 +300,7 @@ export const thoughts = [
         "description": "一条和这晚阅读有关、值得保留上下文的链接。"
       }
     ],
+    "slug": "rainy-night",
     "path": "rainy-night",
     "kind": "thought",
     "draft": false,
@@ -315,7 +309,6 @@ export const thoughts = [
   },
   {
     "title": "今天的声音",
-    "slug": "field-recording",
     "date": "2026-07-22T10:10:00.000Z",
     "tags": [
       "声音"
@@ -328,6 +321,7 @@ export const thoughts = [
         "title": "今天的声音 · 循环片段"
       }
     ],
+    "slug": "field-recording",
     "path": "field-recording",
     "kind": "thought",
     "draft": false,
@@ -336,7 +330,6 @@ export const thoughts = [
   },
   {
     "title": "慢一点看",
-    "slug": "slow-motion",
     "date": "2026-07-19T01:20:00.000Z",
     "tags": [
       "影像"
@@ -349,6 +342,7 @@ export const thoughts = [
         "poster": "https://images.unsplash.com/photo-1544655205-dcbeb868c648?auto=format&fit=crop&w=1400&q=82"
       }
     ],
+    "slug": "slow-motion",
     "path": "slow-motion",
     "kind": "thought",
     "draft": false,
@@ -357,7 +351,6 @@ export const thoughts = [
   },
   {
     "title": "链接不是收藏，是路径",
-    "slug": "links-are-paths",
     "date": "2026-07-16T04:05:00.000Z",
     "tags": [
       "阅读"
@@ -371,6 +364,7 @@ export const thoughts = [
         "description": "让不同网站之间的回复、喜欢与引用重新连接起来。"
       }
     ],
+    "slug": "links-are-paths",
     "path": "links-are-paths",
     "kind": "thought",
     "draft": false,

package/app/lib/github-content.ts

@@ -1,6 +1,16 @@
 import matter from "gray-matter";
+import { parse as parseYaml } from "yaml";
 import type { ContentEntry, MediaItem } from "./content";
 import { repositoryPostPath } from "./repository-path.mjs";
+import { canonicalSiteDate, formatAuthorDate } from "../../scripts/site-date.mjs";
+
+const matterOptions = {
+  engines: {
+    yaml: {
+      parse: (input: string) => parseYaml(input) ?? {},
+    },
+  },
+};
 
 const apiBase = "https://api.github.com";
 
@@ -72,17 +82,23 @@ function isMedia(value: unknown): value is MediaItem[] {
   });
 }
 
-function normalizeThought(source: string, path: string, sha?: string): RepositoryThought | null {
-  const parsed = matter(source);
+function fileStem(filePath: string) {
+  return (filePath.split("/").pop() ?? "").replace(/\.md$/u, "");
+}
+
+function normalizeThought(source: string, filePath: string, sha?: string): RepositoryThought | null {
+  const parsed = matter(source, matterOptions);
   const data = parsed.data;
-  if (typeof data.title !== "string" || typeof data.slug !== "string" || typeof data.date !== "string") {
+  const slug = fileStem(filePath);
+  if (typeof data.title !== "string" || typeof data.date !== "string" || !canonicalSiteDate(data.date) || !slug) {
     return null;
   }
+  if (data.slug !== undefined && data.slug !== slug) return null;
   const media = isMedia(data.media) ? data.media : [];
   const status = data.draft === true ? "draft" : "published";
   return {
-    id: data.slug,
-    slug: data.slug,
+    id: slug,
+    slug,
     title: data.title,
     date: data.date,
     tags: isStringArray(data.tags) ? data.tags : [],
@@ -90,7 +106,7 @@ function normalizeThought(source: string, path: string, sha?: string): Repositor
     media,
     kind: "thought",
     draft: status === "draft",
-    sourcePath: path,
+    sourcePath: filePath,
     content: parsed.content.trim(),
     status,
     sha,
@@ -108,8 +124,7 @@ function serializeThought(thought: {
 }) {
   return matter.stringify(thought.content.trim().concat("\n"), {
     title: thought.title,
-    slug: thought.slug,
-    date: thought.date ?? new Date().toISOString(),
+    date: thought.date ?? formatAuthorDate(),
     tags: thought.tags,
     mediaType: thought.media[0]?.type ?? "text",
     media: thought.media,
@@ -173,7 +188,11 @@ export async function listRepositoryThoughts() {
   );
   return thoughts
     .filter((thought): thought is RepositoryThought => Boolean(thought))
-    .sort((left, right) => Date.parse(right.date) - Date.parse(left.date));
+    .sort((left, right) => {
+      const rightTime = Date.parse(canonicalSiteDate(right.date) ?? "");
+      const leftTime = Date.parse(canonicalSiteDate(left.date) ?? "");
+      return rightTime - leftTime;
+    });
 }
 
 export async function createRepositoryThought(input: Omit<RepositoryThought, "id" | "kind" | "sourcePath" | "draft" | "sha" | "mediaType">) {
@@ -196,7 +215,7 @@ export async function updateRepositoryThought(slug: string, status: "draft" | "p
   if (!existing) throw new Error("未找到对应随想。");
   const thought = normalizeThought(existing.source, path, existing.sha);
   if (!thought) throw new Error("随想内容格式不正确。");
-  const source = serializeThought({ ...thought, status, date: status === "published" ? new Date().toISOString() : thought.date });
+  const source = serializeThought({ ...thought, status, date: status === "published" ? formatAuthorDate() : thought.date });
   const { response } = await mutateRepository(path, "PUT", {
     message: `content: ${status === "published" ? "发布" : "撤回"}随想 ${thought.title}`,
     content: utf8ToBase64(source),
@@ -227,7 +246,7 @@ export async function updateRepositoryPostPinned(input: {
   const existing = await readRepositoryFile(repositoryPath);
   if (!existing) throw new Error("未找到对应博文。");
   const parsed = matter(existing.source);
-  if (parsed.data.slug !== input.slug) {
+  if (fileStem(repositoryPath) !== input.slug) {
     throw new Error("博文标识不匹配，已拒绝修改。");
   }
   const data = { ...parsed.data } as Record<string, unknown>;

package/app/rss.xml/route.ts

@@ -37,9 +37,7 @@ export async function GET() {
         breaks: true,
       });
       const cover = entry.cover
-        ? `<p><img src="${escapeXml(entry.cover)}" alt="${escapeXml(
-            entry.coverAlt ?? entry.title,
-          )}" /></p>`
+        ? `<p><img src="${escapeXml(entry.cover)}" alt="${escapeXml(entry.title)}" /></p>`
         : "";
       return `
     <item>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-garden",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "private": false,
   "description": "用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。",
   "license": "MIT",

package/scripts/build-content.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import matter from "gray-matter";
 import { marked } from "marked";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { canonicalSiteDate } from "./site-date.mjs";
 
 function resolveSiteRoot() {
   if (process.env.GARDEN_SITE) return path.resolve(process.env.GARDEN_SITE);
@@ -52,15 +53,47 @@ const optionalString = (data, key, sourcePath) => {
 };
 
 const normalizeDate = (value, key, sourcePath) => {
-  const normalized = value instanceof Date ? value.toISOString() : value;
-  if (
-    typeof normalized !== "string" ||
-    !normalized ||
-    Number.isNaN(Date.parse(normalized))
-  ) {
-    fail(sourcePath, `${key} 必须是有效日期`);
+  const canonical = canonicalSiteDate(value);
+  if (!canonical) {
+    fail(sourcePath, `${key} 必须是有效日期，例如 2026-09-18 14:39:00`);
   }
-  return normalized;
+  return canonical;
+};
+
+const normalizeReferences = (value, sourcePath) => {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) fail(sourcePath, "references 必须是数组");
+  const references = value.map((item, index) => {
+    const where = `references[${index}]`;
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      fail(sourcePath, `${where} 必须是包含 title 的对象`);
+    }
+    for (const key of Object.keys(item)) {
+      if (key !== "title" && key !== "url") {
+        fail(sourcePath, `${where} 不支持 ${key}`);
+      }
+    }
+    if (typeof item.title !== "string" || !item.title.trim()) {
+      fail(sourcePath, `${where} 缺少有效的 title`);
+    }
+    const title = item.title.trim();
+    if (item.url === undefined || item.url === null || item.url === "") {
+      return { title };
+    }
+    if (typeof item.url !== "string") fail(sourcePath, `${where}.url 必须是字符串`);
+    const url = item.url.trim();
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      fail(sourcePath, `${where}.url 必须是 http 或 https 链接`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      fail(sourcePath, `${where}.url 必须是 http 或 https 链接`);
+    }
+    return { title, url };
+  });
+  return references.length ? references : undefined;
 };
 
 const isExternalAsset = (value) =>
@@ -71,12 +104,13 @@ const isExternalAsset = (value) =>
 
 const assetCache = new Map();
 
-function copyLocalAsset(value, markdownPath, sourcePath) {
+function copyLocalAsset(value, markdownPath, sourcePath, options = {}) {
   if (!value || isExternalAsset(value)) return value;
 
+  const baseDir = options.baseDir ?? path.dirname(markdownPath);
   const [assetPath, suffix = ""] = value.split(/(?=[?#])/u, 2);
   const decodedPath = decodeURIComponent(assetPath.replace(/^<|>$/g, ""));
-  const absoluteSource = path.resolve(path.dirname(markdownPath), decodedPath);
+  const absoluteSource = path.resolve(baseDir, decodedPath);
   const relativeSource = path.relative(contentRoot, absoluteSource);
 
   if (
@@ -85,7 +119,7 @@ function copyLocalAsset(value, markdownPath, sourcePath) {
     !fs.existsSync(absoluteSource) ||
     !fs.statSync(absoluteSource).isFile()
   ) {
-    fail(sourcePath, `找不到本地媒体文件 ${value}`);
+    fail(sourcePath, options.missingMessage ?? `找不到本地媒体文件 ${value}`);
   }
 
   if (!assetCache.has(absoluteSource)) {
@@ -254,9 +288,12 @@ function normalizeMedia(media, markdownPath, sourcePath) {
 
 function validateAndNormalize(data, content, markdownPath, kind, sourcePath) {
   const title = requireString(data, "title", sourcePath);
-  const slug = optionalString(data, "slug", sourcePath) ?? path.basename(markdownPath, ".md");
+  const slug = path.basename(markdownPath, ".md");
   if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(slug)) {
-    fail(sourcePath, "slug 只能包含小写字母、数字和连字符");
+    fail(sourcePath, "文件名只能包含小写字母、数字和连字符");
+  }
+  if (data.slug !== undefined) {
+    fail(sourcePath, "不要写 slug，文件名就是标识");
   }
 
   const date = normalizeDate(data.date, "date", sourcePath);
@@ -286,9 +323,13 @@ function validateAndNormalize(data, content, markdownPath, kind, sourcePath) {
 
   const publishTime = Date.parse(publishAt ?? date);
   if (!includeDrafts && (data.draft === true || publishTime > now)) return null;
+  delete data.coverAlt;
+  const references = normalizeReferences(data.references, sourcePath);
+  delete data.references;
 
   return {
     ...data,
+    references,
     title,
     slug,
     path: kind === "post"
@@ -301,7 +342,10 @@ function validateAndNormalize(data, content, markdownPath, kind, sourcePath) {
     draft: Boolean(data.draft),
     sourcePath,
     cover: data.cover
-      ? copyLocalAsset(data.cover, markdownPath, sourcePath)
+      ? copyLocalAsset(data.cover, markdownPath, sourcePath, {
+          baseDir: path.join(contentRoot, "covers"),
+          missingMessage: `找不到封面 ${data.cover}；本地路径相对 content/covers`,
+        })
       : undefined,
     columnCover: data.columnCover
       ? copyLocalAsset(data.columnCover, markdownPath, sourcePath)
@@ -327,7 +371,13 @@ function readMarkdownTree(directory, kind) {
     if (!entry.name.endsWith(".md")) return [];
 
     const raw = fs.readFileSync(fullPath, "utf8");
-    const parsed = matter(raw);
+    const parsed = matter(raw, {
+      engines: {
+        yaml: {
+          parse: (input) => parseYaml(input) ?? {},
+        },
+      },
+    });
     const sourcePath = path.relative(contentRoot, fullPath);
     const normalized = validateAndNormalize(
       parsed.data,
@@ -399,7 +449,7 @@ function readColumnReferences(posts) {
     if (seenColumns.has(slug)) fail(sourcePath, `专栏 slug ${slug} 重复。`);
     seenColumns.add(slug);
     if (!Array.isArray(value.posts) || !value.posts.every((entry) => typeof entry === "string")) {
-      fail(sourcePath, "posts 必须是博文 slug 或相对路径数组。");
+      fail(sourcePath, "posts 必须是博文相对路径数组。");
     }
     const referenced = new Set();
     return value.posts.map((postReference, order) => {
@@ -474,6 +524,7 @@ export type ContentEntry = {
   draft?: boolean;
   topic?: string;
   tags?: string[];
+  references?: { title: string; url?: string }[];
   pinned?: boolean;
   readingTime?: string;
   kind: "post" | "column" | "thought";
@@ -487,7 +538,6 @@ export type ContentEntry = {
   columnCoverAlt?: string;
   order?: number;
   cover?: string;
-  coverAlt?: string;
   mediaType?: "image" | "audio" | "video" | "link" | "text";
   media?: string | MediaItem[];
   mediaAlt?: string;

package/scripts/new-post.mjs

@@ -1,13 +1,14 @@
 import { randomUUID } from "node:crypto";
 import { lstat, mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { formatAuthorDate } from "./site-date.mjs";
 
 const root = path.resolve(process.env.GARDEN_SITE || process.cwd());
 const option = (name) => (process.env[`GARDEN_NEW_${name}`] ?? "").trim();
 
 async function main() {
   const title = option("TITLE") || "新文章";
-  const date = new Date().toISOString();
+  const date = formatAuthorDate();
   const titleSlug = title.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-|-$/gu, "");
   const slug = option("SLUG") || titleSlug || `post-${date.slice(0, 10)}-${randomUUID().slice(0, 8)}`;
   const directory = option("DIR");
@@ -39,7 +40,6 @@ async function main() {
   const markdown = [
     "---",
     `title: ${JSON.stringify(title)}`,
-    `slug: ${slug}`,
     `date: ${date}`,
     `description: ${JSON.stringify("请填写一句话摘要。")}`,
     `topic: ${JSON.stringify(topic)}`,

package/scripts/site-date.mjs

@@ -0,0 +1,59 @@
+const siteTimeZone = "Asia/Shanghai";
+const siteTimeOffset = "+08:00";
+const civilDatePattern =
+  /^(\d{4})-(\d{2})-(\d{2})(?: (\d{2}):(\d{2})(?::(\d{2}))?)?$/;
+
+const clockInShanghai = (date) => {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: siteTimeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hourCycle: "h23",
+  }).formatToParts(date);
+  const pick = (type) => parts.find((part) => part.type === type)?.value ?? "";
+  return {
+    year: pick("year"),
+    month: pick("month"),
+    day: pick("day"),
+    hour: pick("hour"),
+    minute: pick("minute"),
+    second: pick("second"),
+  };
+};
+
+export function formatAuthorDate(now = new Date()) {
+  const clock = clockInShanghai(now);
+  return `${clock.year}-${clock.month}-${clock.day} ${clock.hour}:${clock.minute}:${clock.second}`;
+}
+
+export function canonicalSiteDate(value) {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : value.toISOString();
+  }
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  const match = civilDatePattern.exec(text);
+  if (match) {
+    const [, year, month, day, hour = "00", minute = "00", second = "00"] = match;
+    const iso = `${year}-${month}-${day}T${hour}:${minute}:${second}${siteTimeOffset}`;
+    const parsed = new Date(iso);
+    if (Number.isNaN(parsed.getTime())) return null;
+    const clock = clockInShanghai(parsed);
+    if (
+      clock.year !== year ||
+      clock.month !== month ||
+      clock.day !== day ||
+      clock.hour !== hour ||
+      clock.minute !== minute ||
+      clock.second !== second
+    ) {
+      return null;
+    }
+    return iso;
+  }
+  return Number.isNaN(Date.parse(text)) ? null : text;
+}