内容写作规范

这套规范适用于站内所有以 Markdown 编写的正文，包括文章、文档与项目说明。每种格式先表达清晰的内容关系，再由主题负责统一视觉呈现。

使用原则

先判断一段内容承担什么作用：划分章节、提出结论、解释原因、列出步骤、保留原话，还是补充次要材料。确定语义后再选择格式，不要仅因为某种样式“更醒目”就使用它。

页面起点

每页先写 Frontmatter，再写一个且仅一个一级标题。title 用于浏览器标题、站内搜索和分享卡片；description 用一句完整的话交代主题、范围或读者能获得什么。

集合与项目入口页使用 pageType: index，通过共享的 CatalogHeader 组件生成唯一的一级标题和导语，不再重复写 Markdown 一级标题。这些页面关闭侧栏目录，使用一致的宽版布局；文章和文档正文继续遵循下方的阅读排版规则。

Excerpts 条目不设正文标题，也不添加隐藏标题。Frontmatter 的 title 仅以 Excerpt YYYY-MM-DD-NN 作为英文内部标号；分享图不展示该标号、日期标题或含编号的网址，保留正文、出处与原文二维码。

署名、日期和机构信息较多的长文可使用 ArticleHeader 包裹原有一级标题、导语、作者和日期；机构、邮箱等补充信息放入其 details 插槽。组件只在页面显式使用时出现，不添加空元数据。详情使用原生折叠语义，分享长图会完整展开；不得删改署名或原始资料信息。可参考私人约定的边界与对抗自由的写法。

---
title: 为个人文档站新增全文搜索
description: 记录搜索功能的选型、接入步骤和发布后的验证结果。
---

# 为个人文档站新增全文搜索

本文说明为什么选择本地搜索索引、如何接入搜索入口，以及发布后需要验证的键盘操作和移动端表现。

Frontmatter 中的 title 与正文一级标题应保持一致；若为了行文自然调整措辞，两者仍须指向同一主题。
description 不写“这是一个关于……的页面”之类空泛句式，应直接说明内容，例如“比较三种备份方案的成本、恢复时间与适用范围”。
页面语言不是简体中文时，增加 lang，例如 lang: en 或 lang: ja。
不用粗体段落模拟标题，也不为了获得更小的字号而跳过标题层级。

Mermaid 图表

用带 mermaid 语言标记的代码块表达流程、时序或结构关系。图表前后仍应有文字解释，并用 accTitle 和 accDescr 提供可访问的标题与说明。图表会随明暗主题变化，也会保留在文章的全文长图中。

下面的流程表示从撰写到验证的三个步骤：

Rendering diagram…

View Mermaid source

flowchart TD
  accTitle: 文档编写流程
  accDescr: 先撰写 Markdown，再预览图表，最后检查内容与导出结果。
  A[撰写 Markdown] --> B[预览图表]
  B --> C[检查内容与导出]

时序图适合说明多个参与者之间的先后关系：

Rendering diagram…

View Mermaid source

sequenceDiagram
  accTitle: 阅读文档的交互
  accDescr: 读者打开文档，网站返回正文与图表。
  participant R as 读者
  participant S as 网站
  R->>S: 打开文档
  S-->>R: 显示正文与图表

点击图表下方的“查看 Mermaid 源码”可以阅读其写法；展示语法示例时，将代码块嵌入更长的 Markdown 围栏，避免示例本身被绘制。
优先使用纵向流程，控制节点数量和标签长度。宽图可横向滚动，但全文长图会缩放至正文宽度，复杂图应拆分。
使用站点统一配色，不在图表内覆盖主题、安全设置或嵌入 HTML、外部图片；语法错误会显示提示并保留源码。

标题与段落

二级标题划分文章的主要部分，三级标题拆分其中的问题、方案或步骤。四至六级标题只在内容确实复杂时使用；若连续出现很多低层级标题，通常应先拆分章节或新建页面。

## 搜索方案与实现

本节先比较可选方案，再说明最终实现。

### 为什么选择本地索引

