Anchors

Note

Remember, though not required, it is a good idea to use a consistent prefix for anchors throughout a document.

To make an anchor (a hyperlink target) that can be targeted with the :ref: role, always use the :name: option if the target is something that appears in a directive (see source excerpt for the adjacent admonition, for instance). Only use the explicit target form (.. _this-is-a-target:) in contexts where a :name: option is not available (most commonly needed above a document title or subsection — see this doc title for instance).

.. prefix: spanc

.. _icgsphinx-anchors:

Anchors
#######

.. admonition:: Note
   :class: aside
   :name: spanc-admon-note

   Remember, though not required, it is a good idea to use a consistent
   :ref:`prefix <spanc-prefix-section>` for anchors throughout a document.

To make an anchor (a hyperlink target) that can be targeted with the
``:ref:`` role, *always* use the ``:name:`` option if the target is
something that appears in a directive (see source excerpt for the adjacent
admonition, for instance). Only use the explicit target form
(``.. _this-is-a-target:``) in contexts where a ``:name:`` option is not
available (most commonly needed above a document title or subsection — see
this doc title for instance).

In the above source excerpt, see how the admonition uses :name:, the anchor for the whole doc appears as an explicit link above the title, and note the declaration of the prefix at the top, which is described next.

Prefixes

A “prefix” is an ICG usage convention adopted to help ensure that anchors use unique strings. It consists of a comment placed at or near the top of the document that declares a fixed string to be prepended to all the document’s anchors.

So declared, all anchors defined within a document — rubrics, figures, tables, equations, included files, literal blocks, etc. — should start with the prefix. This section on “Prefixes” sets an anchor with the rubric’s :name: option; the anchor uses this doc’s prefix (“spanc” — which can be seen to be set at the top of the document in the excerpt shown above).

.. rubric:: Prefixes
   :class: h2
   :name: spanc-prefix-section

ICG Usage Notes

Explicit Anchors

Go directly above the point that they anchor, and take the form
.. _prefix-linklabel: , where prefix = the document prefix, linklabel is whatever text makes sense to the author.

Implicit Anchors using a :name: option on a directive

These take the form prefix-linklabel. No leading .. _ or trailing : necessary.

No “Rules” For Prefixes/Label Strings

There are no usage rules for selecting prefix strings and label strings, though shorter prefixes are probably better, uniqueness of labels is the main goal, and please avoid using underscore (_) in anchors.

Illustration

The admonition above can be linked to using the anchor defined in its :name: option.

.. rubric:: Illustration
   :class: h2
   :name: spanc-point-section

:ref:`The admonition above <spanc-admon-note>` can be linked to using the
anchor defined in its ``:name:`` option.

The explicit anchor above a document title is likely to be the one anchor in the document that does not use the document’s prefix.

The explicit anchor above a :ref:`document title <icgsphinxhelp-anchors>`
is likely to be the one anchor in the document that *does not* use the
document's prefix.