tree-sitter-markdown

tree-sitter-markdown is a Markdown parser for the tree-sitter ecosystem. It is designed to follow the CommonMark specification, with support for various extensions like GitHub Flavored Markdown (GFM).

Important Note on Correctness: This parser is primarily intended for providing syntactical information for syntax highlighting in editors (such as Neovim and Helix). Because Markdown is a complex format to map to tree-sitter's restrictive parsing rules, it is not recommended for use in applications where absolute parsing correctness is critical.

To use the two grammars (block and inline) together in a standalone implementation, follow this two-step process:

1. Block Parse: First, parse the document using the block grammar.
2. Inline Parse: Perform a second parse using the inline grammar. Use ts_parser_set_included_ranges to specify the segments that constitute inline content.

Note on Ranges: The segments passed to ts_parser_set_included_ranges should be the parts marked as inline nodes from the first parse. You must exclude the children of those inline nodes from the specified ranges.

For a reference implementation, see lib.rs in the bindings folder of the repository.

The parser does not work out-of-the-box with WASM/web-tree-sitter because it relies on certain C functions that are not exported by tree-sitter by default.

To use this parser in a WASM environment, you must statically link the parser to tree-sitter.

The tree-sitter-markdown Node.js binding provides access to the Markdown parser and its associated query files. The default export is a binding object that includes the parser and several query strings used for syntax highlighting and injections.

Note that query properties (like HIGHLIGHTS_QUERY) are lazily loaded from the filesystem via getters when first accessed.

import parser from 'tree-sitter-markdown';

// The parser is available on the default export
// Queries are loaded lazily upon access
const highlights = parser.HIGHLIGHTS_QUERY;
const injections = parser.INJECTIONS_QUERY;

The binding may include a nodeTypeInfo property, which contains metadata about the node types defined in the grammar. This is loaded from src/node-types.json within the package.

import parser from 'tree-sitter-markdown';

if (parser.nodeTypeInfo) {
  console.log('Available node types:', parser.nodeTypeInfo);
}

The bindings/node/inline.js file provides access to the inline property of the main tree-sitter-markdown package. This is used to interact specifically with the inline grammar components of the Markdown parser in a Node.js environment.

const inlineParser = require('tree-sitter-markdown/bindings/node/inline');

The binding object exposes several query strings as properties. These are read from .scm files in the repository and are useful for syntax highlighting, injections, and local scope analysis.

Available query properties:

• HIGHLIGHTS_QUERY: Syntax highlighting queries.
• INJECTIONS_QUERY: Injection queries for embedding other languages.
• LOCALS_QUERY: Queries for local scope information.
• TAGS_QUERY: Queries for tag-related information.

// Example of accessing available queries
console.log(parser.HIGHLIGHTS_QUERY);
console.log(parser.INJECTIONS_QUERY);
console.log(parser.LOCALS_QUERY);
console.log(parser.TAGS_QUERY);