hd-garden 0.3.3 → 0.3.4

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

@@ -48,7 +48,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 +92,7 @@ export default async function PostPage({
             <img
               className="u-photo"
               src={post.cover}
-              alt={post.coverAlt ?? `${post.title} 封面`}
+              alt={`${post.title} 封面`}
             />
           </figure>
         )}

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

@@ -52,7 +52,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 +115,7 @@ export default async function ColumnEntryPage({
             <img
               className="u-photo"
               src={entry.cover}
-              alt={entry.coverAlt ?? `${entry.title} 封面`}
+              alt={`${entry.title} 封面`}
             />
           </figure>
         )}

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
 description: 这篇文章记录我为什么重新开始写博客。
 topic: 写作
 tags: [Markdown, 博客]
 pinned: false
-cover: ./assets/cover.jpg
+cover: writing/first-post.jpg
 ---
 
 正文从这里开始。
@@ -43,7 +42,6 @@ cover: ./assets/cover.jpg
 
 const thoughtSource = `---
 title: 雨后的散步
-slug: walk-after-rain
 date: 2026-08-03T18:30:00+08:00
 tags: [生活]
 media:
@@ -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

@@ -33,7 +33,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/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

@@ -72,17 +72,23 @@ function isMedia(value: unknown): value is MediaItem[] {
   });
 }
 
-function normalizeThought(source: string, path: string, sha?: string): RepositoryThought | null {
+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);
   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" || !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 +96,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,7 +114,6 @@ function serializeThought(thought: {
 }) {
   return matter.stringify(thought.content.trim().concat("\n"), {
     title: thought.title,
-    slug: thought.slug,
     date: thought.date ?? new Date().toISOString(),
     tags: thought.tags,
     mediaType: thought.media[0]?.type ?? "text",
@@ -227,7 +232,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.4",
   "private": false,
   "description": "用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。",
   "license": "MIT",

package/scripts/build-content.mjs

@@ -71,12 +71,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 +86,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 +255,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,6 +290,7 @@ 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;
 
   return {
     ...data,
@@ -301,7 +306,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)
@@ -399,7 +407,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) => {
@@ -487,7 +495,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

@@ -39,7 +39,6 @@ async function main() {
   const markdown = [
     "---",
     `title: ${JSON.stringify(title)}`,
-    `slug: ${slug}`,
     `date: ${date}`,
     `description: ${JSON.stringify("请填写一句话摘要。")}`,
     `topic: ${JSON.stringify(topic)}`,