如何添加一篇文档

新建文件

在 src/content/docs/ 下新建一个 .md 文件。文件名会成为 URL：

src/content/docs/my-note.md  →  /docs/my-note/

子目录同样有效，路径会保留：src/content/docs/work/report.md → /docs/work/report/。

填写 frontmatter

每篇文档的开头需要四个字段：

---
title: 文档标题
description: 一句话摘要，会显示在索引与搜索结果里
category: 分类名
updated: 2026-09-23
---

字段	必填	说明
title	是	索引与搜索结果中显示的标题
description	是	一句话摘要，索引行与页面 lede 都用它
category	是	分类名，首页与页脚按它分组
updated	是	更新日期，索引按此倒序排列
draft	否	设为 true 时不进入索引与搜索

插入本地图片

两种方式，按图片存放位置二选一：

1. 图片随文档放（推荐） —— 图片存在 src/content/docs/ 下、与 .md 同目录，正文用标准 Markdown 图片语法 + 相对路径：

![截图](./architecture.png)

Astro 会自动处理并优化 src/ 下的图片（压缩、哈希、打包）。文档和它的图放在同一个目录，移动文档时图跟着走：

src/content/docs/
  how-to-add-a-doc.md
  architecture.png     ← 同目录，./architecture.png 引用

2. 图片放 public/ —— 全站共享、不需要优化的图（如 me.JPG），正文用根路径引用：

![头像](/me.JPG)

public/ 下的文件原样拷贝，不做处理。

需要图注时用 figure 包起来（HTML 直接写在正文里即可）：

<figure>
  <img src="./architecture.png" alt="架构图" />
  <figcaption>一句话说明</figcaption>
</figure>

预览与发布

astro dev --background   # 本地预览
astro dev logs           # 查看日志

内容改动随构建重新生成静态页面，部署到 Cloudflare Workers 即可上线。