[build.highlight]

Syntax-highlighting settings shared by every builder.

Each builder also has a highlight table of its own, [build.pdf.highlight] and [build.html.highlight], so a language can be named once here for the whole project. A builder’s own table inherits every key it does not set from [build.highlight] and wins on every key it does, enabled = false included — so highlighting can be switched off once here for every output format.

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.

Guide: Sharing the highlighting settings between builders.

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