知识文章书写规范 · BraveH的博客

基本原则

文章结构应由内容的从属关系决定，不要为了改变文字大小而选择标题级别。同一级标题应表达同一层级的内容，下一级标题必须是上一级标题的细分。

文章主标题由 Markdown 顶部元信息中的 title 生成，页面会将它显示为一级标题。因此，正文不再书写 # 一级标题，直接从 ## 二级标题 开始。

当前博客文章使用以下字号：

六级标题与正文大小相同，但会通过字重、颜色、字间距和上下间距体现层级。标题的识别不能只依赖字号。

二级标题用于划分文章的主要章节。例如“基本概念”“实现”“常见方法”和“注意事项”。一篇文章通常只需要少量二级标题。

三级标题用于表示主要章节中的独立知识点。例如装饰器、控制器、请求负载或异常过滤器的作用域。

四级标题用于拆分一个知识点的组成部分、使用方式或不同情况。例如“定义服务”“控制器级”和“全局”。

五级标题用于确实存在从属关系的更细步骤。六级标题只在五级标题下仍有多个需要分别说明的小节时使用。

如果内容没有形成独立小节，不要仅为了加粗或放大文字而使用五级、六级标题。也不要跳过标题层级，例如从三级标题直接进入五级标题。

文件名通常只是对后续代码块的标注，不是一个知识点，不应进入文章目录。使用“加粗的行内代码”表示文件名，并且不添加多余的“文件：”前缀。

推荐写法：

#### 请求负载

##### 定义 DTO

**`create-cat.dto.ts`**

```typescript
export class CreateCatDto {}
```

不推荐写法：

##### create-cat.dto.ts

**文件：`create-cat.dto.ts`**

只有当整个小节都围绕某个文件展开，并且包含较多说明、多个代码片段或需要被目录直接定位时，才考虑让文件名成为标题。一般仍优先使用知识点作为标题，把文件名作为代码标注。

加粗用于强调句子中的关键词或结论，不用于代替标题。需要形成独立小节并进入目录的内容，应使用对应级别的标题；只需要强调的内容，应保留在正文中。

单独占一行的加粗内容容易被误认为标题，因此除文件名标注外应尽量避免。

代码块应标注正确的语言，例如 typescript、javascript、bash 或 json，以便正确高亮。涉及具体文件时，将文件名放在代码块正上方；文件名、代码块与前后正文之间各保留一个空行。

一个知识点包含多个文件时，先用标题说明每个文件承担的职责，再分别展示文件名与代码，不要只堆放一组文件名标题。