Configuration keys

Every key ubproject.toml accepts, with its type and default, one page per table. This reference is generated from the configuration schema ubCode validates against; the guides explain the keys with examples.

Guide: Top-level options.

Top-level keys

The keys outside any table, and the keys of [build] itself.

$schema
Type:
string

The URL or path of the JSON schema for this file, which editors read to validate and complete it. ubc ignores this key.

build
Type:
table

Output-build configuration.

Groups the settings of the ubc build output formats, one sub-table per format.

build.smartquotes
Type:
boolean
Default:
true

Whether straight quotes, dashes and ellipses in prose are typeset in the built output.

On by default, as in Sphinx: "text" becomes “text”, it's becomes it’s, -- an en dash, --- an em dash and ... an ellipsis, in ubc build html, ubc build pdf and the editor preview. Code, literal blocks, math, raw content, object signatures and option names are never changed, and neither are needs.json, need titles, table cells of need listings, or the editor’s hover and outline text. A backslash keeps a character as written (\"), in reStructuredText and in Markdown. The quote characters follow [project] language. Set to false to keep every character exactly as written.

Equivalent to Sphinx’s smartquotes configuration value. A smartquotes setting in a conf.py is not read.

build.smartquotes_action
Type:
string
Default:
""

Which typographic replacements smartquotes makes.

Letters, in any order: q quotes, D dashes (-- an en dash, --- an em dash), d or i dashes the other way round, e ellipses, b backtick-style double quotes, B backtick-style double and single quotes, and w " entities. Or a preset: 0 nothing, 1 qbde, 2 qbDe, 3 qbie, or -1, which turns typographic characters back into ASCII.

Unset or an empty string means "qDe". An unknown letter is reported and ignored; the letters around it still apply, as in Sphinx.

Equivalent to Sphinx’s smartquotes_action configuration value (except that an empty string means the default, not nothing).

build_tags
Type:
array of strings
Default:
[]

Build tags for conditional processing, mirroring Sphinx’s tags configuration.

extend
Type:
string

The path to a configuration file to extend.

virtual
Type:
boolean
Default:
false

Virtual configurations do not correspond to an actual project. They are used for providing shared configuration defaults, or for workspaces that are not themselves projects.