Quickstart
inline_reference
relies on a sphinx domain, but within the domain, all the provided roles can be
used like normal sphinx roles; the one caveat is that for all roles, the full syntax, e.g.
:iref:ref:`title<id>`
, which specifies both the title to be displayed and the link ID, must be
used. For example, to create this hyperlink, the
:iref:ref:`this hyperlink<id1>`
rst was used.
Simple cross-reference links
As shown above, to create a link, the :iref:ref:`title<id>`
role has to be used. However, a link
needs a destination, or a target, which is created using the :iref:target:`title<id>`
role. For
a link to be created, an :iref:ref:
role and a :iref:target:
role must share an ID. For
example, the above reference can be linked here by using
:iref:target:`here<id1>`
. Any number of references can be created to point to the same target,
but:
Warning
creating multiple :iref:target:
with the same ID will lead to errors.
Note
The IDs used with :iref:
are global, meaning that a cross-reference can be created
between different documents. However, it also means that the IDs must be globally unique.
Formatting
The
title
provided to the:iref:ref:
role is formatted like any other sphinx hyperlink. Theid
is only used for cross-referencing and is not visible. All of this is the case even when the:iref:ref:
is used to link to a backlink.The
title
provided to:iref:target:
is formatted like the surrounding text and therefore should not be distinguishable. Theid
is likewise used only for cross-referencing and is not made visible.
Backlinks
Backlinks are similar to the targets above, but with the added fun that they also contain links back
to the :iref:ref:
that links to them. They are created with the :iref:backlink:`title<id>`
role, where title
is the text that will be displayed and id
is the globally unique ID used
to link to the correct backlink. Any number of references can be created to point to the same
target, but:
Warning
creating multiple :iref:backlink:
with the same ID will lead to errors.
Note
The IDs used with :iref:
are global, meaning that a cross-reference can be created
between different documents. However, it also means that the IDs must be globally unique.
Formatting
If no
:iref:ref:
links are created to a backlink, i.e. an empty backlink, the backlink will be formatted like the surrounding text and so should not be distinguishable.If exactly one
:iref:ref:
link is created to a backlink, like this backlink, then the backlink will be formatted like a normal sphinx link. In this case, the pair effectively functions like a mutual link.If more than one
:iref:ref:
link is created to the same backlink - like this one, this one, and the one in the section above - then the backlink0,1,2 itself will be formatted like the surrounding text while subscript numbers are used to create the links to the individual:iref:ref:
instances.
Mutual Links
Mutual links form a pair of links that link to each other. They are created using the
:iref:mref:`title<id>`
syntax, where title
is the text that will be displayed and id
is
used for cross-referencing. Exactly two mutual references have to be created for each ID:
Warning
If only one :iref:mref:
with the given id
is created, no link will be made.
Warning
If more than two :iref:mref:
with a given id
are created, the extension will attempt to
create at least one link between two of them, but the rest will be ignored.
Note
The IDs used with :iref:
are global, meaning that a cross-reference can be created
between different documents. However, it also means that the IDs must be globally unique.
Formatting
Both mutual links are formatted like normal sphinx references, as can be seen between this link and this link.