引用和交叉引用

引用和交叉引用#

因为 jupyter-book 是建立在 Sphinx 之上的，所以在你的书中（甚至在其他书籍或Sphinx网站中）有许多引用内容的方式。

引用是通过 角色 或 Markdown链接语法 来实现的，具体取决于你的用例。根据你想要引用的内容类型，有几种方式可以引用书中的内容。

See also

如果你刚开始，可以查看 开始使用引用 获取更多信息。

引用章节标签#

标签是一种为内容部分添加标记的方式，以便你以后可以引用它们。如果你想快速插入链接到书中的其他部分，这很有帮助。标签可以添加在页面的主要元素之前，如标题或图表。

要添加标签，请在使用以下模式 在元素之前：

(my-label)=
# 要标记的内容

例如，我们在本节的标题之前添加了以下标签：

(content:references:labels)=
## 引用章节标签

你可以使用两种语法在内容中插入对标签的交叉引用：

  • {ref}`label-text`

  • [](label-text)

例如，语法 {ref}`content:references:labels` 或 [](content:references:labels) 会生成指向本节的链接，如下所示：引用章节标签。

引用图表#

要引用书中的图表，首先添加一个图表并确保它有 name 和与之关联的标题：

```{figure} ../images/cool.jpg
:name: my-fig-ref

我的图表标题。
```
../_images/cool.jpg

Fig. 1 我的图表标题。#

然后，通过其 :name: 值引用图表。例如：

source

result

Here is {ref}`my-fig-ref`

Here is 我的图表标题。

Here is {ref}`My cool fig <my-fig-ref>`

Here is My cool fig

Here is [](my-fig-ref)

Here is 我的图表标题。

Here is [My cool fig](my-fig-ref)

Here is My cool fig

Here is {numref}`my-fig-ref`

Here is Fig. 1

Here is {numref}`Custom Figure %s text <my-fig-ref>`

Here is Custom Figure 1 text

引用表格#

要引用表格，首先创建一个表格并确保它有 :name: 和标题：

```{table} 我的表格标题
:name: my-table-ref

| 标题 1 | 标题 2 |
|---|---|
| 3 | 4 |
```
Table 1 我的表格标题#

标题 1

标题 2

3

4

以下是引用此内容的几种方式：

source

result

Here is {ref}`my-table-ref`

Here is 我的表格标题

Here is {ref}`My cool table <my-table-ref>`

Here is My cool table

Here is [](my-table-ref)

Here is 我的表格标题

Here is [My cool table](my-table-ref)

Here is My cool table

Here is {numref}`my-table-ref`

Here is Table 1

Here is {numref}`Custom Table %s text <my-table-ref>`

Here is Custom Table 1 text

引用内容文件#

要引用其他书籍内容文件，请使用 {doc} 角色，或直接使用Markdown链接语法链接到另一个文件。例如：

source

result

Here is {doc}`../file-types/myst-notebooks.md`

Here is 完全用 Markdown 编写的笔记本

Here is {doc}`A different page <../file-types/myst-notebooks.md>`

Here is A different page

Here is [](../file-types/myst-notebooks.md)

Here is 完全用 Markdown 编写的笔记本

Here is [A different page](../file-types/myst-notebooks.md)

Here is A different page

引用方程#

要引用方程，首先插入带有标签的方程，如下所示：

```{math}
:label: my-math-ref
w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}
```
(1)#\[w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}\]

要引用公式，请使用 {eq} 角色。它将自动插入公式的编号。 请注意，您不能修改公式链接的文本。

例如：

  • 请参见方程 {eq}`my-math-ref` 结果为：请参见方程 (1)

  • 请参见方程 [](my-math-ref) 结果为：请参见方程 (1)。

选择引用文本#

如果您想选择渲染引用链接的文本，请使用以下模式：

{someref}`您在此处的文本 <reference-target>`

其中，reference-target 是您所引用的目标，而 您在此处的文本 将是页面中显示的文本。

例如，请参见以下引用：

- {ref}`这是另一个引用部分 <content:references:labels>`
- {doc}`这是代码输出部分 <code-outputs>`

编号引用#

您可以为 表格、图表 或 章节 添加 编号引用。 要为表格或图表添加编号引用，请使用 {numref} 角色。

使用编号引用和自定义文本#

如果您在引用中使用自定义文本，请使用 %s 作为编号的占位符。

这里是 {numref}`自定义表格 %s 文本 <my-table-ref>`。

这里是 自定义表格 1 文本。

请参阅上述链接的章节以查看更多示例。

引用编号章节#

要引用编号章节，您应首先在目录中启用编号章节。 然后，您可以像对图表或表格一样使用 {numref} 角色。

使用 Markdown 链接语法引用#

如果您希望使用 Markdown 样式语法，那么 MyST Markdown 将尝试从上述任何引用类型（以及更多！）中找到引用。

这有一个优点，即您可以在文本中使用嵌套的 Markdown 语法，例如：

- [一个指向页面的 **加粗的 _引用_**](./myst.md)
- [一个指向标题的引用](content:references:labels)

如果标题为空，引用将使用目标作为文本，例如：

[](./myst.md)

MyST Markdown 概述

内部与外部 URL

您可以在 _config.yml 中控制 MyST Markdown 如何区分内部引用和外部 URL。 例如，

parse:
   myst_url_schemes: [mailto, http, https]

意味着 [Jupyter Book](https://jupyterbook.org) 将被识别为 URL，但 [Citations](content:citations) 不会：

检查缺失引用#

您可以在构建 Jupyter Book 时检查缺失引用。 为此，请使用以下选项：

jupyter-book build -W -n --keep-going docs/

这将检查缺失引用 (-n) 并将它们转换为错误 (-W)， 但仍会尝试运行完整构建 (--keep-going)， 以便您可以在一次运行中看到所有错误。