Grammar sources

From the built-in list

The preprocessor knows the repositories of the grammars nvim-treesitter supports, each pinned to the revision nvim-treesitter tests, and of a few grammars nvim-treesitter does not list, such as macaulay2, each pinned to a release. Use the language’s name there as its entry; - and _ are interchangeable (c-sharp or c_sharp). A mistyped name fails with a suggestion when a listed name is close.

Their queries are nvim-treesitter’s for the pinned revision, with the queries they inherit from other languages; they are tested against exactly that parser and are usually richer than a repository’s own. Where nvim-treesitter has none, or they do not match the parser, the repository’s own queries are used.

From a git repository

With git, the repository is shallow-fetched at rev and its parser (src/parser.c plus any external scanner) is compiled with the platform’s C compiler. A grammar that commits no generated parser is generated first, which needs the tree-sitter CLI and Node.js.

The repository’s tree-sitter.json locates the grammar and lists its queries, so location is rarely needed. Queries a grammar builds on from another grammar (TypeScript’s extend JavaScript’s) are fetched from that grammar’s repository, at the version the grammar’s package.json pins. Without a tree-sitter.json, queries are read from queries/ beside the grammar or at the repository root.

Checkouts and compiled parsers are cached per user, under mdbook-tsitter/ in the user cache directory ($XDG_CACHE_HOME or ~/.cache on Linux and macOS, %LOCALAPPDATA% on Windows), and shared between books. Network access is only needed the first time a revision is used.

A cached checkout is reused for as long as it exists, so an unpinned grammar stays at the commit first fetched. Pin rev to choose the version explicitly; changing it fetches the new revision. Deleting the cache directory refetches everything.

git may also be a path to a local repository, absolute or relative to the book root, such as a grammar you are developing. Its rev (by default HEAD) is resolved on every build, so new commits are picked up; uncommitted changes are not.

[preprocessor.tsitter.languages.mylang]
git = "../tree-sitter-mylang"

To use different queries, such as your own, set highlights (and optionally injections and locals) to query files in your book.

From a compiled parser (deprecated)

A language may still name a prebuilt parser shared library with library (and its constructor with symbol), with highlights pointing at its query. This is deprecated and prints a warning; see Upgrading from 2.x to replace it.