写作规范

本规范分为两大部分：排版格式（如何写）和内容策略（写什么）。前者确保视觉一致，后者确保知识质量。

本规范参考了 OI Wiki 格式手册、中文技术文档写作风格指南以及中文文案排版指北。

---

第一部分：排版格式

1. 空格

中英文混排时正确使用空格是中文技术文档可读性的基础。

1.1 中英文之间需要增加空格

推荐：使用 BWA 进行比对时，需要先构建索引。

不推荐：使用BWA进行比对时，需要先构建索引。

1.2 中文与数字之间需要增加空格

推荐：Illumina 短读长通常为 150 bp。

不推荐：Illumina 短读长通常为150 bp。

1.3 数字与单位之间需要增加空格

推荐：人类基因组大小约为 3.2 Gb。

不推荐：人类基因组大小约为 3.2Gb。

例外：度数、百分号等与数字之间不加空格，如 90%、45°。

1.4 全角标点与其他字符之间不加空格

推荐：BWA 使用 BWT 算法，速度很快。

不推荐：BWA 使用 BWT 算法 ，速度很快 。

1.5 行内代码前后加空格

推荐：运行 samtools sort 命令后，输出为排序后的 BAM 文件。

不推荐：运行samtools sort命令后，输出为排序后的BAM文件。

2. 标点符号

2.1 中文正文使用全角标点

正文使用全角中文标点（，。；：？！""''（）），不要使用半角标点。

推荐：动态规划的核心思想是：将大问题分解为子问题，逐步求解。

不推荐：动态规划的核心思想是:将大问题分解为子问题,逐步求解.

2.2 英文整句使用半角标点

如果一段文字完全是英文（如引用原文、公式说明），使用半角标点并在后面加空格。

2.3 正确使用引号

• 中文语境使用直角引号「」和『』，或使用中文双引号""和单引号''。
• 不要使用英文引号 "..." 表示中文引用。

2.4 列表项末尾的标点

• 列表项是完整句子时，使用句号结尾。
• 列表项是短语或片段时，统一不加句号，或统一加分号并在末项加句号。
• 同一层级的列表项应保持标点风格一致。

3. 中英文混排

3.1 术语首次出现的标注方式

关键术语首次出现时使用"中文（English, 缩写）"格式：

隐马尔可夫模型（Hidden Markov Model, HMM）是一种常见的概率图模型。

后续出现可以直接使用中文名或缩写。

3.2 保留英文的情况

以下名词不需要翻译，直接使用英文：

• 软件与工具名：BWA、GATK、samtools、BLAST
• 文件格式：FASTQ、BAM、VCF、BED、GFF
• 数据库：NCBI、Ensembl、UniProt、UCSC
• 经典算法专名：Needleman-Wunsch、Smith-Waterman、Viterbi
• 广泛使用的缩写：DNA、RNA、NGS、WGS、SNP、Indel

3.3 一页内保持译法一致

同一个术语在一篇文章中只使用一种翻译。如果有多种常见译法，在首次出现时说明，之后统一使用主译法。

推荐：覆盖度（coverage，也称测序深度）描述了……后文统一使用"覆盖度"。

不推荐：前半段用"覆盖度"，后半段又改称"测序深度"，读者无法确认是否是同一概念。

4. Markdown 语法

4.1 标题

• 只使用二级（##）、三级（###）和四级（####）标题。一级标题由 frontmatter 的 title 自动生成。
• 标题不要使用标点符号结尾。
• 标题中不要写 LaTeX 公式。
• # 后面加一个空格再写标题文字。
• 标题前后各保留一个空行。

推荐：

## 动态规划矩阵

### 递推公式

不推荐：

##动态规划矩阵。
###递推公式

4.2 列表

• 列表前后各保留一个空行。
• 有序列表的序号后面加一个空格：1. 内容。
• 无序列表使用 - 而非 *。
• 列表嵌套时缩进 2 或 4 个空格，保持全文一致。

4.3 代码块

• 代码块使用三个反引号，并标注语言类型。
• 行内代码用单个反引号包裹，前后加空格。
• 代码块前后各保留一个空行。

推荐：

```bash
samtools sort input.bam -o sorted.bam
```

不推荐：

```
samtools sort input.bam -o sorted.bam
```

4.4 公式

