RST is an alternative to the popular markdown. It is used mostly for the Python documentation. But using links and references with RST still confuses me. The relevant information on the spec is quite scattered all over the places. Here is an attempt to scramble them into one place in an organized manner.

Link and Target

All references, links, footnotes and the like comprise of two parts: the link and the target. Based on how they are used, more categories are created. But the pattern is as follows:

Link consists of a string wrapped in a pair of backtick, followed immediately by an underscore:

`name of the link`_

Target consists of two periods, a space, an underscore and followed immediately by a backtick wrapped string, then a colon and a block of text which would be the destination for its link.

.. _`name of the target`:
target

The various categories derive from the above pattern with their own modification. See below for the actual usage.

explicit target

explicit target are those that have to be specified by the user, as opposed to created automatically. Starting with the general pattern

.. _`name of the target`:
target

it can take on multiple forms

as a link that is chained

.. _`name of the target`:
`name of the link`_

.. _`name of the link`:
`name of another link`_

.. _`name of another link`:
`finally the target`

refer to a section or paragraph that follows it immediately

.. _`name of the target`:

another paragraph or a heading

refers to an external location

.. _`name of the target`:
https://www.google.com

implicit target

implicit targets are those created automatically. For example, the sections of a documents are considered target and can be pointed to

link

link can be a standalone (this is limited to targets within the same document)

`just a link`_

or can be a hybrid that acts both as link and target

`link <target>`_

which can be expanded into the following forms

`a website <https://google.com>`_

`another part of the same document <implicit or explicit target>`

:ref:`link name <the actual link to the target>`

The last example is used to refer to a target in a separate rst file

when used as a hybrid, it can also be used as a target for another link (not recommended though)

`google home page <https://google.com>`

`the same google home page <google home page_>`

footnote and references

footnotes and references are special usage of the pattern mentioned above with modified syntax. But the gist of it remain unchanged

to create a footnote link:

[1]_

and then elsewhere in the document, create a footnote target

.. [1] the actual content of the footnote

similarly for citation

here, we make a reference [ABCDEF]

.. [ABBCDEF] the reference content