第五章：让长文档井井有条——结构化写作

5.1 为什么需要良好的文档结构

第五章我们来讲结构化写作。

如果你只写一两百字的短文，结构好不好无所谓。但如果你要写长文档——比如一本书、一本手册、一个项目文档，结构不对，读者读着累，你维护起来也累。

这一节我们来讲讲，为什么结构这么重要。

什么是良好的文档结构？

我给你打个比方：

没有结构的文档，就像一个乱糟糟的抽屉，衣服、书本、笔全都混在一起，你想找东西，翻半天找不到。
有结构的文档，就像一个整理好的衣柜，衬衣一层，裤子一层，内衣一格，你想拿什么，打开直接拿走，一秒钟找到。

就是这么简单。把同类内容放在一起，不同内容分开，就是好结构。

为什么好结构这么重要？我给你说四个好处：

第一，读着舒服，可读性好

我给你看两个对比：

❌ 没有结构，所有内容堆在一起：

 这里讲标题语法，那里讲表格语法，然后说两句链接，又跳回图片，知识点全混着。你想找图片语法，翻半天找不到。

✅ 有结构，分类清晰：

 # Markdown 基础语法
 
 ## 一、文本基础
 ### 1.1 标题和段落
 ### 1.2 加粗斜体
 
 ## 二、区块元素
 ### 2.1 列表
 ### 2.2 代码块
 ### 2.3 表格
 
 ## 三、高级元素
 ### 3.1 链接
 ### 3.2 图片

哪个读着舒服？一眼就能看出来。分类清楚，层次分明，读者顺着读下去，一下子就能懂。

第二，找内容快，读者能快速定位

假设你写了一本几百页的技术入门书，读者看到一半，想找”列表语法”那一节在哪。

没有结构：他得一页一页翻，翻五分钟才能找到。
有结构：他看目录，”第二章基础语法 → 2.2 列表”，点一下直接跳过去，三秒钟找到了。

效率差一百倍。

第三，自己维护方便，更新不容易错

你要更新项目文档，加个新功能进去。

没有结构：你放哪都觉得不对，生怕插错了地方，删的时候还怕误删别的内容。
有结构：”这个功能属于用户模块，打开用户模块那一章，插进去就好了”，一分钟搞定，不会影响别的内容。

第四，结构清楚，读者觉得你专业

同样内容，两种写法：

❌ 乱糟糟：

 Python安装
 
 下载安装包
 
 配置环境变量
 
 验证安装
 
 常用IDE
 
 PyCharm
 
 VS Code
 
 基础语法
 
 变量
 
 函数
 
 类
 
 面向对象
 
 封装

✅ 结构清楚：

 # Python 入门教程
 
 ## 第一章：环境搭建
 ### 1.1 安装 Python
 ### 1.2 配置环境变量
 ### 1.3 验证安装
 
 ## 第二章：开发工具
 ### 2.1 PyCharm
 ### 2.2 VS Code
 
 ## 第三章：基础语法
 ### 3.1 变量和数据类型
 ### 3.2 函数定义
 ### 3.3 类和对象
 
 ## 第四章：面向对象
 ### 4.1 封装
 ### 4.2 继承
 ### 4.3 多态

你要是读者，你觉得哪个更专业？肯定是第二个对吧？结构清楚，读者一眼就能看出来，作者是认真整理过的，信任感一下子就上来了。

哪些场景特别需要好结构？

我给你说几个最常见的：

技术手册 / 帮助文档

知识点多，读者需要快速找到他想看的，结构一定要好。

 # XXX 技术手册
 
 ## 快速开始
 ## 基本概念
 ## 配置说明
 ## API 参考
 ## 常见问题
 ## 更新日志

API 文档

接口多，要分组，开发者要快速找接口，结构清楚省好多时间。

 # XXX API 文档
 
 ## 概述
 - 接口说明
 - 认证方式
 - 请求格式
 
 ## 用户模块
 - 登录接口
 - 注册接口
 - 获取个人信息
 
 ## 订单模块
 - 创建订单
 - 查询订单
 - 取消订单
 
 ## 错误码
 - 错误码对照表
 - 错误处理说明

课程大纲 / 学习计划

知识点要循序渐进，从浅到深，结构清楚学生知道学习路径。

 # Python 课程大纲
 
 ## 第一部分：基础入门（第 1-4 周）
 - 环境搭建
 - 基础语法
 - 数据类型
 - 控制流
 
 ## 第二部分：面向对象（第 5-8 周）
 - 类和对象
 - 继承
 - 多态
 - 异常处理
 
 ## 第三部分：实战项目（第 9-12 周）
 - Web 开发
 - 数据分析
 - 自动化脚本

个人知识库

你积累了一堆笔记，要以后能找到，分类一定要清楚。

 # 个人知识库
 
 ## 技术学习
 - 前端开发
 - 后端开发
 - 数据库
 - 运维部署
 
 ## 工作笔记
 - 项目经验
 - 问题排查
 - 最佳实践
 
 ## 读书笔记
 - 技术书籍
 - 管理书籍
 - 思想类书籍

好结构长什么样，记住这几点

第一，层次分明

# 一级标题（文章主题）
## 二级标题（主要章节）
### 三级标题（小节）
#### 四级标题（小点）

记住：

层次别跳，一级→二级→三级，顺着来
层级别太深，最多四级，太深了你自己找着都累

第二，逻辑递进

从简单到复杂，从基础到进阶，顺着来：

# 主题

## 1. 基础知识（先看这个）
## 2. 进阶技巧
## 3. 实际应用
## 4. 实战项目（最后综合练手）

读者顺着读下来，循序渐进，容易懂。

第三，分类合理

同一类内容放在一起，分类标准要统一。比如按功能分，就都按功能分，别一会儿按功能一会儿按时间。

第四，章节长短差不多

别一章三千字，一章十万字，不均衡。太长了就拆成好几章，保持每章大概的体量，读着不累。

给新手几个设计结构的小建议

先写大纲，再写内容

动手写之前，先把大纲画出来：

# 书名

## 第一部分
- 第一章
- 第二章
- 第三章

## 第二部分
- 第四章
- 第五章
- 第六章

整体框架想清楚了，你再一点点填内容，不会写着写着结构乱了。

开头放目录

长文档一定要有目录，放在开头：

# 文档标题

## 目录

