AI 生成说明： 本文由 AI 根据本站当前源码与主题实现整理生成，并经核验。功能随站点更新可能变化；发文前请仍以本地 npm run build 的结果为准。

Markdown 作者手册

这份手册对应 Rst307 个人网站当前的 Astro 实现。它面向直接写 Markdown 的作者：哪些内容由网站自动完成、哪些必须由作者写在文件里，以及发文前如何自检。

先选文章类型

类型	放置目录	必用布局	自动能力
博客	src/content/blog/	不需要填写 layout	标签、RSS、阅读时长、H2 目录、相邻文章、代码工具栏、回到顶部、图片灯箱
十三班书斋	src/content/library/	不需要填写 layout	文学主题、日期、作者/诗人信息、图片灯箱

本站使用 Content Collections 校验 frontmatter。draft: true 和发布日期晚于构建时刻的文章在开发和生产构建中都会被排除：不会生成 URL、列表、标签页、RSS 或相邻文章。

新建博客文件请放在 src/content/blog/，书斋文件请放在 src/content/library/。frontmatter 不再填写 layout；日期推荐 ISO 8601，例如 2026-07-20T20:30:00+08:00。正文图片若需要优化，请将图片和 Markdown 放在同一内容目录，以相对路径引用，例如 ![说明](./图片.png)；Astro 会在构建时生成响应式 WebP，并自动生成极小模糊预览、懒加载后淡入高清图；作者无需手写占位 HTML，灯箱始终使用清晰大图。

文件名决定 URL。例如 src/content/blog/my-note.md 对应 /blog/posts/my-note/；你好，世界.md 会生成中文 URL。中文文件名可以用，但建议使用简短、稳定的中文或英文文件名；避免空格、#、?、%、/ 等字符，改名会改变旧链接。

博客模板

新建 src/content/blog/你的文件名.md，复制后填写：

---
title: "文章标题"
date: 2026-07-20T20:30:00+08:00
update: 2026-07-21T09:15:00+08:00
description: "用一句话说明这篇文章写什么。"
tags:
  - 随笔
  - 建站
draft: false
---

开头用一两段说明文章内容。

## 第一节

这里会自动进入文章目录。

### 细节标题

`###` 只留在正文中，不会进入本站博客目录。

```bash
/create <完整中文标题> <author-slug> [可选参数]
```