• 行间公式使用独立的 $$ 块，前后各保留一个空行。
• 行内公式使用 $...$，不要用行间格式写行内公式。
• 公式后必须紧跟自然语言解释，不要只给符号不给含义。

推荐：

递推关系为：

$$
F(i,j) = \max\{F(i-1,j-1) + s(x_i, y_j),\; F(i-1,j) + g,\; F(i,j-1) + g\}
$$

其中 $s(x_i, y_j)$ 是替换得分，$g$ 是 gap 罚分。

4.5 图片

• 使用 <figure> + <figcaption> 标签，提供清晰的描述。
• 始终包含有意义的 alt 文本。
• 图片文件放在 public/img/illustrations/（示意图）或 public/img/figures/（成品图）。
• 文件名使用小写英文和连字符，如 sequencing-by-synthesis.svg。

4.6 表格

• 表格适合用于比较不同策略、算法、格式等结构化信息。
• 表头简洁明确，每列有明确的比较维度。
• 如果一个对比会在多篇页面重复出现，优先使用可复用组件。

4.7 链接

• markdown 链接：用相对路径（如 ../core-methods/alignment/edit-distance），由 Astro 原生解析。不要写绝对路径，否则在带 base 前缀的生产环境会 404。
• 组件 to: / href: 字段：用无前缀绝对路径（如 /core-methods/alignment/edit-distance），由 link-utils.ts 统一拼接 base 前缀。不要硬编码 /wiki-bioinfo/。
• 链接文字应该是有描述性的名词，不要使用"点击这里"。
• 外链优先指向论文主页、官方文档或可信数据库。

推荐：详见编辑距离页面。

不推荐：点击这里查看编辑距离。

5. 文件与命名

• 文件名使用小写英文，以连字符 - 分隔单词，如 needleman-wunsch.mdx。
• 默认使用 .mdx 格式；仅纯文本无组件导入的页面才用 .md。
• 每个文件必须包含 frontmatter，至少有 title 和 description。

---
title: "Needleman-Wunsch 算法"
description: Needleman-Wunsch 算法的动态规划递推公式、回溯与完整实例。
---

---

第二部分：内容策略

6. 写作原则

6.1 问题优先，而非工具优先

每篇文章都应从"要解决什么问题"开始，而非从"某个工具怎么用"开始。让读者先理解动机，再进入方法。

6.2 解释关系，而非堆砌术语

不要只给定义，要解释概念之间的联系。读者需要知道的是：这个方法和上游数据、下游流程如何连接。

6.3 避免翻译腔

以下表达在中文技术文档中属于翻译腔，应改用更自然的中文：

| 翻译腔 | 改用 | |--------|------| | "是一个……的存在" | "是……" | | "被用来做 X" | "用于 X" | | "需要注意的是" | "注意" | | "它被设计为" | "它旨在" | | "在……的情况下" | "当……时" | | "基于……的基础上" | "基于……" | | "起到了……的作用" | "起……作用" | | "给出了一个……的例子" | "举一个……的例子" | | "对于 X 来说" | "对 X" | | "正如我们所看到的" | "如上所示" | | "这并不令人惊讶" | 删除，直接陈述 | | "值得注意的是" | 直接陈述要点（如确需强调，每篇至多一次） |

6.4 每篇文章的核心要素

无论哪种类型的页面，都应包含以下要素：

| 要素 | 说明 | |------|------| | 问题定义 | 这篇文章在解决什么问题 | | 动机 | 为什么这个问题值得讲 | | 核心内容 | 模型、算法、概念或流程的核心解释 | | 实例或图示 | 至少一个 worked example、流程图或对比表 | | 局限与前提 | 方法成立的条件、常见误区 | | 交叉链接 | 前置知识、后续阅读、相关页面 |

6.5 先判断内容层级

写新页面前，先判断它主要属于哪一层：

| 层级 | 内容 | 示例 | |------|------|------| | 对象层 | 生物学基础对象与数据表示 | reads、参考基因组、注释、文件格式 | | 模型层 | 抽象计算模型 | 字符串、动态规划、图、概率模型 | | 算法层 | 核心算法方法 | 比对、组装、索引、基因预测 | | 流程层 | 实际分析工作流 | DNA-seq、RNA-seq、宏基因组 | | 资源层 | 数据资源与工具映射 | 数据库、版本选择、工具原理 |

如果一篇页面跨多层，主页面聚焦一层，其他层通过"相关页面"桥接。

