跳到主要内容
返回博客
2026年11月18日星期三

Markdown 目录怎么做?GitHub README 锚点与嵌套目录示例

给 GitHub README 加一个可以点击跳转的 Markdown 目录。文章提供完整可复制示例,演示二级目录、同名标题和跨文件链接,说明如何从渲染后的标题复制锚点,并按症状排查改名后失效、跳错位置与缩进问题。

Markdown 目录怎么做?GitHub README 锚点与嵌套目录示例

在 README 开头写一个项目列表,用 [Quick start](#quick-start) 链接到 ## Quick start。 方括号里是读者看到的文字,井号后面是目标标题的锚点。

GitHub 也会根据 Markdown 文件里的标题生成 Outline(大纲)。浏览别人仓库时,可以直接从大纲跳转。给自己的 README 写目录时,可以挑出读者最常用的几节,让他们打开文件就能看到安装、用法或排查入口。GitHub README 文档

复制一份带目录的完整 README

这份示例有一个子目录项、两个名字相同的标题和四条跳转链接。复制代码块里的内容,放进 Markdown 文件试一下。

# Field Notes

## Contents

- [Quick start](#quick-start)
  - [Import a notebook](#import-a-notebook)
- [Examples for writers](#examples)
- [Examples for reviewers](#examples-1)

## Quick start

Open a notebook and add your first entry.

### Import a notebook

Choose an existing folder of Markdown notes.

## Examples

Writers can group entries by trip.

## Examples

Reviewers can scan entries by date.

Import a notebook 缩进到 Quick start 下面,与正文里三级标题归在二级标题下的关系对应。两节正文都叫 Examples,目录里的名称可以写得更具体,分别提示写作者和审阅者。只要指向各自的锚点,两条链接就可以跳到不同位置。

从渲染后的标题取得锚点

对于简单标题,GitHub 会把字母转为小写,把空格换成短横线,去掉问号等标点和标题中的格式标记。如果锚点与前面的重复,就会追加数字后缀。示例里第一节 Examples 是 #examples,第二节是 #examples-1。GitHub 标题链接规则

遇到中文、标点或行内格式时,可以直接核对实际结果。在 GitHub 打开渲染后的文件,把鼠标移到标题上,点击旁边的链接图标,再从浏览器地址复制井号及后面的内容。要从同一仓库的另一个 Markdown 文件跳过去,在锚点前加相对路径。例如两个文件在同一目录时,可以写 [Quick start](README.md#quick-start)。

排查点了目录却跳错位置

遇到的情况怎么检查
点了以后仍在文件顶部确认链接里有井号,并和渲染后标题的锚点一致。
两条目录项都跳到第一节 Examples重新复制第二节的链接,示例以 -1 结尾。
改完标题后跳转失效重新取锚点,更新目录和其他引用旧锚点的链接。同名标题换了顺序也要重查。
子目录项和上一级排在同一层缩进该项目符号,再看目录的渲染结果。正文标题层级和目录缩进要分别设置。
在一个网站能跳转,换个网站就失效到读者实际会打开的平台复制该标题的锚点。

每次改完标题,在渲染后的 README 里点一遍目录,尤其留意同名标题。目录可以先列读者要找的安装、使用和排查入口,内容较长的章节再加子项,方便直接跳到小节。

汇报文档结构时附一张图

下图用同一份源码从 Markdown2Image 编辑器实际下载,可以看到正文标题层级和目录缩进。需要在幻灯片里讨论文档结构时,可以把图和 README 链接放在一起,读者打开文件即可继续跳转。在 Markdown2Image 预览示例

README 的导出图,显示带缩进的目录项和两节同名的 Examples

打开原始 PNG