5

I have a document in restructuredtest like: 

Header 1
========

and from some any other point (might be the same 'rst' file or a different one) I want to create a hyperlink to that header. So that when a user clicks on it, he gets to the page with the header Header 1

How to do that?

I tried to put the following line in the other document (according to this documentation):

see :ref:`Header 1`

but what I get is the following: 

see Header 1

without any link...

I also tried to follow this documentation:

What I put in to the rst file is the following

see `Header 1`_

and what I see is the following link:

see `Header 1`_

which does not look very nice ...

Alex
  • 41,580
  • 88
  • 260
  • 469

2 Answers2

4

Your first link was almost correct. You need to add a label preceding the section header, separated by a blank line. See Inline markup, Cross-referencing arbitrary locations, using the :ref: directive.

In your case:

.. _header-1-label-name:

Header 1
========

Some text

Here is a section reference: :ref:`header-1-label-name`.

Here is a section reference with a title: :ref:`Header 1 with a title <header-1-label-name>`.
Chris Wesseling
  • 6,226
  • 2
  • 36
  • 72
Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • 1
    But I do not understand - why are all the documentations wrong? What do I miss there? – Alex Feb 22 '18 at 05:34
  • The documentation is correct. The example I wrote is derived from the documentation in the link I provided. – Steve Piercy Feb 22 '18 at 08:59
  • That means I found wrong or incorrect documentation? I have used the description from the two pages I included in my question. Did I do something wrong? Are these documents incorrect? Maybe outdated? – Alex Feb 22 '18 at 09:46
  • The documentation is current and correct. I copy-pasted the examples from http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations then edited it only slightly into a single example. What is it that you do not understand? – Steve Piercy Feb 22 '18 at 10:04
  • What about [this answer](https://stackoverflow.com/a/18704682) which claims that headers form implicit targets, meaning that ` `Header 1`_ ` _should_ work, too? – hcc23 Jan 25 '23 at 16:28
  • You are welcome to use [implicit hyperlink targets](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#implicit-hyperlink-targets), but that introduces ambiguity and potential errors. It is much preferred to use `ref` with explicit labels. From https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role, "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." – Steve Piercy Jan 26 '23 at 07:50
0

In addition to the accepted answer, the label you add (in this case .. _header-1-label-name:) is required to have a dash. So a simple .. _label: won't do. Took me a while to figure that out.

Erwin Matijsen
  • 28
  • 6