站点规模有限，索引可以随构建产物一起发布，查询也不必依赖外部服务。

#### 索引更新时机

正文发生变化后重新运行生产构建，确保标题、摘要和正文进入最新索引。

展示效果

为什么选择本地索引

站内资料规模有限，索引可以随构建产物一起发布。查询在浏览器中完成，不需要把读者输入发送到第三方服务。

索引更新时机

正文发生变化后重新运行生产构建，确保标题、摘要和正文进入最新索引。

多语言内容的分词

简体中文与英文可以沿用默认规则；其他语种上线前，应使用真实关键词检查搜索结果是否完整。

日文页面的回退策略

若较长词语无法命中，可以补充清楚的页面摘要或常用同义表达，而不是堆砌隐藏关键词。

导语回答“本文解决什么问题”和“谁需要阅读”。普通段落一次集中完成一项任务，例如提出判断、解释原因、给出证据或说明限制。段落之间留一个空行；只有诗歌、地址或逐行对应的文本才使用   强制换行，不用连续空格或多个空行制造间距。

行内文本

行内格式只标记局部语义。若同一段同时出现粗体、斜体、高亮和多个代码片段，应先检查信息是否可以拆成更清楚的句子或列表。

**发布前必须通过站内链接检查**；*渐进增强*是本次实现采用的设计原则。

~~旧版手动索引流程已停用~~；<mark>移动端搜索入口</mark>仍需在真机上复核。

配置文件位于 `docs/.vitepress/config.mts`；按 <kbd>Ctrl</kbd> + <kbd>K</kbd> 打开搜索。

<abbr title="Accessible Rich Internet Applications">ARIA</abbr> 属性用于补充无障碍语义。
CO<sub>2</sub> 中的 2 是下标，m<sup>2</sup> 中的 2 是上标。

<small>示例数据更新于 2026 年 7 月 19 日。</small>

展示效果

发布前必须通过站内链接检查；渐进增强是本次实现采用的设计原则。

~~旧版手动索引流程已停用~~；移动端搜索入口仍需在真机上复核。

配置文件位于 docs/.vitepress/config.mts；按 Ctrl + K 打开搜索。

ARIA 属性用于补充无障碍语义。CO₂ 中的 2 是下标，m² 中的 2 是上标。

示例数据更新于 2026 年 7 月 19 日。

粗体用于关键结论、明确风险或必须完成的动作，不用于给普通名词增加视觉重量。
斜体用于首次引入的术语、外文词语或轻微语气强调；中文正文中应克制使用。
高亮标出当前需要定位或复核的词句，不能代替标题或长期强调。
行内代码只包裹命令、文件名、参数、字段和值，不包裹普通中文概念。
~~删除线~~用于保留仍有解释价值的旧说法；正式改写且无需展示修订过程时，直接删除原文。
小号文字用于更新时间、来源补充或版权说明等辅助信息，不承载关键结论。
缩写首次出现时可用 <abbr> 给出全称；上标和下标只用于原本就需要这些位置关系的记号。

Markdown 的 **粗体** 会自动生成带荧光底纹的行内文字层，作者无需手动添加标签。底纹跟随文字换行，不铺满段落或容器。原生 HTML 的  默认仅加粗；确需同样的荧光强调时，使用 重点文字。

组件标题、版本号和元数据使用专用元素与类名控制层级，例如同步提示标题的 、版本号的 。text-emphasis 只用于包住文字的行内层，不承担 Flex、Grid 或整行布局，也不设置宽高。调整正文样式后，应检查长句换行、嵌套链接与行内代码，以及桌面和窄屏、明暗主题下的提示标题和版本号。

链接

链接文字脱离上下文后也应能说明去向。优先写页面名、资料名或动作目标，避免连续使用“这里”“详情”“点击查看”。

发布前，先按[站点维护流程](/guide/getting-started)运行本地检查，再核对线上页面。

展示效果

发布前，先按站点维护流程运行本地检查，再核对线上页面。

