Code and includes

These directives put text on the page verbatim, or bring it in from another file: a highlighted code block, a source file shown as code, a preformatted block with inline markup, and a file spliced into the page as if you had written it there. ubCode renders all four in the editor preview and in its html and pdf builds.

Code blocks

The code-block directive, and its aliases sourcecode and code, renders its body as a syntax-highlighted block in the language its argument names. A block whose language ubCode does not recognise is shown as plain preformatted text — the code is never mangled. The preview, ubc build html and ubc build pdf all resolve the same language table (see Languages).

A code block

.. code-block:: python
   :caption: A greeting
   :linenos:
   :emphasize-lines: 2

   def greet(name: str) -> str:
       return f"Hello, {name}!"
A greeting
1def greet(name: str) -> str:
2    return f"Hello, {name}!"

```{code-block} python
:caption: A greeting
:linenos:
:emphasize-lines: 2

def greet(name: str) -> str:
    return f"Hello, {name}!"
```

The MyST form renders live in the MyST code block.

Note

ubc build pdf currently prints one extra, empty line number after a numbered MyST code block.

A block with no language argument takes the language of the last .. highlight:: directive above it, or else the highlight_language key in your parsing configuration (see The highlight language). These options affect how the block is displayed:

:caption:

A caption line shown above the code; inline markup in it is rendered.

:name:

An identifier for the block, which a :ref: with an explicit title can link to.

:class:

Extra CSS classes for the block.

:linenos:, :lineno-start:, :number-lines:

Number the lines; :lineno-start: and :number-lines: set the first number and imply :linenos:.

:emphasize-lines:

Highlight the given lines, counted from 1 over the lines displayed.

:dedent:

Remove leading indentation from the block’s lines.

:force: is accepted and has no effect; the code-block differences list where the rendered block differs from a Sphinx build.

Literal includes

The literalinclude directive shows a file, or a slice of one, as a code block, so the documentation quotes the source rather than a copy of it. The path is relative to the document, or to the source directory when it starts with /.

A literal include

.. literalinclude:: /../specimens/directives/greeting.py
   :language: python
   :caption: greeting.py
   :lines: 4-7
   :lineno-match:
greeting.py
4def greet(name: str) -> str:
5    """Return a greeting for ``name``."""
6    message = f"Hello, {name}!"
7    return message

```{literalinclude} /../specimens/directives/greeting.py
:language: python
:caption: greeting.py
:lines: 4-7
:lineno-match:
```

The MyST form renders live in the MyST literal include.

Note

ubc build pdf currently prints one extra, empty line number after a numbered literal include.

The display options of code-block apply here too, and :lineno-match: numbers the slice with the line numbers it has in the file. These options select what is shown, applied in this order, as in a Sphinx build:

:start-after: / :start-at:, :end-before: / :end-at:

Start and end the slice at the first line containing a marker string, excluding or including the marker line.

:lines:

The lines to keep, counted within that slice (1,3,5-10,20-).

:dedent:

Remove leading indentation from the kept lines.

:prepend: / :append:

A line added before or after the kept lines.

:tab-width:

The width that tabs are expanded to.

:pyobject:, :diff: and an :encoding: other than UTF-8 are not applied: each is reported, and the file is shown with the remaining options applied (see the included-file differences).

Parsed literal blocks

The parsed-literal directive keeps its body’s line breaks and spacing, like a literal block, but renders the inline markup in it — useful for a command line with a placeholder set in italics.

A parsed literal block

.. parsed-literal::

   ubc build html *source-dir* -o *output-dir*
   ubc build pdf  *source-dir* -o *output-file*

ubc build html source-dir -o output-dir
ubc build pdf  source-dir -o output-file
```{parsed-literal}
ubc build html *source-dir* -o *output-dir*
ubc build pdf  *source-dir* -o *output-file*
```

The MyST form renders live in the MyST parsed literal block.

:class: and :name: are applied as on a code block.

Including files

The include directive splices another file’s contents into the page, where its markup is parsed as if it were written there. Here the file holds one paragraph.

An included file

.. include:: /../specimens/directives/fragment.txt

This paragraph lives in a file of its own, and its markup is parsed where it lands.

```{include} /../specimens/directives/fragment.txt
```

The MyST form renders live in the MyST included file.

A relative path is relative to the top-level document’s directory, and a leading / is relative to the project’s source directory. Give a fragment a suffix your project does not read as a page (.txt here), or it is also built as a page of its own. These options are applied:

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

Any other include option is reported and ignored. A missing file shows an error in its place, nested includes work and are protected against cycles, and the docutils “standard” includes (such as .. include:: <isonum.txt>) are not supported. How a splice differs from a Sphinx build’s textual one — in document state, section nesting and click-through in the editor — is in the included-file differences.