Highlight-text Extension For Quarto

This is a Quarto extension that allows to highlight text in a document for various formats: HTML, LaTeX, Typst, Docx, PowerPoint, Reveal.js, and Beamer.

Installation

quarto add mcanouil/quarto-highlight-text

This will install the extension under the _extensions subdirectory.

If you're using version control, you will want to check in this directory.

Usage

To use the extension, add the following to your document's front matter:

filters:
  - highlight-text

Then you can use either span syntax for inline highlighting or div syntax for block-level highlighting.

Inline Highlighting (Spans)

Highlight text inline using span syntax:

[Red]{colour="#b22222" bg-colour="#abc123"} # UK spelling
[Blue]{color="#0000ff" bg-color="#abc123"} # US spelling

Block Highlighting (Divs)

Highlight entire blocks using div syntax:

::: {fg="#ffffff" bg="#0000ff"}
This is a block-level highlighted section.

It can contain multiple paragraphs, lists, and other content.
:::

Shorter Syntax

You can use abbreviated attribute names (v1.1.1):

[Red text]{fg="#b22222"}
[Red background]{bg="#abc123"}
[White on Red]{fg="#ffffff" bg="#b22222"}
[Text with solid border]{bc="#0000ff"}
[Text with dashed border]{bc="#b22222" bs="dashed"}
[Text with dotted border]{bc="#00aa00" border-style="dotted"}

For block-level highlighting:

::: {fg="#ffffff" bg="#b22222"}
Block with white text on red background.
:::

::: {bc="#b22222" bg="#ffffcc"}
Block with red solid border and light yellow background.
:::

::: {bc="#0000ff" bg="#f0f0f0" bs="dashed"}
Block with blue dashed border and light grey background.
:::

Supported attributes:

• Foreground (text) colour: fg, colour, or color
• Background colour: bg, bg-colour, or bg-color
• Border colour: bc, border-colour, or border-color
• Border style: bs or border-style (values: solid, dashed, dotted, double; defaults to solid)

Using Brand Colours

Define colours once in _brand.yml and reference them throughout your documents (v1.1.0):

color:
  palette:
    red: "#b22222"
    custom-blue: "#0000ff"
  primary: "#abc123"

Reference these colours directly by name:

[Red text]{fg="red"}
[Custom background]{bg="custom-blue"}
[Primary highlight]{bg="primary"}

Note

The old brand-color. prefix syntax (e.g., colour="brand-color.red") is deprecated but still supported (v1.4.0). You'll see a warning when using it. Use the colour name directly instead: colour="red".

Light and Dark Theme Support

With Quarto CLI ≥1.7.28, you can define different colours for light and dark themes (v1.2.0):

Option 1: Define themes in document front matter:

brand:
  light:
    color:
      palette:
        fg: "#ffffff"
        bg: "#b22222"
  dark:
    color:
      palette:
        fg: "#b22222"
        bg: "#ffffff"

Option 2: Use external _brand.yml file:

brand:
  light: _brand.yml
  dark: _brand-dark.yml

Then reference theme-aware colours:

[This text adapts to theme]{fg="fg" bg="bg"}

Note

Only HTML formats support dynamic light/dark mode switching. Other formats will use the light mode colours if available, or fall back to dark mode colours otherwise, unless specified otherwise.

Limitations

LaTeX/PDF Output

The LaTeX \colorbox command does not support line wrapping for highlighted text with background colours. Long highlighted text may overflow or break awkwardly.

For inline highlighting: Use the par=true attribute to add \parbox{\linewidth} (XeLaTeX and PDFLaTeX only):

[Long text with background]{colour="#b22222" bg-colour="#abc123" par=true}

For block-level highlighting: Automatic line wrapping is enabled for all engines. Block divs automatically use \parbox for non-LuaLaTeX engines.

Best solution: Use LuaLaTeX as your PDF engine for proper line wrapping with the lua-ul package:

format:
  pdf:
    pdf-engine: lualatex

Note

LuaLaTeX is the default PDF engine in Quarto CLI ≥1.8.25.

PowerPoint Output

Links are not supported in highlighted text in PowerPoint output, i.e., URLs will be rendered using default styles.

Border colour is not supported in PowerPoint output.

Word Output

Links are not supported in highlighted text in Word output, i.e., URLs will be rendered using default styles.

Example

Here is the source code for a minimal example: example.qmd.

Output of example.qmd:

• HTML
• Typst/PDF
• LaTeX/PDF (XeLaTeX)
• LaTeX/PDF (LuaLaTeX)
• LaTeX/PDF (PDFLaTeX)
• Word/Docx (only supports plain text, i.e., no URLs)
• Reveal.js
• Beamer/PDF
• PowerPoint/Pptx (only supports plain text, i.e., no URLs)