autosectionlabel¶

注意

v0.13.0✨ 中的新功能，myst-parser 现在提供了一个单独的 autosectionlabel 实现，它实现了 GitHub Markdown 风格的书签锚，比如[](file.md#header-anchor).

activate autosectionlabel¶

将以下内容添加到您的 conf.py 文件中，在您的 Sphinx 中激活它：

extensions = [
    'sphinx.ext.autosectionlabel',
]

# Prefix document path to section labels, to use:
# `path/to/file:heading` instead of just `heading`
autosectionlabel_prefix_document = True

当然，激活 autosectionlabel 后也可以同时使用一般的 label 标签。

自动为节标题创建目标¶

此扩展程序允许您引用其标题的部分。

例如：

A Plain Title
-------------

This is the text of the section.

It refers to the section title, see :ref:`A Plain Title`.

在内部，此扩展为每个部分生成标签。如果在整个文档中使用相同的部分名称，则默认情况下使用任何一个作为目标；不过正常来说我们肯定是不希望如此的，所以我们可以使用 autosectionlabel_prefix_document 配置变量，它可以使的不同文件下可以有相同的标签，需要注意的是这个标签在一个文件中是唯一的。

配置¶

autosectionlabel_prefix_document: 如果值为 True ，用它所在的文档的名称作为每个部分标签的前缀，后跟一个冒号。例如，index:Introduction 对于 Introduction 出现在文档中的名为的部分 index.rst。当相同的部分标题出现在不同的文档中时，可用于避免歧义。
autosectionlabel_maxdepth: 如果设置此配置， autosectionlabel 将按深度选择要标记的部分。例如，当设置 autosectionlabel_maxdepth = 1 时，只为顶层部分生成标签，而不标记更深的部分。它默认为None（禁用）。

在 MyST Markdown 中使用 autosectionlabel¶

{ref}`syntax/extend/autosectionlabel:activate autosectionlabel`

{ref}`syntax/extend/autosectionlabel:配置`

[标签 activate-autosectionlabel](#activate-autosectionlabel)

[标签 rstautosectionlabel](./autosectionlabel.html#rstautosectionlabel)

运行渲染效果如下：

activate autosectionlabel

配置

标签 activate-autosectionlabel

标签 rstautosectionlabel

我们在使用 ref 来表示内部链接时的两种写法：

{ref}`syntax/extend/autosectionlabel:配置` ：以文档根目录（source文件夹下开始为根）为起点，以路径唯一地确认到一个文件，并用冒号来指向文件中的一个标题。
{ref}`title <label-name>` ：直接在尖括号中填写 label 标签名，在 title 中添加表示内部链接的文本。

我们在以 Markdown 链接语法 []() 来表示内部链接时：

[标签 activate-autosectionlabel](#activate-autosectionlabel) ：文件内的链接可以直接通过这个方式表示。
[标签 rstautosectionlabel](./autosectionlabel.html#rstautosectionlabel) ：文件外的链接可以直接使用相对路径来表示。当然，我们会发现文件名后缀为 html，但是我们实际的源码文件的后缀是 md ，这是因为我们的构建产生的文档是html的。

MyST Markdown 与 RST 的写法中不同的在于前者需要明确指出文件类型，而且还是最终生成文件的类型；但是后者只需要文件名。

需要注意的是，一般来说，我们的构建产生的文档是html的。

在RST中使用autosectionlabel¶

代码块 3 reStructuredText 语法下¶

:ref:`syntax/extend/autosectionlabel:activate autosectionlabel`

:ref:`syntax/extend/autosectionlabel:配置`

运行渲染效果如下：

activate autosectionlabel

配置

autosectionlabel 自动创建锚点的规律¶

我们可以通过查看此界面的html文件的标题索引：

代码块 4 此界面的html文件的标题索引¶

<ul class="visible nav section-nav flex-column">
   <li class="toc-h2 nav-item toc-entry">
      <a class="reference internal nav-link" href="#activate-autosectionlabel">
         activate autosectionlabel
      </a>
   </li>
   <li class="toc-h2 nav-item toc-entry">
      <a class="reference internal nav-link" href="#id1">
         自动为节标题创建目标
      </a>
   </li>
   <li class="toc-h2 nav-item toc-entry">
      <a class="reference internal nav-link" href="#id2">
         配置
      </a>
   </li>
   <li class="toc-h2 nav-item toc-entry">
      <a class="reference internal nav-link" href="#myst-markdown-autosectionlabel">
         在 MyST Markdown 中使用 autosectionlabel
      </a>
   </li>
   <li class="toc-h2 nav-item toc-entry">
      <a class="reference internal nav-link" href="#rstautosectionlabel">
         在RST中使用autosectionlabel
      </a>
   </li>
   <li class="toc-h2 nav-item toc-entry">
      <a class="reference internal nav-link" href="#id3">
         autosectionlabel 自动创建锚点的规律
      </a>
   </li>
   <li class="toc-h2 nav-item toc-entry">
      <a class="reference internal nav-link" href="#myst-anchors">
         自动为节标题创建标签的另一种实现 myst-anchors
      </a>
   </li>
</ul>

我们可以发现：

对于中文标题
- autosectionlabel 是没有办法识别的，所以它会自动以 id + 数字 编排 label ；例如本文中的自动为节标题创建目标标题。
如果是中英文混搭的标题
- 那么它将会只识别英文；然后便是参考下一级的规律编排 label。例如本文中的在RST中使用autosectionlabel 标题。
对于英文标题
- 如果是一个单词，那么这个单词会作为 label ，如果是多个单词（一般都是以空格间隔），那么单词之间以 - 相连作为此标题的 label ；例如本文中的 activate autosectionlabel 标题。
- 如果发现在此文件中已经存在相同的 label ，那么除了第一个是有效的之外，其他的都是无效的需要重新以 id + 数字 编排 label的；例如本文中的 autosectionlabel 自动创建锚点的规律标题。

自动为节标题创建标签的另一种实现 myst-anchors¶

由于 myst-anchors 与 autosectionlabel 会相互冲突，所以没有激活此功能，故而下文中的例子没有成功渲染。

常见的扩展Markdown语法是在本地使用标头书签链接; [](#header-anchor)，或者跨文件[](path/to/file.md#header-anchor)。要实现这一点，必须为节标题分配锚，这可以在myst-parser 中实现，方法是在 conf.py 中设置 myst_heading_anchors = 2。这将为 h1 和 h2 级别的标题配置标题锚。

锚“slugs”创建的目的是遵循GitHub实现;小写文本，删除标点符号，用-替换空格，唯一性通过后缀枚举-1。要更改 slug 函数，请将 conf.py 中的myst_heading_slug_func设置为接受字符串并返回字符串的函数。你可以使用命令行工具来检查将要创建的链接:

$ myst-anchors -l 2 docs/syntax/optional.md
<h1 id="optional-myst-syntaxes"></h1>
<h2 id="admonition-directives"></h2>
<h2 id="auto-generated-header-anchors"></h2>
<h2 id="definition-lists"></h2>
<h2 id="images"></h2>
<h2 id="markdown-figures"></h2>
<h2 id="direct-latex-math"></h2>

For example：

[](#activate-autosectionlabel) ：
[other-file](./autobuild.md#sphinx-autobuild) : other-file