`[build.pdf]`¶

PDF document configuration.

Page geometry, base type size and the quality bar for the document produced by ubc build pdf.

build.pdf.appendices¶

Type:: array of strings
Default:: []

Documents to print after the body, as appendices.

Each entry is a docname — the name a toctree entry uses, such as appendix/glossary — of a document the root toctree does not reach. They are printed after the body in the order listed, under one “Appendices” heading in the table of contents and the bookmarks. A listed document’s own toctree brings the pages it lists along beneath it, in toctree order, so one entry can be an appendix of several pages. Under the default pagination the appendices start on a new page, and so does each listed document, while the pages it brings in flow on; [build.pdf.pagination] documents changes that as it does for the body. An entry the body already reaches, one that names no document, or one an earlier entry already brought in is reported as a build warning and skipped; a repeat of an entry is reported and skipped; only the first listing counts. A document another page pulls in with include:: is not refused for that: listed, it prints as an appendix, and where it is pulled in too when that page prints. An entry that is "" is a no-op. Unset or [] means no appendices.

build.pdf.base_font_size¶

Type:: float
Default:: 10.0

The base text size, in points.

Defaults to 10.0 and must be between 6.0 and 24.0. Every other size in the document derives from it: headings scale up from it, code and the page number scale down from it, and the line spacing and the gaps between blocks are multiples of it.

build.pdf.cover¶

Type:: table

What the title page carries.

A picture, a subtitle, an author line, extra lines of your own, and four switches — for the title, version, date and selection-count lines. Unset — the default — is the cover this builder has always drawn: the project’s name, its version, the counts of a need selection when there is one, and the date of a build that pinned SOURCE_DATE_EPOCH.

It carries no colour — the cover’s ink is [build.pdf.theme.colors], as every other colour in the document is — and no position: the order the pieces are printed in is fixed, and each of them starts at the left edge of the text. The whole table is ignored when title_page = false, which is the key that decides whether there is a cover at all (a layout dump still lists the keys you wrote).

build.pdf.cover.author¶

Type:: string

A line of text printed under the subtitle.

Whoever the document should be attributed to, in whatever form suits — a person, a team or an organisation. Set in muted ink at the ordinary text size, like the subtitle above it. Unset, "" or blank prints nothing there; in a configuration that extends another, "" turns off a line the other set, and leaving the key out inherits it.

build.pdf.cover.counts¶

Type:: boolean

Print the selection-count line.

On unless counts = false. The line states how many of the project’s needs and documents the file contains, and it is printed only when the build was given a need selection (--need-id or --need-filter). Turning it off removes the one mark ON THE DOCUMENT saying it is an extract; the command still reports the selection on its own output, and so does a layout dump.

build.pdf.cover.date¶

Type:: boolean

Print the date line.

On unless date = false. The date comes only from the SOURCE_DATE_EPOCH environment variable, so the line is absent anyway when that is not set — this turns off a line a pinned build would otherwise get.

build.pdf.cover.lines¶

Type:: array of strings

Extra lines printed at the foot of the cover’s text.

One paragraph each, in the order written, after the version, the counts and the date — the place an imprint, a classification or a copyright line belongs. Set in the ordinary text ink and size. An entry that is "" or blank is a no-op and prints nothing, so a line can be emptied without renumbering the rest. An entry that is a web or mail address on its own — https://, http:// or mailto: — is printed as a clickable link in the document’s link colour; an address inside a sentence is printed as text, and everything on the line is part of the address, a closing full stop included. At most 16 entries, and a longer list is refused when the configuration is read. Unset or [] means no extra lines.

A configured cover is typeset like any other content: where it does not fit on one sheet it runs onto the next, and those sheets carry neither the running header nor a page number.

build.pdf.cover.logo¶

Type:: string

An image file to print above the title.

A path relative to this ubproject.toml (or absolute). PNG, JPEG, GIF, WebP, SVG and PDF files are all drawn; an SVG’s text is set in this builder’s own faces, never in the machine’s. The picture is fitted into a fixed box — two fifths of the text width, and six times the base text size high — keeping its proportions, and a picture smaller than that box is drawn at its own size rather than blown up. A file that is not there, or that cannot be read as a picture, is reported as a build warning and left out: the cover still prints. Unset or "" means no picture — and in a configuration that extends another, "" turns off a picture the other set, where leaving the key out inherits it.

build.pdf.cover.logo_height¶

Type:: float

How tall to print the logo, in millimetres.

Unset — the default — fits the picture into the box described above and never enlarges it. Set, the picture is printed at this height with its proportions kept, and the only remaining limit is the width of the text: a mark too wide for the page is scaled down to fit it. Must be greater than 0 and at most 100.0. Millimetres, like the page margins, because this is a physical size on paper rather than a size of type. It does nothing on its own when no logo is set.

build.pdf.cover.subtitle¶

Type:: string

A line of text printed under the title.

Set in muted ink at the ordinary text size, so that it reads as a second line of the title rather than as a heading. Unset, "" or blank prints nothing there; in a configuration that extends another, "" turns off a line the other set, and leaving the key out inherits it.

build.pdf.cover.title¶

Type:: boolean

Print the project’s name as the cover’s title.

On unless title = false. Turn it off when the logo is a wordmark that already says the name. The document’s title in the PDF’s metadata and outline is unaffected. If nothing else would be left on the cover, the title stays.

build.pdf.cover.version¶

Type:: boolean

Print the version line.

On unless version = false. The line reads Version followed by [project] version, and it is absent anyway when that key is unset or empty — so this turns off a line a project HAS a version for.

build.pdf.deny¶

Type:: string
Default:: "warning"

The lowest severity of finding that fails the build.

ubc build pdf reports two kinds of finding — render-phase build warnings and indexing diagnostics — and this is the single bar both are held to: any finding at or above this level fails the command with exit code 1. Defaults to warning, so any warning-or-worse finding fails the build; error lets warnings through and fails only on errors, and none never fails. The document is written before the gate is applied either way, so a failing build can still be opened for inspection. --deny on the command line overrides this for a single run, and codes silenced under [lint] never reach the gate.

Values:

"none": Never fail on findings.
"info": Fail on any finding, informational ones included.
"warning": Fail on any warning-or-worse finding.
"error": Fail only on errors.

build.pdf.emoji¶

Type:: boolean
Default:: true

Whether the bundled emoji face draws emoji.

The build carries a minimal monochrome emoji set (226 common emoji from Noto Emoji) and uses it last: after the built-in faces and after every font listed under fonts, for emoji none of them has. false turns it off, so the document and its pictures carry no emoji face and an emoji in the text that no other face covers is reported as a missing glyph. Unset means on.

build.pdf.fonts¶

Type:: array of strings
Default:: []

Extra font files for characters the built-in faces do not cover.

Paths are relative to this ubproject.toml (or absolute). Each file is read at build time and added to the document’s fallback chain after the six built-in DejaVu faces, in the order listed: the built-in faces still set every character they cover, and a listed font is used only for characters none of them has. It is the only way to print a private-use character, such as an icon font’s glyphs, and the way to add CJK coverage or emoji beyond the bundled set, whose face comes after every listed font: a listed emoji font draws every emoji it covers that the built-in faces lack. It does not change the typeface of body or code text. The glyphs used are embedded in the PDF, so the fonts’ licensing is yours to satisfy. A file that cannot be read, or that is not a font this builder can load, is reported as a build warning and skipped; the document still builds. Unset or empty means no extra fonts.

build.pdf.footer¶

Type:: table

What is printed in the bottom margin.

The same keys as header. Unset — the default — prints the page number in the middle with no rule above it.

