Markdown 目录怎么做?GitHub README 锚点与嵌套目录示例
给 GitHub README 加一个可以点击跳转的 Markdown 目录。文章提供完整可复制示例,演示二级目录、同名标题和跨文件链接,说明如何从渲染后的标题复制锚点,并按症状排查改名后失效、跳错位置与缩进问题。
在 README 开头写一个项目列表,用 [Quick start](#quick-start) 链接到 ## Quick start。 方括号里是读者看到的文字,井号后面是目标标题的锚点。
GitHub 也会根据 Markdown 文件里的标题生成 Outline(大纲)。浏览别人仓库时,可以直接从大纲跳转。给自己的 README 写目录时,可以挑出读者最常用的几节,让他们打开文件就能看到安装、用法或排查入口。GitHub 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 预览示例