mdbook-tsitter

Tree-sitter syntax highlighting for mdBook — for any language you can point a grammar at.

View the project on GitHub.

mdbook-tsitter is an mdBook preprocessor that parses fenced code blocks with tree-sitter and renders the resulting captures as themeable HTML. It is grammar-agnostic: list a language it knows, name any grammar’s git repository, or supply a compiled parser and its highlight queries, and the same preprocessor can handle anything from Rust and Lua to a language of your own.

Features

• Grammar-agnostic. Over 300 common languages work by name; any other tree-sitter grammar works from its repository or a prebuilt parser. Grammars are fetched and compiled on the first build.
• Structural highlighting. Definitions, calls, types, parameters, properties, macros, and other syntax can receive distinct styles whenever the grammar’s queries distinguish them.
• Embedded languages. Injection queries can highlight fenced code inside Markdown, languages embedded in strings, and other nested syntax.
• Themeable capture classes. Captures become predictable ts-… CSS classes, with a bundled stylesheet that follows mdBook’s light, rust, coal, navy, and ayu themes. A highlight_ts.css in the theme directory replaces it, and a theme that only restyles highlight.js colours tree-sitter blocks to match.
• Side-by-side blocks. Label consecutive blocks with pane="…" to show them side by side under their labels, such as before and after a change, or the same idea in several languages.
• Language aliases and locals queries. Match several fence names to one grammar and opt into scope-aware query behavior where the grammar supports it.
• Selective processing. Leave individual blocks to mdBook when you need its built-in Rust Playground behavior or other native code-block features.
• Build-time rendering. Highlighted HTML is generated with the book; the reader does not need a tree-sitter runtime.
• Plays well with other preprocessors. Blocks are found exactly as mdBook finds them, and highlighted code stays out of reach of math preprocessors.

The documentation book is built with the preprocessor itself. Its examples include Macaulay2, a grammar outside nvim-treesitter’s list, and substantial side-by-side comparisons in Rust, Python, TypeScript, JavaScript, Go, Java, C, C++, Bash, PHP, Lua, and Haskell, and its book.toml is a complete configuration example.

Installation

Install the preprocessor from crates.io:

cargo install mdbook-tsitter

The mdbook-tsitter binary must be available on PATH when mdbook build runs. Grammars that are fetched rather than prebuilt also need git and a C compiler (cc, gcc, clang, or MSVC) on the build machine; see Grammar sources.

Quick start

List the languages to highlight in book.toml:

[preprocessor.tsitter]

[preprocessor.tsitter.languages]
rust = {}
python = {}
typescript = { aliases = ["ts"] }

The first build fetches and compiles each grammar; later builds reuse it. After that, ordinary fenced blocks for the configured languages are highlighted automatically:

```rust
fn main() {
    println!("highlighted at build time");
}
```

Build the book as usual:

mdbook build

Languages that are not configured, blocks without a language tag, and blocks that opt out are left untouched for mdBook to handle.