交叉引用

MyST-Parser 提供了强大的交叉引用功能，可以链接到 URL、文档、标题、图表等，这些功能在输出格式之间是 可移植的，并在链接失效时生成 警告。

本页介绍了为内容设置可引用目标的基础知识以及如何引用它们。

1.  创建显式目标

目标用于定义自定义锚点，您可以在文档的其他地方引用这些锚点。

有三种主要方式可以创建目标：

1. 使用 (target)= 为语法块添加注释

2. 使用 {#id} 属性为语法块/行内/跨行内容添加注释（使用 attrs_block 和 attrs_inline 插件）

3. 在指令中添加 name 选项

(heading-target)=
### Heading

{#paragraph-target}
This is a paragraph, with an `id` attribute.

This is a [span with an `id` attribute]{#span-target}.

:::{note}
:name: directive-target

This is a directive with a `name` option
:::

[reference1](#heading-target), [reference2](#paragraph-target),
[reference3](#span-target), [reference4](#directive-target)

Heading

This is a paragraph, with an id attribute.

This is a span with an id attribute.

备注

This is a directive with a name option

reference1, reference2, reference3, reference4

还有一些特定指令可以创建目标，例如 术语表 为术语创建目标，代码 API 为对象创建目标：

{.glossary}
my other term
: Definition of the term

[Link to a term](<#my other term>)

```{py:class} mypackage.MyClass
:nocontentsentry:
Docstring content
```

[Link to a class](#mypackage.MyClass)

my other term

Definition of the term

Link to a term

class mypackage.MyClass

Docstring content

Link to a class

参见

脚注部分 介绍了如何创建和链接脚注，而 sphinxcontrib.bibtex 插件提供了引用参考文献的功能。

2.  隐式目标

可以通过路径引用整个文档。还可以通过设置 myst_heading_anchors 配置选项为文档中的标题分配隐式目标。该选项应设置为 1 到 6 之间的整数，表示分配目标的标题深度。

锚点“ slugs ”是根据 GitHub 实现 创建的：标题被转换为小写，标点符号被移除，空格替换为 -，并通过后缀枚举确保唯一性。

例如，使用 myst_heading_anchors = 2：

## A heading with slug

## A heading with slug

<project:#a-heading-with-slug>

[Explicit title](#a-heading-with-slug-1)

A heading with slug

A heading with slug

A heading with slug

Explicit title

更多信息请参见 自动生成的标题锚点 部分。

警告

通常不建议依赖隐式目标，因为它们很容易被破坏，例如文档/标题被移动或重命名时。

3.  Markdown 链接语法

Markdown 链接有三种形式：

自动链接 是由 < 和 > 包围的 [URI][uri]，必须始终包含 scheme：

<scheme:path?query#fragment>

行内链接 允许可选的显式文本和标题（在 HTML 中，标题会显示为工具提示）：

[Explicit *Markdown* text](destination "optional explicit title")

或者，如果目标包含空格，

[Explicit *Markdown* text](<a destination> "optional explicit title")

引用链接 在文档中单独定义目标，并且可以多次使用：

[Explicit *Markdown* text][label]
[Another link][label]

[label]: destination "optional explicit title"

参见

CommonMark 规范

3.1.  默认目标解析

链接的目标可以解析为 外部 目标，例如指向另一个网站的 [URL]，也可以是 内部 目标，例如同一项目中的文件、标题或图表。

默认情况下，MyST 将根据以下规则解析链接目标：

1. 以方案开头的目标（例如 xxx:）将根据该方案处理：

   1. 以 project: 开头的目标将被视为内部引用

   2. 以 path: 开头的目标将被视为可下载文件

   3. 以 inv: 开头的目的地将被视为 intersphinx 引用

   4. 以 http:、https:、ftp: 或 mailto: 开头的自动链接或目的地将被视为外部 [URL] 链接。

2. 指向本地文件路径的目的地将被视为该文件的链接。

   1. 如果目的地是相对路径，它将相对于当前文件进行解析。

   2. 如果目的地是绝对路径（以 / 开头），它将相对于项目的根目录（即源目录）进行解析。

   3. 如果该路径与项目中的另一个文档相关（例如 .md 或 .rst 文件），则它将链接到该文档的第一个标题。

   4. 链接到项目文档时，也可以包含 # 片段标识符，以链接到该文档中的特定标题。

   5. 如果路径指向非源文件（例如 .png 或 .pdf 文件），则链接将指向文件本身，例如以下载该文件。

3. 以 # 开头的目的地将被视为内部引用。

   1. 首先，在同一文件中搜索显式目标，如果未找到

   2. 然后，在同一文件中搜索隐式目标，如果未找到

   3. 接着，在整个项目中搜索显式目标，如果未找到

   4. 然后，搜索 intersphinx 引用，如果未找到

   5. 然后，搜索 intersphinx 引用，如果未找到

备注

本地文件路径解析和跨项目引用在单页构建中不可用

3.2.  显式与隐式链接文本

如果链接文本是显式给出的，例如 [text](#dest)，则渲染的文本将是该内容。此文本可以包含嵌套的内联标记，例如 [*emphasis*](#syntax/emphasis)。

如果未提供文本或为自动链接，例如 [](#dest) 或 <project:#dest>，则 MyST 将尝试解析隐式文本。例如，如果目的地是标题，则标题文本将用作链接文本；如果目的地是图/表，则标题将用作链接文本。否则，链接文本将是目的地本身。

3.3.  示例

自动链接

:External URL: <https://example.com>
:Internal target reference: <project:#cross-references>
:Internal file reference: <project:../intro.md>
:Internal file -> heading reference: <project:../intro.md#-get-started>
:Downloadable file: <path:example.txt>
:Intersphinx reference: <inv:sphinx:std#index>

外部链接:

https://example.com

内部目标引用:

Cross-references

内部文件引用:

🚀 开始使用

内部文件 -> 标题引用:

🚀 Get Started

下载文件:

example.txt

Intersphinx 引用:

Sphinx

带有隐式文本的内联链接

:External URL: [](https://example.com)
:Internal target reference: [](#cross-references)
:Internal file reference: [](../intro.md)
:Internal file -> heading reference: [](../intro.md#-get-started)
:Downloadable file: [](example.txt)
:Intersphinx reference: [](inv:sphinx:std#index)

外部链接:

内部目标引用:

Cross-references

内部文件引用:

🚀 开始使用

内部文件 -> 标题引用:

🚀 Get Started

下载文件:

example.txt

Intersphinx 引用:

Sphinx

带有显式文本的内联链接

:External URL: [Explicit text](https://example.com)
:Internal target reference: [Explicit text](#cross-references)
:Internal file reference: [Explicit text](../intro.md)
:Internal file -> heading reference: [Explicit text](../intro.md#-get-started)
:Downloadable file: [Explicit text](example.txt)
:Intersphinx reference: [Explicit text](inv:sphinx:std#index)

外部链接:

Explicit text

内部目标引用:

Explicit text

内部文件引用:

Explicit text

内部文件 -> 标题引用:

Explicit text

下载文件:

Explicit text

Intersphinx 引用:

Explicit text

3.4.  自定义外部 URL 解析

Added in version 0.19: myst_url_schemes 现在允许自定义链接如何转换为 URL，并且可以使用 attrs_inline 扩展将某些链接指定为外部链接。

默认情况下，所有以 http:、https:、ftp: 或 mailto: 开头的链接将被视为外部 [URL] 链接。你可以通过多种方式使用配置选项来自定义此行为。

最简单的方式是将 myst_all_links_external 配置选项设置为 True，这样所有链接都将被视为外部 [URL] 链接。

要选择性地应用于特定链接，你可以启用 attrs_inline 插件，然后为链接添加 external 类。\ 例如，[my-external-link](my-external-link){.external} 变为 my-external-link。

要指定自定义的 URL 方案列表，你可以设置 myst_url_schemes 配置选项。默认情况下，它设置为 ["http", "https", "ftp", "mailto"]。

除了可以是字符串列表外，myst_url_schemes 还可以是字典，其中键是 URL 方案，值定义链接如何转换为 URL。这允许你自定义特定方案的链接到 URL 的转换，例如：

myst_url_schemes = {
    "http": None,
    "https": None,
    "wiki": "https://en.wikipedia.org/wiki/{{path}}#{{fragment}}",
    "doi": "https://doi.org/{{path}}",
    "gh-issue": {
        "url": "https://github.com/executablebooks/MyST-Parser/issue/{{path}}#{{fragment}}",
        "title": "Issue #{{path}}",
        "classes": ["github"],
    },
}

允许使用如下链接：

• [URI](wiki:Uniform_Resource_Identifier#URI_references) 被转换为 URI

• <doi:10.1186/gm483> 被转换为 doi:10.1186/gm483

• <gh-issue:639> 被转换为 Issue #639

小技巧

你还可以使用 sphinx-tippy 插件为链接添加丰富的“悬停”工具提示。

添加 github 类可以很好地与 pydata-sphinx-theme 的 GitHub 链接格式化 集成

每个 scheme 的值可以是：

• None：链接直接转换为外部 URL。

• 字符串：链接使用该字符串作为模板转换为外部 URL。

• 字典：链接使用字典的 url 键作为模板转换为外部 URL。

  • （可选的） title 键是链接隐式标题的模板，即如果链接没有显式标题时使用它。

  • （可选的） classes 键是要添加到链接的类列表。

url 和 title 的模板可以使用变量（用 {{ }} 包裹），这些变量将替换为链接 <scheme>://<netloc>/<path>;<params>?<query>#<fragment> 的相应部分（或使用 uri 表示完整链接）。例如：

• scheme：URL 方案，例如 wiki。

• path：URL 的路径部分，例如 Uniform_Resource_Identifier。

• fragment：URL 的片段部分，例如 URI_references。

3.5.  跨项目（intersphinx）链接

Added in version 0.19.

每个 Sphinx HTML 构建都会生成名为 objects.inv 的文件，其中包含从可引用对象到相对于 HTML 集合根目录的 [URI][uri] 的映射。每个对象由 domain、type 和 name 唯一标识。除了相对位置外，对象还可以包含引用的隐式 text （例如标题的文本）。

你可以使用 myst-inv 命令行工具（随 myst_parser 安装）来可视化和筛选任何远程 URL 或本地文件路径指向的此清单文件（或其父目录）：

# $ myst-inv https://www.sphinx-doc.org/en/master -n index
name: Sphinx
version: 6.2.0
base_url: https://www.sphinx-doc.org/en/master
objects:
  rst:
    role:
      index:
        loc: usage/restructuredtext/directives.html#role-index
        text: null
  std:
    doc:
      index:
        loc: index.html
        text: Welcome

要将外部清单加载到你的 Sphinx 项目中，你必须加载 sphinx.ext.intersphinx 插件，并设置 intersphinx_mapping 配置选项。

extensions = ["myst_parser", "sphinx.ext.intersphinx"]
intersphinx_mapping = {
    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
}

Docutils 配置

使用 docutils.conf 配置文件，更多详情请参见 单页构建。

[general]
myst-inventories:
  sphinx: ["https://www.sphinx-doc.org/en/master", null]

然后，你可以通过在目标 [URI] 前添加 inv 方案来引用清单对象：inv:key:domain:type#name。

key、domain 和 type 是可选的，例如对于 inv:#name，将搜索所有清单、域和类型，如果找到多个匹配项，则会发出警告。

此外，* 是通配符，匹配零个或多个字符，例如 inv:*:std:doc#a* 将匹配所有清单中 name 以 a 开头的 std:doc 对象。注意，要匹配字面 *，请使用 \*。

以下是一些示例：

类型	语法	渲染后
自动链接，完整形式	<inv:sphinx:std:doc#index>	Sphinx
链接，完整形式	[Sphinx](inv:sphinx:std:doc#index)	Sphinx
自动链接，无类型	<inv:sphinx:std#index>	Sphinx
自动链接，无域	<inv:sphinx:*:doc#index>	Sphinx
自动链接，仅名称	<inv:#*.Sphinx>	sphinx.application.Sphinx

4.  引用角色

Sphinx 提供了许多用于引用特定对象的角色。

这些也可以在 MyST 文档中使用，但建议尽可能使用 Markdown 语法，因为它更具可移植性且更符合 MyST 的原生特性。

- {ref}`syntax/referencing`, {ref}`Explicit text <syntax/referencing>`
- {term}`my other term`
- {doc}`../intro`, {doc}`Explicit text <../intro>`
- {download}`example.txt`, {download}`Explicit text <example.txt>`
- {py:class}`mypackage.MyClass`, {py:class}`Explicit text <mypackage.MyClass>`
- {external:class}`sphinx.application.Sphinx`, {external:class}`Explicit text <sphinx.application.Sphinx>`
- {external+sphinx:ref}`code-examples`, {external+sphinx:ref}`Explicit text <code-examples>`

---

- <project:#syntax/referencing>, [][syntax], [Explicit text][syntax]
- [](<#my other term>)
- <project:../intro.md>, [Explicit text](../intro.md)
- <path:example.txt>, [Explicit text](example.txt)
- <project:#mypackage.MyClass>, [Explicit text](#mypackage.MyClass)
- <inv:#*Sphinx>, [Explicit text](#sphinx.application.Sphinx)
- <inv:sphinx#code-examples>, [Explicit text](inv:sphinx#code-examples)

[syntax]: #syntax/referencing

• 交叉引用, 显式文本

• my other term

• 🚀 开始使用, Explicit text

• example.txt, Explicit text

• mypackage.MyClass, Explicit text

• sphinx.application.Sphinx, Explicit text

• Showing code examples, Explicit text

---

• 交叉引用, 交叉引用, Explicit text

• my other term

• 🚀 开始使用, Explicit text

• example.txt, Explicit text

• mypackage.MyClass, Explicit text

• sphinx.application.Sphinx, Explicit text

• Showing code examples, Explicit text

5.  处理无效引用

在构建文档时，建议在挑剔模式下运行，该模式会对任何无效引用发出警告。

你可能会遇到如下警告：

intro.md:1: WARNING: 'myst' cross-reference target not found: 'reference' [myst.xref_missing]

intro.md:2: WARNING: Multiple matches found for 'duplicate': inter:py:module:duplicate, inter:std:label:duplicate [myst.iref_ambiguous]

要完全抑制特定类型的警告，你可以在 Sphinx 的 conf.py 文件中使用 suppress_warnings 配置选项：

suppress_warnings = ["myst.xref_missing", "myst.iref_ambiguous"]

或者在 docutils.conf 或命令行工具中：

[general]
myst-suppress-warnings = myst.xref_missing, myst.iref_ambiguous

在 Sphinx 中，还可以使用 nitpick_ignore 和 nitpick_ignore_regex 配置选项来抑制特定引用警告。

nitpick_ignore = [("myst", "reference")]

要处理模糊引用，对于 intersphinx 引用，请参见 跨项目（intersphinx）链接 部分，或者可以使用 myst_ref_domains 配置全局或按文档限制所有 Markdown 引用搜索的域。

myst_ref_domains = ["std", "py"]