Three slots, each a line of text in which {title}, {section}, {page}, {pages}, {project}, {version} and {date} are replaced by what the page knows; write {{ and }} for literal braces, and anything else in braces is refused where it is written. A slot that resolves to nothing prints nothing, and a band with no printed slot draws nothing at all, its divider included. Never printed on a title page, however many sheets that title page runs to.

build.pdf.footer.center¶

Type:: string

What is printed in the middle of the bottom margin.

Defaults to {page} of {pages}: the page’s printed number, then the number of numbered pages in the file that was built — which excludes a title page and, under --need-id or --need-filter, counts only the extract’s own pages. The pages after a title page are numbered from 1. Write {page} for the bare number, or "" for a document with no page numbers at all.

build.pdf.footer.divider¶

Type:: table

The rule drawn between the text and the footer. Off by default.

build.pdf.footer.divider.show¶

Type:: boolean

Draw a hairline rule between the band and the text.

On for [build.pdf.header] and off for [build.pdf.footer] unless this says otherwise. A band whose slots are all empty draws no rule either, and a band’s rule is left out where it would land inside the text, or across the band’s own line.

build.pdf.footer.divider.weight¶

Type:: float

The rule’s thickness, in points.

Defaults to 0.5. Must be greater than 0 and at most 5.0 — write show = false rather than a zero thickness, so that there is one way to say “no rule”. It does not scale with the band’s size: a hairline is a physical printing fact rather than a size of type.

build.pdf.footer.italic¶

Type:: boolean

Set the band in the oblique face. Off by default.

build.pdf.footer.left¶

Type:: string

What is printed at the left of the bottom margin. Empty by default.

build.pdf.footer.right¶

Type:: string

What is printed at the right of the bottom margin. Empty by default.

build.pdf.footer.size¶

Type:: float

The band’s type size, as a factor of base_font_size.

Defaults to 0.9, which is 9.0 pt under the default 10.0 pt base. Must be between 0.1 and 3.0. The band’s whole geometry scales with it — how far the line sits below the text, and its rule with it. A band too tall for its margin is kept on the sheet rather than printed off the paper, and where the margin is much too small for it the band can be drawn over the last lines of text with nothing reporting it; only its rule is left out.

build.pdf.footer.weight¶

Type:: string

The face the band is set in: normal or bold.

Defaults to normal. It names a face, not a numeric CSS weight: the built-in sans family carries these two.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.header¶

Type:: table

What is printed in the top margin.

Three slots — left, center and right — plus the band’s type, and a divider sub-table for the rule under it. Unset — the default — prints the document’s title on the left with a hairline under it.

build.pdf.header.center¶

Type:: string

What is printed in the middle of the top margin. Empty by default.

build.pdf.header.divider¶

Type:: table

The rule drawn between the header and the text. On by default.

build.pdf.header.divider.show¶

Type:: boolean

Draw a hairline rule between the band and the text.

build.pdf.header.divider.weight¶

Type:: float

The rule’s thickness, in points.

build.pdf.header.italic¶

Type:: boolean

Set the band in the oblique face. Off by default.

build.pdf.header.left¶

Type:: string

What is printed at the left of the top margin.

Defaults to {title}, the title of the document the page belongs to — which is empty on the page a document begins on, so a one-page document is never headed. Set it to "" to print nothing there.

build.pdf.header.right¶

Type:: string

What is printed at the right of the top margin. Empty by default.

build.pdf.header.size¶

Type:: float

The band’s type size, as a factor of base_font_size.

Defaults to 0.9, which is 9.0 pt under the default 10.0 pt base. Must be between 0.1 and 3.0. The band’s whole geometry scales with it — how far the line sits above the text, and its rule with it. A band too tall for its margin is kept on the sheet rather than printed off the paper, and where the margin is much too small for it the band can be drawn over the first lines of text with nothing reporting it; only its rule is left out.

build.pdf.header.weight¶

Type:: string

The face the band is set in: normal or bold.

Defaults to normal. It names a face, not a numeric CSS weight: the built-in sans family carries these two.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.hidden_needs¶

Type:: string
Default:: "full"

How a hidden need (:hide:) is printed.

full, the default, prints its whole card, as a visible need’s is printed. collapsed prints only the card’s header line — its type, title and id — as a browser prints the HTML site’s closed card; a link to a label or a need written inside its body then lands on that header. :hide: is not a confidentiality boundary: either way the need’s content is still published on the HTML site.

Values:

"full": The whole card, as a visible need’s.
"collapsed": The card’s header line only: type, title and id.

build.pdf.highlight¶

Type:: table
Default:: { aliases = {}, enabled = true }

Syntax-highlighting settings for the PDF document.

The same keys as [build.highlight]. This table inherits every key it does not set from [build.highlight] and wins on every key it does.

The builders colour the code in a code-block, a literalinclude and a fenced block — and inline code with a language — using the language the code names. The set of languages is a bundled collection of Sublime Text syntax definitions, so it is the same on every machine and needs nothing installed. The colours are the hl-* roles under [build.pdf.theme.colors] on paper, and the --ubc-hl-* custom properties on the site.

These keys can be written once in [build.highlight] for every output format, or in one format’s own table — [build.pdf.highlight], [build.html.highlight] — which inherits every key it does not set from [build.highlight] and wins on every key it does, enabled = false included.

Both ubc build pdf and ubc build html read them, and they colour code with the same engine, so a language name and a decision about colour mean the same thing on paper and on the site.

build.pdf.highlight.aliases¶

Type:: table of strings
Default:: {}

Extra names for languages, on top of the built-in table.

Each entry maps a name you write — in a code-block argument, a :language: option or a .. highlight:: — to the language it should be coloured as. The value is another language name ("python", "toml", "rst"), or "text" to draw the code plain and report nothing.

An entry wins over the built-in name of the same spelling, so default = "text" turns off the built-in “an unmarked block is Python” behaviour. Names are matched ignoring case and surrounding spaces, and a value is looked up ONCE: it must name a language directly, not another entry in this table. A value that names no language is reported when the project is read, and under the default --deny warning that stops the build — unless highlighting is off for that format, in which case no name is looked up and nothing is reported.

Written here this applies to every output format. A format’s own table ([build.pdf.highlight], [build.html.highlight]) REPLACES this map for that format rather than adding to it.

Empty by default, in which case only the built-in names resolve.

build.pdf.highlight.enabled¶

Type:: boolean
Default:: true

Colour the code in code blocks and in inline code that names a language.

Defaults to true. Setting this to false draws all code in the document’s own code colour — code-fg on paper, the --ubc-code-fg custom property on the site — as the builders did before they could highlight. It does not affect the line-number gutter, and it does not affect the band an :emphasize-lines: option draws behind a line. The colours themselves are the hl-* roles under [build.pdf.theme.colors] on paper, and the --ubc-hl-* custom properties on the site.

build.pdf.margins¶

Type:: table
Default:: { bottom = 20.0, left = 20.0, right = 20.0, top = 20.0 }

The page margins, in millimetres.

Each of top, right, bottom and left defaults to 20.0 and may be set on its own. A negative value is refused, as is any combination leaving a content box narrower or shorter than 50 mm. The page furniture is drawn inside these margins — by default the document’s title in the top one and the page number in the bottom one, and see header and footer to change either; each band stays just inside the page edge when its own margin is too small to hold it.

build.pdf.margins.bottom¶

Type:: float
Default:: 20.0

The bottom margin, in millimetres. Defaults to 20.0. The running page number is drawn inside it.

build.pdf.margins.left¶

Type:: float
Default:: 20.0

The left margin, in millimetres. Defaults to 20.0.

build.pdf.margins.right¶

Type:: float
Default:: 20.0

The right margin, in millimetres. Defaults to 20.0.

build.pdf.margins.top¶

