Syntax themes

Syntax colours come from Shiki themes. You register the ones your project uses, a document chooses one, and a fence can override it.

Registering

provideBlasdocHighlight({
  themes: {
    github: { light: 'github-light', dark: 'github-dark' },
    dracula: { light: 'github-light', dark: 'dracula' },
  },
  defaultTheme: 'github',
});

Theme names autocomplete across all 65 Shiki themes, and only the registered ones are ever downloaded — the full set is 1.4 MB of themes and 8.3 MB of grammars, so lazy loading is not optional.

Choosing one

Per document, in front matter:

---
blasdoc:
  theme: dracula
---

Per block, in the fence meta:

```ts theme="dracula"
const thisBlockDiffers = true;
```

Light and dark without re-highlighting

Each scheme's colour is written on the token as --shiki-light and --shiki-dark, so switching is pure CSS. Nothing is highlighted twice, and the switch costs nothing at runtime.

.blasdoc-code span { color: var(--shiki-light); }
 
@media (prefers-color-scheme: dark) {
  .blasdoc-code span { color: var(--shiki-dark); }
}

Contrast

Editor themes are designed for editors: github-dark puts some comment tokens below 4.5:1, which an audit will flag. Blasdoc will not repaint a theme behind your back, so correction is opt-in and only touches the tokens that fail:

provideBlasdocHighlight({
  themes: { github: { light: 'github-light', dark: 'github-dark' } },
  defaultTheme: 'github',
  ensureContrast: {
    ratio: 4.5,
    background: { light: '#ffffff', dark: '#161b22' },
  },
});

Each scheme is measured against its own background, and only the failing tokens are lifted.

Unknown names

A theme or language that is not registered is reported rather than silently ignored:

BLASDOC_UNKNOWN_THEME     Unknown code theme "draclua". Registered: github.
BLASDOC_UNKNOWN_LANGUAGE  Unknown code language "typscript".