Directives¶

Directives are the block-level building blocks of reStructuredText — each one starts with .. name:: and can take an argument, options, and a body. The ubCode preview renders a known set of core directives richly (as real boxes, images, and blocks), and renders every other directive as a readable generic placeholder that still shows the directive’s name, its options, and its body.

This reference describes the Rendered preview mode; in Structural mode every directive renders as a uniform placeholder (see Authoring). Where the preview differs from a full sphinx-build, this page adds a short note and points to Differences from a Sphinx build, which owns the complete register.

Need directives and the if conditional are covered in Needs; the diagram directives (mermaid, uml, and plantuml) are covered in Diagrams.

The generic placeholder¶

Any directive not listed on this page renders as a generic placeholder: a labelled block showing the directive’s name, a table of the options you gave it, and its body. Crucially, the body content is still rendered as markup — paragraphs, lists, inline formatting, and nested directives inside a placeholder all render normally; only the directive’s own special behaviour is missing.

Well-known directives that currently render this way are the remaining Sphinx-Needs generative directives — needuml / needarch, needextract and needservice: the placeholder shows the options you wrote, but producing their final form needs machinery ubCode does not ship yet. The needs view directives — needlist, needtable, needflow, needsequence, needpie, needbar and needgantt — do render their real output, as does needreport, which reports on the project’s own types, links and fields. list2need creates its needs: each bullet becomes a real need in the index, so it can be filtered, linked to and jumped to like any other — what it does not do yet is lay them out, so :presentation: is read and reported rather than applied. See Differences from a Sphinx build for what differs from a Sphinx build.

Math¶

The math directive typesets a display (block) LaTeX formula (KaTeX), in both the preview and a built site. The formula can be the directive’s argument, its body, or both (an argument is joined to the body with a blank line, as in Sphinx):

.. math:: E = mc^2

.. math::

   a^2 + b^2 = c^2

Blank-line-separated equations in one body are set as aligned rows, and a formula containing a \\ line break is wrapped in a split environment — matching what a Sphinx build produces.

:label: / :name:: Give the equation an identifier. In built output the block gets an id and a hover ¶ permalink; :name: also registers a cross-reference target. Equation numbers and the :eq: role are not yet supported (see Differences from a Sphinx build).
:no-wrap: (or the legacy :nowrap:): Pass the body to the typesetter verbatim — you supply the complete LaTeX environment (for example \begin{aligned}…\end{aligned}), and no \[…\] wrapping is added.
:class:: Extra CSS classes to apply to the block.

A formula KaTeX cannot parse is left as its raw source, with the parse error shown in the tooltip.

Admonitions¶

The preview renders all of the standard admonition directives as titled callout boxes: attention, caution, danger, error, hint, important, note, seealso, tip, and warning, plus the generic admonition. Each named admonition is given its standard title automatically (for example Note, Attention!, and See also); the generic admonition takes a custom title as its argument.

All admonitions accept these options:

:class:: Extra CSS classes to apply to the box.
:name:: An explicit identifier for the box.
:collapsible:: Render the admonition as a collapsible box. Omit the value (or give open) to start expanded; give closed to start collapsed.

.. note::

   This renders as a titled note box.

.. warning::
   :collapsible: closed

   A collapsible warning, shown collapsed until the reader expands it.

.. admonition:: A custom title

   A generic admonition with the title you supply.

Note

Directive titles and arguments are not inline-parsed, so any markup in a custom admonition title is shown literally (see Differences from a Sphinx build).

Images and figures¶

The image and figure directives render as real images in the preview. A figure’s first body paragraph becomes its caption, and any following paragraphs form the legend shown beneath the image.

These options affect how the image is displayed:

:alt:

Alternative text, shown if the image cannot be loaded.

:width: / :height:

The displayed size of the image.

:scale:

Scales the image by a percentage.

:align:

Aligns the image (left, center, or right).

:name:

Give the image or figure an identifier and register it as a cross-reference target, so :ref:`my-figure` links to it. A figure’s name becomes the id of the whole figure — matching a Sphinx build, which moves it there from the image — and in built output its caption gains a hover ¶ permalink. A standalone image’s name stays on the image itself.

Two limits worth knowing. A name is not anchored on an image written inside a substitution definition. And if the name’s slug is already claimed on the page — by a heading of the same words, say — the figure takes it and the heading is renumbered, which moves that heading’s link; give one of the two a distinct name to avoid it.

The :target: and :class: options are accepted but are not currently applied in the preview.

Note

A * wildcard extension (.. image:: logo.*) selects the best available file in ubc build html and in the editor’s hover preview, but the Rendered preview does not yet resolve it — the full selection rules are in Differences from a Sphinx build.

.. figure:: diagrams/architecture.png
   :alt: System architecture
   :width: 480px
   :align: center

   The overall architecture.

   This second paragraph becomes the figure legend.

Image paths are resolved the way you would expect: a local path is looked up against the project’s source directory or the directory of the document that references it, and a remote https:// URL is loaded directly. Images stored outside your workspace do not load in the preview.

Videos¶

