In RST, one can easily refer to a title/heading (or more generally to a section start, which the heading really is) by using its text as a reference. For example:
... some text and then reference to `My Heading`_ ... My Heading ~~~~~~~~~~ ... some more text ... ... back reference to `My Heading`_ ...
Sometimes, though we may want to use some kind of ID to refer to the heading/title/section. One reason may be to avoid going back and change all the references after the heading changed. Some other reason may be that the document is generated automatically and we may not know the heading text at the moment of creating a (forward) reference to it.
RST uses internally (reference) identifiers to create references/links in the (output) documents. RST text uses reference names (a.k.a. simple references or phrase references) to cross-reference. Explcitly defined phrase references are typically used for hyperlinks:
Want to learn `python`_? .. python:: https://www.python.org
Headings/titles yield implicit phrase references that most authors learn to use intuitively. However,
one can use the explicit
hyperlink targets,
e.g. as above .. python:: https://www.python.org, for internal references, too. These are calledinternal hyperlink targets and they just have empty "target" (i.e. no https://www.python.org):
.. _my picture: .. image:: bild.png ... some paragraph text ... .. _my_paragraph: ... my paragraph text refering to `my heading`_ ... ... your paragraph text ... .. _my heading: Your Heading ------------ ... some more text ...
Note that the hyperlink text (in the output document) is likely to be the label of the internal hyperlink target. That is, my heading as in the example above. Note that the label can be almost anything and can include white spaces. You can certainly define multiple internal hyperlink targets for the same anchor:
.. _my hyperlink: .. _your_hyperlink: Their Title ===========
For certain directives, there is the :name:: attribute (a.k.a.
name option) that yields the same
effect as the internal hyperlink target:
.. image:: bild.png :name: my picture
For more details read about:
- Hypelink References.
- Hyperlink Targets to learn about other types of reference targets like anonymous hyperlinks.