README第一次跨越一千行,我做了每个人都在做的事情:我滚动。然后我又滚动了一些。第四遍周围的某个地方寻找"部署"部分,我放弃了,开始在文件顶部手写目录。那一直有效,直到我重新命名了一个标题,忘记更新链接,并发货了一个README,其中"配置"没有指向任何东西。在自己的文档中,一个破损的页面链接是一件小事,但它是那种告诉读者没有人介意商店的小事。
建[toolz。dev](/,基于浏览器的开发者实用工具集合,我维护了很多Markdown:工具指南,README文件,内部规范,以及你现在正在阅读的docs。我必须手工维护的目录,是一个最终会撒谎的内容表。所以我构建了 Markdown TOC 生成器 每次都正确地完成无聊的部分,这本指南是我构建锚链路时学到的一切。
TL;博士: Markdown目录是跳转到同一页标题的链接的嵌套列表,链接的工作是因为每个标题都得到一个自动锚id,GitHub分配的slug遵循一个特定的规则:将文本小写,删除连字符以外的标点符号,将空格粘贴到生成器中,选择要包含哪些标题级别,并复制列表该工具计算精确的slugs GitHub渲染,包括
-1重复标题的后缀,因此当您将其粘贴回来时,不会出现任何中断。
什么是 Markdown 目录?
Markdown 中的目录不是一个特殊的语法。 共同标记 github 味道标记法定义没有这样的构造,GitHub 味道标记法也没有定义,它是一个普通的列表,其中每个项目都是一个链接,每个链接都指向同一文档内部的一个锚点,当像 GitHub 这样的 Markdown 渲染器将一个标题变成 HTML 时,它还给出了该标题 a id 属性。写为的标题 ## Getting Started 变得粗略 <h2 id="getting-started">Getting Started</h2>.一旦该 id 存在,一个链接写为 [Getting Started](#getting-started) 将页面滚动到它。
因此,目录只是这些链接的集合,缩进以反映标题层次结构:
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
整个技巧都存在于该示例中的一个单词中:锚。获取锚错误并且链接默默失败,无处滚动。获取正确且内容块在 GitHub 上工作,在大多数静态站点生成器中,以及在遵循相同约定的文档平台内部。硬部分不是编写列表。硬部分是预测每个渲染器将分配的确切 ID,这就是为什么手动执行它是任何更改的文档的失败游戏。
航向锚的实际生成方式如何?
GitHub's slug算法是确定性的,值得记忆,因为一旦知道了,就可以预测页面上的每一个锚点,步骤,依次是:将标题文字转换为小写,去掉任何不是字母、数字、空格或连字符的字符,然后用连字符替换每个空格,那就是整个规则。
后果是人们旅行的地方。考虑一个标题 ## Set Up & Config.下套给出 set up & config。去掉安培数(但留下周围的空间)给出 set up config 有两个空格 & 过去是。将空格变成连字符产生 set-up--config的, 带双连字符,那个双连字符看起来像是一个错误,但它正是 GitHub 所渲染的,所以它正是你的链接所需要的。"清理"的工具,双连字符会产生一个不解析的链接。
标点符号- 重标题比您预期的更严重崩溃。 ## C++ Guide 变成 c-guide的,因为两个加号都被剥离,剩下的空格变成一个单连字符。 ## What's New? 变成 whats-new的,因为撇号和问号消失了表情符号和大多数符号完全消失了。的 Markdown TOC 生成器 将此规则字符应用于字符,以便它向您显示的 slug 是 GitHub 将构建的 ID,不涉及猜测。
当两个标题相同时会发生什么?
文档重复标题。变更日志可能有三个部分,全部标题为 ### Fixed.若每一种都产生了slug fixed者,只有第一个链接才行,github通过对重复项进行编号来解决这个问题:第一个 Fixed 获得 fixed,第二个得到 fixed-1,第三个得到 fixed-2(document)顺序依此类推,后缀附加在slug底数后面,并带有连字符。
这是手写目录不同步的最常见原因之一。您添加第二个部分,其中包含您已经使用的名称,锚会悄悄变为 -1的,而你的旧链接现在指向了错误的地方或根本没有地方,生成器跟踪它已经发出的每一个slug,并应用相同的数字后缀,所以重复的标题链接到正确的发生。
该工具读取哪些类型的标题?
Markdown 有两种标题样式,一个完整的生成器必须同时读取两种,常见的就是 ATX,其中一行以一到六开头 # 字符后跟标题文本。哈希数就是级别,所以 # 是H1和 ###### 是H6。第二种样式是Setext,其中下一行文本下划线,对于H1或对于H2的连字符等于符号:
Document Title
==============
A Section
---------
2种样式都产生带有锚id的标题,因此都属于目录中,带有Setext的棘手部分是在讲述一个除了水平规则之外的真实下划线标题,因为一行连字符可以表示任一生成器使用的规则,连字符下划线只有在其正上方的行是普通段落文本时才算作标题,而不是空行、列表项、块引用或另一个块构造。A --- 独自坐着,周围有空白的线条,这是一个主题突破,它被正确地忽略了。
还有一个类别需要处理,它就是一个悄悄破坏天真的工具的类别:代码内部的标题。如果您的文档包含一个显示 shell 命令的围栏代码块,其中一些行将以开头 # as comments。those 不是标题,而且它们绝不能出现在内容中。生成器跟踪有围栏的代码块(由三重回扣或三重波浪号界定的),并跳过任何 # 里面有线。 shell 评论,喜欢 # install dependencies 在示例中保留其所属的位置,在示例中。
如何控制目录的深度?
H6 下列出每个标题的目录不是目录,它是文档的第二份副本,大多数 README 在内容仅涵盖 H2 和 H3 时读得最好,为读者提供主要部分及其直系子女,而不会淹死他们的详细生成器,让您设置最小和最大级别,并且它仅包括属于该范围内的标题。
这里的微妙行为是缩进。如果将 H2 包含到 H4,则您保留的最浅标题是 H2,并且它应该与左边距齐平,而不是像其上方有一个看不见的 H1 一样缩进。生成器相对于其实际包含的最浅标题测量嵌套深度,因此从 H2 开始的内容块以没有缩进开始。这就是看起来有意的列表和看起来丢失第一列的列表之间的区别。
您还可以选择列表标记。无序列表对每个条目使用项目符号,这是 README 的常规查找。有序列表对条目进行编号,生成器重新启动每个嵌套级别内的计数,以便编号的轮廓正确读取,而不是从一到五十直接计数。缩进可以是两个空格、四个空格或一个选项卡,具体取决于文档的其余部分使用什么。
重音和非拉丁标题怎么样?
并非每个标题都是普通的英语,slug 规则必须应对。 GitHub 保留其他字母的字母而不是剥离它们,因此标题就像 ## Configuración 保留其重音字符并成为 configuración的,而一个标题用西里尔字母或希腊语也保留了这些字母。被删除的是标点符号和符号,而不是字母,无论脚本如何。生成器遵循相同的原则,将任何 Unicode 字母或数字视为有效的 slug 字符,因此多语言文档产生的锚点与 GitHub 渲染的内容相匹配,而不是一排空链接。
这比它第一次出现更重要。用西班牙语、德语或日语编写文档的团队经常发现天真的 slug 工具会将标题破坏为无法使用的锚,因为这些工具假设 ASCII。如果您的链接曾经对翻译的 README 没有指向任何内容,那么默默丢弃非 ASCII 字母的 slug 几乎可以肯定是为什么。使用 Unicode 感知工具生成内容块会删除整个类别的损坏链接,这意味着同一文档可以保留多种语言的标题,而不会丢失任何一个锚。
我应该何时使用生成的 TOC 与自动 TOC?
有些平台为您构建目录。 GitLab 支持 a [[_TOC_]] token,一些wiki会自动注入一个内容框,而像docusaurus这样的文档框架会从你的标题中渲染页面上的大纲,而你不会写任何东西,当你在其中一个系统内工作时,使用内置功能,它会保持当前状态,而不会花费零努力,因为平台会在每个渲染上重新生成它。
Generator 在其他地方都赢得自己的位置,而 " 在其他地方" 就是一个很大的地方。GitHub README 不会自动生成内容块,因此一个存储库登陆页面需要一个真正的 Markdown 列表,该列表会提交到文件中。转换为其他内容、通过电子邮件发送、粘贴到问题中或由最少的查看器渲染的 Markdown 需要一个静态内容块,因为没有引擎可以即时构建一个。下表列出了每种方法适合的位置。
| 情况 | 最佳方法 | 为什么 |
|---|---|---|
| GitHub 阅读器 | 生成静态列表 | GitHub 渲染标题 ID,但不会自动插入 TOC |
| GitLab wiki 或文档 | [[_TOC_]] 令牌 |
本地,始终是最新的 |
| Docusaurus/MkDocs 页面 | 内置轮廓 | 框架从标题中呈现它 |
| 用于导出的普通标记文件 | 生成静态列表 | 没有渲染器在查看时间构建一个 |
| 发出或拉取请求描述 | 生成静态列表 | 锚起作用,但没有自动生成列表 |
经验法则:如果显示您的 Markdown 的东西可以自己构建内容,请让它。如果您的 Markdown 可能被读取到无法读取的地方,请生成列表并提交。当您在格式之间转换时, 标记到 HTML 转换器 和 HTML 到 Markdown 转换器 自然地与生成的内容块配对,因为锚在往返中幸存下来。
这如何适合 Markdown 工作流程的其余部分?
目录是一张保持长文档可读性的表格,它与几个习惯一起工作效果最好。一旦您发布了指向它的链接,请保持标题文本稳定,因为重命名标题会改变其 slug 并破坏指向它的每个链接。当您重命名时,重新生成内容而不是编辑您记住的一个链接,因为重命名通常会将重复后缀编号进一步移至文件下方。
结构化内容受益于同一系列中的其他工具。当文档依赖于表格数据时, 降价表生成器 构建正确对齐的管道表,而手工打字的表几乎永远不会正确。当您继承需要变为干净的 Markdown 的混乱 HTML 或需要变为 HTML 的干净 Markdown 时,转换器在保留标题结构的同时处理翻译。并且如果您正在审核文档的长度或关键字平衡,则 字数计数器 为您提供数字,而无需将草稿粘贴到任何基于云的内容中。
Everything都在浏览器中运行,这比听起来更重要,一个README通常包含未发布的功能名称,内部URL或客户端详细信息,而这些都不应上传到第三方服务器,只是为了构建链接列表生成器用客户端JavaScript解析您的Markdown,因此文档永远不会离开您的机器如果开发人员工具中的隐私是您所考虑的,那么写入 数据隐私和在线工具 涵盖了为什么本地处理是正确的默认值,以及 web开发人员工具包 收集我每天接触到的其余公用事业。
一个快速工作的例子
假设您有此文档:
# Payment Service
## Getting Started
### Requirements
### Local Setup
## API Reference
### Authentication
### Errors
## Deployment
H3 设置范围为 H2, 选择项目符号列表, 并在上面留下锚链路, 生成器产生:
- [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Local Setup](#local-setup)
- [API Reference](#api-reference)
- [Authentication](#authentication)
- [Errors](#errors)
- [Deployment](#deployment)
H1标题被排除,因为它位于范围之上,H2部分被齐平左移,他们的H3孩子被缩进一个级别粘贴在你的README中的标题正下方,每个条目跳转到它在GitHub上的部分,那就是整个工作,在阅读这句话所需的时间内完成,它保持正确,因为机器计算的是slugs而不是你。
常见问题
标记目录如何工作?
Markdown目录是指向同一页面内的标题锚的链接列表,Markdown文档中的每个标题都给出一个自动id,以及一个写为的链接 科段 jump 到它。这个工具读取你的标题,构建匹配的锚,并为你组装嵌套列表。
锚链路是如何生成的?
Anchors遵循GitHub slug规则:标题文本是小写的,除去连字符以外的标点符号,空格变成连字符。"设置&配置"成为id设置 -config。当两个标题产生相同的slug时,第二个得到-1后缀,第三个-2,依此类推,匹配GitHub如何渲染它们。
它适用于 GitHub README 文件吗?
是。slug算法镜像GitHub用来渲染标题id的那个,所以目录链接在github。com上的一个README内部正确解析。粘贴你的README,选择你的标题级别,然后将生成的列表放在标题下方。
我可以选择出现哪些标题级别吗?
是。设置最小和最大水平,例如H2到H4,并且仅包括该范围内的标题。嵌套深度是相对于最浅的包含标题测量的,因此轮廓从不以大的空缩进开始。
代码块内的标题是否包括在内?
No。 围栏代码块内以 # 开头的行(由三重回扣或三重波浪号分隔)被视为代码,而不是标题,因此示例片段和 shell 注释永远不会出现在目录中。
有序 TOC 和无序 TOC 有何区别?
无序目录对每个条目使用连字符等项目符号,而有序目录使用在每个嵌套级别内递增的数字。当读者从编号的轮廓中受益时选择有序,对于更轻、更传统的内容块选择无序。
该工具支持 Setext 标题吗?
是。它读取以#开头的ATX标题和Setext标题,其中一行文本下划线,H1的符号相等,H2的连字符。两种样式都以相同的方式转换为锚链路。
Markdown TOC 生成器是免费且私密的吗?
是的。它是完全免费的,没有注册,也没有限制。所有解析都发生在使用客户端 JavaScript 的浏览器中,因此您粘贴的 Markdown 永远不会离开您的设备,并且一旦页面加载,该工具就会离线工作。
