The .norg File Format: Plain-Text Notes Built for Neovim's Neorg

If you've opened a note inside Neovim and seen a file ending in .norg, you've met the native format of Neorg, a note-taking and organization plugin for Neovim. The useful takeaway: .norg is just structured plain text, so you can read, grep, diff, and version-control it like any source file — but its syntax is its own thing, not Markdown, and the tooling that fully understands it lives in the Neovim ecosystem.

What .norg actually is

Neorg ("Neovim Org") is a plugin that brings org-mode-style life organization — notes, tasks, agendas, journals — into Neovim. Rather than adopting Markdown or Emacs Org syntax wholesale, its authors designed a dedicated markup specification called norg. Files using it carry the .norg extension.

The design goal was a format that is unambiguous to parse. Markdown's many edge cases (is this a list item or an indented paragraph?) make tooling fragile; norg's spec tries to give every construct one clear meaning so parsers and future tooling behave consistently. That's an engineering trade-off worth understanding before you commit notes to it.

The syntax at a glance

Norg will feel familiar if you've used any lightweight markup, but the details differ. Common constructs include:

• Headings: leading asterisks, e.g. * Heading, ** Subheading.
• Lists: unordered items with -, ordered with ~ in the spec's convention.
• Tasks: list items with a status marker such as - ( ) pending task or - (x) done task.
• Links: curly-brace syntax, e.g. {https://example.com} or links to other norg files.
• Verbatim code: @code ... @end blocks for multi-line snippets.

Because the spec has evolved across versions, treat any single cheat sheet — including this one — as approximate. Check the norg specification in the Neorg project's repository for the version your plugin implements.

A worked example

Here is a small but realistic projects.norg file:

* Website rebuild
** Tasks
- (x) Pick a static site generator
- ( ) Write the landing page copy
- ( ) Set up CI deploys

** Notes
The deploy pipeline doc lives in {./deploy-notes.norg}.

@code bash
hugo build --minify
@end

Inside Neovim with Neorg installed, the task markers are interactive: keybindings cycle a task between pending, done, and other states, and the link to deploy-notes.norg is followable. Outside Neovim, the file is still perfectly readable — which is the point of a plain-text format.

The trade-off: ecosystem lock-in by design

The honest limitation is tooling depth. Markdown has renderers, linters, static-site generators, and editor support everywhere. Norg's first-class tooling is essentially Neorg itself. Converters exist in the ecosystem (for example, exporting norg to Markdown), but coverage of the full spec can lag, and you should verify round-trips before relying on them for archival purposes.

Practical implications:

• Your notes remain greppable and diffable forever — plain text is the safety net.
• Rich features (agendas, queries, task rollups) only work inside Neorg; if you stop using Neovim, you keep the text but lose the behavior.
• Sharing notes with non-Neovim collaborators means exporting, so test that export path early, not after a year of notes.

How to check your setup

If you want to try it: install Neorg via your Neovim plugin manager, then run :Neorg workspace notes (or your configured workspace) inside Neovim and create a file. Confirm the basics work: nvim projects.norg should trigger Neorg's filetype detection, task markers should toggle with the documented keybind, and :checkhealth neorg should report no missing dependencies. If filetype detection fails, the usual cause is the plugin not loading before the file opens — check your plugin manager's lazy-loading rules.

The decision, in the end, is simple: if you live in Neovim and want structured notes with task tracking, norg is a coherent, well-specified choice. If you need your notes to render everywhere with zero friction, Markdown's ecosystem is still hard to beat — and norg's plain-text nature means migrating later is a parsing problem, not a data-loss problem.