heading_links¶

Heading Cross Reference Links¶

Index¶

For each word in a heading, a link is included in the index from the word to the heading. In addition, each word is added to the html keyword meta data next to the page heading.

Labels¶

A cross reference label is defined for linking from anywhere to a heading. The details of how to use these labels are described below.

Level Zero¶

Each page can have only one header at the first level which is a title for the page.

page_name¶

The input below will display the page name as the linking text:

:ref: ` page_name -name `

There is an exception to this, automatically generated pages xrst_search , xrst_index , and xrst_contents , do not include the initial xrst_ in the linking text; see xrst_search.rst , and xrst_contents.rst , and xrst_index.rst .

page_title¶

The input below will display the page title as the linking text:

:ref: ` page_name -title `

Linking Text¶

You can also explicitly choose the linking text using:

:ref: ` linking_text < page_name -name> `

Other Levels¶

The label for linking a heading that is not at level zero is the label for the heading directly above it plus an at sign character @, plus the conversion for this heading. These labels use the page_name for level zero, without the -name or --title at the end.

Heading@To@Label¶

The conversion of a heading to a label removes all backslashes \ and changes at signs @ to dashes -.

For example, the label for the heading above is

heading_links@Labels@Heading-To-Label

The label corresponding to a header is used to reference the heading using the :ref: role.

Label To Anchor¶

There is a further conversion to create the HTML anchor corresponding to a label. To be specific:

1. The anchor is converted to lower case. 3. Characters that are not letters or decimal digits are converted to dashes. 4. Multiple dashes are converted to one dash. 5. The beginning of the anchor is trimmed until a letter is reached. 6. The end of the anchor is trimmed until a letter or digit is reached.

If for one page, these anchors are not unique, xrst reports an error.

Discussion¶

Note that for level zero one uses the page_name and not the title; e.g., in the example above one uses heading_links and not Heading Cross Reference Links .
The @ and not . character is used to separate levels because the . character is often used in titles and page names; e.g. conf.py.
The xrst automatically generated labels end in -name , -title , or have a @ character in them. Other labels, that you create using rst commands, should not satisfy this condition (and hence are easy to distinguish).
Including all the levels above a heading in its label may seem verbose.
1. This avoids ambiguity when the same heading appears twice in one page. For example, this link to the project name Default which is one of many Default headings on that page.
2. It also helps keep the links up to date. If a heading changes, all the links to that heading, and all the headings below it, will break. This identifies the links that should be checked to make sure they are still valid.
It is an error for two headings have the same HTML anchor. This makes the html location of a heading valid as long as its label does not change. This is useful when posting the answer to a questions using a particular heading.
The html location of a heading does not depend on the location of its page in the documentation tree or the source code. Hence an html heading location is still valid after changing its documentation and/or source code locations.

Example¶

heading_example