使用自定义文本在reStructuredText中创建内部超链接

Question

我知道如何创建带有自定义文本的外部超链接。

`My cool link <http://www.asdf.com>`_

但我想链接到一个内部参考。

.. _foo:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua.

所以我想做类似于以下的事情

`My cool internal link <foo>`_

但这行不通。

- John

Answer 1

解决方案：

`My cool internal link <foo_>`_

- John

---

由于某种原因，使用此解决方案无法找到我的标签（错误：未知目标名称）。 - tuxayo

Answer 2

在文本上使用2个下划线，目标链接上使用1个下划线，例如：

`My cool internal link <foo_>`__

... somewhere lower ...

.. _foo:

This staff is referenced by "My cool internal link"

当我使用一个下划线代替两个时，rst2pdf会抛出一个错误。

- user2626972

---

这个不起作用。 - user366312

Answer 3

使用 reStructuredText 与 Sphinx 一起，可以使用 ref role 引用文档中的其他位置：

:ref:`link text <link-target>`

如果引用的对象定义了标题或说明文字（如文档、章节、图像等），则自定义的链接文本是可选的。此时，目标的标题将被用作链接文本，但必须省略尖括号：:ref:`link-target`。当引用段落或图像时，链接文本是必需的，因为它们没有与之关联的标题/说明文字。

链接目标必须在文档中某个地方定义，可能在其他文档中，即.rst文件中。对于章节，扩展Autosectionlabel会自动完成此操作，然后该章节的标题成为目标，也成为链接文本。在所有其他情况下，必须手动声明内部超链接目标，例如：

.. _paragraph-to-be-linked-to:

This paragraph will be referenced from elsewhere in the documentation
with :ref:`that paragraph <paragraph-to-be-linked-to>`.

请注意目标定义中的前导下划线。它可以被看作是一个向右指的箭头，这里指向链接目标内部。我们还可以使用内联内部目标来链接到（长）段落内的特定位置。

We want to point to _`this position` inside the paragraph
with :ref:`that paragraph <this position>` from elsewhere.

使用单独的Docutils时，reStructuredText中没有ref角色，因为它是由Sphinx添加的语法扩展。相反，我们需要以下语法来创建超链接：

`link text <link-target_>`_

请注意两个下划线，一个在链接目标后面，另一个在完整超链接之后。这里的想象箭头指向外部。

Docutils仅处理独立文件。它被Sphinx用作解析单个reStructuredText源文件的后端。在Sphinx文档中，后一种语法仅适用于同一文档内的内部链接，而不适用于跨文档，即在一个.rst文件中定义的超链接引用到另一个文件中的目标。

与ref角色不同，人们可能会发现Sphinx提供的any角色更方便。它还将自动查找由扩展创建的链接目标，例如使用Autodoc记录的源代码对象。当在conf.py中声明为默认角色时，使用default_role = 'any'，我们可以编写`链接文本<链接目标>`甚至只需`链接目标`即可创建内部超链接。除了没有下划线之外，前者看起来很像Docutils识别的单文档reStructuredText语法，但是由Sphinx以跨文档方式处理。

- john-hen

Answer 4

如果John的解决方案对您无效：

`My cool internal link<foo>`

- tuxayo

---

似乎不起作用。我必须在最后一个反引号后使用 my link <target_>，并在 _ 后面添加。另外，链接目标不幸的是对标题无效，只对锚点有效。为了解决这个问题，我将 #my-heading-text 作为目标放置，这对 HTML 有效。 - Nick Treleaven

Answer 5

您只需要删除自定义标题后面、尖括号前面的空格，并使用:ref:指令：

这样做是有效的：

:ref:`My cool internal link with no space before bracket<foo>`

这不行：

:ref:`My cool internal link with space <foo>`

- user2662404