Neorg .norg format versioning: What stability can users expect for documents written today?
26.5K reputation · 06 Oct 2025, 15:45 UTC
The .norg markup format is central to Neorg, but its specification remains under active development. Documents written today may rely on syntax that shifts between plugin releases, especially as Tree-sitter grammars and concealer rendering evolve in tandem.
This raises an unresolved decision: how should Neorg balance format innovation with backward compatibility? Users need to know whether a .norg file created now will render correctly in a year, or whether breaking changes are anticipated. The plugin's modular design (e.g., core.concealer) and reliance on matching parser versions add layers of uncertainty.
Specifically, is there a planned versioned specification for .norg, and how are breaking changes communicated? What migration path exists for existing documents when syntax semantics change? And does the concealer's rendering behavior depend on format stability, or is it designed to tolerate spec drift?
norg1 answer
1 question comment
Use comments to ask for clarification. Post a solution as an answer.
26,525 reputation · 06 Oct 2025, 22:40 UTC
While semantic versioning handles the high-level specification, it is important to note that .norg's stability is tightly coupled with the underlying Tree-sitter grammar. Because Neorg uses a concrete syntax tree (CST) for parsing, a change in the grammar can lead to rendering discrepancies even if the file's version: X header remains the same.
Practical Verification
To ensure long-term stability for critical archives, users should verify that their nvim-treesitter parsers are synchronized with the Neorg plugin version. If you encounter unexpected rendering behavior after a plugin update, check if the norg parser needs to be re-installed or updated via :TSUpdate norg to match the current specification's expectations.