站内页面使用以 / 开头的路径，外部资料使用完整网址。若链接会下载文件、打开新窗口或跳转到站外，应在链接文字或相邻句子中提前说明；同一段内不要让多个链接都使用相同的模糊名称。

列表

无序列表表示并列项目，有序列表表示必须依次完成的步骤或明确的优先级。每个列表项应保持相近的语法结构，不要把名词、命令和长段解释随意混在同一层。

- 核对页面标题与摘要是否准确
- 检查页面中的全部链接
  - 站内链接指向现有路由
  - 外部链接可以正常访问
- 在桌面端与手机宽度下阅读全文

1. 运行 `npm run check`
2. 打开生产预览并检查关键页面
3. 发布后重新验证公开网址

展示效果

核对页面标题与摘要是否准确
检查页面中的全部链接
- 站内链接指向现有路由
- 外部链接可以正常访问
在桌面端与手机宽度下阅读全文

运行 npm run check
打开生产预览并检查关键页面
发布后重新验证公开网址

短语式列表可以不加句号。只要任一项是完整句子、包含多个分句或需要解释原因，所有列表项就应使用一致的句末标点。嵌套列表只表示真实的从属关系，通常不超过两层。

引用与出处

短引用可直接写在正文中并加引号；原话需要独立呈现时使用引用块。引用不是普通段落的装饰，应尽量同时给出作者、作品、日期或链接，让读者能够核对来源。

html

<blockquote>
  <p>每种格式先表达清晰的内容关系，再由主题负责统一视觉呈现。</p>
  <footer>— <cite><a href="/guide/writing-style">《正文写作与排版规范》</a></cite></footer>
</blockquote>

展示效果

每种格式先表达清晰的内容关系，再由主题负责统一视觉呈现。
— 《正文写作与排版规范》

转述他人观点时不要使用引号，也不要改写后仍称为“原话”。引用其他语言时，在容器或段落上写明语言，例如 <blockquote lang="en">。无法核验的“网传”内容不作为正式出处。

代码

短命令、参数和文件名使用行内代码。多行代码使用围栏代码块，并写明语言，以获得语法高亮、复制按钮和准确的纯文本内容。

运行 `npm run docs:build` 生成生产版本。

```js
const article = {
  title: "为个人文档站新增全文搜索",
  description: "记录搜索功能的选型、接入步骤和验证结果。",
  status: "ready"
};

export default article;
```

展示效果

运行 npm run docs:build 生成生产版本。

const article = {
  title: "为个人文档站新增全文搜索",
  description: "记录搜索功能的选型、接入步骤和验证结果。",
  status: "ready"
};

export default article;

代码块只放可以选择和复制的文本，不用截图代替代码。
文件名、运行位置和前置条件写在代码块前，不混入需要删除后才能执行的提示文字。
示例省略内容时，用注释或正文明确说明省略了什么，避免读者复制后得到无法解释的错误。
命令与输出分别使用 bash、powershell、text 等合适的代码块，不把两者混在一起。

数学公式

数学变量和短公式使用 $...$ ，独立公式使用单独成行的 $$...$$。公式由 VitePress 的 MathJax3 在构建时渲染；代码、命令、金额和用于展示语法的示例仍保留原来的语义，不批量替换反引号或美元符号。

当 $a \ne 0$ 时：

$$
x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}
$$

矩阵使用 pmatrix 等 LaTeX 环境，分数使用 \frac。引用块中的公式仍需在每行前保留 >，并在公式前后留空行。长公式在自身区域横向滚动；不要缩小整段正文字号，也不要强制压缩公式宽度。

以数学偶拾基准页检查行内基线、映射、列矩阵、分数和多点坐标。其他页面按实际数学语义逐篇迁移，每次核对原式，并检查桌面、手机和明暗主题下的显示。

表格

表格适合比较字段一致、列数稳定的信息。叙述、步骤或长段论证应改用正文与列表；列较多时还要确认窄屏可以在表格内部横向滚动，而不是让整页溢出。