Type:: float
Default:: 20.0

The top margin, in millimetres. Defaults to 20.0.

build.pdf.mermaid¶

Type:: table

Mermaid settings for the PDF document.

The same keys as [build.mermaid], plus enabled (on by default). This table inherits every key it does not set from [build.mermaid] and wins on every key it does.

build.pdf.mermaid.browser¶

Type:: string
Default:: ""

See [build.mermaid] browser.

build.pdf.mermaid.browser_args¶

Type:: array of strings
Default:: []

See [build.mermaid] browser_args.

build.pdf.mermaid.enabled¶

Type:: boolean
Default:: true

Draw mermaid diagrams in the PDF.

On by default: when a document has a mermaid diagram and a browser is found (or named with browser), the diagram is drawn; otherwise it stays a placeholder box showing its source, reported as build.pdf_diagram_unrendered. false never looks for a browser and never starts one. Applies to mermaid directives and {mermaid} fences; needflow, needsequence and converted uml diagrams are unaffected.

build.pdf.mermaid.min_version¶

Type:: string
Default:: ""

See [build.mermaid] min_version.

build.pdf.mermaid.timeout¶

Type:: integer
Default:: 30

See [build.mermaid] timeout.

build.pdf.page_size¶

Type:: string
Default:: "a4"

The page size of the document.

a4 (210 × 297 mm, the default) or letter (8.5 × 11 in). An enum rather than a dimension string, so there are no units to spell and no invalid geometry to express.

Values:

"a4": ISO A4 — 210 × 297 mm.
"letter": US Letter — 8.5 × 11 in.

build.pdf.pagination¶

Type:: table

Where pages break, and what is kept together on one.

Six keys: which documents start on a new page, a section heading level that always starts one, how many lines a heading keeps with it, the fewest lines a split leaves on each side of a page break, and whether a line ending in a colon stays with the block it introduces.

Every key has a default, and unset is the document this builder draws without the table: the root document, the documents its toctree lists directly and each [build.pdf] appendices entry start on a new page, no heading level forces one, a heading keeps three lines of what follows it, a split leaves at least two lines on each side, and a line ending in a colon stays with the block it introduces.

build.pdf.pagination.break_before_level¶

Type:: integer

Start every section heading at this outline level or above on a new page.

Defaults to 0, which starts none. Levels are counted as the table of contents counts them: the root document’s title is level 1, and a document at toctree depth d sets its title at level d, at most 6 (a title deeper than that is set at level 6, and its sections nest from there), so 2 starts every level-2 heading on a new page. It acts as a break-before class on each such heading: a heading whose document already starts a page is not given a second one, and a heading directly under a document title that has nothing else on its page stays on the title’s page. A rubric is not a section heading and never breaks.

build.pdf.pagination.documents¶

Type:: string

Which documents start on a new page.

"top-level" — the default — starts the root document, each document its toctree lists directly and each [build.pdf] appendices entry on a new page, and lets deeper documents follow on where the text ends. "all" starts every document on a new page, and "none" starts none: each follows on where the one before it ends. The body starts on the page after the title page and the table of contents when the project prints them, and a page a document starts carries no running header.

Values:

"top-level": The root document, every document its toctree lists directly and each [build.pdf] appendices entry; deeper documents follow on where the text ends.
"all": Every document.
"none": None: each document follows on where the one before it ends.

build.pdf.pagination.heading_keep_lines¶

Type:: integer

How many lines of what follows a heading share its page.

Defaults to 3, and must be 1 or more. The lines are counted through the blocks under the heading: a paragraph, listing, table or list long enough to split keeps that many of its own lines, or orphans if that is more, so 1 keeps only the next line with the heading unless that line starts a block that splits. A caption ends the count: the block it captions keeps by its own rule. A heading that cannot share a page with that many lines keeps what fits.

build.pdf.pagination.keep_introducers¶

Type:: boolean

Keep a paragraph ending in a colon on the page of the block it introduces.

On unless keep_introducers = false. A line such as “For example:” then never ends a page with its example on the next; false lets the page break after it.

build.pdf.pagination.orphans¶

Type:: integer

The fewest lines a page break leaves at the foot of a page.

Defaults to 2, and must be 1 or more. Counted in lines for a paragraph, in source lines for a code listing and in rows for a table’s body; 1 lets a split leave a single line or row. A block with fewer lines than orphans and widows together is not split when it fits on one page, so a large value keeps every block whole that one page can hold.

build.pdf.pagination.widows¶

Type:: integer

The fewest lines a page break carries onto the next page.

Defaults to 2, and must be 1 or more. Counted as orphans counts them; 1 lets a split carry a single line or row over.

build.pdf.plantuml¶

Type:: table

External PlantUML renderer settings for the PDF document.

The same four keys as [build.plantuml]. This table inherits every key it does not set from [build.plantuml] and wins on every key it does, enabled = false included.

ubCode can draw the needuml and needarch views, the authored uml / plantuml directives (and their MyST {uml} / {plantuml} fences), and — when needflow / needsequence are set — the needflow and needsequence views, by running a PlantUML executable you install and maintain, instead of converting them to Mermaid. It is off by default, and the live preview always uses the Mermaid conversion.

These keys can be written once in [build.plantuml] for every output format, or in one format’s own table such as [build.html.plantuml], which inherits every key it does not set from [build.plantuml] and wins on every key it does, enabled = false included.

PlantUML 1.2026.2 or newer is required. Older releases accept the command-line options this feature relies on and then ignore them, so the diagram it produced would not be under the controls described here.

ubCode always sets PlantUML’s SANDBOX profile, as a JVM property and in the environment. That is a safe default rather than a guarantee: the executable is yours, and what you put in command can relax it — a later -DPLANTUML_SECURITY_PROFILE=UNSECURE, a wrapper script that re-exports the profile, or an entry that strips the environment. That is your explicit choice: ubCode does not diagnose which of the two PlantUML prefers, and cannot contain what PlantUML then reads.

build.pdf.plantuml.command¶

Type:: array of strings
Default:: []

The PlantUML executable to run, written as a command and its arguments.

Always a list, never a single string. For a JAR give the launcher and the JAR — ["java", "-jar", "/opt/plantuml.jar"] — and put any JVM options (-Xmx512m) before -jar; for a wrapper script or a native build, one entry is enough.

The FIRST entry is the program: a bare name is looked up on PATH, and one containing a path separator is taken relative to this ubproject.toml. Every entry after it is passed through EXACTLY as written.

To point at a file beside this ubproject.toml, write {config_dir} and ubCode replaces it with that directory — anywhere in any entry, as often as you like: ["java", "-jar", "{config_dir}/libs/plantuml.jar"]. Nothing else in an argument is rewritten, so a container image name, a KEY=VALUE pair or a URL reaches your program unchanged.

Required when the renderer is enabled — a command that cannot be run is reported as the build warning build.plantuml_exec_failed, and so is an unset or empty one.

ubCode always runs PlantUML under its SANDBOX profile, and what you write here can relax it: a later -DPLANTUML_SECURITY_PROFILE=UNSECURE argument, or a wrapper script that re-exports the profile before starting PlantUML. That is your explicit choice — ubCode does not diagnose whether PlantUML prefers the property or the environment, cannot contain what PlantUML then reads, and PlantUML’s own allowlist confines neither .. nor symbolic links.

build.pdf.plantuml.enabled¶

Type:: boolean
Default:: false

Render PlantUML diagrams with an external PlantUML executable instead of converting them to Mermaid.

Applies to the needuml / needarch views and the authored uml / plantuml directives in the built output, and to the needflow / needsequence views when their own keys are also set. Defaults to false, which leaves each builder to draw the diagram itself — in the HTML site, as the Mermaid conversion. The live preview always uses the Mermaid conversion, so an enabled project’s diagrams can look different in the preview than on the built page. Writing this table without setting this key leaves the renderer off.