![这里是图片的文字说明](https://example.com/image.png "可选图片标题")

update 是可选字段；首次发布且未修改时，可以删除这一行。

书斋模板

新建 src/content/library/你的文件名.md，poet 和 author 二选一即可。诗词推荐用 poet，其他投稿可用 author。

---
title: "作品标题"
date: 2026-07-20T20:30:00+08:00
update: 2026-07-21T09:15:00+08:00
poet: "作者姓名"
description: "可选：作品的一句话说明。"
draft: false
---

正文从这里开始。

可以正常使用段落、强调、链接、图片、列表和引用。

书斋文章不会自动生成博客标签页、RSS、阅读时长、相邻文章或右侧目录；不要为了获得这些效果改用博客布局。

Frontmatter 字段

Frontmatter 是文件开头被 --- 包住的 YAML。title、date 是每篇文章必须写的字段；布局由文件所在集合自动决定，不再填写 layout。

字段	是否必填	类型	示例	实际用途
title	必填	字符串	"投稿机器人使用指南"	页面标题、列表标题、SEO 标题、RSS 标题
date	必填	ISO 8601 日期	2026-07-20T20:30:00+08:00	列表和文章日期；博客排序、RSS 时间、上一篇/下一篇都使用它
update	可选	ISO 8601 日期	2026-07-21T09:15:00+08:00	页面显示“更新时间”
description	建议填写	字符串	"本文介绍……"	SEO 描述；博客 RSS 项目的摘要。省略时博客用“标题 · Rst307 博客”，RSS 退回标题
tags	博客建议填写	字符串数组	- 工具	生成博客页标签、文章标签和 /blog/tags/标签名/ 静态标签页
poet	书斋可选	字符串	"殷健棋"	书斋显示“诗人：……”；优先级高于 author
author	书斋可选	字符串	"郑名然"	书斋显示“作者：……”；博客当前不在文章头部展示
draft	可选	布尔值	true	草稿不会生成任何页面、列表、RSS、标签页或相邻文章

日期请使用 ISO 8601 格式，例如 2026-07-20T20:30:00+08:00。不要只写模糊日期或混用不完整格式，否则 schema 校验、排序、RSS 时间和相邻文章可能不符合预期。

本站自动完成的事

博客目录与锚点

博客正文中的二级标题 ## 标题 会自动生成锚点，并进入目录。桌面端目录固定在右侧；移动端收在“目录”折叠控件内。# 主标题通常由 frontmatter 的 title 自动生成，### 和更深层标题不会进入目录。

不要手写一份目录，也不要手动猜锚点 URL。重复的 H2 标题会由 Markdown 处理器自动加后缀以避免冲突，但读者体验较差，建议同一篇文章的 H2 保持唯一。

标签、排序、RSS 与相邻文章

博客的 tags 必须写成 YAML 数组。标签名会原样出现在链接和静态路径中，建议使用 2 到 6 个稳定、简短的中文词，例如“随笔”“工具”“建站”；同义词请统一写法，避免“机器人”和“机器人相关”分散成两个标签。

博客按照 date 从新到旧排列。文章底部的“上一篇”是日期更旧的文章，“下一篇”是日期更新的文章。/rss.xml 只收录博客目录中的文章，不收录书斋文章；RSS 使用 description，未填写时使用标题。

阅读时长

博客列表和文章页自动显示“约 x 分钟”。本站按清理 Markdown 后的正文约每 400 个字符估算，至少为 1 分钟；代码块、行内代码、图片和大部分 Markdown 标记不计入估算。作者不用手填，也不需要在 frontmatter 加字段。

代码块与复制

用标准 Markdown 围栏，优先明确写语言：

```bash
/create <标题> <作者>
```

```python
print("hello")
```

```json
{ "title": "示例" }
```

当前站点用 Shiki 的 One Light / One Dark Pro 双主题。常用 bash、python、json、html、css、javascript、typescript 等语言会获得语义高亮。未标语言的围栏中，如果每行都是以 / 开头的机器人命令，本站会自动按 bash 高亮；流程图、说明文字等其他未标语言围栏会按纯文本显示。

每个代码块自动生成语言栏和复制图标，复制成功会变成勾选。不要手写复制按钮、代码框外壳或相关 HTML。行内代码用反引号：npm run build。

图片与灯箱

图片使用标准写法：

![图片说明：方舟动物园思维导图](https://example.com/map.png)

正文图片会自动具备灯箱：点击打开；滚轮或工具栏缩放；放大后可拖拽；双击重置；移动端支持双指缩放；按 Esc 关闭。图片替代文字会显示为灯箱说明，因此应具体描述图片内容，避免写“图”“图片”这类无信息文字。

优先使用稳定、可公开访问的 HTTPS 图片地址。外链图片可能失效、限流或跨地区无法加载；本站不会下载或镜像外链图片。需要长期保留的图片应放到受控的静态资源位置，再使用站内路径。

常用 Markdown

以下写法已经在本站现有文章中使用并正常渲染：

用途	写法
标题	## 二级标题、### 三级标题
段落	空一行分段
强调	**加粗**、*斜体*
链接	[链接文字](https://example.com)
悬停提示	[文字](^提示内容)
图片	
无序列表	- 项目
有序列表	1. 项目
引用	> 引用内容
分隔线	---
行内代码	`code`
代码块	```bash ... ```
表格	使用 `

本站当前配置没有引入 MDX 组件或自定义 Markdown 容器。不要假定 <Component />、::: warning、:::tip 之类写法可用。脚注、任务列表、删除线等未被本站文章模板专门验收；除非先在本地构建确认，否则不要把它们作为发布必需能力。

不要这样写

• 不要省略 title 或 date，也不要在 Content Collections 中填写旧的 layout 字段。
• 不要在博客正文手写目录、复制按钮、灯箱或回到顶部按钮；这些由站点自动提供。
• 不要把博客文章放进书斋目录，或把书斋文章放进博客目录后还期望原有 URL 不变。
• 不要把 tags 写成单个字符串，例如 tags: 随笔；应写成 YAML 数组。
• 不要给无意义代码块乱标语言。流程图/输出文字用不带语言的围栏；真实代码、命令才标注语言。
• 不要依赖未配置的 MDX、React 组件、自定义容器或未验证的扩展语法。
• 不要手写 markdown-tooltip 的 HTML 来模拟悬停提示；提示由 [文字](^内容) 自动生成。
• 不要用包含空格、保留符号或频繁变动的文件名；改文件名就是改 URL。

发布流程

以下命令适用于 Windows PowerShell。先在仓库根目录 D:\ImportantFileFolder\onlineSite 打开终端：

# 1. 新建或修改 Markdown 文件后，先构建
npm run build

# 2. 查看待提交内容
git status

# 3. 有意提交指定文章和文档
git add "src/content/blog/你的文件名.md"
git commit -m "feat(blog): 发布文章标题"

# 4. 推送到主分支，Netlify 会从 GitHub 自动构建部署
git push origin master

书斋文章只需把 git add 的路径换成 src/content/library/你的文件名.md。本地图片与文章放在同一内容目录时，Astro 会生成优化产物；构建成功不代表外链仍然可访问，发布前仍应检查外链。

常见问题

构建失败

先检查 frontmatter 的 YAML 缩进、引号和 --- 是否成对。tags 的每一项要比 tags: 多两个空格。再运行 npm run build，按终端给出的文件和行号修正。

标签页没有生成

确认文章位于 src/content/blog/，并把 tags 写成非空数组；同时确认没有 draft: true 且日期不在未来。标签页在构建时静态生成，修改后必须重新构建和部署。

博客目录没有出现

目录只读取 ##。确认文章中至少有一个非空的二级标题；###、加粗文字和手写链接都不会生成目录项。

代码没有高亮

给围栏补语言标识，例如 bash、python、json。机器人命令可不写语言，但只有每行都以 / 开头时才会自动按 Bash 处理。普通流程说明保持纯文本是预期行为。

图片打不开或点不开

先在浏览器单独打开图片 URL。确认使用 HTTPS、地址没有过期、服务器允许公开访问。图片若放在链接 <a> 内，本站默认不把它接入灯箱，以免覆盖原链接行为。

中文 URL 看起来被编码

浏览器地址栏可能显示百分号编码，这是正常的 URL 编码。不要因为显示编码就随意改文件名；只有需要改变链接时才改名，并同步更新站内引用。

每次发文前检查

• 文件位于正确的 src/content/blog/ 或 src/content/library/ 目录。
• title、date 已填写，日期使用 ISO 8601；需要暂不发布时填写 draft: true。
• 博客已填写一句清晰的 description 和统一的 tags；书斋已填写 poet 或 author。
• H2 结构清楚且不重复；没有手写目录。
• 真实代码都标了语言；命令、流程说明没有混用。
• 图片有准确 alt，外链在浏览器中可打开。
• 悬停提示写法正确：提示含空格或英文 ) 时使用了尖括号形式。
• npm run build 成功。
• git status 中只包含准备发布的文件，然后再 commit 和 push。

悬停提示（Tooltip）

Markdown 本身没有悬停提示，但本站支持一种接近链接的写法：把文字和目标写成链接形式，目标地址以 ^ 开头，鼠标悬停（或键盘聚焦、手机点按）时就会弹出提示气泡：

[什么是 RSS3](<^一个基于区块链的内容分发协议，RSS3 是 Rst307 名字的来源。>)

渲染后，触发文字带虚线下划线和小问号，提示气泡会显示在文字上方。例如把鼠标移到悬停提示^?这就是悬停提示的效果。这个词上，或手机点按它试试。规则如下：

• 提示内容只支持纯文本，不解析 Markdown，不要在里面嵌套 **加粗**、行内代码、图片等格式；触发文字本身也只按纯文本显示。
• 提示内容中出现英文右括号 ) 或空格（如中英文混排的“RSS3 是”）时，Markdown 会把它当成普通文字而不是链接；遇到这两种字符时，用尖括号包住整个目标：[文字](<^提示 (内容)>)。中文括号 （ ） 不受影响，纯中文提示可以直接写。
• 提示为空时不会生成悬停提示，只显示为普通文字。
• 悬停提示依赖本站样式，不要手写 markdown-tooltip 相关 HTML 来模拟效果。