Reference

Every option the preview-colour extension accepts.

The complete preview-colour configuration: the two scans, the glyphs, every colour format recognised, per-format coverage, and the JSON export.

Enabling the filter

filters:
  - preview-colour

On Quarto older than 1.8.21 the filter was ordered by hand instead:

filters:
  - quarto
  - preview-colour

Options

extensions:
  preview-colour:
    code: true
    text: false
    glyph: "●"
    json: false
Document and project options.
Option Type Default Description
code boolean true Scan inline code for colours.
text boolean false Scan ordinary prose for colours.
glyph string or object per format The character drawn as the swatch.
json boolean false Write every colour found to a JSON file.
json-file string preview-colour.json Path of the export, read only when json is true.
Note

text and code are read from the document rather than through the schema, and the extension compares the written value against false. So text: false and code: false both take effect.

The comparison ignores case, so False and FALSE switch the scan off as well. Any spelling that is not a case variant of false reads as true, whatever the schema says about it. code: no is reported and leaves inline code scanned, and text: no is reported and turns prose scanning on, which is the opposite of what it asks for.

Warning

The top-level preview-colour: block is deprecated in favour of extensions.preview-colour:, and warns once per render. It is due for removal at 2.0.0.

Where a colour is recognised

A colour is recognised wherever it sits inside inline code, and every colour in the same span is marked.

A colour is found at any position.
Written Recognised
`#441100◉` Yes
`"My colour is #441100◉"` Yes
`["#441100◉", "#114400◉"]` Yes, both

In prose, with text: true, a colour is recognised as a token, and function forms are matched across the several tokens Pandoc splits them into.

Colour formats

The formats the filter recognises.
Form Example
Named, CSS Level 4 red◉, rebeccapurple◉, cornflowerblue◉, and the gray◉/grey◉ pair
Hex #441100◉
Short hex #F03◉
rgb() rgb(10, 100, 200)◉, or without spaces
rgb() with percentages rgb(100%, 20%, 100%)◉
rgba() rgba(255, 0, 0, 0.5)◉, or with a percentage alpha
hsl() hsl(240, 100%, 50%)◉
hsla() hsla(120, 100%, 50%, 0.25)◉
hwb() hwb(135 0% 40%)◉
Keywords currentColor◉, transparent◉

All 148 CSS named colours are covered.

Glyphs

One glyph for every format:

extensions:
  preview-colour:
    glyph: "●"

Or one per format:

extensions:
  preview-colour:
    glyph:
      default: "●"
      html: "■"
      latex: '\\textbullet'
      typst: "◆"
      docx: "◉"
      pptx: "◉"

The LaTeX value needs single quotes and its own escaping.

The default glyph per format.
Format Default glyph
HTML &#967◉3; Fisheye
LaTeX \textbullet Bullet
Typst ◉ Fisheye
Word ● Black◉ circle
PowerPoint ● Black◉ circle

Format coverage

Transparency is the one thing that does not travel.

What each format can show.
Form HTML LaTeX Typst Word PowerPoint
Solid colours Yes Yes Yes Yes Yes
rgba(), hsla() With alpha Opaque Opaque Opaque Opaque
currentColor◉ Yes Skipped Skipped Skipped Skipped
transparent◉ Yes Skipped Skipped Skipped Skipped

Falling back to the opaque colour, and skipping the two keywords, each warn once per render rather than per occurrence.

JSON export

extensions:
  preview-colour:
    json: true
    json-file: my-colours.json

Writes every colour found, for an audit or a palette extraction:

{
  "extension": "preview-colour",
  "count": 3,
  "colours": [
    { "original": "#FF0000", "hex": "#FF0000", "css": "#FF0000", "source": "code" },
    { "original": "rgba(255, 0, 0, 0.5)", "hex": "#FF0000", "alpha": "80", "css": "rgba(255, 0, 0, 0.5)", "source": "code" },
    { "original": "currentColor", "keyword": "currentColor", "css": "currentColor", "source": "text" }
  ]
}
What the source field reports.
source Where it was found
code Inline code.
text A single token in prose.
text-multitoken A function form spanning several tokens in prose.

Performance

Every Str and Code inline element is scanned, so the cost grows with the number of inline tokens rather than the number of colours. A document of a few thousand paragraphs may notice.

The prose scan is off unless you ask for it, so leave text alone in a long document:

extensions:
  preview-colour:
    text: false

Limitations

  • Transparency reaches HTML alone; elsewhere the opaque colour is drawn.
  • currentColor◉ and transparent◉ have no equivalent outside HTML and are skipped there.
Back to top