build.pdf.plantuml.min_version¶

Type:: string
Default:: ""

The oldest PlantUML version this project accepts.

Written the way PlantUML writes it, 1.2026.4, and checked once per build against the version the executable reports. Below it the renderer is switched off for that build with the warning build.plantuml_version_unsupported and the diagrams fall back to what the builder draws without the renderer (in the HTML site, the Mermaid conversion).

This can only RAISE the bar: it cannot be set below the built-in minimum of 1.2026.2, and a lower value is reported as the build warning build.plantuml_exec_failed and ignored in favour of that minimum. An executable whose reported version cannot be read at all is reported as build.plantuml_version_unparsed and not used, since there is then no version to check against the minimum.

Diagram appearance can change between PlantUML releases, so upgrading can change how your diagrams look. Unset or "" means 1.2026.2.

build.pdf.plantuml.needflow¶

Type:: boolean
Default:: false

Also draw the needflow views with the external PlantUML executable.

Needs enabled as well: this key chooses which diagrams the renderer draws, never whether there is one, so needflow = true on its own changes nothing. Defaults to false in both builders, which draws every needflow the way ubCode draws it today (in the HTML site, as a client-side Mermaid flowchart; in the PDF, as a box showing the diagram source).

This is a FIDELITY setting: the diagram is laid out by PlantUML itself, the way a Sphinx-Needs build with needs_flow_engine = "plantuml" lays it out, and each node becomes a link to its need. Some intents cannot be carried over exactly — :direction: up and :direction: left are drawn on their axis mate, a type style that is not a PlantUML keyword is drawn as a rectangle, and style_start / style_end are ignored.

[needs] flow_engine is the low-precedence default for this key, so a ubproject.toml shared with a Sphinx-Needs build need not say the same thing twice. A diagram’s own :engine: option overrides both, in either direction. The live preview always uses the Mermaid conversion, whatever this says.

build.pdf.plantuml.needsequence¶

Type:: boolean
Default:: false

Also draw the needsequence views with the external PlantUML executable.

Needs enabled as well, exactly as needflow does, and defaults to false in both builders. A separate key from needflow because a project may well want its traceability graph drawn by PlantUML and its message diagrams left as they are.

[needs] flow_engine does NOT drive this key. Sphinx-Needs’ own needsequence is PlantUML-only and has no engine option at all, so the key that chooses between engines has nothing to say about this family.

With it off, a needsequence is the Mermaid sequence diagram ubCode draws itself (a box showing that source, in the PDF). With it on, it is laid out by PlantUML. The live preview always uses the Mermaid conversion, whatever this says.

build.pdf.plantuml.timeout¶

Type:: integer
Default:: 60

How long the whole diagram-rendering step may take, in seconds.

The bound covers the single run that renders every diagram needing an update, not each diagram. Diagrams that produced no output when it expires are reported as the build warning build.plantuml_timeout and fall back to what the builder draws without the renderer (in the HTML site, the Mermaid conversion). Defaults to 60; 0 is refused as build.plantuml_exec_failed.

build.pdf.running_header¶

Type:: boolean
Default:: true

Print each page’s document title in the top margin.

On unless running_header = false. When on, and unless the header table below says otherwise, every page carries the title of the document its content belongs to — or that document’s file name when it has no title — above the text, set in muted ink with a hairline rule under it, as the counterpart of the page number in the bottom margin. Not on the page where a document begins, where its own heading is already the title, and not on a title page, which belongs to no document — so a document that fits on one page is never headed at all. A title too wide for the page is cut short with an ellipsis, and the rule is left out where a small top margin would put it inside the text.

It is a shorthand for the header table below: running_header = false empties that table’s default slots, and any slot you write there still applies on top of it.

build.pdf.theme¶

Type:: table

The colours the document is painted in, and the type of classed elements.

Three tables — palette for your own named colours, colors for the roles the document paints, and classes for how the text of an element carrying a class is set. Unset — the default — paints the document in ubCode’s own palette, which is the HTML site’s light theme, and styles only the two built-in classes, ssp-tinier and ssp-tiny.

build.pdf.theme.classes¶

Type:: table of tables
Default:: { ssp-tinier = { size = 0.75 }, ssp-tiny = { size = 0.5 } }

How an element carrying a class is set: its text, and its colours.

Each key is a class name as it reaches the element, and each value may set size, weight and italic, and colors — the colours of the element and everything inside it. reStructuredText normalises a class the way docutils’ make_id does — lower case; each run of characters other than letters and digits becomes one -; a leading run of digits or -, and a trailing -, is dropped — and so do a MyST directive’s :class:, a need’s :style: and a needtable’s or needflow’s :class: (:style: red_border is the class red-border); a MyST {.name} is kept as written. A class no key names is left as it is, and a key no element carries does nothing. Of two classes on one element, both sizes apply, and the later class’s face and each colour it sets win. An extending configuration merges bundle by bundle and key by key.

Two bundles are built in, at sphinx-simplepdf’s own table sizes: ssp-tinier (size = 0.75) and ssp-tiny (size = 0.5). Writing either name changes the keys it writes, and size = 1.0 turns one off. Unset — the default — styles those two classes and no other.

Each entry: The type and the colours of every element carrying one class.

A bundle that sets no key is accepted and does nothing.

build.pdf.theme.classes.<name>.colors¶

Type:: table

The colours of the element and everything inside it.

