Markdown 行文规范

教程：如何编写一篇文档，并在右侧显示目录（TOC）

本教程将介绍：

如何从 0 开始写一篇 Markdown 文档
如何使用标题结构生成右侧目录（Table of Contents）
MkDocs Material 对目录的默认行为与注意事项

1. Markdown 文档的基本结构

MkDocs 的文档本质上就是 Markdown 文件。

一个最基本的文档结构如下：

# 文档标题（一级标题）

这里是正文内容的简介部分。

## 第一章

这里是第一章的内容。

## 第二章

这里是第二章的内容。

规则：

# 表示一级标题（页面主标题，只能有一个）
## 表示二级标题
### 表示三级标题
标题层级越深，目录层级越深

2. 右侧目录（TOC）是如何生成的？

在 MkDocs Material 中：

右侧目录是自动生成的，不需要手动配置。

它的生成规则是：

自动扫描当前页面中的 ##、###、#### 等标题
忽略 #（页面主标题）
按标题层级生成右侧目录树

示例

下面这段 Markdown：

# 如何写一个文档

## 前言

## 安装环境

### Windows

### Linux

## 开始写作

### 创建文件

### 编写内容

会在右侧生成类似结构：

前言
安装环境
  ├─ Windows
  └─ Linux
开始写作
  ├─ 创建文件
  └─ 编写内容

3. 一个完整、可直接使用的示例文档

你可以直接复制下面这份内容使用：

# 如何编写一篇文档并生成目录

本文介绍如何在 MkDocs 中编写 Markdown 文档，并自动生成右侧目录。

---

## 文档结构说明

一篇规范的文档通常包括：

- 页面标题
- 章节划分
- 层级清晰的小节

---

## 编写第一个章节

这是第一个章节的正文内容。

### 小节一：背景说明

这里可以写一些背景说明。

### 小节二：目标说明

这里描述本文的目标。

---

## 编写第二个章节

这是第二个章节。

### 操作步骤

1. 创建 Markdown 文件
2. 使用标题结构组织内容
3. 保存并预览

### 注意事项

- 页面中只能有一个 `#`
- 不要跳级使用标题（例如直接从 `##` 到 `####`）

---

## 总结

只要正确使用 Markdown 标题，MkDocs Material 就会自动生成右侧目录。

4. 常见问题与排查

4.1 右侧没有目录？

请检查以下几点：

是否使用了 Material 主题
页面中是否存在 ## 及以上级别标题
是否误把所有标题都写成了 #

4.2 为什么目录不显示三级标题？

Material 默认行为：

显示 ## 和 ###
如果你只写了 # 和正文，是不会有目录的

5. 进阶（了解即可）

如果你将来需要更复杂的控制，例如：

控制目录最大深度
固定目录展开层级
在某些页面隐藏 TOC

这些都可以通过 mkdocs.yml 中的 theme.features 或页面级 front matter 实现。

当前阶段 不需要动这些配置，保持默认是最稳妥的。

6. 建议的文档写作规范（强烈推荐）

每个页面：
1 个 #
多个 ##
## 用于“章节”
### 用于“步骤 / 小节”
不要为了样式而乱用标题