How it works

mdBook passes every chapter to the preprocessor as Markdown. mdbook-tsitter parses it with mdBook’s own Markdown parser and settings (pulldown-cmark with the extensions [output.html] enables), locates top-level fenced code blocks for configured languages, and sends their source through tree-sitter-highlight.

The highlighted events become semantic CSS classes and are spliced back into the chapter as ready-made HTML:

<pre class="treesitter"><code class="no-highlight" data-language="rust">…spans…</code></pre>

The block deliberately has no language-* class: mdBook’s highlight.js would re-highlight any block whose language-* class names a language it knows, even one marked no-highlight, and its colours would override the tree-sitter ones. The fence tag is kept in data-language instead.

mdBook adds its own code-block features (Rust Playground markup, the implicit fn main, hidden lines) only to plain-text blocks, so the preprocessor applies the same rules before highlighting. A runnable Rust block, for example, becomes:

<pre class="treesitter playground"><code class="no-highlight edition2021" data-language="rust">…spans…</code></pre>

Other preprocessors that run afterwards see highlighted blocks as HTML rather than code fences, so $ and \ in highlighted code are written as HTML entities, which math preprocessors do not read as their syntax.

A group of pane="…" blocks becomes a treesitter-side-by-side element with one treesitter-pane per block. A pane holding a block left to mdBook keeps its fence, separated from the surrounding HTML by blank lines so mdBook still renders it as Markdown:

<div class="treesitter-side-by-side">
<div class="treesitter-pane">
<div class="treesitter-pane-label">Before</div>

<pre class="treesitter">…</pre>

</div>
…
</div>

Finally, every chapter with a highlighted block gets the highlighting stylesheet as a <style> element in the mdbook-tsitter cascade layer: the theme directory’s highlight_ts.css, or else the bundled stylesheet, with any colours carried over from highlight.js stylesheets the theme replaces.