← Book Configuration Themes →

Markup Reference

uscribe accepts a restricted RST-like dialect. Unknown constructs are either ignored, treated as plain text, or left as raw directives.

Headings 

Chapter Title
=============

Section
-------

Subsection
~~~~~~~~~~

Characters = - ~ ^ " are recognized as underline styles (chapter through heading 5). Heading level follows the underline character. The underline length must be greater than or equal to the title length.

Document fields

A chapter may start with an RST field list (Docutils bibliographic fields). Repeat :author: for several names. Book chapters show these as a byline under the first heading; omit the fields and nothing is added. Reports also use :title: , :trnumber: , :abstract: , :keywords: , and :docclass: for the cover — see Reports for the one-paper and catalog workflows. 

:author: Jane Doe
:author: Pat Lee
:date: 2026-08-15
:copyright: 2026, Jane Doe

Chapter Title
=============

Book-wide title, logo, theme, and PDF name belong in book.conf (see Book Configuration ). They are not chapter fields.

Paragraphs and lists

Blank lines separate paragraphs. Bullet lists use - or * with a following space. Numbered lists use 1. / 1) or auto-number #. . Indented continuation lines belong to the current item. Nested lists, .. note:: , and .. code-block:: indented under an item are parsed as that item's body (a blank line between items is allowed).

Source: 

1. Install the ``uscribe`` binary (:doc:`install`)
2. Write a tiny book (:doc:`quickstart`)
#. Pick a theme (:doc:`themes`)

Rendered:

  1. Install the uscribe binary ( Installation )

  2. Write a tiny book ( Quick Start )

  3. Pick a theme ( Themes )

A list item can also hold a nested listing: 

- Default mode prompt:

  .. code-block:: text

     admin@r0>

- Configure mode is a nested list of its own:

  - enter with ``config``
  - leave with ``end``

Definition lists

A term on its own line followed by an indented body. Blank lines inside the body start a new paragraph.

Source: 

format
   Selects the builder.

   Use ``html`` for a browsable book, or ``latex`` / ``pdf`` for print.

theme
   Names the HTML skin (``basic``, ``classic``, or ``dark``).

Rendered:

format

Selects the builder.

Use html for a browsable book, or latex / pdf for print.

theme

Names the HTML skin ( basic , classic , or dark ).

Tables

Simple tables use = column separators. The first row is the header. PDF output uses longtable with wrapping paragraph columns so long identifiers and prose stay within the page.

Source: 

=====  ==========
Flag   Meaning
=====  ==========
html   HTML book
latex  ``book.tex``
pdf    run a TeX engine
=====  ==========

Rendered:

Flag Meaning
html HTML book
latex ``book.tex
pdf run a TeX

Grid tables use +---+ borders; a border with = marks the header. Omit an internal | to span columns:

Source: 

+--------+--------+--------+
| Left   | Mid    | Right  |
+========+========+========+
| A      | B spanning two  |
+--------+-----------------+
| C spanning two  | D      |
+-----------------+--------+

Rendered:

Left Mid Right
A B spanning two
C spanning two D

A plain grid without spans:

Source: 

+--------+------------+
| Flag   | Meaning    |
+========+============+
| html   | HTML book  |
+--------+------------+
| latex  | book.tex   |
+--------+------------+

Rendered:

Flag Meaning
html HTML book
latex book.tex

List tables use the list-table directive. The optional argument is the table caption (shown under the table in HTML, and as a LaTeX caption). Word-style labels such as Figure 6: … are kept as written:

Source: 

.. list-table::
   :header-rows: 1

   * - Flag
     - Meaning
   * - html
     - HTML book
   * - pdf
     - run a TeX engine

Rendered:

Flag Meaning
html HTML book
pdf run a TeX engine

Labels and cross-references

Place .. _name: immediately before a heading, figure, or table. Pass 1 collects explicit labels and title slugs; pass 2 turns ref roles into chapter.html#anchor links.

Source: 

.. _stable-labels:

Stable labels
-------------

A preceding ``.. _name:`` attaches to the next heading. Link with a
ref role naming that label, optionally with display text in angle
brackets.

Rendered:

Stable labels

A preceding .. _name: attaches to the next heading. Link with a ref role naming that label, optionally with display text in angle brackets.

Live refs (explicit label and display-text form):

Title-only refs (matching a heading exactly) still work. Full chapter sources are linked from each HTML footer as source (and txt in the report index Formats column).

Inline markup

Directives

Admonition bodies are re-parsed as nested blocks (lists, code, nested directives). Source then rendered: 

.. note::

   Admonition bodies can hold nested blocks:

   - a bullet list
   - and even a nested tip

   .. tip::

      Nested directives are parsed, not flattened.

Note

Admonition bodies can hold nested blocks:

  • a bullet list

  • and even a nested tip

Tip

Nested directives are parsed, not flattened.

Also: warning , tip , important , caution , attention , danger , error , hint .

CLI command signatures use .. clicmd:: , like FRR’s command reference: the argument is the syntax line; an indented body hangs under the command as its description. 

.. clicmd:: pki gen <key-name> <key-type> <key-length>

   Generate a private key.

Figures take a caption. If the caption already starts with Figure N or Table N , HTML and LaTeX keep that label instead of adding another number. Uncaptioned .. image:: is not numbered. 

.. _logo-figure:

.. figure:: images/uscribe-logo.png

   :alt: uscribe logo

   The uscribe mark.

See The uscribe mark. .

Other authoring forms (shown literally): 

.. code-block:: unicon

   procedure main()
      write("ok")
   end

.. image:: images/diagram.svg

   Optional alt text

.. include:: path/to/fragment.rst

.. literalinclude:: path/to/file.icn

   :language: unicon
   :lines: 1-10
   :start-after: marker
   :end-before: marker
   :dedent: 3

Paths are resolved next to the including chapter, then under the process cwd. Nested include is allowed; circular includes warn and are skipped.

Include / literalinclude

literalinclude shows a file as a listing; include parses it as markup. The tip below is the same fragment both ways.

Source ( includes/shared-tip.rst ): 

.. tip::

   Snippets under ``includes/`` can be pulled into any chapter with
   ``.. include::`` so the same advice is not copy-pasted.

Rendered:

Tip

Snippets under includes/ can be pulled into any chapter with .. include:: so the same advice is not copy-pasted.

Pull a real .icn file as a listing. Language defaults from the extension ( .icn → unicon ); override with :language: : 

# Shared sample for literalinclude demos
procedure main()
   write("hello from includes/hello.icn")
   write(&version)
end

The same file, only the body between markers: 

   write("hello from includes/hello.icn")
   write(&version)

Unicon listings

code-block languages unicon , icon , and icn get Unicon syntax highlighting in HTML (via highlight-unicon.js ). json is highlighted the same way (strings, numbers, true / false / null , and // comments in JSONC samples). Other languages are emitted as plain <pre><code class="language-…"> without extra highlighting — use sh for shell, rst or text for markup samples. literalinclude of .icn files uses the same Unicon highlighting.

Example Unicon program as it appears in the built book: 

# Hello from a uscribe listing
procedure main()
   every i := 1 to 3 do
      write("tick ", i)
   write(&version)
end

A line ending in :: (RST literal-block introducer) followed by an indented block is also treated as a code listing. Unicon:: becomes the label Unicon: plus the indented tree; a lone :: introduces a block with no label.

Unknown .. name:: directives become HTML comments so content is not silently dropped.

See also Quick Start and Command Line .

← Book Configuration Themes →