References and links¶
The constructs that point somewhere else:
targets and the :ref: role, hyperlinks, footnotes and citations, substitutions,
the :doc:, :term: and :any: roles, downloads, and references into other projects.
ubCode resolves all of them in the editor preview and in its html build,
and all but :download: in its pdf build,
and reports a reference that resolves to nothing, as a Sphinx build does.
A label is a name for the whole project,
so every label in the specimens below starts with this page’s own prefix.
Targets and :ref:¶
A target, .. _name: on a line of its own, names the element that follows it.
The :ref: role links to a target from any page of the project;
with no text of its own, it reads the title of the section the target names,
and with text <name> it reads your text.
A target can also be reached as a hyperlink, name_, on its own page.
A target and its references
.. _ex-references-target:
This paragraph carries a target.
Link to it :ref:`with your own text <ex-references-target>`
or as a hyperlink, ex-references-target_;
link to a section by its title: :ref:`authoring_references_citations`.
This paragraph carries a target. Link to it with your own text or as a hyperlink, ex-references-target; link to a section by its title: Citations.
(ex-references-myst-target)=
This paragraph carries a target.
Link to it {ref}`with your own text <ex-references-myst-target>`
or as a Markdown link, [to the target](#ex-references-myst-target);
link to a section by its title: {ref}`authoring_references_citations`.
The MyST form renders live in the MyST targets.
A :ref: with no text of its own needs a target that sits above a section title,
or names a figure or a table with a caption,
because that title is what it reads;
link any other target with your own text.
A Sphinx build reads a ! before the target (:ref:`!name`) as the text without a link,
where ubCode shows a chip;
see the ref-role differences for both.
Hyperlinks¶
A hyperlink to another site is written in one of four ways:
a named reference, `text`_, with its URL on a target line of the same name;
an anonymous one, `text`__, which takes the next anonymous target, __ URL;
an embedded one, `text <URL>`_, with its URL inline;
and a bare URL, which links itself.
Hyperlinks
A named reference to `Docutils`_, used twice: `Docutils`_.
An anonymous one to `the Sphinx site`__,
an embedded one to `MyST-Parser <https://myst-parser.readthedocs.io/>`_,
and a bare URL, https://www.sphinx-doc.org/.
.. _Docutils: https://docutils.sourceforge.io/
__ https://www.sphinx-doc.org/
A named reference to Docutils, used twice: Docutils. An anonymous one to the Sphinx site, an embedded one to MyST-Parser, and a bare URL, https://www.sphinx-doc.org/.
An inline link to [Docutils](https://docutils.sourceforge.io/),
a reference-style one to [MyST-Parser][ex-references-myst],
and an autolink, <https://www.sphinx-doc.org/>.
[ex-references-myst]: https://myst-parser.readthedocs.io/
The MyST form renders live in
the MyST hyperlinks.
A bare URL is plain text in MyST unless its linkify extension is enabled,
which this site does not do.
A named hyperlink target, one that gives a URL, is local to its page, so the same name on two pages is two targets. How a dangling or ambiguous reference is reported is in the hyperlink differences.
Footnotes¶
A footnote reference is a label in brackets with a trailing underscore,
and its definition is .. [label] followed by the text.
The label is a number, # to number the footnote automatically,
#name to number it automatically and refer to it by name, or * for a symbol.
Every footnote must be referenced: an unreferenced one is reported.
Footnotes
A numbered footnote [1]_, an automatic one [#]_,
a named one [#ex-references-note]_, referred to twice [#ex-references-note]_,
and a symbol [*]_.
.. [1] Numbered by hand.
.. [#] Numbered automatically.
.. [#ex-references-note] Numbered automatically, referred to by name.
.. [*] Marked with a symbol.
A numbered footnote [^1] and a named one [^ex-references-myst-note],
referred to twice [^ex-references-myst-note].
[^1]: Numbered in the order it is first referenced.
[^ex-references-myst-note]: Named, and numbered the same way.
The MyST form renders live in the MyST footnotes. MyST numbers every footnote in the order it is first referenced, whatever its label, and gathers the definitions at the foot of the page.
Note
ubc build pdf sets each footnote at the foot of the page that refers to it.
The numbering rules, and how a reference to a missing or duplicated footnote is reported, are in the footnote differences.
Citations¶
A citation is written like a footnote with a label that is not a number:
[LABEL]_ refers to it and .. [LABEL] defines it.
Unlike a footnote’s, a citation’s label belongs to the whole project,
so any page can cite a definition made on one page, such as a bibliography.
A citation
The reference is checked against the specimen [EX-REFERENCES-2026]_.
.. [EX-REFERENCES-2026] The specimen this page cites.
The reference is checked against the specimen [EX-REFERENCES-2026].
The specimen this page cites.
MyST has no citation syntax.
Note
ubc build pdf collects the citations into a Bibliography at the end of the book.
How citation findings are worded is in the footnote differences.
Substitutions¶
A substitution reference, |name|, is replaced by the definition of that name,
written anywhere on the same page:
replace:: gives text, with inline markup;
unicode:: gives characters by their code points;
and date:: gives the build’s date in a strftime format.
A reference written |name|_ also links, to the target of the same name.
|version|, |release| and |today| are defined for every page,
from the project’s version and release and the build’s date.
Substitutions
|ex-references-name| |version| is |ex-references-copy| useblocks,
built in |ex-references-year|;
it follows |ex-references-site|_.
.. |ex-references-name| replace:: **ubCode**
.. |ex-references-copy| unicode:: U+00A9
.. |ex-references-year| date:: %Y
.. |ex-references-site| replace:: the Sphinx conventions
.. _ex-references-site: https://www.sphinx-doc.org/
ubCode 0.38.0 is © useblocks, built in 2026; it follows the Sphinx conventions.
MyST writes substitutions only with its substitution extension,
which ubCode does not implement
(see MyST extensions), so there is no MyST specimen.
A substitution name is local to its page. How an undefined or self-referring substitution is reported is in the substitution differences.
Documents, terms and :any:¶
:doc: links to a page by its path, relative to the current page or, with a leading /,
to the source directory, and reads the page’s title unless you give your own text.
:term: links to a glossary term,
and :any: to a page, a label or a term, whichever its target names.
Documents, terms and any
See :doc:`rst_basics`, or :doc:`the tables page </authoring/rst_tables>`.
The :term:`Specimen term` is defined on another page,
and :any:`authoring_references_footnotes` finds a section by its label.
See reStructuredText basics, or the tables page. The Specimen term is defined on another page, and Footnotes finds a section by its label.
See {doc}`rst_basics`, or {doc}`the tables page </authoring/rst_tables>`.
The {term}`MyST specimen term` is defined on another page,
and {any}`authoring_references_footnotes` finds a section by its label.
The MyST form renders live in the MyST documents, terms and any.
The glossary these terms come from is on Glossary, index, confval and envvar.
:any: tries a page, then a label, then a term, and reports a target that matches more than one;
see the any-role differences.
Downloads¶
:download: links to a file of the project and publishes the file with the site,
so the reader can save it.
A path that starts with / is read from the source directory
(this site keeps its specimen files one level above it);
a target with :// in it is linked as a URL and never copied.
A download
Save :download:`the builders table </../specimens/tables/builders.csv>`
to compare the builders offline.
Save the builders table
to compare the builders offline.
Save {download}`the builders table </../specimens/tables/builders.csv>`
to compare the builders offline.
The MyST form renders live in the MyST download.
Note
ubc build pdf cannot place a :download: link yet
(it reports one as build.pdf_block_unsupported),
so the PDF shows this specimen’s source only.
How the published file is named, and what happens when it is missing, is in the download differences.
References to other projects¶
With the intersphinx configuration, a reference can reach a label, page or term of another project’s documentation:
:ref:`python:comparisons`
:external:ref:`comparisons`
:external+sphinx:doc:`usage/restructuredtext/basics`
A plain :ref: or :term: that your project cannot resolve
falls back to the other projects’ inventories (a plain :doc: does not, unless you allow it);
a project: prefix names the one project to look in;
and the :external: roles always look outside.
There is no live specimen here, because the inventories are fetched over the network.
How the three forms reach the inventories is in
How references reach the inventories.
:numref: and :eq:, which number figures, tables and equations,
are not supported: see Numbering.
Cross-references and hydration¶
Several roles are cross-references: they point at something elsewhere in your project — a labelled location, a document, a glossary term, or a need.
Before the project has been indexed in the background — and for any target that cannot be resolved — a cross-reference shows as a placeholder chip carrying the role name and the target text. Once the background index is ready, the preview is hydrated: each resolved cross-reference becomes a clickable link that opens the target file at the right line. An open preview re-hydrates as indexing progresses, so chips upgrade to links on their own. (For how hydration works across the preview as a whole, see RST preview.)
These roles hydrate into links:
Role |
Links to |
|---|---|
|
A labelled location (a section, or an explicit target) |
|
Another document |
|
A glossary term |
|
A document, a label or a glossary term |
|
A need, by its ID |
|
The need it names (a Sphinx-Needs build lists that need’s incoming or outgoing links instead) |
:need: also accepts a dotted part reference (:need:`REQ_001.part_a`),
and links to the base need.
:need_part: (with its alias :np:) shows its chip
but does not yet become a link.
The need roles have their own specimens in the need roles;
for need IDs, link types and the need cards the preview builds, see Needs.
With the sphinx.ext.autosectionlabel port enabled
in your parsing configuration,
every section title is a :ref: target of its own,
with no explicit .. _label: written above the section —
:ref:`guide/intro:Overview` with autosectionlabel_prefix_document on —
and the resolved link jumps to the section itself.
See Parsing for the port’s options
and how duplicate titles are resolved.
Finding what you can reference¶
Rather than guessing a target name, ask the project what it can cross-reference:
ubc query search installation # ranked hits, each with the role to paste
ubc query search --kind label # no query: list every label, by name
ubc query search --kind term glossary # search glossary terms only
ubc query search --scope python array # search one intersphinx project only
ubc query search -f json installation # machine-readable
The command (re)indexes the project,
then searches both its own :ref: labels, glossary terms, documents and filed index entries
and every entry of every loaded intersphinx inventory.
Each hit carries the object type, the scope it comes from,
its location, and — the point of the exercise — the exact role to paste,
project-absolute where that matters (:doc:`/guide/install`).
A few things worth knowing:
It searches reference targets and filed index entries, not document content.
--kindaccepts adomain:objtypeglob (py:*,*:label) or one of the shorthandslabel,term,doc,index; a kind that matches nothing is an empty result rather than an error, since any inventory may introduce an object type.--scopeacceptslocal,external, or one configured project name, and anything else is an error listing what would have worked.An
index:entryhit carries no snippet: no role resolves to an index entry, so what it answers is the neighbouring question — is this phrase already indexed, and where?Matching is keyword-based and ANDed, so pass a few specific words or the exact name; an exact name ranks first, and a partial name completes by prefix.
Exit codes suit a script:
0when something was found,1when nothing was,2for a usage, configuration or license error.Need references are deliberately absent: they are graph edges, so
ubc query cypher(see Writing a filter) is their tool.
The same search backs the search_references tool
the MCP server exposes to AI agents.