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 include toctree, csv-table, list-table, and math.

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).

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

.. 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.

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.

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.