hd-garden 0.3.4 → 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";
@@ -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";
@@ -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/GardenContentGuide.tsx

@@ -26,7 +26,7 @@ function SourcePanel({ path, source, language }: SourcePanelProps) {
 
 const postSource = `---
 title: 我的第一篇文章
-date: 2026-08-03T09:00:00+08:00
+date: 2026-08-03 09:00:00
 description: 这篇文章记录我为什么重新开始写博客。
 topic: 写作
 tags: [Markdown, 博客]
@@ -42,7 +42,7 @@ cover: writing/first-post.jpg
 
 const thoughtSource = `---
 title: 雨后的散步
-date: 2026-08-03T18:30:00+08:00
+date: 2026-08-03 18:30:00
 tags: [生活]
 media:
   - type: image

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";

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/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";
 
@@ -77,10 +87,10 @@ function fileStem(filePath: string) {
 }
 
 function normalizeThought(source: string, filePath: string, sha?: string): RepositoryThought | null {
-  const parsed = matter(source);
+  const parsed = matter(source, matterOptions);
   const data = parsed.data;
   const slug = fileStem(filePath);
-  if (typeof data.title !== "string" || typeof data.date !== "string" || !slug) {
+  if (typeof data.title !== "string" || typeof data.date !== "string" || !canonicalSiteDate(data.date) || !slug) {
     return null;
   }
   if (data.slug !== undefined && data.slug !== slug) return null;
@@ -114,7 +124,7 @@ function serializeThought(thought: {
 }) {
   return matter.stringify(thought.content.trim().concat("\n"), {
     title: thought.title,
-    date: thought.date ?? new Date().toISOString(),
+    date: thought.date ?? formatAuthorDate(),
     tags: thought.tags,
     mediaType: thought.media[0]?.type ?? "text",
     media: thought.media,
@@ -178,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">) {
@@ -201,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),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-garden",
-  "version": "0.3.4",
+  "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) =>
@@ -291,9 +324,12 @@ 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"
@@ -335,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,
@@ -482,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";

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");

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;
+}