7. 页面类型

根据内容性质，页面分为四种类型。以下是各类型的核心章节（必选）和可选章节：

7.1 概念页

适合基础对象、数据库资源、数据格式、术语说明。

• 核心章节：是什么 → 为什么重要 → 核心概念 → 相关页面
• 可选章节：应用场景、常见误区、参考资料

7.2 算法页

适合编辑距离、比对、索引结构、HMM 等核心方法。

• 核心章节：是什么 → 要解决什么问题 → 数学模型 → worked example → 相关页面
• 可选章节：输入与输出、复杂度与适用前提、与真实工具的连接、常见误区、参考资料

7.3 流程页

适合 RNA-seq、variant calling、宏基因组等分析流程。

• 核心章节：任务目标 → 步骤总览 → 每步说明 → 相关页面
• 可选章节：输入输出、前置知识、常见错误、worked example、后续阅读

7.4 板块入口页

适合一个大板块的入口导航。

• 核心章节：PageHeaderMeta 导读 → 本板块概述 → 子主题导航 → 与其他板块的连接
• 可选章节：学习前置、推荐阅读顺序
• 七个顶级板块入口页均使用 PageHeaderMeta（传入 audience 与 startWith）；子板块入口页可按需选用。

8. MDX 与组件

默认使用 .mdx。仅当页面是纯文本且不导入任何组件时，才使用 .md。常见组件如下：

• 需要 NoteCard（variant="summary" 摘要 / variant="pitfalls" 误区 / variant="tools" 工具映射）
• 需要 PrerequisitesBox（前置知识）
• 需要 DataTable（variant="comparison" 对比 / variant="decision-matrix" 决策矩阵）
• 需要 LinkGrid（variant="navigation" 导航网格 / variant="related" 相关页面卡片）
• 需要 DefinitionList（术语/定义列表）
• 需要 PageHeaderMeta（板块顶级入口页头部导读，自动推断所属板块；子板块入口与专题页可选）
• 需要 WorkflowSteps（流程页的步骤总览）

新增 MDX 页面时，优先复用 src/components/docs/ 中已有组件。不要为单个页面发明一次性的样式方案。

9. 代码与命令

• 命令必须能直接运行，或明确标注需要替换的部分（如 <your-file.fastq>）。
• 示例输入输出尽量简短，突出要点。
• 对算法页：伪代码和矩阵示意通常比完整实现更重要。
• 对流程页：命令只是辅助，重点是解释为什么要做这一步。
• 代码块必须标注语言类型。

10. 引用与参考资料

• 引用教材和论文时写明完整信息：作者、年份、书名/论文名、出版社/期刊。
• 外链优先指向论文原文、官方文档或可信数据库（NCBI、Ensembl 等）。
• 每个核心页面末尾应有"相关页面"章节，建立站内知识网络。
• 板块入口页应主动链接所有子页面，而不只是依赖 sidebar。

---

第三部分：快速参考

排版速查表

| 场景 | 推荐写法 | 不推荐写法 | |------|----------|------------| | 中英文之间 | 使用 BWA 进行比对 | 使用BWA进行比对 | | 中文与数字之间 | 通常为 150 bp | 通常为150 bp | | 术语首次出现 | 覆盖度（coverage） | 覆盖度（Coverage） | | 标题格式 | ## 动态规划矩阵 | ##动态规划矩阵。 | | 代码块 | ```bash | ``` | | 站内链接 | 详见[编辑距离](../core-methods/alignment/edit-distance) | 点击[这里](...)查看 | | 标点符号 | 分解为子问题，逐步求解。 | 分解为子问题,逐步求解. | | 文件名 | needleman-wunsch.mdx | NeedlemanWunsch.mdx |

页面自检清单

发布前快速过一遍：

• [ ] frontmatter 包含 title 和 description
• [ ] 文章从"为什么"开始，而非从"怎么做"开始
• [ ] 关键术语首次出现附英文
• [ ] 中英文之间有空格
• [ ] 代码块标注了语言
• [ ] 图片有 alt 文本
• [ ] 包含"相关页面"章节
• [ ] npm run check 通过

---

相关页面

导论

知识库设计理念与组织原则

延伸阅读

如何贡献

贡献流程与技术细节

延伸阅读

学习路线

推荐的学习路径

延伸阅读