The video directive embeds a video with the browser’s native player. Its argument is one source file or URL, optionally followed by a second source as a format fallback — the player uses the first source it can play.

This directive comes from the third-party sphinxcontrib-video package; install it to use the directive in a full sphinx-build. ubCode implements it natively, with nothing to install — it only needs the extension name listed in your parsing configuration:

[parse]
extensions = ["sphinxcontrib.video"]

.. video:: media/demo.mp4
   :width: 640
   :muted:
   :loop:

.. video:: media/demo.mp4 media/demo.webm
   :poster: media/cover.png
   :caption: A short demo clip.

A local source path — and the :poster: image — is resolved like an image path (see Images and figures above) and copied into the build output alongside your other assets. A remote https:// URL is passed through verbatim and never downloaded.

The full upstream option set is supported:

:autoplay: / :loop: / :muted: / :playsinline:: Flag options passed through to the player as the matching HTML5 attributes.
:nocontrols:: Hides the player controls, which are otherwise shown.
:controlslist:: A comma-separated subset of nodownload, nofullscreen, and noremoteplayback, hiding individual browser controls.
:alt:: Fallback text shown when the video cannot be played.
:poster:: An image shown before the video plays.
:preload:: A loading hint for the browser: auto, metadata, or none.
:width: / :height:: The player’s size in pixels (bare numbers). :width: also accepts a percentage such as 50%, in which case the width scales with the page and any :height: is ignored.
:caption: / :figwidth:: A caption renders the video as a captioned figure; :figwidth: sets that figure’s width and only applies when a caption is present. It takes a number followed by any CSS unit or % (a bare number is pixels); anything else raises a warning and the figure renders unsized. A full sphinx-build validates this option not at all and writes the value straight into the figure’s style attribute.
:class: / :align:: Extra CSS classes for the player, and horizontal alignment (left, center, or right).

An invalid option value never fails a build — the video renders without the offending attribute instead: an out-of-set :align: or :preload: value is flagged with a warning diagnostic and dropped, while an invalid :width:, :height:, or :controlslist: value (one unknown token drops that whole option) is dropped silently — :figwidth: is the exception and warns. Anything after the second source in the argument is likewise ignored — where a full sphinx-build reports an error for the extra source — and body content is accepted but never rendered.

In Markdown (MyST) the directive is written as a fence, with the same options:

```{video} media/demo.mp4
:width: 640
:muted:
```

Note

In the editor’s Rendered preview a local video currently shows the player frame but does not play — the preview cannot yet stream local media files — while remote URLs play normally. The same local source plays fine in the output of ubc build html.

Code blocks¶

The code-block directive and its aliases sourcecode and code render as syntax-highlighted code blocks in the preview. The language comes from the directive argument; an argument-less directive inherits the language set by a preceding .. highlight:: directive or by the highlight_language key in your parsing configuration. A block whose language the preview does not recognise is shown as plain preformatted text — the code is never mangled.

These options affect how the block is displayed:

:caption:: A caption line shown above the code.
:name:: An explicit identifier for the block.
:class:: Extra CSS classes to apply to the block.

The :linenos:, :lineno-start:, :emphasize-lines:, :dedent:, and :force: options are accepted but not currently applied in the preview (see Differences from a Sphinx build).

.. code-block:: python
   :caption: A greeting
   :name: hello-block

   print("hello")

.. highlight:: rust

.. code-block::

   // argument-less: inherits rust from the highlight directive
   fn main() {}

Plain :: literal blocks follow the same rule: they are highlighted when a .. highlight:: language (or the configured default) applies, and shown as plain preformatted text otherwise.

Syntax examples¶

The syntax-example directive shows a block of markup twice — once as its raw, highlighted source, and once as the rendered result of parsing that source. It is meant for documentation that teaches a markup syntax, where the reader needs to see both what to type and what it produces.

This directive comes from the third-party sphinx-syntax-example package (module name sphinx_syntax_example); install it to use the directive in a full sphinx-build. The preview implements it natively, with nothing to install — it only needs that module name listed in your parsing configuration:

[parse]
extensions = ["sphinx_syntax_example"]

The optional argument is a title shown above the block (Example when omitted), and the :highlight: option sets the source language. When :highlight: is omitted the language follows the document’s configured format (the parser chosen for its source suffix), not a guess from the file name: rst for reStructuredText sources, and markdown for Markdown sources (a full sphinx-build prefers a myst lexer for Markdown when one is registered, while the ubCode preview always uses markdown; pass :highlight: myst explicitly to use the preview’s bundled MyST grammar). An unknown :highlight: value falls back to the inferred language rather than failing the build. Because the content is rendered as real nested markup rather than reassembled text, an example may itself contain code blocks, backticks, or nested directives without any escaping.

The syntax_example_numbering key (see Parsing) numbers each document’s examples — Example N without a title argument, Example N: <title> with one, counting from 1 again in every document, and continuing across an .. include:: rather than restarting in the fragment. It is off by default, which keeps the plain titles described above, and it needs sphinx-syntax-example 0.2.0 or later to match in a full sphinx-build. Inline markup in the title argument is a known divergence: a full sphinx-build parses it, while the preview shows the title as plain text, so *nice* stays literal.

