Roles

Roles are inline markers that give a fragment of text a special meaning: they format it, or turn it into a link. A role is written :name:`text` in reStructuredText and {name}`text` in MyST, and the role set is the same in both. ubCode renders every role on this page in the editor preview and in its html and pdf builds; a role it does not recognise is shown as a chip carrying the role’s name and its text. The roles that point somewhere else — :ref:, :doc:, :term:, :any:, :download: and the references into other projects — are on References and links.

Text styling roles

These roles format their text. Several have a short alias: :sub: for :subscript:, :sup: for :superscript:, :t: and :title: for :title-reference:, :ab: for :abbreviation: and :ac: for :acronym:.

Text styling roles

:emphasis:`Emphasis`, :strong:`strong`, :literal:`literal` and :code:`code`;
H\ :sub:`2`\ O and E = mc\ :sup:`2`;
:title-reference:`The Book of Roles`,
:abbreviation:`approx.` and :acronym:`NASA`.

Emphasis, strong, literal and code; H2O and E = mc2; The Book of Roles, approx. and NASA.

{emphasis}`Emphasis`, {strong}`strong`, {literal}`literal` and {code}`code`;
H{sub}`2`O and E = mc{sup}`2`;
{title-reference}`The Book of Roles`,
{abbreviation}`approx.` and {acronym}`NASA`.

The MyST form renders live in the MyST text styling roles. A MyST role needs no backslash-space to start inside a word.

A role’s text is not parsed again for inline markup, so *stars* inside :strong: are printed as written. :title-reference: marks the title of a work, and is the role of text in bare single backticks unless the default role is changed (see The default role and custom roles).

Math

The :math: role typesets an inline LaTeX formula (KaTeX), in both the preview and a built site. Its live specimen is with the math directive, in Inline math.

UI and file roles

These Sphinx roles mark up what a reader types, clicks or reads on a screen.

Keys, labels and menus

Press :kbd:`Ctrl+S`, or choose :menuselection:`File --> Save As...`
and click :guilabel:`&Save`.

Press Ctrl+S, or choose File ‣ Save As… and click Save.

Press {kbd}`Ctrl+S`, or choose {menuselection}`File --> Save As...`
and click {guilabel}`&Save`.

The MyST form renders live in the MyST keys, labels and menus.

:kbd:

One keycap per key: a combination is split on -, +, ^ or a space (ubc build pdf sets the whole combination as one key).

:menuselection:

A menu path, with --> between its items drawn as a triangle.

:guilabel:

A label of the user interface; an & before a letter marks that letter as its access key.

Files, commands and terms

Edit :file:`~/.config/{project}/ubproject.toml`,
then run :samp:`ubc build {builder}`.
The :command:`ubc` command, or :program:`ubc`, reads :makevar:`PATH`.
A :dfn:`specimen` shows its source and its result;
this page is :mimetype:`text/html`,
a label here matches :regexp:`^ex-roles-[a-z]+$`,
and a stack is :abbr:`LIFO (last in, first out)`.
See :manpage:`ls(1)`, the :mailheader:`Content-Type` header
and :newsgroup:`comp.lang.python`.

Edit ~/.config/project/ubproject.toml, then run ubc build builder. The ubc command, or ubc, reads PATH. A specimen shows its source and its result; this page is text/html, a label here matches ^ex-roles-[a-z]+$, and a stack is LIFO. See ls(1), the Content-Type header and comp.lang.python.

Edit {file}`~/.config/{project}/ubproject.toml`,
then run {samp}`ubc build {builder}`.
The {command}`ubc` command, or {program}`ubc`, reads {makevar}`PATH`.
A {dfn}`specimen` shows its source and its result;
this page is {mimetype}`text/html`,
a label here matches {regexp}`^ex-roles-[a-z]+$`,
and a stack is {abbr}`LIFO (last in, first out)`.
See {manpage}`ls(1)`, the {mailheader}`Content-Type` header
and {newsgroup}`comp.lang.python`.

The MyST form renders live in the MyST files, commands and terms.

:file:, :samp:

Literal text in which a {placeholder} is emphasised.

:command:, :program:, :makevar:

A name in bold.

:dfn:, :mimetype:, :manpage:, :mailheader:, :newsgroup:

A term in italics.

:regexp:

A regular expression in monospace.

:abbr:

An abbreviation; a trailing (expansion) becomes its hover text.

Note

ubc build pdf prints an :abbr: expansion in parentheses after the abbreviation.

How :kbd: and :manpage: differ from a Sphinx build is in the inline-role differences.

Badges

sphinx-design’s badge roles draw a short label as a coloured pill. A role is named bdg- and a colour (primary, secondary, success, info, warning, danger, light, muted, dark, white or black), with -line for an outlined badge; a bdg-ref- or bdg-link- role makes the badge a link, taking the target of :ref: or a URL.

Badges

:bdg-primary:`primary`, :bdg-info-line:`outlined`,
and :bdg-ref-success:`a link to this page <authoring:roles>`.

primary, outlined, and a link to this page.

{bdg-primary}`primary`, {bdg-info-line}`outlined`,
and {bdg-ref-success}`a link to this page <authoring:roles>`.

The MyST form renders live in the MyST badges.

The default role and custom roles

Text in bare single backticks, with no role named, takes the default role, which is :title-reference: unless you change it: the .. default-role:: directive changes it from that point of the page on, and the default_role key of the parsing configuration sets it for every page (see The default role).

The .. role:: directive defines a custom role, from that point of the page on. A plain custom role renders its text in a span whose CSS class is the role’s name, for a stylesheet to style.

A custom role

.. role:: ex-roles-flag

A :ex-roles-flag:`flagged` word carries the class ``ex-roles-flag``.

A flagged word carries the class ex-roles-flag.

```{role} ex-roles-myst-flag
```

A {ex-roles-myst-flag}`flagged` word carries the class `ex-roles-myst-flag`.

The MyST form renders live in the MyST custom role.

A derived role, written .. role:: name(base), behaves as its base role does. Roles from an extension ubCode does not know can be declared with extend_roles in the parsing configuration.

Highlighted inline code

A role derived from :code: can carry a :language: option, and its text is then highlighted as code of that language — the inline twin of the code-block directive.

Highlighted inline code

.. role:: ex-roles-python(code)
   :language: python

In Python, :ex-roles-python:`len("abc") + 2` is :ex-roles-python:`5`.

In Python, len("abc") + 2 is 5.

```{role} ex-roles-myst-python(code)
:language: python
```

In Python, {ex-roles-myst-python}`len("abc") + 2`
is {ex-roles-myst-python}`5`.

The MyST form renders live in the MyST highlighted inline code.

The language names are the ones code blocks accept, and a language ubCode does not recognise is shown as plain inline code. A chain of derived roles takes the language of the nearest definition that sets one. The plain :code: role, and a derived role with no :language:, render like :literal:: the role’s name is never used as the language. How highlighted inline code differs from a Sphinx build is in the code-block differences.

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

  • References and links — the cross-reference roles, footnotes, citations and substitutions.

  • Needs — needs, need IDs, and the need roles.

  • Differences from a Sphinx build — how ubCode differs from a Sphinx build.

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