- [第一章：为什么需要结构](#为什么需要结构)
  - [什么是好结构](#什么是好结构)
  - [好处](#好处)
- [第二章：怎么设计结构](#怎么设计结构)

读者一眼就能看到整体内容，想去哪直接点过去，体验好很多。

标题要明确，让人一看就知道里边写什么

❌ 别这么写：

## 内容
## 介绍
## 说明

✅ 要这么写：

## 安装步骤
## 使用方法
## 常见问题

能用编号就用编号，顺序感强

# 主题

## 1. 第一大块
## 2. 第二大块
## 3. 第三大块

### 1.1 第一小节
### 1.2 第二小节

编号了，顺序清楚，引用也方便。

5.2 文档结构设计四个核心原则

上一节我们说了为什么要结构，这一节说具体原则，记住这四个原则，设计结构不会错。

原则一：层级关系一定要清楚

什么是层级关系？就是谁是大标题，谁是小标题，谁属于谁，要清清楚楚。

 # 一级标题（文章主题，就一个）
   ## 二级标题（主要章节）
     ### 三级标题（小节）
       #### 四级标题（具体小点，最多到这了）

正确例子：

 # Python 入门教程
 
 ## 第一章：环境搭建
 
 ### 1.1 Python 安装
 - Windows 安装
 - Mac 安装
 - Linux 安装
 
 ### 1.2 环境变量配置
 ### 1.3 安装验证
 
 ## 第二章：基础语法
 
 ### 2.1 变量和数据类型
 #### 2.1.1 变量定义
 #### 2.1.2 数据类型
 
 ### 2.2 控制流
 #### 2.2.1 条件语句
 #### 2.2.2 循环语句

这样就很清楚，一级→二级→三级→四级，顺着来，不跳级，不混乱。

新手常犯的错误：

错误一：跳级

 # 教程
 
 ### 1.1 简介 ← 直接从一级跳到三级，跳过二级了，错了
 
 ## 第二章 ← 又跳回二级，乱了

改正好：

 # 教程
 
 ## 第一章
 
 ### 1.1 简介
 
 ## 第二章

错误二：层级太深

 # 教程
 
 ## 第一章
 
 ### 1.1 小节
 
 #### 1.1.1 小小节
 
 ##### 1.1.1.1 小小小小节 ← 太深了，读者看着累

建议最多到四级，再深就拆分成新的章节吧，别往死里嵌套。

错误三：同级标题层级不对

 # 教程
 
 ## 第一章 ← 二级
 
 ### 1.1 小节
 
 ### 1.2 小节 ← 这两个三级是对的，都属于第一章二级，没问题

记住：同一级别的内容，用同一个层级标题，别一会儿三级一会儿二级，乱了。

原则二：顺序一定要符合逻辑递进

什么叫逻辑递进？就是从简单到复杂，从基础到高级，顺着来，别跳。

正确例子，教程类文档就这么排：

 # Python 教程
 
 ## 1. 环境搭建 ← 先得装好才能用
 ## 2. 基础语法 ← 装好先学基础
 ## 3. 进阶语法 ← 基础学好学进阶
 ## 4. 实战项目 ← 都学会了综合练手

逻辑对：先装环境→再学基础→再学进阶→最后实战，读者顺着看下来，能学会。

技术手册就这么排：

 # XXX 技术手册
 
 ## 1. 概述 ← 先让读者知道这是什么
 ## 2. 快速开始 ← 看完概述快速跑起来
 ## 3. 详细说明 ← 跑起来再讲细节
 ## 4. 高级用法 ← 细节懂了学高级
 ## 5. API 参考 ← 最后放索引
 ## 6. 常见问题 ← 出问题了方便查

错的例子：

# 教程

## 1. 高级技巧 ← 基础还没学，先讲高级，新手看不懂
## 2. 基础语法 ← 基础放后面，顺序反了
## 3. 环境搭建 ← 环境最后装，上来怎么写代码

顺序反了，新手根本读不下去。

记住： 读者是什么水平，就从什么水平开始，一点点往难了走，别跳。

原则三：章节要合理划分

就是一句话：一节一个主题，长短合适，内容不交叉。

正确例子，按功能分：

# 软件使用手册

## 1. 用户管理 ← 这一章就讲用户管理
### 1.1 添加用户
### 1.2 删除用户
### 1.3 修改用户

## 2. 订单管理 ← 这一章就讲订单管理，不交叉
### 2.1 创建订单
### 2.2 查询订单
### 2.3 取消订单

每个章节一个主题，内容不交叉，要找什么直接去那个章节，清楚。

新手常犯的错误：

错误一：一章内容太多

# 教程

## 第一章 ← 一章把环境、基础、进阶、实战全都放进去，几万字，太长了

改正：拆开，环境一章，基础一章，进阶一章，实战一章，每个人章几千字，读着不累。

错误二：拆得太碎

# 教程

## 1.1 准备工作 ← 不到一百字也整个章，太碎了
## 1.2 下载软件 ← 同样太碎

改正：合并，第一章：环境准备，里面分小节 ### 1.1 准备工作 ### 1.2 下载安装，这样就合适了。

错误三：内容交叉

# 教程

## 第一章：基础语法 ← 这里又讲环境又讲基础，内容交叉了

## 第二章：环境安装 ← 又讲一遍环境，重复了

改正：环境就是环境一章，基础就是基础一章，内容分开，不重复不交叉。

给你一个参考：

一节就是一个主题，别把八个杆子放一个主题
一章两千到五千字最合适，太长就拆，太短就合并
一本书五到十五章最合适，太多了就分部分

原则四：标题命名要规范

就是你的标题，让人一眼看出这里写什么，风格统一。

好的例子：

全用动词开头（适合操作指南）：

## 1. 安装软件
## 2. 配置环境
## 3. 验证安装

全用名词（适合说明类内容）：

## 1. 软件安装
## 2. 环境配置
## 3. 安装验证

全用问句（适合问答类）：

## 1. 怎么安装软件？
## 2. 怎么配置环境？
## 3. 怎么验证安装好了？

不管你用哪种，保持统一风格，就好看。

新手常犯的错误：

错误一：标题太模糊

## 1. 介绍
## 2. 说明
## 3. 其他

读者不知道你这里写什么，这不行。

改正：## 1. 环境搭建介绍，明明白白。

错误二：风格不统一

## 1. 安装软件 ← 动词
## 2. 环境配置 ← 名词
## 3. 怎么验证？ ← 问句

一会儿一个风格，看着乱。全用一种风格，看着舒服。

错误三：标题太长

## 1. 如何在 Windows 系统上面下载安装 Python 并且配置好环境变量呢？

太长了，看着累。

改正：## 1. 安装和环境配置，短一点，具体放小节里说：### 1.1 Windows 安装 ### 1.2 环境变量配置，清清楚楚。

一个完整的正确例子，你参考一下

# Python 入门教程

## 第一部分：环境准备

### 1.1 Python 安装
#### Windows 安装
#### Mac 安装
#### Linux 安装

### 1.2 开发工具
#### VS Code
#### PyCharm
#### 其他编辑器

## 第二部分：基础语法

### 2.1 变量和数据类型
#### 变量定义
#### 数字类型
#### 字符串类型
#### 布尔类型

### 2.2 控制流
#### 条件语句
#### 循环语句

### 2.3 函数
#### 函数定义
#### 参数传递
#### 返回值

## 第三部分：进阶特性

### 3.1 面向对象
#### 类和对象
#### 继承
#### 多态

### 3.2 异常处理
#### try-except
#### finally
#### 手动抛出异常

## 第四部分：实战应用

### 4.1 Web 开发
### 4.2 数据分析
### 4.3 自动化脚本

## 第五部分：常见问题

### 5.1 安装问题
### 5.2 运行问题
### 5.3 调试技巧

你看看，这个结构：

✅ 层级清楚，最多到四级
✅ 逻辑递进，环境→基础→进阶→实战→问题
✅ 章节划分合理，一节一个主题
✅ 标题简洁，风格统一

完美。

设计完结构，你这么检查一遍

检查项	是否合格
层级连续不跳跃，最多到四级	☐
同级标题用一样的层级	☐
顺序从简单到复杂，从基础到应用	☐
一节一个主题，内容不交叉	☐
章节长度合适，太长太短都不对	☐
标题简洁明确，风格统一	☐

都打勾了，你的结构就是合格的。

5.3 做个目录，读者找内容更快

长文档一定要有目录，这就像是文章的地图，读者打开先看目录，一下子就能找到他想看的内容，不用瞎翻。

这一节我们讲怎么在 Markdown 做目录，不同工具都能用。

目录就是把文章所有章节列个表，放在开头，读者点一下就能跳过去。作用就是：

读者一眼就能看到文章整体结构
想找什么内容，点一下直接跳过去，不用翻半天
能看到整体进度，学到哪了清清楚楚

最简单：手动做目录，所有工具都能用

不管你用什么工具，手动做目录肯定没问题，语法也简单：

 # 文章标题
 
 ## 目录
 
 - [第一章：环境搭建](#第一章：环境搭建)
 - [第二章：基础语法](#第二章：基础语法)
 - [第三章：进阶技巧](#第三章：进阶技巧)
 - [第四章：实战项目](#第四章：实战项目)
 
 ---
 
 ## 第一章：环境搭建
 ...

如果有子章节，就缩进一下，层次清楚：

 ## 目录
 
 - [第一部分：基础入门](#第一部分：基础入门)
   - [第一章：环境搭建](#第一章：环境搭建)
   - [第二章：基础语法](#第二章：基础语法)
   - [第三章：第一个程序](#第三章：第一个程序)
 - [第二部分：进阶学习](#第二部分：进阶学习)
   - [第四章：函数](#第四章：函数)
   - [第五章：类和对象](#第五章：类和对象)

给你几个小技巧：

目录一定要放在文章最开头，标题之后就是目录，读者打开就能看到
目录写完加分隔线，和正文分开，看着清楚
目录层次和文章层次对应，文章二级标题，目录就是二级缩进，别错了
可以用编号，看着更整齐，比如 1. [第一章] 2. [第二章]

不同工具，自动生成目录更方便

很多工具支持自动生成目录，不用你手动维护，改了标题它自动更，特别方便。

Typora：左侧边栏自动显示目录，不用你手动做，打开就能看
VS Code：装个 Markdown All in One 插件，命令生成目录
语雀：左侧边栏自动生成目录，支持折叠展开
GitHub：README 自动在右侧显示目录
掘金/知乎：不支持自动目录，你手动做一个就行

我给你整理了一个表，一目了然：

工具	手动目录	自动目录	说明
掘金	✅	❌	只能手动
知乎	✅	❌	只能手动
语雀	✅	✅	侧边栏自动有
飞书	✅	⚠️	部分支持
Typora	✅	✅	侧边栏自动有
VS Code	✅	🔧	装插件支持
Obsidian	✅	🔧	装插件支持
GitHub	✅	✅	右侧自动显示

目录可以做的更好看，给你几个样式参考

样式一：简单编号（最常用）

 ## 目录
 
 1. [第一章：基础入门](#第一章：基础入门)
 2. [第二章：进阶学习](#第二章：进阶学习)
 3. [第三章：实战应用](#第三章：实战应用)

干净清楚，适合教程、手册。

样式二：加 Emoji 分类，更好看

 ## 目录
 
 - 📚 [第一章：基础入门](#第一章：基础入门)
 - 💪 [第二章：进阶学习](#第二章：进阶学习)
 - 🚀 [第三章：实战应用](#第三章：实战应用)

活泼一点，适合博客、笔记。

样式三：显示进度，一目了然

 ## 目录
 
 - ✅ [第一章：基础入门](#第一章：基础入门)
 - 🔄 [第二章：进阶学习](#第二章：进阶学习)
 - ⏳ [第三章：实战应用](#第三章：实战应用)

做学习计划、项目进度，用这个特别合适，进度一眼就能看到。

样式四：分部分，大文章用

 ## 目录
 
 - 📚 第一部分：基础入门
   - [第一章：环境搭建](#第一章：环境搭建)
   - [第二章：基础语法](#第二章：基础语法)
   - [第三章：第一个程序](#第三章：第一个程序)
 - 💪 第二部分：进阶学习
   - [第四章：函数](#第四章：函数)
   - [第五章：类和对象](#第五章：类和对象)
 - 🚀 第三部分：实战应用
   - [第六章：Web 开发](#第六章：web-development)
   - [第七章：数据分析](#第七章：数据分析)

文章长，分成几个部分，目录看着清楚。

最佳实践，记住这几条

一，放在对的位置

 # 文章标题
 
 ## 目录 ← 放在标题后面，正文前面
 
 ---
 
 ## 第一章

读者一打开就能看到，没错。

二，层次别太深

最多到三级就够了：

 - 一级章节
   - 二级小节
     - 四级小点 ← 太深了，别弄

太深了目录太长，看着累。

三，改了标题，记得更更新目录

你正文标题改名字了，目录里的链接也要跟着改，不然点不对。新增删除章节，目录也要增删，保持一致。

四，给章节加返回链接

长文章，每章末尾加个返回目录，读者看完直接回目录，方便：

## 第一章：xxx

... 正文 ...

[🔼 返回目录](#目录)

这个小细节，体验好很多。

一个完整的例子，你参考一下

# Python 入门教程 🐍

## 📋 目录

### 📚 第一部分：基础入门

1. [第一章：环境搭建](#第一章：环境搭建) ✅ 完成
2. [第二章：基础语法](#第二章：基础语法) ✅ 完成
3. [第三章：数据类型](#第三章：数据类型) 🔄 进行中
4. [第四章：控制流](#第四章：控制流) ⏳ 未开始

### 💪 第二部分：进阶学习

5. [第五章：函数](#第五章：函数) ⏳ 未开始
6. [第六章：类和对象](#第六章：类和对象) ⏳ 未开始
7. [第七章：模块和包](#第七章：模块和包) ⏳ 未开始
8. [第八章：异常处理](#第八章：异常处理) ⏳ 未开始

### 🚀 第三部分：实战应用

9. [第九章：Web 开发](#第九章：web-development) ⏳ 未开始
10. [第十章：数据分析](#第十章：数据分析) ⏳ 未开始
11. [第十一章：自动化脚本](#第十一章：automation) ⏳ 未开始
12. [第十二章：综合项目](#第十二章：project) ⏳ 未开始

---

## 第一章：环境搭建 { #第一章：环境搭建 }

### 1.1 Python 安装
### 1.2 环境变量配置
### 1.3 开发工具安装

[🔼 返回目录](#目录)

---

## 第二章：基础语法 { #第二章：基础语法 }

### 2.1 变量和赋值
### 2.2 基本数据类型
### 2.3 运算符

[🔼 返回目录](#目录)

这样就很完整了，读者用着舒服。

5.4 章节导航：让读者读得更轻松

这一节我们讲章节导航。有了导航，读者在长文章里不会迷路，想去哪点一下就到了，体验好很多。

什么是章节导航，有什么用？

说白了，导航就是给文章”指路”：

你现在在哪
往前能去哪，往后能去哪
怎么回到开头，怎么回到目录

就像走路有路标，爬山有指示牌，读者读长文章，有了导航，轻轻松松就能找到他想去的地方。

四种最常用的导航方式

第一种：面包屑导航，告诉你现在在哪

这个名字来自童话《汉赛尔与格莱特》，两个小孩在森林里撒面包屑标记回家的路，所以叫面包屑导航。

用法就是，在章节开头告诉你，现在在文章的什么位置：

 # Python 教程
 
 ## 第一章：环境搭建
 
 **当前位置**：🐍 Python 教程 > 第一章：环境搭建
 
 ### 1.1 Python 安装
 
 **当前位置**：🐍 Python 教程 > 第一章：环境搭建 > 1.1 Python 安装

加点图标更好看：

 **当前位置**：🏠 Python 教程 > 第一章：环境搭建

记住：层级别太深，三级就够了，太深了看着累。

第二种：返回顶部按钮，读完一章快速回去

你写了一大章，读者读完，想回到开头或者目录，不用慢慢滚，点一下就回去了。

放在章节末尾就好：

 ## 第一章：xxx
 
 ... 正文 ...
 
 ---
 
 [🔼 返回顶部](#)

就这么简单。如果你的工具支持 HTML，还能做成按钮样子：

 <a href="#" style="display: inline-block; padding: 8px 16px; background: #eee; border-radius: 4px;">
   🔼 返回顶部
 </a>

第三种：前后章节链接，顺着读很方便

读者顺着一章一章读，在章节开头直接放好上一章下一章链接，不用翻回目录，点一下就能继续读，特别方便。

 ## 第一章：环境搭建
 
 **➡️ 下一章**：[第二章：基础语法](#第二章：基础语法)

前后都有就更好了：

 ## 第二章：基础语法
 
 **⬅️ 上一章**：[第一章：环境搭建](#第一章：环境搭建) | **➡️ 下一章**：[第三章：数据类型](#第三章：数据类型)

第一章没有上一章，最后一章没有下一章，照着来：

 ## 第一章：环境搭建
 
 **➡️ 下一章**：[第二章：基础语法](#第二章：基础语法)

 ## 第十章：综合项目
 
 **⬅️ 上一章**：[第九章：API 开发](#第九章：api-development)
 
 🎉 恭喜你读完了整本教程！

还能加上进度，读者知道读到哪了：

## 第三章：数据类型

**⬅️ 上一章**：[第二章：基础语法](#...) | 进度：3/10 | **➡️ 下一章**：[第四章：控制流](#...)

第四种：侧边栏导航，工具自动帮你做

现在大部分工具都支持侧边栏导航，不用你手动做：

Typora：左边自动显示文章大纲，点击跳转
语雀：左边自动显示文档目录，支持折叠
VS Code：装插件也能显示大纲
GitHub：README 自动在右边显示目录

所以你不用手动做，工具帮你做了，挺好。

不同工具支持情况，我给你整理好了

导航类型	手动能做	Typora	语雀	VS Code	掘金	知乎
面包屑导航	✅	❌	✅	❌	⚠️	⚠️
返回顶部	✅	❌	⚠️	❌	✅	✅
前后章节链接	✅	❌	⚠️	❌	✅	✅
侧边栏导航	❌	✅	✅	🔧	❌	❌

说明：

✅ 完全支持，你手动能做
❌ 不用你手动做，工具自动有
🔧 需要装插件

最佳实践，照着做就好了

组合用效果最好

# 文章标题

## 目录
... 目录 ...

---

## 第一章：xxx

**当前位置**：🏠 文章标题 > 第一章

**⬅️ 上一章**：[...](#...) | **➡️ 下一章**：[...](#...)

... 正文 ...

---

[🔼 返回目录](#目录) | [🔼 返回顶部](#)

---

## 第二章：xxx

多种导航都有，读者怎么读都方便。

导航放在固定位置

面包屑放章节开头
前后链接放章节标题下面
返回顶部/目录放章节末尾

位置固定了，读者习惯了，找都不用找。

样式统一，别换来换去

就用一种风格，比如都用箭头图标：

**⬅️ 上一章**：[...] | **➡️ 下一章**：[...]

别一会儿用箭头，一会儿用文字，一会儿用别的图标，看着乱。

导航够用就行，别弄太多

❌ 太多导航：
[← 上一章](#) | [→ 下一章](#)
[🔼 返回顶部](#) | [⬆️ 返回目录](#)
[📖 看目录](#) | [🔍 找内容](#)

这样就太多了，乱糟糟的。其实有前后链接+返回目录，够用了。

一个完整例子，你参考一下

# Python 入门教程 🐍

## 📋 目录

### 📚 第一部分：基础入门
- [第一章：环境搭建](#第一章：环境搭建) 1/10
- [第二章：基础语法](#第二章：基础语法) 2/10

---

## 第一章：环境搭建 { #第一章：环境搭建 }

**📍 当前位置**：🐍 Python 入门教程 > 第一章：环境搭建

**🔗 导航**：➡️ [下一章：基础语法](#第二章：基础语法)

### 1.1 Python 安装

... 正文 ...

### 1.2 环境变量配置

... 正文 ...

---

**🔗 快速导航**：[🔼 返回目录](#目录) | [🔼 返回顶部](#)

---

## 第二章：基础语法 { #第二章：基础语法 }

**📍 当前位置**：🐍 Python 入门教程 > 第二章：基础语法

**🔗 导航**：⬅️ [上一章：环境搭建](#第一章：环境搭建) | ➡️ [下一章：数据类型](#第三章：数据类型)

... 正文 ...

---

**🔗 快速导航**：[🔼 返回目录](#目录) | [🔼 返回顶部](#)

---

...

## 第十章：综合项目 { #第十章：综合项目 }

**📍 当前位置**：🐍 Python 入门教程 > 第十章：综合项目

**🔗 导航**：⬅️ [上一章：API 开发](#第九章：api-development)

🎉 恭喜你读完了整本教程！

... 正文 ...

---

**🔗 快速导航**：[🔼 返回目录](#目录) | [🔼 返回顶部](#)

5.5 长文档管理：一万字以上也能管得住

前面我们讲了结构、目录、导航，这一节讲长文档——一万字、几万字的大文档，怎么管理才轻松。

什么是长文档，长文档有什么麻烦？

一般超过一万字，或者几十页，就算长文档了。常见的：

技术手册：可能上百页，要经常更新
系列教程：好多章，好多节，内容递进
API 文档：上百个接口，每个接口都要说明
项目文档：从需求到设计到实现，一大堆内容

长文档麻烦在哪？

文件太大，打开编辑都卡，保存半天
结构太复杂，找东西找不到
多人一起改，容易冲突，不好协作

技巧一：拆成多个小文件，好管理

别把所有内容放一个超大文件里，按着主题拆成多个小文件，每个人文件几千字，打开保存都快。

常见拆分方法：

按章节拆（教程、书）：

 python-tutorial/
 ├── 01-foreword.md
 ├── 02-environment.md
 ├── 03-basic-syntax.md
 ├── 04-control-flow.md
 ├── 05-function.md
 └── 06-project.md

按主题拆（技术手册）：

 technical-manual/
 ├── 01-overview.md
 ├── 02-install.md
 ├── 03-configuration.md
 ├── 04-user-guide.md
 ├── 05-api-reference.md
 ├── 06-faq.md
 └── 07-changelog.md

按模块拆（系统文档，多人协作）：

 system-docs/
 ├── user-module/
 │   ├── login.md
 │   ├── register.md
 │   └── profile.md
 ├── order-module/
 │   ├── create.md
 │   ├── query.md
 │   └── cancel.md
 └── payment-module/
     ├── alipay.md
     └── wechat-pay.md

按读者水平拆（给不同水平读者看）：

 learning-guide/
 ├── beginner.md
 ├── quick-start.md
 ├── advanced.md
 └── expert.md

拆分完，做个索引：

拆完了，根目录放个索引，读者点开就能看到所有内容：

 # Python 教程
 
 ## 目录
 
 - [前言](01-foreword.md)
 - [环境搭建](02-environment.md)
 - [基础语法](03-basic-syntax.md)
 - [控制流](04-control-flow.md)

这样就清楚了，读者点一下就能跳过去。

命名建议：

加数字前缀：01-xxx.md 02-xxx.md，排序清楚
名字能看懂：第一章-环境搭建.md 比 chapter1.md 清楚
尽量用小写加横线：environment-setup.md，不容易出错

拆分原则：

一个文件五千到一万字最合适，太大就接着拆
一个文件一个主题，内容别交叉
能独立看懂，尽量减少依赖

技巧二：模块化写作，复用方便

什么叫模块化？就是把内容拆成一个个独立模块，一个模块讲一件事，想改改这个模块，不影响别人，想复用就能拿去用。

比如你写教程：

 tutorial/
 ├── modules/
 │   ├── basics/
 │   │   ├── variables.md
 │   │   ├── data-types.md
 │   │   └── operators.md
 │   ├── control-flow/
 │   │   ├── if.md
 │   │   ├── loops.md
 │   │   └── functions.md
 │   └── oop/
 │       ├── classes.md
 │       ├── inheritance.md
 │       └── exceptions.md
 └── 00-index.md

好处就是：

每个模块独立，改一个模块不影响别的
别的教程想用你这个模块，直接拿去用就行，不用复制粘贴
多人协作，每个人改自己的模块，不容易冲突

模块化原则：

一个模块一个核心主题，别把好几个主题混一个模块里
模块尽量独立，少依赖别的模块
能复用的模块就独立出来，别写死在大文件里

技巧三：用 Git 做版本控制，不怕改错

为什么要用版本控制？你改了文档，改错了，能回去啊；多人改，不容易冲突；改了什么，都有记录，谁改的，什么时候改的，清清楚楚。

最简单的用法，每个人都能会：

 # 进到文档目录
 cd my-document/
 
 # 初始化 Git
 git init
 
 # 加个 ignore，忽略临时文件
 echo "*.bak" > .gitignore
 echo "*.tmp" >> .gitignore
 
 # 第一次提交
 git add .
 git commit -m "初始化文档仓库"

改了就提交，写清楚改了什么

 # 改完第一章，提交
 git add 02-environment.md
 git commit -m "docs: 更新安装步骤，修正了 Java 版本要求"

好的提交信息：说清楚你改了什么，比如 fix: 修正安装步骤里的下载地址，比你写”更新”强一百倍。

提交频率：改完一个模块就提交，别攒一堆一起交，改错了好回滚。

想回滚就回滚，不怕错

# 想看历史
git log

# 想回到上个版本
git reset --hard HEAD~1

# 想看一个文件的修改历史
git log 02-environment.md

放到 GitHub 备份，也方便协作

# 提交到 GitHub
git remote add origin git@github.com:your-name/your-docs.git
git push -u origin main

放 GitHub，不会丢，别人也能协作改，挺好。

技巧四：多人协作，一套流程不乱

多人一起写文档，怎么弄不乱？

第一步：分工明确

项目文档/
├── 张三/
│   ├── 需求.md
│   └── 产品设计.md
├── 李四/
│   ├── 技术架构.md
│   └── API 文档.md
└── 王五/
    ├── 测试文档.md
    └── 部署文档.md

谁写什么，分清楚，不抢活。

第二步：每个人一个分支

# 张三写用户文档，建自己分支
git checkout -b zhangsan-user-docs

# 写完，改完，合并回主分支
git checkout main
git merge zhangsan-user-docs

每个人在自己分支改，不影响别人，稳。

第三步：定好规范，大家都遵守

规范不用复杂，就几条：

所有文件都是 Markdown，UTF-8 编码
标题层级不超过四级
文件名用小写加横线，不要奇怪字符
提交信息写清楚改了什么

就够了。

一个完整例子，你参考一下

python-tutorial/
├── .git/
├── .gitignore
├── README.md         ← 主索引
├── docs/
│   ├── 01-intro.md
│   ├── 02-install.md
│   ├── modules/        ← 模块化
│   │   ├── basic/
│   │   │   ├── variables.md
│   │   │   └── data-types.md
│   │   └── control-flow/
│   │       ├── if.md
│   │       └── loops.md
│   ├── 03-advanced.md
│   └── 04-faq.md
└── CONTRIBUTING.md   ← 协作规范

这样结构清楚，打开快，改起来方便，多人协作也不乱。

5.6 实战案例：看完整的结构化写作例子

这一节我们看几个完整的实战案例，都是日常写作最常用的，你可以直接照着改改就能用。

案例一：技术手册结构设计

需求

给 FastAPI 设计一份技术手册结构。

完整结构

 # FastAPI 技术手册 🚀
 
 ## 📋 目录
 
 ### 📚 第一部分：快速入门
 
 1. [第一章：FastAPI 简介](#第一章：fastapi-intro) (5 分钟)
 2. [第二章：安装指南](#第二章：install) (10 分钟)
 3. [第三章：第一个 Hello World](#第三章：hello-world) (5 分钟)
 
 ### 💪 第二部分：核心概念
 
 4. [第四章：路由与请求](#第四章：route) (15 分钟)
 5. [第五章：响应处理](#第五章：response) (10 分钟)
 6. [第六章：异常处理](#第六章：exception) (10 分钟)
 
 ### 🔧 第三部分：进阶功能
 
 7. [第七章：中间件](#第七章：middleware) (15 分钟)
 8. [第八章：依赖注入](#第八章：di) (10 分钟)
 9. [第九章：数据库集成](#第九章：database) (20 分钟)
 
 ### 🚀 第四部分：实战项目
 
 10. [第十章：构建 RESTful API](#第十章：rest-api) (30 分钟)
 11. [第十一章：WebSocket 实时通信](#第十一章：websocket) (20 分钟)
 12. [第十二章：部署上线](#第十二章：deploy) (15 分钟)
 
 ---
 
 ## 第一章：FastAPI 简介 { #第一章：fastapi-intro }
 
 **📍 当前位置**：📚 FastAPI 技术手册 > 第一章：FastAPI 简介
 
 **🔗 导航**：[➡️ 下一章：安装指南](#第二章：install)
 
 ### 1.1 什么是 FastAPI？
 
 FastAPI 是一个现代、高性能的 Python Web 框架...
 
 ### 1.2 核心特性
 
 - 🚀 高性能，比 Flask 快很多
 - 📝 自动类型提示
 - 🔏 原生支持异步
 - 🛠️ 简单易学
 
 ---
 
 ## 🔗 快速导航
 
 [🔼 返回顶部](#) | [⬆️ 返回目录](#目录)

结构分析

设计点	做得怎么样
层级关系	分四个部分，从入门到实战，层级清楚 ✓
逻辑递进	从入门到核心到进阶到实战，顺序对 ✓
章节划分	每章一个主题，不长不短 ✓
导航	每章都有面包屑+前后链接，最后有快速导航 ✓

这个设计用上了我们所有讲过的技巧：层次清楚，逻辑递进，导航齐全，非常好用。

案例二：API 文档组织

需求

给电商平台设计 API 文档结构。

完整结构

 # 电商平台 API 文档 🔗
 
 ## 📋 目录
 
 ### 🔧 第一部分：接入准备
 
 - [概述](#overview)
 - [认证方式](#auth)
 - [请求格式](#request-format)
 - [响应格式](#response-format)
 
 ### 👤 第二部分：用户模块
 
 - [用户注册](#user-register)
 - [用户登录](#user-login)
 - [个人信息](#user-profile)
 - [修改密码](#change-password)
 
 ### 🛒 第三部分：商品模块
 
 - [商品列表](#product-list)
 - [商品详情](#product-detail)
 - [商品搜索](#product-search)
 - [商品分类](#category)
 
 ### 📦 第四部分：订单模块
 
 - [创建订单](#create-order)
 - [查询订单](#query-order)
 - [取消订单](#cancel-order)
 - [订单支付](#pay-order)
 
 ### 💳 第五部分：支付模块
 
 - [支付宝支付](#alipay)
 - [微信支付](#wechat-pay)
 - [退款处理](#refund)
 
 ### ⚠️ 第六部分：错误码
 
 - [常见错误码](#error-codes)
 - [错误处理建议](#error-handling)
 
 ---
 
 # 概述 { #overview }
 
 **📍 当前位置**：🔗 电商 API 文档 > 概述
 
 **🔗 导航**：[➡️ 下一章：认证方式](#auth)
 
 ## API 概述
 
 本文档提供电商平台完整的 API 接口说明...
 
 ---
 
 ## 用户注册 { #user-register }
 
 **📍 当前位置**：🔗 电商 API 文档 > 用户模块 > 用户注册
 
 **🔗 导航**：[⬅️ 上一章：概述](#overview) | [➡️ 下一章：用户登录](#user-login)
 
 ### 接口说明
 
 - **接口地址**：`POST /api/v1/user/register`
 - **请求示例**：
   ```json
   {
     "username": "test",
     "password": "123456"
   }

响应示例： {
“code”: 200,
“message”: “注册成功”,
“data”: {
“userId”: 123456
}
}

参数说明

参数名	类型	必填	说明
username	String	是	用户名，3-20 个字符
password	String	是	密码，6-20 个字符

🔗 快速导航

 
 ### 设计评价
 
 - 按功能模块分组，清楚 ✓
 - 每个接口独立成章，完整 ✓
 - 参数用表格放着，一眼能看清楚 ✓
 - 导航齐全，读者不用瞎找 ✓
 
 ---
 
 ## 案例三：课程大纲设计
 
 ### 需求
 给 Python 全栈开发课程设计 12 周课程大纲。
 
 ### 完整结构
 
 ```markdown
 # Python 全栈开发课程大纲 🎓
 
 ## 📋 课程基本信息
 
 | 项目 | 内容 |
 |:-----|:-----|
 | 📚 课程名称 | Python 全栈开发 |
 | 👨 课程时长 | 12 周（每周 10 课时） |
 | 🎯 适合 | 有编程基础，想转全栈开发 |
 | 🎓 学习目标 | 掌握 Python 全栈开发独立做项目 |
 
 ## 📋 目录
 
 ### 📚 第一部分：基础入门（第 1-4 周）
 
 #### 🗓️ 第 1 周：环境搭建与基础语法
 
 ##### 1.1 Python 安装
 - 下载 Python
 - 安装 Python
 - 配置环境变量
 
 ##### 1.2 基础语法
 - 变量和数据类型
 - 运算符
 - 输入输出
 
 ##### 1.3 控制流
 - 条件语句
 - 循环语句
 - 函数定义
 
 #### 🗓️ 第 2 周：数据结构与函数
 
 ##### 2.1 列表和元组
 ##### 2.2 字典和集合
 ##### 2.3 函数定义
 ##### 2.4 参数与返回值
 
 ...
 
 ---
 
 ## 第 1 周：环境搭建与基础语法 { #第1周：环境搭建与基础语法 }
 
 **📍 当前位置**：🎓 Python 全栈开发 > 第一部分：基础入门 > 第 1 周：环境搭建与基础语法
 
 **🔗 导航**：[⬅️ 上一周：课程介绍](#课程介绍) | [➡️ 下一周：数据结构与函数](#第2周：数据结构与函数)
 
 ### 本周目标
 
 - [x] 完成 Python 安装
 - [x] 掌握基础语法
 - [x] 理解控制流
 
 ### 课程安排
 
 | 课时 | 内容 | 时长 |
 |:-----|:-----|:-----|
 | 1 | Python 安装 | 1 小时 |
 | 2 | 基础语法 | 2 小时 |
 | 3 | 控制流 | 2 小时 |
 | 4 | 实践练习 | 2 小时 |
 
 ### 课后作业
 
 1. 安装 Python 环境
 2. 写一个简单计算器
 3. 写一个猜数字游戏
 
 ---
 
 ## 🔗 快速导航
 
 [🔼 返回顶部](#) | [⬆️ 返回目录](#目录)

设计评价

按学习阶段分组，从浅入深，符合逻辑 ✓
每周分小节，不长不短，合适 ✓
导航齐全，面包屑+前后周链接 ✓
有目标有作业有课时安排，完整 ✓

案例四：项目文档完整目录结构

需求

给 SaaS 平台项目设计文档目录结构。

完整结构（文件系统）

 project-docs/
 ├── .git/
 ├── .gitignore
 ├── README.md              # 项目总索引
 ├── docs/
 │   ├── overview/
 │   │   ├── project-intro.md
 │   │   ├── architecture.md
 │   │   └── tech-stack.md
 │   ├── getting-started/
 │   │   ├── install.md
 │   │   ├── config.md
 │   │   └── quick-start.md
 │   ├── modules/
 │   │   ├── user-module/
 │   │   │   ├── register.md
 │   │   │   ├── login.md
 │   │   │   └── profile.md
 │   │   ├── order-module/
 │   │   │   ├── create-order.md
 │   │   │   ├── query-order.md
 │   │   │   └── cancel-order.md
 │   │   └── payment-module/
 │   │       ├── alipay.md
 │   │       ├── wechat-pay.md
 │   │       └── refund.md
 │   ├── api/
 │   │   ├── auth.md
 │   │   ├── user-api.md
 │   │   ├── order-api.md
 │   │   └── payment-api.md
 │   ├── deployment/
 │   │   ├── dev.md
 │   │   ├── test.md
 │   │   └── prod.md
 │   ├── troubleshooting/
 │   │   ├── common-issues.md
 │   │   ├── error-codes.md
 │   │   └── performance.md
 │   └── changelog/
 │       ├── v1.0.0.md
 │       ├── v1.1.0.md
 │       └── v2.0.0.md
 ├── diagrams/              # 图片存这里
 │   ├── architecture.png
 │   ├── flow.png
 │   └── sequence.png
 ├── .vscode/             # VS Code 配置
 │   └── settings.json
 └── CONTRIBUTING.md    # 协作规范

README 主页索引

 # SaaS 平台项目文档 🏢
 
 ## 📋 快速导航
 
 ### 📚 项目概览
 - [项目介绍](docs/overview/project-intro.md)
 - [系统架构](docs/overview/architecture.md)
 - [技术栈](docs/overview/tech-stack.md)
 
 ### 🔧 快速开始
 - [安装指南](docs/getting-started/install.md)
 - [配置说明](docs/getting-started/config.md)
 - [快速上手](docs/getting-started/quick-start.md)
 
 ### 📚 功能模块
 
 #### 用户模块
 - [用户注册](docs/modules/user-module/register.md)
 - [用户登录](docs/modules/user-module/login.md)
 - [个人中心](docs/modules/user-module/profile.md)
 - [接口文档](docs/modules/user-module/api-reference.md)
 
 #### 订单模块
 - [创建订单](docs/modules/order-module/create-order.md)
 - [查询订单](docs/modules/order-module/query-order.md)
 - [取消订单](docs/modules/order-module/cancel-order.md)
 
 #### 支付模块
 - [支付宝支付](docs/modules/payment-module/alipay.md)
 - [微信支付](docs/modules/payment-module/wechat-pay.md)
 - [退款](docs/modules/payment-module/refund.md)
 
 ---
 
 ## 团队协作
 
 ### 文档分工
 
 | 模块 | 负责人 | 状态 |
 |:-----|:-------|:-------|
 | 用户模块文档 | 张三 | ✅ 完成 |
 | 订单模块文档 | 李四 | 🔄 进行中 |
 | 支付模块文档 | 王五 | ⏳ 待开始 |
 | 部署文档 | 赵六 | ⏳ 待开始 |
 
 ### 版本分支
 
 - 主分支：`main`
 - 开发分支：`dev`
 - 功能分支：`feature/*`
 - 文档分支：`docs/*`

设计评价

按模块拆分文档，每个模块独立文件，方便维护 ✓
模块化结构，多人协作分工清楚 ✓
索引清楚，读者找内容方便 ✓
符合我们讲的拆分原则：一个文件一个主题 ✓

5.7 不同工具兼容性对比，心里有数

不同 Markdown 工具支持的功能不完全一样，我给你整理好了一张表，你一看就知道哪个工具支持什么，不支持什么。

一张表看懂兼容性

功能	Typora	语雀	飞书	VS Code	掘金	知乎	GitHub
手动目录	✅	✅	✅	✅	✅	✅	✅
自动目录	✅	✅	⚠️	🔧	❌	❌	✅
面包屑导航	❌	✅	⚠️	❌	⚠️	⚠️	❌
前后章节链接	❌	⚠️	⚠️	❌	✅	✅	❌
内部锚点跳转	✅	✅	✅	✅	✅	✅	✅
侧边栏大纲	✅	✅	✅	🔧	❌	❌	❌
支持文档拆分	✅	✅	✅	✅	❌	❌	✅

说明：

✅ 完全支持，直接用
⚠️ 部分支持，需要你手动做
❌ 不支持，用不了
🔧 需要装插件才能用

你看，手动目录和锚点跳转，所有工具都支持，所以你写的时候，尽量用通用语法，兼容性最好。

每个工具具体支持什么，给你说清楚

Typora（本地编辑器）

支持很好：

✅ 左侧自动显示大纲，不用你手动做目录
✅ 支持自定义锚点：## 标题 {: #anchor-name}
✅ 支持多文件拆分，链接互相跳转
✅ 快捷键切换大纲视图

小技巧：

你写本地文档，直接用侧边栏大纲，不用手动做目录
需要跳转就用锚点，很方便

语雀（云端知识库，团队协作）

支持很好：

✅ 左侧自动显示目录，自动高亮当前位置
✅ 自带面包屑导航，告诉你现在在哪
✅ 支持文档树，多文档管理方便
⚠️ 前后章节导航需要你手动加

小技巧：

团队写知识库，语雀真的方便，自动导航都做好了
长文章要加前后章节链接，读者顺着读方便

飞书（企业协作）

支持情况：

✅ 手动目录完全支持
⚠️ 自动目录部分支持
⚠️ 导航需要手动加
✅ 云端文档管理，文件夹分组好用

小技巧：

手动做目录，自己维护，也不麻烦
适合企业内部团队协作

VS Code（代码编辑器）

支持情况：

🔧 需要装插件才有自动目录，推荐装这两个：
- Markdown All in One：基础增强，自动生成目录
- Markdown Preview Enhanced：高级预览，自定义目录
✅ 锚点跳转支持
✅ 多文件编辑，快速切换

小技巧：

程序员写文档，VS Code 很爽，插件装好了自动目录也有
配合 Git，版本控制方便

掘金（技术博客）

支持情况：

✅ 手动目录完全支持
✅ 前后章节链接完全支持
✅ 锚点跳转支持，需要手动设置
❌ 没有自动目录，没有侧边栏

小技巧：

文章开头手动做个目录，读者找内容方便
每章开头加前后链接，连载文章读者顺着读方便

知乎（专栏文章）

支持情况和掘金差不多：

✅ 手动目录
✅ 前后导航
✅ 锚点
❌ 没有自动目录

小技巧：

长文一定要开头放目录，读者看着舒服
发布前记得预览一下，链接都点一遍对不对

GitHub（开源项目）

支持很好：

✅ README 自动在右侧生成目录，不用你手动做
✅ 自动给标题生成锚点，链接直接用
✅ 支持多文件拆分，相对路径链接好用
✅ 子文档管理方便

小技巧：

README 不用手动做目录，GitHub 自动给你弄好了
长文档拆成多个文件，主 README 做索引，结构清楚

什么场景选什么工具，直接给你推荐

场景一：写技术手册、写书

推荐：Typora + Git

理由：

本地编辑，自动大纲，写着舒服
Git 做版本控制，不怕改错
写完再发布到别的平台

场景二：团队知识库，多人协作

推荐：语雀

理由：

自动面包屑，自动目录，体验好
云端同步，多人编辑
文档树管理，结构清楚

场景三：开源项目文档

推荐：VS Code + GitHub

理由：

VS Code 插件好用，写着方便
GitHub 自动目录，不用手动做
Git 版本控制，多人协作

场景四：个人笔记、知识库

推荐：Obsidian / Typora

理由：

纯本地 Markdown，数据自己掌握
Obsidian 双向链接，知识图谱，适合笔记
Typora 简单直接，适合写长文

场景五：发博客、发专栏

推荐：掘金 / 知乎

理由：

流量大，曝光多
手动做目录也不麻烦
支持锚点跳转，结构清楚

5.8 实战练习：检验一下你的学习成果

做完这几个练习，第五章结构化写作你就真的掌握了。

练习一：设计一份技术文档结构

练习要求

选一个你熟悉的技术主题
设计完整的文档结构
符合我们讲过的四个设计原则

参考答案（Redis 技术文档）

 # Redis 缓存技术文档 🗞️
 
 ## 📋 目录
 
 ### 📚 第一部分：基础概念
 
 1. [什么是 Redis？](#1-what-is-redis)
 2. [为什么选择 Redis？](#2-why-redis)
 
 ### 🔧 第二部分：安装配置
 
 3. [安装指南](#3-install)
 4. [配置说明](#4-config)
 5. [启动验证](#5-verify)
 
 ### 💪 第三部分：基本使用
 
 6. [数据类型](#6-data-types)
 7. [基本命令](#7-commands)
 8. [持久化配置](#8-persistence)
 
 ### 🚀 第四部分：进阶特性
 
 9. [缓存策略](#9-cache-strategy)
 10. [主从复制](#10-replication)
 11. [集群部署](#11-cluster)
 
 ### 🧩 第五部分：实战应用
 
 12. [应用示例一：Session 缓存](#12-session-cache)
 13. [应用示例二：计数器](#13-counter)
 14. [应用示例三：排行榜](#14-leaderboard)
 
 ---
 
 ## 1. 什么是 Redis？ { #1-what-is-redis }
 
 ### 1.1 Redis 简介
 
 Redis 是一个开源的内存数据结构存储系统...
 
 ### 1.2 核心特性
 
 - 🗞️ 基于内存
 - 🚀 高性能
 - 💪 数据结构丰富
 
 ---
 
 ## 🔗 快速导航
 
 [🔼 返回顶部](#) | [⬆️ 返回目录](#目录)

自己检查一下：

层次清楚，不跳级
逻辑递进：从基础到应用
一节一个主题，不交叉
标题明确，一看就知道写什么

练习二：创建一个带完整目录和导航的文档

练习要求

至少三个章节
每个章节两到三个小节
要有目录和导航
要有返回顶部按钮

参考答案（Python 异步编程教程）

 # Python 异步编程教程 🐍
 
 ## 📋 目录
 
 ### 📚 第一部分：基础概念
 
 1. [什么是异步？](#1-what-is-async)
 2. [同步 vs 异步](#2-sync-vs-async)
 3. [事件循环](#3-event-loop)
 
 ### 🔧 第二部分：核心概念
 
 4. [回调函数](#4-callback)
 5. [Promise 对象](#5-promise)
 6. [async/await](#6-async-await)
 
 ### 💪 第三部分：实战应用
 
 7. [异步文件操作](#7-async-file)
 8. [网络请求](#8-network)
 9. [并发控制](#9-concurrency)
 
 ---
 
 ## 1. 什么是异步？ { #1-what-is-async }
 
 **📍 当前位置**：🐍 Python 异步编程 > 第一部分：基础概念 > 1. 什么是异步
 
 **🔗 导航**：[➡️ 下一章：同步 vs 异步](#2-sync-vs-async)
 
 ### 1.1 同步代码示例
 
 ```python
 def task():
     print("开始任务")
     time.sleep(2)
     print("任务完成")

1.2 异步代码示例

 import asyncio
 
 async def async_task():
     print("开始任务")
     await asyncio.sleep(2)
     print("任务完成")

🔗 快速导航

 
 ### 自己检查一下：
 - [ ] 目录完整，包含所有章节
 - [ ] 链接都能正常跳转
 - [ ] 导航位置对（开头结尾都有）
 - [ ] 返回顶部按钮能用
 
 ---
 
 ## 练习三：实现文档内跳转
 
 ### 练习要求
 - 每个章节设置锚点
 - 创建跳转链接
 - 添加返回顶部链接
 
 ### 参考答案（Web 开发教程）
 
 ```markdown
 # Web 开发教程 🌐
 
 ## 📋 目录
 
 1. [第一章：HTML 基础](#html-basic)
    - [1.1 HTML 结构](#html-structure)
    - [1.2 常用标签](#html-tags)
 2. [第二章：CSS 样式](#css-basic)
    - [2.1 CSS 选择器](#css-selector)
    - [2.2 常用属性](#css-property)
 
 ---
 
 ## 第一章：HTML 基础 { #html-basic }
 
 ### 1.1 HTML 结构 { #html-structure }
 
 HTML 文档的基本结构...
 
 快速跳转：
 - [去 CSS 选择器 →](#css-selector)
 
 ### 1.2 常用标签 { #html-tags }
 
 `<div>`：块级容器...
 
 ---
 
 ## 第二章：CSS 样式 { #css-basic }
 
 **📍 当前位置**：🌐 Web 开发教程 > 第二章：CSS 样式
 
 **🔗 导航**：[⬅️ 上一章：HTML 基础](#html-basic)
 
 ### 2.1 CSS 选择器 { #css-selector }
 
 元素选择器...
 
 ---
 
 ## 🔗 快速导航
 
 [🔼 返回顶部](#) | [⬆️ 返回目录](#目录)

自己检查一下：

锚点设置对不对：## 标题 { #anchor-name }
链接对不对：[文字](#anchor-name)
跨章节跳转正常
返回顶部链接有效

练习四：做一份课程大纲

练习要求

按学习阶段分组
每周有明确的课时安排
要有进度指示
用编号和图标美化

参考答案（全栈开发课程大纲）

 # 全栈开发课程大纲 💻
 
 ## 📋 课程基本信息
 
 | 项目 | 内容 |
 |:-----|:-----|
 | 📚 课程名称 | 全栈开发实战 |
 | 👨 时长 | 12 周（每周 10 课时）|
 | 🎯 适合 | 有编程基础，想学 Web 开发 |
 | 🎓 目标 | 掌握全栈开发，独立做项目 |
 
 ## 📊 课程进度
 
 ### 📚 第一部分：前端基础（第 1-4 周）
 
 **第 1 周**：📅 HTML + CSS ✅ 完成
 - [x] 第一天：HTML 基础语法
 - [x] 第二天：CSS 基础语法
 - [x] 第三天：盒子模型
 - [x] 第四天：布局基础
 - [x] 第五天：响应式入门
 
 **第 2 周**：📅 JavaScript 基础 ✅ 完成
 ...
 
 ### 💪 第二部分：后端开发（第 5-8 周）
 
 ...
 
 ---
 
 ## 🔗 快速导航
 
 [🔼 返回顶部](#) | [⬆️ 返回目录](#目录)

自己检查一下：

按学习阶段分组清楚
每周内容安排合理
进度一目了然
导航完善

练习五：设计 API 文档结构

练习要求

按功能模块分组
每个接口要有参数说明
要有请求和响应示例
要有错误码说明

参考答案（电商平台 API）

 # 电商平台 API 文档 🛒
 
 ## 📋 目录
 
 ### 🔧 第一部分：接入准备
 
 1. [概述](#overview)
 2. [认证方式](#auth)
 3. [请求格式](#request-format)
 4. [响应格式](#response-format)
 
 ### 👤 第二部分：用户模块
 
 5. [用户注册](#user-register)
 6. [用户登录](#user-login)
 ...
 
 ---
 
 ## 用户注册 { #user-register }
 
 ### 接口说明
 
 - **地址**：`POST /api/v1/user/register`
 - **认证**：不需要
 - **Content-Type**：`application/json`
 
 ### 请求参数
 
 | 参数名 | 类型 | 必填 | 说明 |
 |:-------|:-----|:-----|:-----|
 | username | String | 是 | 用户名，3-20 字符 |
 | password | String | 是 | 密码，6-20 字符 |
 | email | String | 是 | 邮箱 |
 
 ### 请求示例
 
 ```json
 {
   "username": "test",
   "password": "123456",
   "email": "test@example.com"
 }

响应示例

 {
   "code": 200,
   "message": "注册成功",
   "data": {
     "userId": 123456
   }
 }

常见错误码

错误码	说明	解决方案
1001	用户名已存在	换个用户名
1002	密码太短	密码不少于 6 位

🔗 快速导航

 
 ### 自己检查一下：
 - [ ] 按功能模块分组正确
 - [ ] 参数表格清晰
 - [ ] 请求响应示例完整
 - [ ] 错误码单独放一章
 - [ ] 导航完善
 
 ---
 
 ## 恭喜你完成练习！
 
 做完这五个练习，你应该掌握了：
 
 | 技能 | 掌握了吗 |
 |:-----|:-------|
 | 设计清晰的文档结构 | ✅ |
 | 创建完整目录和导航 | ✅ |
 | 文档内跳转 | ✅ |
 | 做课程大纲 | ✅ |
 | 设计 API 文档 | ✅ |
 ---

5.9 本章实战练习

欢迎来到第五章的最后一节！🎉🎉

这一节我们通过6个实战练习来检验结构化写作的学习成果！

完成这些练习，你就真正掌握了结构化写作的所有技巧！

📝 练习1：设计技术文档结构

练习目标

为一份技术文档设计合理的结构。

练习要求

选择一个技术主题
设计完整的文档结构
确保符合4个设计原则

参考答案

主题：Redis缓存技术文档

 # Redis缓存技术文档 🗞️
 
 ## 📋 目录
 
 ### 📚 第一部分：基础概念
 
 1. [什么是Redis？](#1-什么是redis)
 2. [为什么选择Redis？](#2-为什么选择redis)
 
 ### 🔧 第二部分：安装配置
 
 3. [安装指南](#3-安装指南)
 4. [配置说明](#4-配置说明)
 5. [启动验证](#5-启动验证)
 
 ### 💪 第三部分：基本使用
 
 6. [数据类型](#6-数据类型)
 7. [基本命令](#7-基本命令)
 8. [持久化配置](#8-持久化配置)
 
 ### 🚀 第四部分：进阶特性
 
 9. [缓存策略](#9-缓存策略)
 10. [主从复制](#10-主从复制)
 11. [集群部署](#11-集群部署)
 
 ### 🧩 第五部分：实战应用
 
 12. [应用示例1：Session缓存](#12-应用示例1：session缓存)
 13. [应用示例2：计数器](#13-应用示例2：计数器)
 14. [应用示例3：排行榜](#14-应用示例3：排行榜)
 
 ---
 
 ## 1. 什么是Redis？ {: #1-什么是redis}
 
 ### 1.1 Redis简介
 
 Redis是一个开源的内存数据结构存储系统...
 
 ### 1.2 核心特性
 
 - 🗞️ 基于内存
 - 🚀 高性能
 - 💪 数据结构丰富
 
 ---
 
 ## 🔗 快速导航
 
 [🔼 返回顶部](#) | [⬆️ 返回目录](#) | [📖 查看全部章节](#)
 
 ---
 
 ## 2. 为什么选择Redis？ {: #2-为什么选择redis}
 
 ### 2.1 性能优势
 
 Redis的读写速度极快...
 
 ### 2.2 功能丰富
 
 支持多种数据结构...
 
 ---
 
 ## 🔗 快速导航
 
 [🔼 返回顶部](#) | [⬆️ 返回目录](#) | [📖 查看全部章节](#)

自检清单

结构清晰（层级分明）
逻辑递进（从基础到应用）
章节合理（一节一个主题）
标题明确（清楚表达内容）

📝 练习2：创建带目录的文档

练习目标

创建一个带完整目录的Markdown文档。

练习要求

至少3个章节
每个章节2-3个小节
添加目录和导航
添加返回顶部按钮

参考答案

 # Python异步编程教程 🐍
 
 ## 📋 目录
 
 ### 📚 第一部分：基础概念
 
 1. [什么是异步？](#1-什么是异步)
 2. [同步vs异步](#2-同步vs异步)
 3. [事件循环](#3-事件循环)
 
 ### 🔧 第二部分：核心概念
 
 4. [回调函数](#4-回调函数)
 5. [Promise对象](#5-promise对象)
 6. [async/await](#6-async/await)
 
 ### 💪 第三部分：实战应用
 
 7. [异步文件操作](#7-异步文件操作)
 8. [网络请求](#8-网络请求)
 9. [并发控制](#9-并发控制)
 
 ---
 
 ## 1. 什么是异步？ {: #1-什么是异步}
 
 **📍 面包屑**：🐍 Python异步编程教程 > 第一部分：基础概念
 
 **🔗 导航**：[➡️ 下一章：同步vs异步](#2-同步vs异步)
 
 ### 1.1 同步代码示例
 
 ```python
 def task():
     print("开始任务")
     time.sleep(2)  # 模拟耗时操作
     print("任务完成")

1.2 异步代码示例

 import asyncio
 
 async def async_task():
     print("开始任务")
     await asyncio.sleep(2)  # 异步等待
     print("任务完成")

1.3 对比分析

同步代码问题：

阻塞主线程
无法并发执行
效率低

异步代码优势：

不阻塞主线程
支持并发执行
效率高

🔗 快速导航

🔼 返回顶部 | ⬆️ 返回目录 | 📖 查看全部章节

 
 ### 自检清单
 
 - [ ] 目录完整（包含所有章节）
 - [ ] 目录链接正确（可点击跳转）
 - [ ] 导航位置合理（章节开头/结尾）
 - [ ] 返回顶部按钮有效
 
 ---
 
 ## 📝 练习3：实现文档内跳转
 
 ### 练习目标
 
 在文档中实现内部锚点跳转。
 
 ### 练习要求
 
 1. 每个章节设置锚点
 2. 创建跳转链接
 3. 添加返回顶部链接
 
 ### 参考答案
 
 ```markdown
 # Web开发教程 🌐
 
 ## 📋 目录
 
 1. [第一章：HTML基础](#html基础)
    - [1.1 HTML结构](#html结构)
    - [1.2 常用标签](#常用标签)
 2. [第二章：CSS样式](#css样式)
    - [2.1 CSS选择器](#css选择器)
    - [2.2 常用属性](#常用属性)
 3. [第三章：JavaScript](#javascript)
    - [3.1 变量和函数](#变量和函数)
    - [3.2 DOM操作](#dom操作)
 
 ---
 
 ## 第一章：HTML基础 {: #html基础}
 
 ### 1.1 HTML结构 {: #html结构}
 
 HTML文档的基本结构...
 
 **跳转到其他主题**：
 - [CSS样式 →](#css样式)
 - [JavaScript →](#javascript)
 
 ### 1.2 常用标签 {: #常用标签}
 
 `<div>`：块级容器...
 `<span>`：内联容器...
 `<p>`：段落容器...
 
 **跳转到其他主题**：
 - [CSS样式 →](#css样式)
 - [JavaScript →](#javascript)
 
 ---
 
 ## 第二章：CSS样式 {: #css样式}
 
 **📍 面包屑**：🌐 Web开发教程 > 第二章：CSS样式
 
 **🔗 导航**：[⬅️ 上一章：HTML基础](#html基础) | [➡️ 下一章：JavaScript](#javascript)
 
 ### 2.1 CSS选择器 {: #css选择器}
 
 元素选择器...
 
 **快速跳转**：
 - [返回HTML基础 →](#html基本结构)
 - [跳转到常用属性 →](#常用属性)
 
 ### 2.2 常用属性 {: #常用属性}
 
 字体、颜色、边距...
 
 **快速跳转**：
 - [返回HTML结构 →](#html结构)
 
 ---
 
 ## 第三章：JavaScript {: #javascript}
 
 **📍 面包屑**：🌐 Web开发教程 > 第三章：JavaScript
 
 **🔗 导航**：[⬅️ 上一章：CSS样式](#css样式)
 
 ### 3.1 变量和函数 {: #变量和函数}
 
 变量声明、函数定义...
 
 ### 3.2 DOM操作 {: #dom操作}
 
 获取元素、修改内容...
 
 ---
 
 ## 🔗 快速导航
 
 [🔼 返回顶部](#) | [⬆️ 返回目录](#) | [📖 查看全部章节](#)

自检清单

锚点设置正确（{: #锚点}）
跳转链接有效（文字）
跨章节跳转正常
返回顶部链接有效

📝 练习4：制作课程大纲

练习目标

为课程制作详细的大纲和进度跟踪。

练习要求

按学习阶段分组
每周有明确的课时安排
添加进度指示
使用编号和图标

参考答案

 # 全栈开发课程大纲 💻
 
 ## 📋 课程信息
 
 | 项目 | 内容 |
 |:-----|:-----|
 | 📚 课程名称 | 全栈开发课程 |
 | 👨 课程时长 | 12周（每周10课时）|
 | 🎯 适用对象 | 编程基础，想学Web开发 |
 | 🎓 学习目标 | 掌握全栈开发，独立完成Web项目 |
 
 ## 📊 课程进度
 
 ### 📚 第一部分：前端基础（第1-4周）
 
 **第1周**：📅 HTML5 + CSS3（100%）
 - [x] 第1天：HTML基础语法
 - [x] 第2天：CSS基础语法
 - [x] 第3天：盒子模型
 - [x] 第4天：布局基础
 - [x] 第5天：响应式设计入门
 
 **第2周**：📅 JavaScript基础（100%）
 - [x] 第1天：变量和数据类型
 - [x] 第2天：函数和作用域
 - [x] 第3天：对象和数组
 - [x] 第4天：ES6语法
 - [x] 第5天：DOM操作
 
 **第3周**：📅 前端框架（100%）
 - [x] 第1天：Vue.js简介
 - [x] 第2天：组件化开发
 - [x] 第3天：响应式原理
 - [x] 第4天：状态管理
 - [x] 第5天：路由配置
 
 **第4周**：📅 前端工程化（100%）
 - [x] 第1天：Webpack配置
 - [x] 第2天：Babel配置
 - [x] 第3天：ESLint配置
 - [x] 第4天：Git版本控制
 - [x] 第5天：CI/CD配置
 
 ### 💪 第二部分：后端开发（第5-8周）
 
 **第5周**：📅 Node.js基础（100%）
 - [x] 第1天：Node.js运行时
 - [x] 第2天：模块系统
 - [x] 第3天：异步编程
 - [x] 第4天：事件循环
 - [x] 第5天：文件系统操作
 
 **第6周**：📅 Express框架（100%）
 - [x] 第1天：Express简介
 - [x] 第2天：路由和中间件
 - [x] 第3天：请求和响应
 - [x] 第4天：错误处理
 - [x] 第5天：会话管理
 
 **第7周**：📅 数据库设计（100%）
 - [x] 第1天：MySQL基础
 - [x] 第2天：表结构设计
 - [x] 第3天：索引优化
 - [x] 第4天：查询优化
 - [x] 第5天：事务处理
 
 **第8周**：📅 数据库实战（100%）
 - [x] 第1天：用户模块
 - [x] 第2天：订单模块
 - [x] 第3天：支付模块
 - [x] 第4天：关联查询
 - [x] 第5天：数据验证
 
 ### 🚀 第三部分：项目实战（第9-12周）
 
 **第9周**：📅 项目设计（100%）
 - [x] 第1天：需求分析
 - [x] 第2天：技术选型
 - [x] 第3天：架构设计
 - [x] 第4天：数据库设计
 - [x] 第5天：接口设计
 
 **第10周**：📅 前端开发（100%）
 - [x] 第1天：项目搭建
 - [x] 第2天：登录注册
 - [x] 第3天：商品展示
 - [x] 第4天：购物车
 - [x] 第5天：订单提交
 
 **第11周**：📅 后端开发（100%）
 - [x] 第1天：API设计
 - [x] 第2天：用户API
 - [x] 第3天：商品API
 - [x] 第4天：订单API
 - [x] 第5天：支付API
 
 **第12周**：📅 部署上线（100%）
 - [x] 第1天：服务器配置
 - [x] 第2天：Ngin配置
 - [x] 第3天：域名SSL
 - [x] 第4天：数据库备份
 - [x] 第5天：监控告警
 
 ---
 
 ## 🎯 学习目标
 
 完成本课程后，你将能够：
 
 - [ ] 独立完整的Web应用
 - [ ] 理解前后端分离架构
 - [ ] 掌握主流前端框架
 - [ ] 使用Node.js开发后端
 - [ ] 设计和优化数据库
 - [ ] 部署应用到生产环境
 
 ---
 
 ## 💰 时间投入
 
 | 阶段 | 理论课时 | 实践课时 | 总课时 |
 |:-----|:---------|:---------|:-------|
 | 📚 第一部分：前端基础 | 20课时 | 20课时 | 40课时 |
 | 💪 第二部分：后端开发 | 20课时 | 20课时 | 40课时 |
 | 🚀 第三部分：项目实战 | 10课时 | 50课时 | 60课时 |
 | **总计** | **50课时** | **90课时** | **140课时** |
 
 ---
 
 ## 🔑 考核与评估
 
 ### 阶段考核
 
 | 阶段 | 考核方式 | 占比 |
 |:-----|:---------|:-----|
 | 第一部分 | 理论考试 + 实践作业 | 30% |
 | 第二部分 | 理论考试 + 实践作业 | 30% |
 | 第三部分 | 项目完成度 | 40% |
 
 ### 项目评分标准
 
 | 评分项 | 权重 | 说明 |
 |:-------|:-----|:-----|
 | 功能完整性 | 30% | 所有功能是否实现 |
 | 代码质量 | 25% | 代码规范性、可读性 |
 | 界面设计 | 20% | UI美观、用户体验 |
 | 数据库设计 | 15% | 表结构、索引优化 |
 | 部署上线 | 10% | 服务器配置、SSL |
 
 ---
 
 ## 🔗 快速导航
 
 [🔼 返回顶部](#) | [⬆️ 返回目录](#) | [📖 查看全部章节](#)

自检清单

课程进度清晰（按周分组）
课时安排合理（理论+实践）
学习目标明确
考核评估合理
导航完善（返回顶部、目录链接）

📝 练习5：设计API文档结构

练习目标

为API接口文档设计清晰的结构。

练习要求

按功能模块分组
每个接口详细说明
包含请求/响应示例
添加错误码说明

参考答案

 # 电商平台API文档 🛒
 
 ## 📋 目录
 
 ### 🔧 第一部分：接入准备
 
 1. [概述](#概述)
 2. [认证方式](#认证方式)
 3. [请求格式](#请求格式)
 4. [响应格式](#响应格式)
 
 ### 👤 第二部分：用户模块
 
 5. [用户注册](#用户注册)
 6. [用户登录](#用户登录)
 7. [个人信息](#个人信息)
 8. [修改密码](#修改密码)
 
 ### 🛒 第三部分：商品模块
 
 9. [商品列表](#商品列表)
 10. [商品详情](#商品详情)
 11. [商品搜索](#商品搜索)
 12. [商品分类](#商品分类)
 
 ### 🛍 第四部分：订单模块
 
 13. [创建订单](#创建订单)
 14. [查询订单](#查询订单)
 15. [取消订单](#取消订单)
 16. [订单支付](#订单支付)
 
 ### 💳 第五部分：支付模块
 
 17. [支付宝支付](#支付宝支付)
 18. [微信支付](#微信支付)
 19. [退款处理](#退款处理)
 
 ### ⚠️ 第六部分：错误码
 
 20. [常见错误码](#常见错误码)
 21. [错误处理建议](#错误处理建议)
 
 ---
 
 ## 概述 {: #概述}
 
 ## API概述
 
 本文档提供电商平台完整的API接口说明...
 
 **API基础地址**：`https://api.example.com/v1`
 
 ## 认证方式 {: #认证方式}
 
 ### Token认证
 
 使用Token进行身份验证...
 
 **请求头**：

Authorization: Bearer {token}

 
 ---
 
 ## 用户注册 {: #用户注册}
 
 ### 接口说明
 
 - **接口地址**：`POST /api/v1/user/register`
 - **认证方式**：不需要认证
 - **Content-Type**：`application/json`
 
 ### 请求参数
 
 | 参数名 | 类型 | 必填 | 说明 |
 |:-------|:-----|:-----|:-----|
 | username | String | 是 | 用户名，3-20字符 |
 | password | String | 是 | 密码，6-20字符 |
 | email | String | 是 | 邮箱地址 |
 | phone | String | 否 | 手机号 |
 
 ### 请求示例
 
 ```json
 {
   "username": "testuser",
   "password": "123456",
   "email": "test@example.com",
   "phone": "13800138000"
 }

响应参数

参数名	类型	说明
code	Integer	状态码，200表示成功
message	String	提示信息
data	Object	返回数据

响应示例

成功响应：

 {
   "code": 200,
   "message": "注册成功",
   "data": {
     "userId": 123456,
     "username": "testuser"
   }
 }

失败响应：

{
  "code": 1001,
  "message": "用户名已存在"
}

常见错误码 {: #常见错误码}

错误码	说明	解决方案
1001	用户名已存在	更换用户名
1002	密码错误	检查密码
1003	Token过期	重新登录
1004	参数错误	检查请求参数
1005	数据库错误	联系管理员

5.1 为什么需要良好的文档结构

什么是良好的文档结构？

为什么好结构这么重要？我给你说四个好处：

第一，读着舒服，可读性好

第二，找内容快，读者能快速定位

第三，自己维护方便，更新不容易错

第四，结构清楚，读者觉得你专业

哪些场景特别需要好结构？

技术手册 / 帮助文档

API 文档

课程大纲 / 学习计划

个人知识库

好结构长什么样，记住这几点

第一，层次分明

第二，逻辑递进

第三，分类合理

第四，章节长短差不多

给新手几个设计结构的小建议

先写大纲，再写内容

开头放目录

标题要明确，让人一看就知道里边写什么

能用编号就用编号，顺序感强

5.2 文档结构设计四个核心原则

原则一：层级关系一定要清楚

正确例子：

新手常犯的错误：

原则二：顺序一定要符合逻辑递进

正确例子，教程类文档就这么排：

技术手册就这么排：

错的例子：

原则三：章节要合理划分

正确例子，按功能分：

新手常犯的错误：

给你一个参考：

原则四：标题命名要规范

好的例子：

新手常犯的错误：

一个完整的正确例子，你参考一下

设计完结构，你这么检查一遍

5.3 做个目录，读者找内容更快

什么是目录，目录有什么用？

最简单：手动做目录，所有工具都能用

给你几个小技巧：

不同工具，自动生成目录更方便

目录可以做的更好看，给你几个样式参考

样式一：简单编号（最常用）

样式二：加 Emoji 分类，更好看

样式三：显示进度，一目了然

样式四：分部分，大文章用

最佳实践，记住这几条

一，放在对的位置

二，层次别太深

三，改了标题，记得更更新目录

四，给章节加返回链接

一个完整的例子，你参考一下

5.4 章节导航：让读者读得更轻松

什么是章节导航，有什么用？

四种最常用的导航方式

第一种：面包屑导航，告诉你现在在哪

第二种：返回顶部按钮，读完一章快速回去

第三种：前后章节链接，顺着读很方便

第四种：侧边栏导航，工具自动帮你做

不同工具支持情况，我给你整理好了

最佳实践，照着做就好了

组合用效果最好

导航放在固定位置

样式统一，别换来换去

导航够用就行，别弄太多

一个完整例子，你参考一下

5.5 长文档管理：一万字以上也能管得住

什么是长文档，长文档有什么麻烦？

技巧一：拆成多个小文件，好管理

常见拆分方法：

拆分完，做个索引：

命名建议：

拆分原则：

技巧二：模块化写作，复用方便

模块化原则：

技巧三：用 Git 做版本控制，不怕改错

最简单的用法，每个人都能会：