Reference

Every attribute the highlight-text extension accepts.

The complete highlight-text configuration: the colour attributes and their aliases, accepted colour values, brand colours, light and dark themes, and per-format support.

Enabling the filter

filters:
  - highlight-text

Syntax

A span colours inline text; a div colours a block.

[Inline]{fg="#b22222" bg="#ffffcc"}

::: {fg="#ffffff" bg="#b22222"}
A block.
:::

Attributes

Each has several spellings, so a document can keep whichever reads best.

Attributes accepted on a span or a div.
Attribute Aliases Description
Foreground colour, color, ink, fg Text colour.
Background bg-colour, bg-color, bg, paper Background colour.
Border colour border-colour, border-color, bc Border colour. Drawing a border needs this attribute.
Border style border-style, bs solid, dashed, dotted, or double. Defaults to solid.
Opacity opacity A number from 0 to 1, or a percentage such as "50%". Applied to the background when there is one, otherwise to the whole element.
Gradient gradient A full linear-gradient(...) or radial-gradient(...), or a comma-separated list of colour stops, which becomes a left-to-right linear gradient. Blocks only.
Line wrapping par LaTeX only, and on a span only. Wraps inline highlighted text in a \parbox so it can break across lines.

Where several spellings of the same attribute are given, the first in the alias list above wins, and the render warns which one it used. A hyphenated spelling also works with underscores, such as bg_colour, and comes just after the hyphenated form in that order. A boolean attribute needs a value. Pandoc does not parse an attribute written without one, so the span is left as text.

Named styles

A named style keeps a set of attributes under one class name. Define the styles under extensions.highlight-text.styles, in the front matter or in _quarto.yml:

extensions:
  highlight-text:
    styles:
      alert:
        fg: "#ffffff"
        bg: "#b22222"
      boxed:
        bc: primary
        bs: dashed

Then apply a style with its class, on a span or on a div:

[Danger]{.alert}

[Danger on black]{.alert bg="black"}

[Danger in a box]{.alert .boxed}

::: {.alert}
A block.
:::
  • A style accepts every attribute in the table above, with the same aliases and colour values.
  • When an element has more than one style class, the styles merge in class order, and a later class wins.
  • An attribute on the element wins over the same attribute in a style.
  • The filter removes each style class from the output, so the result is the same as when the element carries the attributes itself.
  • Other classes on the element stay in the output.
  • A class with no matching style does not change.

A style takes over any class with the same name. For example, a style named mark replaces the yellow highlight that Pandoc gives to .mark.

The schema check reports a style that is not a map, an unknown attribute in a style, and a style name that is not a valid class name. The render continues after each report.

Colour values

Accepted colour values.
Form Example Where it works
Hex #b22222, #abc Every format. Three or six digits.
Brand colour red, primary Every format. A name from the color.palette or the role names in _brand.yml.
CSS named firebrick Every format. Converted to a hex code for Typst and the binary writers.
CSS functional rgb(178 34 34), hsl(0 71% 42%), hwb(0 13% 30%) HTML and RevealJS.
CSS custom property var(--brand-primary) HTML and RevealJS. Resolved by the browser rather than by the filter.

LaTeX, Word, and PowerPoint need a colour they can write as a hex triplet, so a value they cannot convert is dropped with a warning and the rest of the styling is written without it.

An unrecognised colour is skipped with a warning rather than written out, so a typo cannot produce malformed output in any format.

Typst takes a hex code, so a value is converted to one before it is written: a hex code of either length, a brand colour, and a CSS named colour all work, while a CSS functional colour cannot be expressed that way and is skipped with a warning.

Brand colours

color:
  palette:
    red: "#b22222"
    custom-blue: "#0000ff"
  primary: "#abc123"
[Red text]{fg="red"}
[Primary highlight]{bg="primary"}
Note

The older brand-color. prefix, as in colour="brand-color.red", still works and warns. Use the plain name.

Light and dark

A brand can define both:

brand:
  light: _brand.yml
  dark: _brand-dark.yml
[This adapts to the theme]{fg="fg" bg="bg"}

HTML and Reveal.js switch between them live. Every other format takes the light value, or the dark one when there is no light.

Format support

What each format supports.
Feature HTML, RevealJS LaTeX, Beamer Typst Word PowerPoint
Foreground and background Yes Yes Yes Yes Yes
Border Yes Yes Yes Yes No
Opacity Yes No Yes No No
Gradient Yes No Yes No No
var() colours Yes No No No No
Links inside highlights Yes Yes Yes No No

A border colour requested in PowerPoint warns once per render.

LaTeX line wrapping

\colorbox does not break across lines, so a long inline highlight overflows.

  • Blocks wrap automatically; the filter uses \parbox for every engine except LuaLaTeX.
  • Inline highlights need par=true, which applies to XeLaTeX and PDFLaTeX.
  • LuaLaTeX handles it properly through lua-ul, and needs neither.
format:
  pdf:
    pdf-engine: lualatex

LuaLaTeX is Quarto’s default PDF engine.

Limitations

  • Word drops links inside highlighted text, rendering them in the default style.
  • PowerPoint flattens a highlight to plain characters, so a link, emphasis, or inline code inside one keeps its text and loses its formatting.
  • PowerPoint has no border support.
  • Opacity and gradients reach HTML and Typst only.
  • var() colours are resolved by the browser, so they are HTML and RevealJS only.
  • Gradients apply to blocks, not to inline spans.
  • A format outside the list above is left alone: the span or div renders as it would without the filter.
Back to top