Markdown 目录完整指南：生成可靠标题锚点、自动导航与可维护 README 结构

先建立可靠的 Markdown 标题层级

目录无法修复结构混乱的文档。文档应只有一个主标题，主要主题使用二级标题，只有在确实有助于导航时才使用三级标题表示细分内容。不要为了字号选择标题级别。从二级直接跳到四级虽然可能正常渲染，却意味着结构中缺少一层，并会生成令人困惑的嵌套目录。

# Deployment Guide

## Prerequisites
## Configure the service
### Environment variables
### Database connection
## Validate the deployment
## Troubleshooting

使用标题链接编写 Markdown 目录

每个目录项的可见部分是普通 Markdown 链接文本。目标地址以 # 开头，因为它指向当前文档内的标识符。缩进用于形成列表层级，但缩进本身不会创造有效关系，目录层级应与文档标题层级一致。

## Table of contents

- [Prerequisites](#prerequisites)
- [Configure the service](#configure-the-service)
  - [Environment variables](#environment-variables)
  - [Database connection](#database-connection)
- [Validate the deployment](#validate-the-deployment)
- [Troubleshooting](#troubleshooting)

不要假设可见标题文字就是实际锚点。多数渲染器会进行规范化：字母可能转为小写，空格通常改为连字符，标点可能被删除，重复标识符还可能获得后缀。具体算法由渲染器决定，并不是 Markdown 标准统一规定的。

理解 Markdown 标题锚点生成规则

GitHub 会为渲染后的标题生成自动锚点，但静态网站生成器、文档框架、编辑器以及 Word 转换流程可能采用不同的 slug 逻辑。应以目标渲染器为准，并在真实目标环境中测试，而不能只依赖本地预览。

为 README 创建 GitHub Markdown 目录

当 README 较长、用户无法一眼看到主要章节时，目录最有价值。目录通常放在开头摘要之后、详细安装步骤之前。顶层应聚焦读者真正寻找的任务，例如安装、配置、使用、API 参考、故障排查、贡献方式和许可证，而不是列出所有标题。

当锚点不确定时，可以通过 GitHub 渲染界面获取标题链接。打开渲染后的 README，定位对应标题并复制链接，就能确认最终 slug，避免猜测标点、表情符号、非拉丁文字或重复标题的处理方式。标题改名后应重新检查，因为外部页面也可能依赖这些锚点。

自动生成并维护 Markdown 目录

当文档标题很多或经常变化时，自动化非常有用。编辑器扩展、命令行工具、文档生成器和构建脚本都可以扫描标题，并替换一个带标记的目录区域。更安全的流程会明确划定自动生成块，始终使用同一生成器，并在提交前审查生成差异。

1. 1确定权威渲染器
   选择 GitHub、文档框架或其他目标环境，生成器必须匹配它的锚点行为。
2. 2定义标题深度
   只包含读者真正需要的层级；过深目录可能比正文更难浏览。
3. 3结构修改后重新生成
   标题新增、删除、改名或调整顺序后，都应运行同一命令或编辑器操作。
4. 4审查差异并点击测试
   检查意外的 slug 变化、重复锚点、错误嵌套以及跳转到错误章节的链接。

选择手动或自动 Markdown 目录

自动生成并不代表无需审查。生成器可能忠实复制错误标题结构、包含不需要的标题，或者采用与生产环境不同的 slug 规则。应在可重复流程中固定工具版本，并在贡献说明中记录命令。

修复失效的 Markdown 目录链接

排查失效链接时，如果平台允许，应检查渲染后 HTML 的实际标识符。可见标题、源 Markdown 和最终元素 ID 是三种不同表示形式。只检查源语法，无法发现浏览器真正使用的值。

长期维护可靠的 Markdown 目录

1. 确认文档只有一个明确主标题，并且标题层级有序。
2. 根据读者任务选择目录最大深度，而不是列出所有标题。
3. 按照生产环境渲染器生成锚点。
4. 处理重复标题、标点、表情符号和非拉丁文字等边界情况。
5. 在渲染后的目标环境中点击每个目录项。
6. 标题新增、删除、改名或排序后重新生成目录。
7. 把目录变化纳入 Pull Request 或发布检查清单。
8. 外部链接可能依赖稳定标题时，应避免随意重命名。

渲染行为可参考 GitHub 关于链接和网址的官方说明，以及 CommonMark 规范中的核心 Markdown 解析规则。锚点生成仍属于渲染器扩展，因此必须在生产目标中测试。

用真实 README 执行 Markdown 目录回归审计

目录是否“看起来正确”不是验收标准；可验证的标准是：每个目录链接都能在目标渲染器中定位到唯一且正确的标题，键盘焦点和浏览器地址栏中的片段标识符同步变化，并且标题改名后不会留下过期入口。下面的样例故意同时包含重复标题、标点、行内代码和中文标题，用来覆盖普通示例最容易漏掉的边界。

# 数据连接指南

## 安装与配置
## API v2.0：快速开始
## `connect()` 参数
## 常见问题
### Windows 常见问题
## 常见问题

先在 README 的权威发布位置渲染这组标题，再从渲染结果复制每个标题链接，不要只根据肉眼猜测 slug。把得到的片段标识符记录成基线；随后修改标题、重新生成目录并比较差异。重复的“常见问题”通常会获得后缀，但后缀的具体形式属于渲染器行为，不应被当成所有 Markdown 平台都支持的通用规则。

对于经常更新的仓库，可以在 Pull Request 中把“重新生成目录”和“检查生成差异”设为必选项。自动检查适合发现目录块与当前标题不一致，却不能证明链接跳到了语义正确的章节，因此仍要对重复标题、非拉丁文字和重要入口做人工点击验证。发布记录至少应保存生成器名称与版本、目标渲染器、测试日期、失败链接及修复提交，方便以后判断变化来自内容还是工具升级。

识别 Markdown 目录在不同渲染器与 Word 转换中的边界

Markdown 只定义链接和标题等基础结构，并没有规定所有平台必须采用同一种标题 ID 算法，也没有统一的“自动目录”指令。GitHub、静态站点生成器、笔记应用和桌面编辑器可能对空格、标点、大小写、重音符号、表情符号与重复标题采用不同规则。由一个平台生成的目录复制到另一个平台后，即使页面能够渲染，片段链接仍可能失效。

因此，Markdown 转 Word 工具适合用于创建可编辑交付副本，但不能替代 Word 中的标题样式、字段目录和接收方兼容性测试。源 Markdown 的目录负责源文档导航；Word 目录是否可更新、页码是否准确、内部链接是否保留，则是另一套验收对象。涉及合规、投标或正式出版时，应保留原始 Markdown、导出文件、工具版本和人工检查记录，不能只以“转换成功”作为质量结论。

官方来源与参考资料

本文把通用 Markdown 语法、平台渲染行为与转换工具边界分开说明。基础链接与标题结构以 CommonMark 规范为语法参考；README 的存放位置、自动目录入口和仓库呈现方式参考 GitHub 官方 README 文档；跨格式转换选项和标题、目录相关能力参考 Pandoc 用户手册。这些来源支持规则与能力边界，但不会替代你在实际仓库、站点或 Word 文件中的验证。

阅读来源时应记录“它证明了什么”。CommonMark 可以证明链接和标题的基础解析方式，却不统一平台 slug；GitHub 文档说明 GitHub 的 README 功能，却不代表其他渲染器；Pandoc 手册说明转换参数与支持范围，却不证明特定模板、插件或接收方 Word 版本的呈现结果。把来源与结论逐项对应，可以避免把平台特性误写成 Markdown 标准，也让后续维护者知道何时需要重新验证。

Markdown 目录常见问题

关于本指南