| 内容关系 | 推荐格式 | 选择理由 |
| --- | --- | --- |
| 一组同级检查项 | 无序列表 | 不暗示先后顺序 |
| 必须依次完成的发布流程 | 有序列表 | 读者可以按步骤跟踪进度 |
| 三种方案的成本、风险与限制 | 表格 | 字段一致，便于横向比较 |
| 来源明确的一段原话 | 引用块 | 同时保留内容与出处 |

展示效果

内容关系	推荐格式	选择理由
一组同级检查项	无序列表	不暗示先后顺序
必须依次完成的发布流程	有序列表	读者可以按步骤跟踪进度
三种方案的成本、风险与限制	表格	字段一致，便于横向比较
来源明确的一段原话	引用块	同时保留内容与出处

表头应能独立说明每列含义，同一列使用相同的数据类型和表达方式。单元格内容超过两三句话、需要多层列表或依赖阅读顺序时，说明这组信息不再适合表格。

术语与定义

连续解释多个术语时，可以使用语义化的定义列表。它需要少量 HTML，但比“加粗词语 + 普通段落”更准确，也便于辅助技术识别术语与释义的关系。

html

<dl>
  <dt>页面摘要</dt>
  <dd>用一句完整的话概括页面主题、范围或读者可以获得的结果。</dd>
  <dt>替代文本</dt>
  <dd>在图片无法显示或读者使用读屏软件时，传达图片所含关键信息的文字。</dd>
</dl>

展示效果

页面摘要: 用一句完整的话概括页面主题、范围或读者可以获得的结果。
替代文本: 在图片无法显示或读者使用读屏软件时，传达图片所含关键信息的文字。

术语名称保持简短，释义先说明“它是什么”，再补充用途或边界。若只解释一个词，直接在正文首次出现处说明即可，不必单独建立定义列表。

提示块

提示块用于把正文之外的背景、建议、注意事项和严重风险分级。标题应直接说明提示内容，不要只写“注意”或“说明”，也不要让整篇文章被彩色块切碎。

::: info 示例环境
下列命令都在仓库根目录运行，示例使用 Windows PowerShell。
:::

::: tip 提交前运行完整检查
先运行 `npm run check`，再打开生产预览；两项都通过后再准备发布。
:::

::: warning 标题层级不是字号工具
把整段文字加粗并不会创建可导航的标题；需要新层级时，请使用连续的 Markdown 标题。
:::

::: danger 覆盖操作可能丢失内容
执行会覆盖文件或改写历史的命令前，先确认目标路径、当前分支和未提交修改，并保留可恢复的副本。
:::

展示效果

示例环境

下列命令都在仓库根目录运行，示例使用 Windows PowerShell。

提交前运行完整检查

先运行 npm run check，再打开生产预览；两项都通过后再准备发布。

标题层级不是字号工具

把整段文字加粗并不会创建可导航的标题；需要新层级时，请使用连续的 Markdown 标题。

覆盖操作可能丢失内容

执行会覆盖文件或改写历史的命令前，先确认目标路径、当前分支和未提交修改，并保留可恢复的副本。

折叠内容与分隔线

补充材料会打断主线、但部分读者仍可能需要时，使用折叠内容。本站统一使用原生 <details> 与 <summary>，使它与项目文章中的折叠列表保持相同的上下分隔线和展开标记。摘要应预告展开后能看到什么，例如“展开查看移动端验收记录”，不要只写“更多”或“详情”。

<details>
<summary>展开查看移动端验收记录</summary>

| 验收项 | 结果与说明 |
| --- | --- |
| 390 px 窄屏 | 通过。正文和表格均无页面级横向溢出。 |
| 键盘操作 | 通过。`Tab` 可聚焦摘要，`Enter` 可展开或收起。 |
| 深色模式 | 通过。标题、边框和正文层级清晰。 |

</details>

上方内容完成一次功能验收。

---

下方内容转入新的发布阶段。

展示效果

展开查看移动端验收记录

验收项	结果与说明
390 px 窄屏	通过。正文和表格均无页面级横向溢出。
键盘操作	通过。`Tab` 可聚焦摘要，`Enter` 可展开或收起。
深色模式	通过。标题、边框和正文层级清晰。

