写作规范

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

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

---

第一部分：排版格式

1. 空格

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

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

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

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

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

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

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

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

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

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

例外：度数、百分号等与数字之间不加空格，如 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 链接

• 站内链接使用相对路径。
• 链接文字应该是有描述性的名词，不要使用”点击这里”。
• 外链优先指向论文主页、官方文档或可信数据库。

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

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

5. 文件与命名

• 文件名使用小写英文，以连字符 - 分隔单词，如 needleman-wunsch.mdx。
• 普通知识页优先使用 .md 格式。
• 需要导入组件（如 SummaryBox、PrerequisitesBox）时使用 .mdx。
• 每个文件必须包含 frontmatter，至少有 title 和 description。

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

---

第二部分：内容策略

6. 写作原则

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

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

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

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

6.3 每篇文章的核心要素

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

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

6.4 先判断内容层级

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

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

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

7. 页面类型

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

7.1 概念页

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

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

7.2 算法页

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

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

7.3 流程页

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

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

7.4 板块入口页

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

• 核心章节：本板块概述 → 子主题导航 → 与其他板块的连接
• 可选章节：学习前置、推荐阅读顺序

8. MDX 与组件

普通页面优先使用 .md。满足以下条件时使用 .mdx：

• 需要 SummaryBox（页面摘要）
• 需要 PrerequisitesBox（前置知识）
• 需要 ComparisonTable（结构化对比）
• 需要 PitfallsBox（常见误区）
• 需要 RelatedLinks（相关页面卡片）

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

9. 代码与命令

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

10. 引用与参考资料

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

---

第三部分：快速参考

排版速查表

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

页面自检清单

发布前快速过一遍：

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

---

相关页面

• 关于本项目 — 知识库设计理念
• 如何贡献 — 贡献流程与技术细节
• 学习路线 — 推荐的学习路径