Neorg and Neovim Tree-sitter Runtime: Parser ABI Compatibility

Integration Boundary

Neorg relies on a dedicated Tree-sitter grammar to enable core functionality such as syntax highlighting, folding, and concealing. This requires the norg parser to be compiled and registered with the Neovim built-in Tree-sitter runtime.

Compatibility Constraints

Because Neovim bundles a specific version of the Tree-sitter library, the parser ABI must match the runtime version. Discrepancies between the grammar revision provided by nvim-treesitter and the Neovim core version can lead to loading failures or degraded rendering where highlights simply disappear without explicit error messages.

Since Neorg does not pin a specific grammar revision, there is uncertainty regarding which parser commit is guaranteed to be compatible with a given Neovim release.

• How can a user deterministically identify the compatible norg parser revision for their specific Neovim version?
• Is there a mechanism to verify if a rendering failure is caused by a Tree-sitter ABI mismatch versus a configuration issue in Neorg's internal modules?