Roles

Roles are inline markers that give a fragment of text a special meaning — formatting it, or turning it into a link. In the Rendered preview ubCode styles the text-formatting roles, turns :pep: / :rfc: and the cross-reference roles into links, and shows any role it does not recognise as a readable placeholder chip carrying the role name and its content.

This is :strong:`important` and :literal:`inline code`.

Roles work the same way in Markdown (MyST), written with the curly-brace form ({strong} instead of :strong:); the role set and its rendering are identical on both surfaces.

This reference describes the Rendered preview mode; in Structural mode every directive and role renders as a uniform placeholder (see Authoring). Where the preview differs from a full sphinx-build, see Differences from a Sphinx build.

Text styling roles

These roles format their content. Role names are matched case-insensitively, and several carry short aliases.

Role (and aliases)

Rendered as

:emphasis:

Italic text

:strong:

Bold text

:literal:

Inline code (monospace)

:subscript: / :sub:

Subscript

:superscript: / :sup:

Superscript

:title-reference: / :title: / :t:

A citation-style reference, like a cited work title; also the default role for text in bare single backticks (see below)

:abbreviation: / :ab:

An abbreviation (no tooltip)

:acronym: / :ac:

An acronym, styled like an abbreviation

Text inside a role is shown as-is: inline markup written within it is not re-parsed, so *stars* inside :emphasis: appear literally rather than as emphasis.

Note that :math: is not one of these roles. A :math: role is shown as raw source, not typeset — see Differences from a Sphinx build.

UI and file roles

These Sphinx roles describe user-interface elements, files, and other technical text.

Role

Rendered as

:kbd:

Keystrokes as keycaps; a multi-key sequence (split on -, +, ^, or a space) becomes one keycap per key

:guilabel:

A user-interface label; an & before a character marks an access key

:menuselection:

A menu path; a --> between items becomes a triangular separator

:file:

A file path in monospace; a {placeholder} segment is emphasised

:samp:

Literal text in monospace; a {placeholder} segment is emphasised

:command:

A command name (bold)

:program:

A program name (bold)

:makevar:

A make variable (bold)

:dfn:

A term being defined (italic)

:mimetype:

A MIME type (italic)

:regexp:

A regular expression (monospace)

:abbr:

An abbreviation; a trailing (expansion) becomes hover text

 
Press :kbd:`Ctrl+C` to copy.
Open :menuselection:`File --> Save As...`.
Edit :file:`~/.config/{project}/settings.toml`.
The :abbr:`LIFO (last in, first out)` order applies.

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

:ref:

A labelled location (a section, or an explicit target)

:doc:

Another document

:term:

A glossary term

:need:

A need, by its ID

:need_incoming: / :need_outgoing:

A need, following an incoming or outgoing link

 
See :ref:`installation` for setup.
:ref:`Custom link text <installation>`
:ref:`!installation`
:need:`REQ_001`
:need:`REQ_001.part_a`

  • Custom link text. The titled form (second line above) uses your text as the link label instead of the target’s own title.

  • Opting out of a link. Prefixing the target with ! (third line above) keeps the reference as a chip and never turns it into a link, even when the target resolves.

  • Need parts. :need: also accepts a dotted part reference (last line above); it links to the base need.

Not every reference-style role is linked. :numref:, :any:, and :download: are not recognised and render as placeholder chips, and :need_part: (with its alias :np:) shows its chip but does not yet become a link.

For everything specific to needs — need IDs, link types, and the need cards the preview builds — see Needs.

The default role and custom roles

Text written in single backticks with no explicit role uses the default role, which is :title-reference: unless you change it. Two things can change it:

  • The .. default-role:: directive changes the default role from that point in the document onward; a bare .. default-role:: resets it to :title-reference:.

  • The default_role key in Parsing seeds the default role for every document in the project.

The .. role:: directive defines a custom role. A plain custom role renders as a span carrying a CSS class named after the role; a derived role, written .. role:: name(base), inherits the behaviour of the existing base role. The directives themselves are covered on Directives.

The variant role

:variant: resolves a dotted path into your configured variant data and shows the resolved value as plain text. Because it belongs with the other variant-authoring constructs, its full entry lives on its own page: see Variants.

See also

  • Directives — the directive reference, including .. default-role:: and .. role::.

  • Needs — needs, need IDs, and need cards.

  • Differences from a Sphinx build — how the preview differs from a full sphinx-build.

  • Parsing — the [parse] configuration, including default_role and extend_roles for custom roles from your extensions.

  • Linting — how diagnostics are surfaced and configured.