41

I have a document with many headings and sub-headings. Further into the text I want to link back to one of the headings. How can I do this without the redundancy of :ref: labels? The contents seems to pick up headers just fine. I was hoping for something like this: `#polled-data-retrieval`_.

3

4 Answers 4

49

reStructuredText supports implicit hyperlink targets. From the reStructuredText quick reference:

Section titles, footnotes, and citations automatically generate hyperlink targets (the title text or footnote/citation label is used as the hyperlink name).

So the following text (lifted from the reStructuredText quick reference, spelling mistakes and all):

Titles are targets, too
=======================
Implict references, like `Titles are targets, too`_.

produces HTML similar to the following:

<strong><a name="title">Titles are targets, too</a></strong>

<p>Implict references, like <a href="#title">Titles are targets, too</a>.</p>
1
  • 2
    Using the headline text isn't a good choice. Headlines may change or might get corrected. There is now easy way to figure out who many and where links are broken after a change. You should use explicit linking with references (like LaTeX does since ages.)
    – Paebbels
    Dec 28, 2019 at 17:00
31

A small addition to the answer by Chris:

If you want to link to headings without using the exact name of that heading for the link, you can do it like this:

Titles are targets, too
=======================

See `here <#titles-are-targets-too>`_

This will render as:

<h1 id="titles-are-targets-too">Titles are targets, too</h1>

<p>See <a href="#titles-are-targets-too">here</a></p>
2
  • 4
    This is the most general-purpose answer. Most answers assume Sphinx, which is certainly fair enough for a question referencing Sphinx. Since Sphinx fails to apply to generic reStructuredText documents (e.g., README.rst in GitHub or GitLab repositories), however, answers assuming Sphinx-specific :ref: syntax fail to generalize. See also this authoritative answer elsewhere. Apr 26, 2020 at 6:29
  • 2
    @CecilCurry Unless you need the output to work in something that isn't a browser.
    – Peilonrayz
    Jan 24, 2021 at 14:23
30

New, better answer for 2016!

The autosection extension lets you do this easily, with real cross references.

=============
Some Document
=============


Internal Headline
=================

then, later...

===============
Some Other Doc
===============


A link-  :ref:`Internal Headline`

This extension is built-in, so all you need is to edit conf.py

extensions = [
    .
    . other
    . extensions
    . already
    . listed
    .
    'sphinx.ext.autosectionlabel',
]

The only thing you have to be careful of is that now you can't duplicate internal headlines across the doc collection. (Worth it.)

3
  • Thank you. I kept thinking this was always enabled by default, couldn't figure out why some of my refs weren't working. Oct 2, 2017 at 17:01
  • 1
    A minor addition: :ref:`Short link <Very long headline that clutters your text otherwise>` is possible as well
    – rvf
    Nov 18, 2019 at 8:26
  • This option worked for me, thank you! However, it is not compatible with sphinx_togglebutton extension. Do you have any suggestion on it or should I compose a new question about it?
    – TheClem
    Jun 30, 2021 at 8:00
11

Using the headline text isn't a good choice. Headlines may change or might get corrected. There is now easy way to figure out who many and where links are broken after a change.

Using ref is advised over standard reStructuredText links to sections (like `Section title`_) because it works across files, when section headings are changed, will raise warnings if incorrect, and works for all builders that support cross-references.
Source: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref

Using the sphinx.ext.autosectionlabel extension as proposed by Adam Michael Wood is at least a more structured approach then using implicitly defined anchors as proposed by Chris.


You should use explicit linking with references and symbolic target names (like LaTeX does since ages.)

  1. Use .. _refname: to create a target.
  2. Use :ref:`refname` to reference the target.

If a target is followed by a headline, this headline will be used als link text.

1
  • 5
    Reading the first part of the answer I'm thinking "yeah, makes sense" but... when are the examples, how should one actually use it? Jan 21, 2021 at 9:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.