`[parse]`¶

Configuration for parsing source documents.

ignore_directives, extend_directives and extend_roles apply to all parsers. Individual parsers are configured under [parse.parsers.<name>] (e.g. [parse.parsers.rst], [parse.parsers.md]).

With no parsers configured, documents are parsed as reStructuredText. Once any parser is configured, the listed parsers are the complete set and file discovery is derived from their include globs — so a lone [parse.parsers.md] parses Markdown only.

Guide: Parsing.

parse.autosectionlabel_maxdepth¶

Type:: integer
Default:: 0

How deep automatic section labels are generated.

Unset or 0 means no limit: every section gets a label. Set to N to label only the top N section levels of each document (1 = every top-level section). Active only when sphinx.ext.autosectionlabel is listed in [parse].extensions.

Equivalent to Sphinx’s autosectionlabel_maxdepth configuration value, and shares its default (unlimited).

parse.autosectionlabel_prefix_document¶

Type:: boolean
Default:: false

Whether automatic section labels are prefixed with the document name.

Off by default, matching Sphinx: a section is referenced by its bare title, e.g. :ref:`Section Title`. When on, labels become :ref:`doc/path:Section Title` — recommended, since bare titles easily collide across documents. Active only when sphinx.ext.autosectionlabel is listed in [parse].extensions.

Equivalent to Sphinx’s autosectionlabel_prefix_document configuration value, and shares its default.

parse.default_role¶

Type:: string
Default:: ""

The role applied to bare interpreted text (`text`).

Unset or an empty string means the docutils default, title-reference. An in-document .. default-role:: directive overrides this from its point onward; a bare .. default-role:: reset returns to title-reference, not to this value.

Equivalent to Sphinx’s default_role configuration value.

parse.extend_directives¶

Type:: table of tables
Default:: {}

A map of directive names to extend the directives with.

Each entry: Configuration to define parsing rules for a single directive.

parse.extend_directives.<name>.argument¶

Type:: boolean
Default:: false

If True, the directive accepts an argument.

parse.extend_directives.<name>.content¶

Type:: boolean
Default:: false

If True, the directive accepts content.

parse.extend_directives.<name>.content_required¶

Type:: boolean
Default:: false

If True, a warning will be logged if the directive contains no content.

parse.extend_directives.<name>.description¶

Type:: string
Default:: ""

A short, human readable description of the directive.

parse.extend_directives.<name>.extension¶

Type:: string
Default:: ""

The extension that provides the directive, if any.

parse.extend_directives.<name>.named_options¶

Type:: table of tables
Default:: {}

A map of named options to specifications.

Each entry: Configuration to define a single directive option.

parse.extend_directives.<name>.named_options.<name>.choices¶

Type:: array of strings

A list of valid choices for the option.

parse.extend_directives.<name>.named_options.<name>.description¶

Type:: string
Default:: ""

A short, human readable description of the option.

parse.extend_directives.<name>.named_options.<name>.flag¶

Type:: boolean
Default:: false

If True, the option is a flag, i.e. it has no value.

parse.extend_directives.<name>.options¶

Type:: boolean
Default:: false

If True, the directive accepts options.

parse.extend_directives.<name>.parse_content¶

Type:: boolean
Default:: false

If True, the directive content is parsed.

parse.extend_roles¶

Type:: table of tables
Default:: {}

A map of role names to extend the roles with.

Each entry: Configuration to define a single role.

parse.extend_roles.<name>.description¶

Type:: string
Default:: ""

A short, human readable description of the role.

parse.extend_roles.<name>.extension¶

Type:: string

The extension that provides the role, if any.

parse.extensions¶

Type:: array of strings or table of (boolean or table)
Default:: {}

Built-in Sphinx-extension ports to switch on or off, by extension name.

Each entry overrides one port’s default, and a list entry means exactly the same as name = true:

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

# or, to switch ports off as well as on:
[parse.extensions]
"sphinx.ext.autosectionlabel" = true
"sphinxcontrib.video" = { active = false }

Markup ports are on by default, so their markup renders without being listed: sphinxcontrib.video, sphinx_syntax_example, sphinx.ext.todo, sphinx_design, sphinxcontrib.mermaid and sphinxcontrib.plantuml. sphinx.ext.autosectionlabel is off by default because it changes resolution project-wide (a :ref: target per section title) with no markup opting in, and sphinx.ext.extlinks activates on its own data — a populated [parse.extlinks] table switches it on.

Switching off a port that gates DIRECTIVES does not make its markup unknown: it still parses, its options are still validated and completed, and each use site renders as a labelled placeholder showing its source and warns (directive.extension_disabled) naming the extension and this key.