The same keys as [build.pdf.theme.colors], each replacing that table’s colour for the element, except the four page-band keys (header-text, header-rule, footer-text, footer-rule), which are refused here. Of two classes on one element the later one’s colour wins, and an inner class’s wins inside an outer one. Each value is a hex colour (#rgb or #rrggbb), or @name naming an entry of [build.pdf.theme.palette]. Unset, the element takes the colours around it: an enclosing class’s, then the document’s.

build.pdf.theme.classes.<name>.colors.bg-soft¶

Type:: string

The recessed background: table header rows, key caps (:kbd:), placeholder boxes, and topic and sidebar boxes. A code block’s and an inline literal’s ground is code-bg.

build.pdf.theme.classes.<name>.colors.border¶

Type:: string

The default border and rule colour: a container’s frame, a table’s cell rules, a chart’s grid lines, the rule between sections.

build.pdf.theme.classes.<name>.colors.brand¶

Type:: string

A need card’s type badge. A role of its own rather than a use of link: the site declares --ubc-brand and --ubc-link as separate tokens that happen to carry one value, so a project that recolours link alone leaves its badges where they were — on paper exactly as on the site. The badge’s outline is not painted by this; it is the type’s own [[needs.types]] color.

build.pdf.theme.classes.<name>.colors.chart-1¶

Type:: string

Chart slot 1 — the fill of a wedge, a bar or a legend swatch. A chart with more series than slots cycles back to this one.

build.pdf.theme.classes.<name>.colors.chart-2¶

Type:: string

Chart slot 2 — the fill of a wedge, a bar or a legend swatch.

build.pdf.theme.classes.<name>.colors.chart-3¶

Type:: string

Chart slot 3 — the fill of a wedge, a bar or a legend swatch.

build.pdf.theme.classes.<name>.colors.chart-4¶

Type:: string

Chart slot 4 — the fill of a wedge, a bar or a legend swatch.

build.pdf.theme.classes.<name>.colors.chart-5¶

Type:: string

Chart slot 5 — the fill of a wedge, a bar or a legend swatch.

build.pdf.theme.classes.<name>.colors.chart-6¶

Type:: string

Chart slot 6 — the fill of a wedge, a bar or a legend swatch.

build.pdf.theme.classes.<name>.colors.chart-7¶

Type:: string

Chart slot 7 — the fill of a wedge, a bar or a legend swatch.

build.pdf.theme.classes.<name>.colors.chart-8¶

Type:: string

Chart slot 8 — the fill of a wedge, a bar or a legend swatch.

build.pdf.theme.classes.<name>.colors.chart-halo-1¶

Type:: string

The halo stroked under a value label on slot 1’s fill, so the glyphs keep an edge.

build.pdf.theme.classes.<name>.colors.chart-halo-2¶

Type:: string

The halo stroked under a value label on slot 2’s fill, so the glyphs keep an edge.

build.pdf.theme.classes.<name>.colors.chart-halo-3¶

Type:: string

The halo stroked under a value label on slot 3’s fill, so the glyphs keep an edge.

build.pdf.theme.classes.<name>.colors.chart-halo-4¶

Type:: string

The halo stroked under a value label on slot 4’s fill, so the glyphs keep an edge.

build.pdf.theme.classes.<name>.colors.chart-halo-5¶

Type:: string

The halo stroked under a value label on slot 5’s fill, so the glyphs keep an edge.

build.pdf.theme.classes.<name>.colors.chart-halo-6¶

Type:: string

The halo stroked under a value label on slot 6’s fill, so the glyphs keep an edge.

build.pdf.theme.classes.<name>.colors.chart-halo-7¶

Type:: string

The halo stroked under a value label on slot 7’s fill, so the glyphs keep an edge.

build.pdf.theme.classes.<name>.colors.chart-halo-8¶

Type:: string

The halo stroked under a value label on slot 8’s fill, so the glyphs keep an edge.

build.pdf.theme.classes.<name>.colors.chart-on-1¶

Type:: string

The text of a value label drawn on slot 1’s fill.

build.pdf.theme.classes.<name>.colors.chart-on-2¶

Type:: string

The text of a value label drawn on slot 2’s fill.

build.pdf.theme.classes.<name>.colors.chart-on-3¶

Type:: string

The text of a value label drawn on slot 3’s fill.

build.pdf.theme.classes.<name>.colors.chart-on-4¶

Type:: string

The text of a value label drawn on slot 4’s fill.

build.pdf.theme.classes.<name>.colors.chart-on-5¶

Type:: string

The text of a value label drawn on slot 5’s fill.

build.pdf.theme.classes.<name>.colors.chart-on-6¶

Type:: string

The text of a value label drawn on slot 6’s fill.

build.pdf.theme.classes.<name>.colors.chart-on-7¶

Type:: string

The text of a value label drawn on slot 7’s fill.

build.pdf.theme.classes.<name>.colors.chart-on-8¶

Type:: string

The text of a value label drawn on slot 8’s fill.

build.pdf.theme.classes.<name>.colors.code-bg¶

Type:: string

The background of a code block, and of an inline literal. A role of its own rather than a use of bg-soft: the site declares the two as separate tokens that happen to carry one value, so a project that recolours bg-soft alone leaves its code ground where it was — on paper exactly as on the site. A key cap (:kbd:) is NOT painted by this; its fill is bg-soft.

build.pdf.theme.classes.<name>.colors.code-fg¶

Type:: string

The ink of a code block’s lines, and of an inline literal. A role of its own rather than a use of fg, for the reason code-bg is one: the site declares it separately, so recolouring fg alone leaves the code ink where it was. A code block’s line-number gutter is NOT painted by this; it is drawn in fg.

build.pdf.theme.classes.<name>.colors.danger¶

Type:: string

The accent of a danger or error box — its leading bar, and its title band at a fifth of the same colour.

build.pdf.theme.classes.<name>.colors.fg¶

Type:: string

Body text, and the rule struck through deleted text.

build.pdf.theme.classes.<name>.colors.fg-border¶

Type:: string

The stronger border colour, for boxes that read as edged: a topic’s or sidebar’s leading bar.

build.pdf.theme.classes.<name>.colors.fg-muted¶

Type:: string

Secondary text: the running header and a need card’s id chip.

build.pdf.theme.classes.<name>.colors.footer-rule¶

Type:: string

The rule above the bottom margin’s band. Paper only; unset, it follows border.

build.pdf.theme.classes.<name>.colors.footer-text¶

Type:: string

The text of the bottom margin’s band, the page number included. Paper only; unset, it follows fg-muted.

build.pdf.theme.classes.<name>.colors.generic¶

Type:: string

The accent of a kindless .. admonition:: box — its leading bar, and its title band at a fifth of the same colour.

build.pdf.theme.classes.<name>.colors.header-rule¶

Type:: string

The rule under the top margin’s band. Paper only; unset, it follows border.

build.pdf.theme.classes.<name>.colors.header-text¶

Type:: string

The text of the top margin’s band. Paper only; unset, it follows fg-muted.

build.pdf.theme.classes.<name>.colors.heading-rule¶

Type:: string

The rule under a heading, when [build.pdf.typography] asks for one. Left unset it follows border.

build.pdf.theme.classes.<name>.colors.hl-addition-bg¶

Type:: string

The background behind an INSERTED line in a highlighted diff block.

build.pdf.theme.classes.<name>.colors.hl-addition-fg¶

Type:: string

The text of an INSERTED line in a highlighted diff block.

build.pdf.theme.classes.<name>.colors.hl-attr¶

Type:: string

Attribute names in a highlighted code block — a TOML or YAML key, an HTML attribute, a CSS property.

build.pdf.theme.classes.<name>.colors.hl-built-in¶

Type:: string

Built-in and support functions in a highlighted code block, and the prompt character of a console session ($, >>>).

build.pdf.theme.classes.<name>.colors.hl-bullet¶

Type:: string

List bullets in a highlighted code block, in a markup language such as Markdown or reStructuredText.

build.pdf.theme.classes.<name>.colors.hl-comment¶

Type:: string

Comments in a highlighted code block.

build.pdf.theme.classes.<name>.colors.hl-deletion-bg¶

Type:: string

The background behind a DELETED line in a highlighted diff block.

build.pdf.theme.classes.<name>.colors.hl-deletion-fg¶

Type:: string

The text of a DELETED line in a highlighted diff block.

build.pdf.theme.classes.<name>.colors.hl-escape¶

Type:: string

Escape sequences in a highlighted block — \n, \u00e9, and a backslash escape in a markup listing.

build.pdf.theme.classes.<name>.colors.hl-function¶

Type:: string

The NAMES of functions and methods in a highlighted code block, where they are declared or called. Types are hl-type.

build.pdf.theme.classes.<name>.colors.hl-keyword¶

Type:: string

Keywords and storage words in a highlighted code block — if, def, struct, const.

build.pdf.theme.classes.<name>.colors.hl-label¶

Type:: string

Names that anchor a cross-reference in a highlighted markup block — a reStructuredText target, footnote, citation or substitution, and a MyST (name)= — and a label a language declares, such as a goto target.

build.pdf.theme.classes.<name>.colors.hl-link¶

Type:: string

URLs and hyperlink targets in a highlighted markup block, in the site’s link colour.

build.pdf.theme.classes.<name>.colors.hl-literal¶

Type:: string

Language constants in a highlighted code block — true, nil, None.

build.pdf.theme.classes.<name>.colors.hl-name¶

Type:: string

Tag names, CSS selectors and quoted passages in a highlighted code block — an XML element name, a Markdown blockquote.

build.pdf.theme.classes.<name>.colors.hl-number¶

Type:: string

Numbers in a highlighted code block — 42, 0x1f, 3.14.

build.pdf.theme.classes.<name>.colors.hl-operator¶

Type:: string

Operators in a highlighted code block, word forms (and, not) included.

build.pdf.theme.classes.<name>.colors.hl-section¶

Type:: string

Headings in a highlighted code block, in a markup language such as Markdown or reStructuredText. Set bold as well as coloured.

build.pdf.theme.classes.<name>.colors.hl-string¶

Type:: string

Strings in a highlighted code block. An escape sequence is hl-escape.

build.pdf.theme.classes.<name>.colors.hl-type¶

Type:: string

The NAMES of types, classes, structs, enums and namespaces in a highlighted code block, where they are declared.

build.pdf.theme.classes.<name>.colors.hl-variable¶

Type:: string

Variables and parameters in a highlighted code block.

build.pdf.theme.classes.<name>.colors.important¶

Type:: string

The accent of an important box — its leading bar, and its title band at a fifth of the same colour.

build.pdf.theme.classes.<name>.colors.link¶

Type:: string

A link’s text.

build.pdf.theme.classes.<name>.colors.link-underline¶

Type:: string

A link’s underline. Left unset it follows link — on paper the link’s colour, on the site the link’s current text colour in every state — so recolouring links recolours their underlines; set it to decouple the two, which is the underline-style treatment, where the link text stays in the body colour and the underline carries the accent.

build.pdf.theme.classes.<name>.colors.need-blue-fill¶

Type:: string

The background of a need card with :style: blue. An OPAQUE colour on paper: the site paints a translucent tint, and this is what it composites to over white.

build.pdf.theme.classes.<name>.colors.need-blue-line¶

Type:: string

The frame or trailing bar of a need card with :style: blue_border or blue_bar.

build.pdf.theme.classes.<name>.colors.need-discreet-fill¶

Type:: string

The background of a need card with :style: discreet. An OPAQUE colour on paper: the site paints a translucent tint, and this is what it composites to over white.

build.pdf.theme.classes.<name>.colors.need-discreet-line¶

Type:: string

The frame of a need card with :style: discreet_border. There is no discreet_bar upstream, so this colour draws no bar. An OPAQUE colour on paper: the site states it translucently, and this is what it composites to over white.

build.pdf.theme.classes.<name>.colors.need-gray-fill¶

Type:: string

The background of a need card with :style: gray. An OPAQUE colour on paper: the site paints a translucent tint, and this is what it composites to over white.

build.pdf.theme.classes.<name>.colors.need-green-fill¶

Type:: string

The background of a need card with :style: green (or implemented). An OPAQUE colour on paper: the site paints a translucent tint, and this is what it composites to over white.

build.pdf.theme.classes.<name>.colors.need-green-line¶

Type:: string

The frame or trailing bar of a need card with :style: green_border or green_bar.

build.pdf.theme.classes.<name>.colors.need-orange-line¶

Type:: string

The trailing bar of a need card with :style: orange_bar. There is no orange_border upstream, so this colour draws no frame.

build.pdf.theme.classes.<name>.colors.need-red-fill¶

Type:: string

The background of a need card with :style: red (or open). An OPAQUE colour on paper: the site paints a translucent tint, and this is what it composites to over white.

build.pdf.theme.classes.<name>.colors.need-red-line¶

Type:: string

The frame or trailing bar of a need card with :style: red_border or red_bar.

build.pdf.theme.classes.<name>.colors.need-yellow-fill¶

Type:: string

The background of a need card with :style: yellow (or in_progress). An OPAQUE colour on paper: the site paints a translucent tint, and this is what it composites to over white.

build.pdf.theme.classes.<name>.colors.need-yellow-line¶

Type:: string

The frame or trailing bar of a need card with :style: yellow_border or yellow_bar.

build.pdf.theme.classes.<name>.colors.note¶

Type:: string

The accent of a note box — its leading bar, and its title band at a fifth of the same colour.

build.pdf.theme.classes.<name>.colors.seealso¶

Type:: string

The accent of a seealso box — its leading bar, and its title band at a fifth of the same colour.

build.pdf.theme.classes.<name>.colors.tip¶

Type:: string

The accent of a tip or hint box — its leading bar, and its title band at a fifth of the same colour.

build.pdf.theme.classes.<name>.colors.todo¶

Type:: string

The accent of a todo box — its leading bar, and its title band at a fifth of the same colour.

build.pdf.theme.classes.<name>.colors.version-added¶

Type:: string

The lead label’s text in a .. versionadded:: box.

build.pdf.theme.classes.<name>.colors.version-added-bar¶

Type:: string

The leading bar of a .. versionadded:: box.

build.pdf.theme.classes.<name>.colors.version-changed¶

Type:: string

The lead label’s text in a .. versionchanged:: box.

build.pdf.theme.classes.<name>.colors.version-changed-bar¶

Type:: string

The leading bar of a .. versionchanged:: box.

build.pdf.theme.classes.<name>.colors.version-deprecated¶

Type:: string

The lead label’s text in a .. deprecated:: box.

build.pdf.theme.classes.<name>.colors.version-deprecated-bar¶

Type:: string

The leading bar of a .. deprecated:: box.

build.pdf.theme.classes.<name>.colors.version-removed¶

Type:: string

The lead label’s text in a .. versionremoved:: box.

build.pdf.theme.classes.<name>.colors.version-removed-bar¶

Type:: string

The leading bar of a .. versionremoved:: box.

build.pdf.theme.classes.<name>.colors.warning¶

Type:: string

The accent of a warning, caution or attention box — its leading bar, and its title band at a fifth of the same colour.

build.pdf.theme.classes.<name>.italic¶

Type:: boolean

Set the element’s text in the oblique face.

It is not set on a heading, title, term, attribution, caption or table head inside the element, which keeps its own, and it has no effect on monospaced text. Unset, the slant is left as it is.

build.pdf.theme.classes.<name>.size¶

Type:: float

Set the element’s text this many times the size it would otherwise have — and, with it, the element’s code lines, list markers and table box.

Must be between 0.1 and 4.0. Unset, the size is left as it is.

build.pdf.theme.classes.<name>.weight¶

Type:: string

The face the element’s text is set in.

It is not set on a heading, title, term, attribution, caption or table head inside the element, which keeps its own, nor on a code block’s or parsed literal’s lines. Unset, the face is left as it is.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.theme.colors¶

Type:: table
Default:: {}

The colours the PDF document is painted in.

Every key is a site theme token’s name without its --ubc- prefix, so a colour set here and the same token set in [build.html] extra_css mean the same thing. Each value is a hex colour (#rgb or #rrggbb), or @name naming an entry of [build.pdf.theme.palette]. A key that is not one of the names below is refused when the configuration is read. Unset — the default — leaves every colour at its built-in value.

Takes the same keys as build.pdf.theme.classes.<name>.colors.

build.pdf.theme.palette¶

Type:: table of strings
Default:: {}

Your project’s own named colours, for reuse across colors.

Each key is a name of your choosing — letters, digits, _ and -, not starting with a digit — and each value a hex colour (#rgb or #rrggbb). Refer to one from [build.pdf.theme.colors] as @name. A palette entry may not refer to another entry. A configuration that writes this table at all replaces it whole, rather than merging with a palette it extends. Unset — the default — means no named colours.

build.pdf.title_page¶

Type:: boolean
Default:: true

Open the document with a title page.

On unless title_page = false. When on, the document starts with a cover carrying the project name — or, when no name is set, the root document’s title, or its file name when that document has no title — the version from [project] version when there is one, and how many of the project’s needs the file contains, when the build was given a need selection. A date is added only when the SOURCE_DATE_EPOCH environment variable is set, so that two builds of the same sources stay byte-identical. The cover carries no page number — the pages after it are numbered from 1, and a PDF reader’s own page box shows the same numbers — and it takes the first entry in the document outline. --title-page and --no-title-page override it for a single run, and cover below says what the cover carries.

build.pdf.toc¶

Type:: table
Default:: { depth = 3, enabled = true, title = "Contents" }

The table of contents printed in the front matter.

Three keys: whether the table is printed at all, how many heading levels it lists, and the heading printed over it. Unset — the default — is a table listing three levels of headings, and enabled = false is what takes it away. The document opens with a table listing its headings and the page each one starts on, on its own sheets after the title page — or as the document’s first sheets when title_page = false. Those sheets carry neither the running header nor a page number, and the body is numbered from 1 on the sheet after them. --toc and --no-toc override the switch for a single run.

build.pdf.toc.depth¶

Type:: integer

How many heading levels the table lists.

Defaults to 3. Levels are counted from the root document’s title, which is level 1, so the default lists that title, the titles of the documents the root toctree reaches and their own top-level sections, and the [build.pdf] appendices, under their heading. Must be 1 or more; a project that wants every heading listed writes a large number. It does nothing when enabled = false.

build.pdf.toc.enabled¶

Type:: boolean

Print a table of contents in the front matter.

On unless enabled = false. The table lists every section heading down to depth levels with the page it starts on, each entry a link, and it is drawn on its own sheets before the body — after the title page when there is one. --toc and --no-toc override it for a single run.

build.pdf.toc.title¶

Type:: string

The heading printed above the table.

Defaults to Contents. Set in the same type as a top-level heading, and it takes no entry in the document outline. "" prints the table with no heading at all; in a configuration that extends another, "" turns off a heading the other set, where leaving the key out inherits it. It does nothing when enabled = false.

build.pdf.typography¶

Type:: table

How each construct is set: its size, its face, and two decorations.

One sub-table per construct — the six heading levels and what they share, every paragraph, the monospaced constructs, a link’s underline, the scripts, and the seven constructs the builder styles itself. Each sub-table carries only the keys its construct decides. Every size is a FACTOR rather than a point size, and [build.pdf] base_font_size stays the one key that scales the whole document: a block construct’s factor multiplies base_font_size itself, while literal, kbd, subscript, superscript, badge, id-chip, display and version-label multiply the size of the text they sit in: each is applied to the enclosing style at its draw site rather than to base_font_size. Every weight names a FACE rather than a numeric weight, because the built-in family carries two. Unset — the default — is the type this builder has always set.

build.pdf.typography.admonition-title¶

Type:: table

An admonition’s TITLE. Defaults to bold at the ordinary text size.

build.pdf.typography.admonition-title.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.admonition-title.size¶

Type:: float

How big the construct is set, as a factor of base_font_size.

1.0 — the ordinary text size — unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.admonition-title.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.badge¶

Type:: table

A need card’s TYPE badge — the chip carrying the need’s type.

size defaults to 0.9 and multiplies the size of the header it sits in. Size only: the badge is set in font-mono, and its colour is the brand role in [build.pdf.theme.colors].

build.pdf.typography.badge.size¶

Type:: float

How big the construct is set, as a factor of the size it composes onto.

Must be between 0.1 and 4.0.

build.pdf.typography.body¶

Type:: table

Every PARAGRAPH, wherever it appears.

Not “body text” in the narrow sense: a list item, a table cell, a need card’s body, an admonition’s body, a block quote, the paragraph under a caption and a line block’s lines are all paragraphs, and a list’s bullet or number follows the paragraph it opens. A construct with a row of its own — a caption, a table head, a heading — takes that row on top of this one. Defaults to the regular upright face.

It has no size key: [build.pdf] base_font_size IS the body size.

build.pdf.typography.body.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.body.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.caption¶

Type:: table

A table’s, a view’s or a code block’s CAPTION. Defaults to bold at the ordinary text size.

build.pdf.typography.caption.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.caption.size¶

Type:: float

How big the construct is set, as a factor of base_font_size.

1.0 — the ordinary text size — unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.caption.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.card-title¶

Type:: table

A need card’s TITLE. Defaults to bold at the ordinary text size.

build.pdf.typography.card-title.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.card-title.size¶

Type:: float

How big the construct is set, as a factor of base_font_size.

1.0 — the ordinary text size — unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.card-title.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.code¶

Type:: table

A code block’s lines, and the line numbers in its gutter.

size defaults to 0.9. Size only: a listing’s weight is its :emphasize-lines: option, which is content rather than styling, and the built-in monospaced family has no oblique face.

build.pdf.typography.code.size¶

Type:: float

How big the construct is set, as a factor of the size it composes onto.

Must be between 0.1 and 4.0.

build.pdf.typography.definition-term¶

Type:: table

A definition list’s TERM. Defaults to bold at the ordinary text size.

build.pdf.typography.definition-term.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.definition-term.size¶

Type:: float

How big the construct is set, as a factor of base_font_size.

1.0 — the ordinary text size — unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.definition-term.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.display¶

Type:: table

The title page’s DISPLAY line: the document’s title on the cover.

size defaults to 2.4 in the bold face — a step above the largest heading, so a cover reads as a cover. Whether the line is printed at all is [build.pdf.cover] title.

build.pdf.typography.display.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.display.size¶

Type:: float

How big the construct is set, as a factor of base_font_size.

1.0 — the ordinary text size — unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.display.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.figure-caption¶

Type:: table

A figure’s, a gantt’s, a diagram’s or a video’s CAPTION, under its picture or the box standing in for it.

Defaults to the regular OBLIQUE face at the ordinary text size — unlike caption above (a table’s, a view’s or a code block’s), which is bold.

build.pdf.typography.figure-caption.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.figure-caption.size¶

Type:: float

How big the construct is set, as a factor of base_font_size.

1.0 — the ordinary text size — unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.figure-caption.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.font¶

Type:: string

The family every paragraph, heading, table, card, caption and the cover are set in, named as a font file listed under [build.pdf] fonts declares it.

The family must supply regular, bold, italic and bold italic faces; otherwise it is refused with a warning and the built-in family is used. Unset, "" or blank keeps the built-in family; in a configuration that extends another, "" turns off a family the other set, and leaving the key out inherits it. Pictures follow it; the running header and footer do not.

build.pdf.typography.font-mono¶

Type:: string

The family every code block, inline literal and :kbd: cap is set in, named as a font file listed under [build.pdf] fonts declares it.

The family must supply regular and bold faces; otherwise it is refused with a warning and the built-in monospaced family is used. Unset, "" or blank keeps the built-in family; in a configuration that extends another, "" turns off a family the other set, and leaving the key out inherits it. A code span is always upright, whatever faces the family carries.

build.pdf.typography.heading¶

Type:: table

What every heading level has in common: its face and its rule.

A key on heading-1 … heading-6 wins over the same key here.

build.pdf.typography.heading.italic¶

Type:: boolean

Set every heading level in the oblique face.

Off unless this says otherwise. A key on heading-1 … heading-6 wins over the same key here.

build.pdf.typography.heading.rule¶

Type:: table

The rule drawn under every heading level.

No rule unless this says otherwise. A rule key on heading-1 … heading-6 wins over the same key here, key by key: a level that sets rule = { weight = 1.0 } keeps the show written here.

build.pdf.typography.heading.rule.show¶

Type:: boolean

Draw a hairline rule under the heading.

Off unless this says otherwise. The rule separates a heading from the block that follows it, and is drawn centred in the gap the heading already leaves before that block, so turning it on adds no height and moves no page break; a heading with no block after it in the same container — the document, a container’s body, a list item, a table cell or a definition — draws none. It spans the width of the text, and is painted in the heading-rule colour role, which follows border while it is unset.

build.pdf.typography.heading.rule.weight¶

Type:: float

The rule’s thickness, in points.

Defaults to 0.5. Must be greater than 0 and at most 3.0 — write show = false rather than a zero thickness, so that there is one way to say “no rule”. The rule is drawn centred in the gap the heading already leaves before the block that follows it, and 3.0 is small enough that even the thickest rule stays inside that gap at every text size. It does not scale with the heading’s size: a hairline is a physical printing fact rather than a size of type.

build.pdf.typography.heading.weight¶

Type:: string

The face every heading level is set in.

"bold" unless this says otherwise. A key on heading-1 … heading-6 wins over the same key here.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.heading-1¶

Type:: table

A level-1 heading. size defaults to 1.9.

build.pdf.typography.heading-1.italic¶

Type:: boolean

Set this level in the oblique face.

Takes [build.pdf.typography.heading] italic when unset, and off when that is unset too.

build.pdf.typography.heading-1.rule¶

Type:: table

The rule drawn under this level.

Each key takes the same key of [build.pdf.typography.heading] rule when unset, and its own built-in value when that is unset too.

build.pdf.typography.heading-1.rule.show¶

Type:: boolean

Draw a hairline rule under the heading.

build.pdf.typography.heading-1.rule.weight¶

Type:: float

The rule’s thickness, in points.

build.pdf.typography.heading-1.size¶

Type:: float

How big this level is set, as a factor of base_font_size.

1.9, 1.6, 1.35, 1.2, 1.1 and 1.0 for levels 1 to 6 unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.heading-1.weight¶

Type:: string

The face this level is set in.

Takes [build.pdf.typography.heading] weight when unset, and "bold" when that is unset too.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.heading-2¶

Type:: table

A level-2 heading. size defaults to 1.6.

Takes the same keys as build.pdf.typography.heading-1.

build.pdf.typography.heading-3¶

Type:: table

A level-3 heading. size defaults to 1.35.

Takes the same keys as build.pdf.typography.heading-1.

build.pdf.typography.heading-4¶

Type:: table

A level-4 heading. size defaults to 1.2.

Takes the same keys as build.pdf.typography.heading-1.

build.pdf.typography.heading-5¶

Type:: table

A level-5 heading. size defaults to 1.1.

Takes the same keys as build.pdf.typography.heading-1.

build.pdf.typography.heading-6¶

Type:: table

A level-6 heading, and every level deeper than six.

size defaults to 1.0 — the ordinary text size, so a heading this deep is distinguished by its face rather than by being bigger. A document’s headings run deeper than its sources’ do, because a document included at depth d renders its own title at level d.

Takes the same keys as build.pdf.typography.heading-1.

build.pdf.typography.id-chip¶

Type:: table

A need card’s ID chip.

size defaults to 0.9 and multiplies the size of the header it sits in. Size only, as badge is; its colour is the fg-muted role in [build.pdf.theme.colors].

build.pdf.typography.id-chip.size¶

Type:: float

How big the construct is set, as a factor of the size it composes onto.

Must be between 0.1 and 4.0.

build.pdf.typography.kbd¶

Type:: table

A :kbd: key cap, and an option list’s option.

size defaults to 0.9. Size only, as literal is.

build.pdf.typography.kbd.size¶

Type:: float

How big the construct is set, as a factor of the size it composes onto.

Must be between 0.1 and 4.0.

build.pdf.typography.lead-in¶

Type:: table

A LEAD-IN: a topic’s, a sidebar’s or a .. contents:: title, a sphinx-design component’s title slot, a tab’s label. Defaults to bold at the ordinary text size.

build.pdf.typography.lead-in.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.lead-in.size¶

Type:: float

How big the construct is set, as a factor of base_font_size.

1.0 — the ordinary text size — unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.lead-in.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.link¶

Type:: table

How a link is decorated.

build.pdf.typography.link.underline¶

Type:: boolean

Draw the underline under a link.

On unless underline = false. Turning it off leaves the link in the link colour and still clickable — on paper it is then distinguished by its colour alone, which is worth weighing against a document that may be printed in black and white. The underline’s position and thickness are the typeface’s own and are not configurable.

build.pdf.typography.literal¶

Type:: table

An inline literal — ``text`` in reStructuredText, `text` in Markdown — and an object description’s signature.

size defaults to 0.9. Size only: a literal keeps the weight and slant of the sentence around it.

build.pdf.typography.literal.size¶

Type:: float

How big the construct is set, as a factor of the size it composes onto.

Must be between 0.1 and 4.0.

build.pdf.typography.math¶

Type:: table

Typeset maths.

size defaults to 1.21 and multiplies the size of the text around the formula, which is the size the HTML build sets maths at beside the same text. Size only: maths is set in its own faces.

build.pdf.typography.math.size¶

Type:: float

How big the construct is set, as a factor of the size it composes onto.

Must be between 0.1 and 4.0.

build.pdf.typography.placeholder-detail¶

Type:: table

A placeholder box’s DETAIL lines, set in the monospaced family.

size defaults to 0.85, in the regular upright face. italic has no effect: a monospaced construct is always set upright, whatever faces the family carries.

build.pdf.typography.placeholder-detail.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.placeholder-detail.size¶

Type:: float

How big the construct is set, as a factor of base_font_size.

1.0 — the ordinary text size — unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.placeholder-detail.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.placeholder-headline¶

Type:: table

A placeholder box’s first line — what was not rendered.

size defaults to 0.9, in the bold face. A placeholder box is drawn where this builder cannot typeset a construct yet, or where a picture’s file could not be read.

build.pdf.typography.placeholder-headline.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.placeholder-headline.size¶

Type:: float

How big the construct is set, as a factor of base_font_size.

1.0 — the ordinary text size — unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.placeholder-headline.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.quote-attribution¶

Type:: table

A block quote’s ATTRIBUTION line.

Defaults to the regular OBLIQUE face at the ordinary text size.

build.pdf.typography.quote-attribution.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.quote-attribution.size¶

Type:: float

How big the construct is set, as a factor of base_font_size.

1.0 — the ordinary text size — unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.quote-attribution.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.subscript¶

Type:: table

A :sub: subscript. size defaults to 0.7.

Size only: a subscript keeps the face of the sentence around it, and how far it is dropped below the baseline is not configurable.

build.pdf.typography.subscript.size¶

Type:: float

How big the construct is set, as a factor of the size it composes onto.

Must be between 0.1 and 4.0.

build.pdf.typography.superscript¶

Type:: table

A :sup: superscript. size defaults to 0.7.

Size only, as subscript is.

build.pdf.typography.superscript.size¶

Type:: float

How big the construct is set, as a factor of the size it composes onto.

Must be between 0.1 and 4.0.

build.pdf.typography.table-head¶

Type:: table

A table’s HEADER cells. Defaults to bold at the ordinary text size.

build.pdf.typography.table-head.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.table-head.size¶

Type:: float

How big the construct is set, as a factor of base_font_size.

1.0 — the ordinary text size — unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.table-head.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

build.pdf.typography.version-label¶

Type:: table

A version-change box’s lead LABEL — “Added in version 2.5” and its three siblings.

Defaults to bold at the ordinary text size; its colour is the version-added, version-changed, version-deprecated or version-removed role for its own kind.

build.pdf.typography.version-label.italic¶

Type:: boolean

Set the construct in the oblique face.

build.pdf.typography.version-label.size¶

Type:: float

How big the construct is set, as a factor of base_font_size.

1.0 — the ordinary text size — unless this says otherwise. Must be between 0.1 and 4.0.

build.pdf.typography.version-label.weight¶

Type:: string

The face the construct is set in.

Values:

"normal": The regular face.
"bold": The bold face.

[build.pdf]¶

`[build.pdf]`¶