.. syntax-example:: A note

   Use a ``note`` admonition for **supplementary** information.

   .. note::

      This box is rendered from the source shown above.

That example renders like this:

A note

Use a ``note`` admonition for **supplementary** information.

.. note::

   This box is rendered from the source shown above.

Use a note admonition for supplementary information.

Note

This box is rendered from the source shown above.

Todos¶

The todo directive marks an outstanding task inline in the documentation, rendered as an admonition titled Todo; todolist gathers every todo in the project into one place, each entry followed by a link back to where it was written.

These come from Sphinx’s own sphinx.ext.todo extension. ubCode implements them natively, with nothing to install — they only need the extension name listed in your parsing configuration:

[parse]
extensions = ["sphinx.ext.todo"]

.. todo:: Decide whether this stays configurable.

.. todo::
   :name: retire-legacy-flag

   Retire the legacy flag once the migration lands.

Warning

:name: on a todo aborts a full sphinx-build with an unhandled error inside sphinx.ext.todo itself — it registers the block’s name twice. ubCode accepts it and treats it as any other admonition name, but do not use it in a source tree you also build with Sphinx. Every todo already gets an automatic anchor, so you rarely need it.

Each block takes the usual admonition options, and gets an anchor so a todolist can link back to it — todo-1, todo-2, … in document order, or the :name: you supply. Put .. todolist:: on a page of its own to collect them:

.. todolist::

Set [parse].todo_include_todos = false to hide every todo and every list (see Parsing for that and todo_link_only). Note that ubCode renders todos by default where a full sphinx-build hides them unless todo_include_todos is set — set the value explicitly in a project that builds with both. Inside a list, each entry’s body is shown as plain text; the original block renders its markup in full.

Structural blocks¶

The preview renders the following structural and layout directives:

Directive	Renders as	Options honoured
`topic`	A self-contained titled aside box (requires a title argument).	`:class:`, `:name:`
`sidebar`	A titled sidebar box, with an optional subtitle.	`:class:`, `:name:`, `:subtitle:`
`rubric`	An informal heading (a title with no body).	`:class:`, `:name:`
`container`	A plain block that groups its body; the argument sets its CSS classes.	`:name:`
`compound`	A block that joins its body into a single compound paragraph.	`:class:`, `:name:`
`epigraph` / `highlights` / `pull-quote`	A block quote styled by the directive name.	none
`parsed-literal`	A preformatted block; the body is shown verbatim and inline markup is not interpreted.	`:class:`, `:name:`
`line-block`	A block that preserves your line breaks.	`:class:`, `:name:`
`centered`	Centered, bold text taken from the argument.	none
`hlist`	A single bullet list arranged into columns.	`:columns:`

An hlist uses two columns unless you set :columns:. If you give one of these directives an option it does not support (for example :collapsible: on topic, or :heading-level: on rubric), it falls back to the generic placeholder described above.

Version markers¶

The version-change directives render with their standard Sphinx labels. Each one requires a version number as its argument; any text after the version becomes the marker’s first paragraph.

Directive	Label shown
`versionadded`	Added in version X
`versionchanged`	Changed in version X
`deprecated`	Deprecated since version X
`versionremoved`	Removed in version X

.. versionadded:: 1.4
   The ``:collapsible:`` option on admonitions.

State-changing directives¶

A few directives change how later content in the same document is parsed, rather than producing content of their own. In the preview each renders as a small marker chip showing the directive and its value, so you can see where the state changes.

.. default-role::: Changes what bare interpreted text — text in single backticks — renders as. By default it renders as a title reference; after .. default-role:: emphasis the same text renders as emphasis (italic). The project-wide default is set by the default_role key (see Parsing).
.. role::: Defines a custom inline role for the current document. Name a base role in parentheses to inherit that role’s rendering. For a plain custom role (without a base), the :class: option sets the CSS class applied to the text.
.. highlight::: Sets the language applied to the language-less code blocks that follow it — argument-less code-block directives and plain :: literal blocks (see Code blocks above).
.. default-domain::: Accepted and recorded, but has no visible effect in the preview yet.

Including files¶

The include directive splices another file’s contents inline in the Rendered preview, so you see the combined result as it will build. These options are honoured:

:literal:: Insert the file as a literal block instead of parsing it.
:start-line: / :end-line:: Include only a range of lines.
:start-after: / :end-before:: Include only the text between two marker strings.

.. include:: shared/intro.rst

.. include:: CHANGELOG.txt
   :literal:
   :start-after: [unreleased]

Any other include option is flagged with a lint diagnostic and ignored. Paths are resolved the way Sphinx resolves them: a relative path is relative to the top-level document’s directory, and a leading / is relative to the project’s source directory. If the referenced file is missing, an inline error chip is shown in its place. Nested includes are supported and protected against cycles. The docutils “standard” includes (such as .. include:: <isonum.txt>) are not supported, and are reported with a diagnostic.

A spliced include behaves slightly differently from a textual sphinx-build splice — for example in how document state, section nesting, and click-through are handled. See Differences from a Sphinx build for the details.