rehype-tree-sitter

rehype plugin to use tree-sitter to highlight code in

 blocks


Contents

What is this?
When should I use this?
Install
Use
API

unified().use(rehypeTreeSitter[, options])
 
Types
Compatibility
Security
Contribute
License


What is this?
This package is a unified (rehype) plugin to highlight code within a hast document. This plugin scans the source node tree for a 
 element pair that contains a language-{} attribute, and runs the tree-sitter highlight code. This produces a list of annotated spans that can be customized with css.

unified is a project that transforms content with abstract syntax trees (ASTs). rehype adds support for HTML to unified. hast is the HTML AST that rehype uses. This is a rehype plugin that highlights code using tree-sitter.

When should I use this?
This plugin is useful when you want a more sophisticated highlighting experience than what TextMate grammars provide.
This plugin is built on hastscript, which does the work on syntax trees. rehype focusses on making it easier to transform content by abstracting such internals away.

Install
This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

npm install rehype-tree-sitter


Use

TODO

API
This package exports no identifiers. The default export is rehypeTreeSitter.

unified().use(rehypeTreeSitter[, options])
Highlight the code within the tree. This works by transforming the text within the code block into annotated  elements. The span elements will have their class list as the highlight name stack from tree-sitter.

options
Configuration.

options.treeSitterGrammarRoot
This option is REQUIRED. This is the source folder path on your file system where tree-sitter will look for grammar source repositories. Without this variable set, the plugin will throw an error asking you to set it.

options.scopeMap
This option is a mapping of language-{} to tree-sitter scope (source.js, scope.xml, scope.sh). There is a default mapping included that supports a couple languages, but if you are using a custom grammar, it's required that you place the mapping between language identifier (usually found in the code block attributes) and the scope.
This option is OPTIONAL. This is the source folder path on your file system where tree-sitter will look for grammar source repositories. Without this variable set, the plugin will throw an error asking you to set it.

Compatibility
Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+.

Security
This plugin compiles and executes Rust code. In the Rust code, an underlying dependency (tree-sitter) will attempt to read tree-sitter grammar source repositories and compile and execute them. Please take care with your tree-sitter grammar repositories, and audit them to make sure the code is safe to run. Other than that, the plugin is safe.

License
BSD-2-Clause © Haze Booth