The two ports that gate something else are quieter, and neither can warn per use site: sphinx.ext.extlinks gates ROLES whose names come from your own [parse.extlinks] table, so switched off they fall back to a plain chip carrying the role name and its text, with no warning; and sphinx.ext.autosectionlabel has no markup at all, so switching it off simply stops the labels existing.

active is the only field an entry table may carry; an entry table without it (including an empty one) switches the port on, and any other key is reported as unknown (config.unknown_extension_option) and ignored.

sphinx_test_reports carries configuration of its own, in the [test_reports] section, which switches it on by itself (an empty section means the defaults). Listing it here is the same as writing an empty section when there is none; false switches it off and keeps the section’s settings, including a section inherited through extend, and an explicit false under either of its two names beats an explicit true under the other. Switched off, its need types and fields are not added and its directives render as labelled placeholders, unless a need type — or a [parse.extend_directives] entry — of the same name owns them (config.test_reports_switched_off says so once). Its old name, sphinxcontrib.test_reports, is read as sphinx_test_reports (config.extension_renamed).

Names ubcode ships no port for are ignored, so a conf.py extensions list can be mirrored wholesale. Three answers are given rather than silence: a name close to a known port’s is reported as a likely typo (config.unknown_extension); sphinx_needs is built in and cannot be switched off (config.extension_always_on); and a name ubcode knows but ships no port for, such as sphinx.ext.autodoc, is reported when switched on (config.extension_unsupported) because only Sphinx can run it.

If you also build with sphinx-build, list the extensions you use explicitly: the defaults here are a ubcode-side courtesy, and Sphinx needs each extension named in its own extensions list.

Forms:

an array of strings: Extension names whose ports are switched on.
a table of (boolean or table): Extension names mapped to their port setting.

Forms:

a boolean: Switch the port on (true) or off (false).
a table: Switch the port on or off through an entry table.

parse.extensions.<name>.active¶

Type:: boolean

Whether the port is active. Omitted in an entry table means active.

parse.extlinks¶

Type:: table of tables
Default:: {}

extlinks link-shorthand roles, each mapping a role name to a URL template and an optional caption.

Writing this table is all it takes: a populated [parse.extlinks] activates the sphinx.ext.extlinks port by itself, so the role names become usable without also naming the extension in [parse].extensions.

In each entry %s is replaced by the role’s text: e.g. [parse.extlinks.issue] with url = "https://github.com/o/r/issues/%s" makes the role issue with text 123 a link to .../issues/123. A literal percent is written %%, and each string may hold at most one %s (a template with more is reported and the role is skipped).

To keep the table but switch the roles off, set "sphinx.ext.extlinks" = false in [parse.extensions]: an explicit false is a kill switch that wins over the table, and the role names then stay unknown.

Each entry: A single extlinks link-shorthand role (Sphinx sphinx.ext.extlinks).

parse.extlinks.<name>.caption¶

Type:: string

The link-text template. %s is replaced by the role’s text (a literal percent is written %%; at most one %s). When unset the link text is the fully expanded URL.

parse.extlinks.<name>.url¶

Type:: string
Default:: ""

The URL template. %s is replaced by the role’s text; a literal percent is written %%. At most one %s is allowed.

parse.highlight_language¶

Type:: string
Default:: ""

The highlight language applied to literal and code blocks that have no language of their own.

Unset or an empty string means such blocks get no language class. An in-document .. highlight:: directive overrides this from its point onward.

Equivalent to Sphinx’s highlight_language configuration value (though ubCode does not default it to Sphinx’s default).

parse.id_style¶

Type:: string
Default:: "github"

How HTML ids and # link anchors are made from section titles and names.

"github" (the default) follows GitHub’s heading anchors: lowercase; letters of any script, digits, _ and - are kept; each space becomes -; other punctuation is removed; and a repeated anchor on one page gets -1, -2, …. So Needs_Types 2.0 anchors at #needs_types-20, and a link written for GitHub or for MyST-Parser’s heading anchors reaches the same heading for a plain-text heading on a page where nothing else claims its slug; the differences page lists the exceptions.

"docutils" makes Sphinx’s anchors: ASCII only, so Needs_Types 2.0 anchors at #needs-types-2-0, a title with nothing left once accents and compatibility forms are folded to ASCII (日本語, Привет) gets id1, and a repeated heading gets id1, id2, …. Set it when a Sphinx build of the same sources must produce the same anchors, or to keep existing deep links and bookmarks into your site working.

Either way, glossary terms keep their term- prefix and object descriptions (such as confval) keep Sphinx’s own anchors.

Values:

"github": GitHub’s heading-anchor convention (the default).
"docutils": Sphinx’s anchors (docutils’ make_id), to keep a Sphinx build’s anchors and existing deep links.

parse.ignore_directives¶

Type:: array of strings
Default:: []

A set of directive names that will not emit a warning if they are unknown.

