mkdocs-autorefs

自动链接MkDocs中的页面。

安装

使用pip

python3 -m pip install mkdocs-autorefs

用法

# mkdocs.yml
plugins:
  - search
  - autorefs

在您的Markdown文件之一（例如 doc1.md）中创建一些标题

## Hello, world!

## Another heading

Link to [Hello, World!](#hello-world) on the same page.

这是一个常规 链接到锚点。MkDocs为每个标题生成锚点，它们始终可用于链接到某个内容，无论是同一页内（如此处所示）还是通过指定其他页面的路径。

但是使用这个插件，您可以从网站上的任何其他页面 链接到一个标题，而不需要知道这两个页面的路径，只需要知道标题的名称。
让我们再创建一个Markdown页面来尝试这个功能， subdir/doc2.md

We can [link to that heading][hello-world] from another page too.

This works the same as [a normal link to that heading](../doc1.md#hello-world).

在不了解目标页面路径的情况下链接到标题可能很有用，例如，当页面具有深度嵌套的路径、彼此相距较远或经常移动时。

非唯一标题

当链接到在网站中多次出现的标题时，此插件会记录一条警告信息，指出找到了多个URL，并建议使标题唯一，并使用找到的第一个URL来解决链接。

为了防止收到警告，请使用 Markdown锚点 为您的标题添加唯一的别名，并在引用标题时使用这些别名。

如果您不能使用Markdown锚点，例如因为您在多个位置注入相同的生成内容（例如mkdocstrings的API文档），那么您可以通过启用 resolve_closest 选项来尝试减轻警告。

plugins:
- autorefs:
    resolve_closest: true

当 resolve_closest 被启用时，如果为相同的标识符找到了多个URL，插件将尝试解析到当前页面（包含链接的页面）最近的那个。所谓“最近”，意味着

• 相对于当前页面URL的URL，向上爬升父级
• 如果多个URL相对于它，则尽可能使用距离最短的URL。

如果多个相对URL距离相同，则使用这些URL中的第一个。如果没有URL相对于当前页面的URL，则使用找到的所有URL中的第一个。

示例

Markdown锚点

autorefs插件提供了一个名为“Markdown锚点”的功能。这些锚点可以添加到文档的任何位置，并可以从任何其他位置链接到。

语法是

[](){#id-of-the-anchor}

如果您仔细观察，它以链接的常规语法开始，即[]()，但是链接的文本值和URL都是空的。然后我们看到{#锚点的id}，这是由attr_list扩展支持的语法。它将HTML id设置到锚点元素。autorefs插件只是给这样的锚点赋予了意义。请注意，不支持的原始HTML锚点，如<a id="foo"></a>。

必须启用attr_list扩展才能使Markdown锚点功能生效

# mkdocs.yml
plugins:
  - search
  - autorefs

markdown_extensions:
  - attr_list

现在，您可以在文档中添加锚点

Somewhere in a document.

[](){#foobar-paragraph}

Paragraph about foobar.

...这使得可以与我们的自动链接链接到这个锚点

In any document.

Check out the [paragraph about foobar][foobar-paragraph].

如果您在标题上方直接添加Markdown锚点，则此锚点将重定向到标题本身

[](){#foobar}
## A verbose title about foobar

链接到foobar锚点将直接带到标题，而不是锚点本身，因此URL将显示为#a-verbose-title-about-foobar而不是#foobar。因此，这些锚点充当标题的“别名”。可以为每个标题定义多个别名。

[](){#contributing}
[](){#development-setup}
## How to contribute to the project?

这种别名在多个不同页面中出现相同标题时特别有用。没有别名时，链接到标题是未定义的行为（可能导致任何一个标题）。在标题上方使用唯一的别名，您可以确保链接到正确的标题。

例如，考虑以下设置。您有一个文档，每个文档描述如何使用操作系统包管理器或从源代码安装项目。

docs/
  install/
    arch.md
    debian.md
    gentoo.md

每个页面都有

## Install with package manager
...

## Install from sources
...

您不想更改标题并使它们重复，例如 ## Arch: 使用包管理器安装 和 ## Debian: 使用包管理器安装，只是为了能够使用autorefs引用正确的标题。相反，您可以这样做

[](){#arch-install-pkg}
## Install with package manager
...

[](){#arch-install-src}
## Install from sources
...

...在其他页面中将 arch 改为 debian、gentoo 等。

您还可以更改标题的实际标识符，多亏了 Markdown 扩展 attr_list

## Install from sources { #arch-install-src }
...

...但请注意，这将影响 URL 锚点（因此也会影响标题的永久链接）。