上方内容完成一次功能验收。

下方内容转入新的发布阶段。

<summary> 后和 </details> 前各保留一个空行，内部的 Markdown 列表、表格和代码才能稳定解析。分隔线只表示明显的场景转换；若下方内容仍属于同一论述，应继续使用段落，而不是插入分隔线。

图片、图注与无障碍文本

图片必须有能替代其信息的 alt 文本；只有不传达任何信息的纯装饰图片才使用空的 alt=""。替代文本说明图片中与上下文有关的内容，图注则解释读者为什么要看这张图、应注意什么结果。

html

<figure>
  <img
    src="/images/search-mobile.webp"
    alt="手机端搜索面板打开后，输入框位于顶部，下方按页面标题列出三条搜索结果"
  >
  <figcaption>390 px 窄屏下，搜索结果保持单列排列，标题和摘要均完整可读。</figcaption>
</figure>

不写“图片”“截图”或文件名作为替代文本，除非图片类型本身就是内容的一部分。
图表的替代文本先说结论，再补充关键数值；复杂数据仍应在正文或表格中提供。
截图中的关键报错、按钮名称和操作结果要在正文中复述，不能让信息只存在于像素里。
大图发布前压缩到合适尺寸，并检查手机宽度下是否会溢出、变形或小到无法辨认。

同步内容与来源

直接来自其他仓库的项目说明与维护文档采用“同步”模式，不在本站另存一份独立改写的正文。内容事实、章节增删和版本信息先在上游维护；本站导入时只改写链接、补充导航与来源信息，并把列表、折叠内容等语法适配到当前排版规范。

每个同步页面都要显示上游仓库、精确源文件、锁定的 commit 和同步时间，让读者能够核对当前内容。
页面需明确说明“内容修改先进入上游”，避免读者把本站生成文件误认为另一份手工维护的副本。
格式适配不得改变原文结论、版本号、命令、协议字符串或多语言内容；若原文表达本身需要修改，应回到上游提交。
不直接编辑生成目录。同步规则发生变化时，修改导入器并重新生成全部页面，确保下一次同步仍能得到相同结构。

同步不是照搬

“同步”保留上游内容的维护权与可追溯性，也允许本站统一展示格式；“照搬”则会产生无法自动更新、来源边界不清的静态副本。项目文档必须采用前一种方式。

发布前检查

页面标题和摘要准确描述实际内容，不含“页面标题”“一句话说明”等占位文字。
页面只有一个一级标题，标题层级连续，目录单独阅读也能看懂文章结构。
每段集中表达一个中心意思；列表、表格、引用和提示块各自承担合适的信息关系。
粗体、斜体、高亮和小号文字均有明确语义，没有同时争夺注意力。
链接文字能说明去向；引语与转述区分清楚，能够核对来源。
命令和代码可复制，代码块标明语言，省略内容与运行前提已经说明。
折叠摘要能预告内部内容，重要结论没有被藏在默认收起的区域。
图片具有有效替代文本，图注提供上下文而不是重复文件名。
同步页面指向锁定 commit 的精确源文件，格式适配没有改写上游事实。
在桌面与手机宽度、浅色与深色主题下都能顺畅阅读和操作。

内容写作规范 ​

页面起点 ​

Mermaid 图表 ​

标题与段落 ​

为什么选择本地索引

索引更新时机

多语言内容的分词

日文页面的回退策略

行内文本 ​

链接 ​

列表 ​

引用与出处 ​

代码 ​

数学公式 ​

表格 ​

术语与定义 ​

提示块 ​

折叠内容与分隔线 ​

图片、图注与无障碍文本 ​

同步内容与来源 ​

发布前检查 ​

内容写作规范

页面起点

Mermaid 图表

标题与段落

行内文本

链接

列表

引用与出处

代码

数学公式

表格

术语与定义

提示块

折叠内容与分隔线

图片、图注与无障碍文本

同步内容与来源

发布前检查