tree-sitter-markdown

tree-sitter-markdown

A Markdown parser for tree-sitter.

The parser is designed to read markdown according to the CommonMark Spec, but some extensions to the spec from different sources such as Github flavored markdown are also included. These can be toggled on or off at compile time. For specifics see Extensions

Goals

Even though this parser has existed for some while and obvious issues are mostly solved, there are still lots of inaccuarcies in the output. These stem from restricting a complex format such as markdown to the quite restricting tree-sitter parsing rules.

As such it is not recommended to use this parser where correctness is important. The main goal for this parser is to provide syntactical information for syntax highlighting in parsers such as neovim and helix.

Contributing

All contributions are welcome. For details refer to CONTRIBUTING.md.

Extensions

Extensions can be enabled at compile time through environment variables. Some of them are on by default, these can be disabled with the environment variable NO_DEFAULT_EXTENSIONS.

Name	Environment variable	Specification	Default	Also enables
Github flavored markdown	EXTENSION_GFM	link	✓	Task lists, strikethrough, pipe tables
Task lists	EXTENSION_TASK_LIST	link	✓
Strikethrough	EXTENSION_STRIKETHROUGH	link	✓
Pipe tables	EXTENSION_PIPE_TABLE	link	✓
YAML metadata	EXTENSION_MINUS_METADATA	link	✓
TOML metadata	EXTENSION_PLUS_METADATA	link	✓
Tags	EXTENSION_TAGS	link
Wiki Link	EXTENSION_WIKI_LINK	link

Usage in Editors

For guides on how to use this parser in a specific editor, refer to that editor's specific documentation, e.g.

• neovim
• helix

Standalone usage

To use the two grammars, first parse the document with the block grammar. Then perform a second parse with the inline grammar using ts_parser_set_included_ranges to specify which parts are inline content. These parts are marked as inline nodes. Children of those inline nodes should be excluded from these ranges. For an example implementation see lib.rs in the bindings folder.

Usage with WASM

Unfortunately using this parser with WASM/web-tree-sitter does not work out of the box at the moment. This is because the parser uses some C functions that are not exported by tree-sitter by default. To fix this you can statically link the parser to tree-sitter. See also https://github.com/tree-sitter/tree-sitter/issues/949, https://github.com/MDeiml/tree-sitter-markdown/issues/126, and https://github.com/MDeiml/tree-sitter-markdown/issues/93