Does Neorg's concealer depend on a specific Tree-sitter parser version to render .norg files correctly?

Question

I'm setting up Neorg for personal notes and task tracking in Neovim, and I want to understand the relationship between the plugin's concealer module and the Tree-sitter norg parser installed through nvim-treesitter.

My understanding is that syntax highlighting, folding, and the concealer's styled rendering of markup all derive from the Tree-sitter parse tree rather than from regex-based rules. If that's true, then the parser and the plugin presumably need to stay in sync: a grammar update could rename or restructure nodes that the concealer queries, and an older parser with a newer plugin (or vice versa) might silently degrade rendering instead of failing loudly.

What I'm unsure about is how tight that coupling actually is in practice, and how version drift is supposed to be detected. The Norg format specification also hasn't been declared fully stable, which makes me wonder whether parser revisions track spec revisions directly or lag behind them.

So, concretely:

Does the concealer query Tree-sitter captures directly, making it sensitive to parser version, or does it use a more stable abstraction layer?
Is there a documented compatibility matrix or health check that reports a parser/plugin mismatch?
When the spec changes, which component is expected to move first—the grammar or the plugin?

Tasadduq Burney · Answer

Answer
Yes – Neorg’s concealer module renders markup by evaluating Tree‑sitter capture queries against the parse tree produced by the norg parser. Because the queries are tied to specific node names, a change in the parser’s grammar can break or silently degrade the concealer’s output.
Confirmed facts

The concealer does not use its own regex‑based highlighting; it reads captures defined in queries/norg/*.scm that are shipped with the plugin.
Neovim’s :checkhealth neorg reports whether the norg (and related) parsers are installed and accessible, but it does not compare query‑node names to the actual grammar.
When the parser renames or restructures nodes (e.g., heading levels, todo markers, fenced‑code blocks), the concealer’s queries stop matching, which appears as missing icons, unstyled code blocks, or broken folding rather than an explicit error.

Likely explanation of version drift
Neorg’s own query files are updated in lock‑step with the plugin releases. If you upgrade Neorg without also updating the norg parser (via :TSUpdate norg or your plugin manager), the queries may expect node names that no longer exist, leading to the silent degradation described above. Conversely, a newer parser paired with an older Neorg version can produce extra nodes that the old queries ignore, which is usually harmless but can hide upcoming incompatibilities.
Practical steps to verify alignment

Run :checkhealth neorg and confirm that the norg parser is reported as installed.
Run :TSInstallInfo to see the exact version/revision of the installed norg parser.
Open a sample .norg file and execute :InspectTree. Note the node names for headings, todo items, and fenced code blocks.
Compare those names with the capture patterns in Neorg’s query files (queries/norg/highlights.scm, queries/norg/indents.scm, etc.) located in your plugin directory.
If any expected capture is missing from the tree, the concealer will not render the corresponding markup.

What to do if you suspect a mismatch
If the health check shows the parser is present but you still see missing icons or unstyled blocks, please share the output of :TSInstallInfo norg (or the parser’s revision hash) so we can confirm whether the parser version matches the Neorg release you are running.

Does Neorg's concealer depend on a specific Tree-sitter parser version to render .norg files correctly?

1 answer

Answer

Confirmed facts

Likely explanation of version drift

Practical steps to verify alignment

What to do if you suspect a mismatch

Your perspective belongs here.

0 question comments