parse.parsers¶

Type:: table of tables
Default:: {}

Per-parser configuration, keyed by parser name (e.g. rst, md).

The parser type is inferred from the canonical keys rst and md; give any other key an explicit type. Each parser’s include globs select which files it handles.

Each entry: Configuration for a single parser, defined under [parse.parsers.<name>].

Fields not relevant to the inferred parser type are ignored (e.g. flavour and extensions only apply to Markdown parsers).

parse.parsers.<name>.all_links_external¶

Type:: boolean

Treat every link in a Markdown document as an external URL, turning cross-referencing off (Markdown parsers only).

With this on, no destination is looked up: [](#target), [](other.md), <project:…>, <path:…> and <inv:…> alike keep the URL exactly as written, url_schemes templates are not applied, and nothing is reported as an unresolved reference. Unset means false — destinations are cross-referenced as documented above.

parse.parsers.<name>.extensions¶

Type:: array of strings or table of (boolean or table of (boolean or integer or string))
Default:: {}

Per-extension configuration (Markdown parsers only).

Forms:

an array of strings: Extension names to enable with default options.
a table of (boolean or table of (boolean or integer or string)): Extension names mapped to their settings.

Each entry: The setting for a single extension within a [parse.parsers.md.extensions] table.

An extension may be given either a bare boolean (deflist = true) to enable or disable it with default options, or a sub-table of per-extension options (dollarmath = { allow_space = true }), which also enables it.

Forms:

a boolean: Enable (true) or disable (false) the extension with default options.
a table of (boolean or integer or string): Enable the extension with the given per-extension options.

parse.parsers.<name>.flavour¶

Type:: string

The Markdown flavour (Markdown parsers only).

Values:

"commonmark": Plain CommonMark with no extensions enabled by default.
"myst": MyST Markdown — enables directive/role syntax, front matter, and tables (the always-on MyST core). Matching MyST-Parser, no optional extensions are enabled by default; enable them explicitly via the parser’s extensions setting.
"gfm": GitHub Flavored Markdown — enables the GFM extension set by default.

parse.parsers.<name>.footnote_sort¶

Type:: boolean

Collect footnote definitions to the foot of the page and sort them (Markdown parsers only).

With this on, every footnote definition the page itself wrote is moved to the foot of the page (below the last section, when there is one) into one list, ordered by its rendered number, and auto footnotes are numbered by the order their references appear rather than the order they are defined. A definition inside an extracted or imported card stays in the card. Turning it off does BOTH: definitions render where they are written, auto footnotes are numbered in definition order, and no rule is written even with footnote_transition on. Inert on a flavour with no footnote syntax (commonmark). Unset means true.

parse.parsers.<name>.footnote_transition¶

Type:: boolean

Write a horizontal rule above the collected footnotes (Markdown parsers only).

The rule is <hr class="footnotes" />, written directly above the collected footnote list. It is omitted on a page whose every top-level block is a footnote definition, and — because footnote_sort = false also disables the collection — whenever that key is off. Inert on a flavour with no footnote syntax (commonmark). Unset means true.

parse.parsers.<name>.include¶

Type:: array of strings

Glob patterns selecting which discovered files this parser handles.

Defaults to the parser type’s default (["*.rst"] for RST, ["*.md"] for Markdown) when unset.

parse.parsers.<name>.links_external_new_tab¶

Type:: boolean

Open external links in a new browser tab (myst flavour only).

A link that renders as an external URL — a plain web link, an unrecognised-scheme autolink, or a destination a url_schemes entry rewrote — gains target="_blank" and rel="noreferrer noopener". Cross-references, downloads and inventory-resolved links stay in the same tab. Unset means false.

parse.parsers.<name>.priority¶

Type:: integer

Routing priority, used to break ties when a file matches more than one parser equally specifically. Higher wins; defaults to 0.

parse.parsers.<name>.type¶

Type:: string

Explicit parser type, overriding inference from the sub-table key name.

Values:

"rst": The reStructuredText parser.
"md": The Markdown parser.

parse.parsers.<name>.url_schemes¶

Type:: array of strings or table of (string or table)
Default:: {}

Custom URL schemes a link destination may carry (Markdown parsers only).

A destination whose scheme is listed here is an external link, rewritten by the entry’s url template if it has one. http, https, mailto and ftp are always recognised, so declaring one scheme does not un-recognise those:

[parse.parsers.md]
url_schemes = ["doi"]                       # recognise, rewrite nothing

# …or, to rewrite as well as recognise:
[parse.parsers.md.url_schemes]
doi = "https://doi.org/{{path}}"
gh = { url = "https://github.com/{{path}}", title = "GitHub: {{path}}" }

inv, path and project are reserved for cross-referencing and cannot be redefined here; an entry naming one is reported and ignored.

Forms:

an array of strings: Scheme names recognised as external links, with no rewriting.
a table of (string or table): Scheme names mapped to what a destination carrying them becomes.

Forms:

a string: A URL template the destination is rewritten to.
a table: What a link destination carrying one custom URL scheme becomes: the URL to rewrite it to, the text to give it when the author wrote none, and any extra HTML classes. Every key is optional, and an empty table simply recognises the scheme as an external link.

parse.parsers.<name>.url_schemes.<name>.classes¶

Type:: array of strings

Extra HTML classes to add to the rendered link, after any the author attached to it inline.

parse.parsers.<name>.url_schemes.<name>.title¶

Type:: string

The link text to use when the author wrote none — an autolink (<wiki:Rust>) or an empty label ([](wiki:Rust)). A link with its own text keeps that text. Substitutes the same variables url does.

parse.parsers.<name>.url_schemes.<name>.url¶

Type:: string

The URL template the destination is rewritten to. Unset leaves the destination untouched, so an entry can annotate without rewriting.

A template may substitute any of the seven parts of the destination: {{uri}} (the whole destination, scheme included), {{scheme}}, {{netloc}}, {{path}}, {{params}}, {{query}} and {{fragment}}. Surrounding whitespace inside the braces is allowed ({{ path }}). Substitution is plain text replacement, not Jinja: any other {{name}} is left in the result verbatim, and a part the destination does not have substitutes as the empty string (so a template writing #{{fragment}} on a fragment-less destination leaves a bare trailing #).

{{params}} is always empty: ubcode never splits a trailing ;parameters segment off the path, so {{path}} keeps it.

parse.raw_enabled¶

Type:: boolean
Default:: true

Whether the raw directive passes its content through to the output.

On by default, matching docutils and Sphinx: a raw block’s content reaches the built HTML verbatim, unescaped. Set it to false when the project builds contributions you do not control — the directive then passes nothing through, warns (directive.raw_disabled), and renders a placeholder showing its own source instead. This applies everywhere a document is processed: ubc build, ubc check, and the editor preview.

Gates the raw DIRECTIVE only — the reStructuredText .. raw:: form and its MyST twin — exactly like the docutils setting of the same name. HTML written directly in a Markdown document is not a directive and is not affected.

parse.rst_epilog¶

Type:: string
Default:: ""

reStructuredText source appended to every RST document.

Unset or an empty string means nothing is appended. The content is parsed as RST at the very end of each document.

Equivalent to Sphinx’s rst_epilog configuration value.

parse.rst_prolog¶

Type:: string
Default:: ""

reStructuredText source prepended to every RST document.

Unset or an empty string means nothing is prepended. The content is parsed as RST at the very start of each document, so a .. default-role:: or .. role:: here applies to the whole document (state flows out of the prologue into the body).

Equivalent to Sphinx’s rst_prolog configuration value.

parse.syntax_example_numbering¶

Type:: boolean
Default:: false

Number the syntax-example blocks of each document.

Off by default, which titles every block Example (or its title argument, when given). When on, the blocks of a document are counted 1, 2, … and titled Example N, or Example N: <title> when a title argument is given. The count restarts at each document.

Active only when sphinx_syntax_example is listed in [parse].extensions; inert otherwise, like the extension’s own directive. Equivalent to the syntax_example_numbering configuration value of the sphinx-syntax-example Sphinx extension, which requires version 0.2.0 or later of that package — an earlier one ignores the confval, so a sphinx-build against it renders unnumbered titles while ubCode renders numbered ones.

parse.todo_include_todos¶

Type:: boolean
Default:: true

Whether todo blocks are rendered, and todolist blocks expanded.

On by default: enabling the sphinx.ext.todo port is normally how a project says it wants its todos visible. Set it to false to hide them — a todo then renders nothing at all and a todolist renders nothing at all, exactly as if the markup were absent, which is how the build reads for an audience that should not see outstanding work.

Active only when sphinx.ext.todo is listed in [parse].extensions; until then both directives render as unhandled placeholders and this setting is inert.

Equivalent to Sphinx’s todo_include_todos configuration value, whose default is false; ubCode defaults it to true instead. A project that shares one source tree between sphinx-build and ubCode should therefore set both values explicitly rather than relying on either default.

parse.todo_link_only¶

Type:: boolean
Default:: false

Whether a todolist entry’s backlink is shown on its own, without the surrounding “is located in <file>, line <n>” sentence.

Off by default, which renders the full sentence. Turn it on for a listing that is read on its own, where the file-and-line detail is noise. Active only when sphinx.ext.todo is listed in [parse].extensions.

Equivalent to Sphinx’s todo_link_only configuration value, and shares its default.

[parse]¶

`[parse]`¶