Neorg: structured note taking inside Neovim, built on the .norg format

The problem Neorg solves, and for whom

Most note tools make you choose between a format you can read in any editor and features that only exist inside one application. Neorg takes the other route: every feature is built on a single base file format, `.norg`, which the user has to learn once. The README states the premise directly, that all features sit on top of that one format, so task management, time tracking and document writing share the same underlying syntax rather than each inventing its own markup.

The audience is narrow and specific. You need Neovim 0.10 or above, and you need to be comfortable with Lua configuration, because Neorg is a plugin, not a standalone program. The README also points at a kickstart config for people who do not want to assemble a Neovim setup themselves, which is the closest thing to an on-ramp for a newcomer. If you write in a graphical editor and never open a terminal, this is not aimed at you.

The interesting part is the portability claim. Because `.norg` is plaintext and the README describes the format as easy to parse, the files are meant to be usable outside Neorg itself. That is a real design commitment: the value lives in the files, not in a database the plugin owns.

How the .norg format and the module system fit together

Neorg is written in Lua, and the repository layout reflects a modular design: a `lua/` directory for the implementation, `queries/` for tree-sitter queries, `doc/` and `docs/` for generated documentation, and a `docgen/` directory with its own `minimal_init.vim` and `init.lua` used to build that documentation. The Makefile exposes this as `make documentation`, which runs Neovim headless against the docgen init file.

Parsing is where tree-sitter enters. The README's rocks.nvim instructions require `nvim-treesitter` and a separate `nvim-treesitter-legacy-api` rock, and the note in that section says those steps will eventually not be required. In other words, the current dependency list is a transitional state, and the README is explicit that it is temporary rather than a permanent architectural choice.

The data flow is straightforward: `.norg` files on disk are parsed into a syntax tree, and Neovim's highlighting plus Neorg's own modules operate on that tree. The `queries/` directory holds the tree-sitter queries that drive highlighting. Everything else, from task states to document export, is a module layered on the same parse. That is why the project can claim integration between features without glue code between separate tools.

Installing Neorg with rocks.nvim or lazy.nvim

The README is honest that setup is more complex than the average plugin, and it asks for patience. Two paths are documented. With rocks.nvim, you install two rocks and create two small Lua files. First install the config helper and Neorg itself, then add the setup call.

:Rocks install rocks-config.nvim
:Rocks install neorg

From the root of your configuration, which the README gives as `~/.config/nvim/` on unix-like systems, create `lua/plugins/neorg.lua` containing the setup call.

require("neorg").setup()

Until a new luarocks release lands, the README says you also need `nvim-treesitter`: install `nvim-treesitter-legacy-api`, then create `lua/plugins/treesitter.lua` with the config below. The README notes these last steps will eventually not be required.

require("nvim-treesitter.configs").setup({
  highlight = {
    enable = true,
  },
})

With lazy.nvim the prerequisite is `luarocks` on your system, installed through your package manager on Linux and Mac. The README's snippet pins the stable release and disables lazy loading.

{
    "nvim-neorg/neorg",
    lazy = false, -- Disable lazy loading as some `lazy.nvim` distributions set `lazy = true` by default
    version = "*", -- Pin Neorg to the latest stable release
    config = true,
}

After installation, the README's instruction is to run `:checkhealth neorg` and confirm everything is correct. That command is the first thing to run when something looks wrong, and the README names disabling lazy loading as the first debugging step if the plugin loads incorrectly.

Where Neorg breaks or simply is not the right tool

The README carries its own warning: Neorg is young software, considered stable, but users should be prepared for occasional breaking workflow changes and should pin the version they want. That is not marketing hedging, it is a maintenance instruction. Version 9.0.0 introduced breaking changes, and the README links to a blog post describing what changed. If you follow a rolling branch instead of a release tag, you are opting into that churn.

The plugin-manager situation is a second constraint. The README states that because of the complexities of luarocks, other plugin managers are not supported for the time being, though it is on the TODO list. Packer is documented but the README says it is not recommended because it is unmaintained. So the realistic choices are rocks.nvim and lazy.nvim with a system luarocks, plus packer if you accept an unmaintained manager.

Lazy loading is a third failure mode with a clear cause. The README notes that loading Neorg on specific commands or filetypes can cause it to load incorrectly and produce a broken plugin, which is why the lazy snippet sets `lazy = false`. Finally, the scope boundary: Neorg is a Neovim plugin. If you want a browser or mobile client, or WYSIWYG editing with a mouse, the README describes nothing of the sort, and none of the installation paths lead there.

Neorg compared with Emacs Org mode, Obsidian and Vimwiki

The obvious comparison is Emacs Org mode, and the difference is architectural rather than cosmetic. Org mode is a major mode inside Emacs, written in Emacs Lisp, with decades of accumulated extensions. Neorg is a Neovim plugin written in Lua, built on tree-sitter parsing of a separate `.norg` format. The README frames Neorg as reimagining organization rather than reimplementing Org, and the format is its own thing, not an Org parser. If your existing notes are `.org` files, nothing in the README claims they will open as `.norg`.

Against Obsidian, the split is local versus application-bound. Obsidian is a graphical application with its own vault model; Neorg is a plugin that operates on plaintext files inside your editor. The README's emphasis that `.norg` files are usable outside Neorg is the counterweight to Obsidian's ecosystem. The cost is that you give up the graphical interface entirely.

Against Vimwiki, the difference is the parser and the feature base. Vimwiki is Vimscript-era tooling with its own wiki syntax; Neorg uses tree-sitter queries in `queries/` and a module system in `lua/`, and requires Neovim 0.10 or above rather than working across Vim and Neovim. The README's requirement of a modern Neovim is a hard line, not a preference.

Maintenance, releases and the GPL-3.0 licence

The last push to the repository was on 2026-08-14, and the most recent release listed is v9.6.4 from 2026-04-09, preceded by v9.6.2 and v9.6.1 on 2026-04-09. Releases and commits are therefore not in lockstep: the branch moves between tagged versions, which is exactly why the README tells you to pin a version and update when you are ready.

Upgrade cost is dominated by the 9.0.0 breaking changes and by the transitional tree-sitter dependency. The README says the extra `nvim-treesitter-legacy-api` step will eventually be removed, so the install procedure you follow today may not match the one documented after the next luarocks release. Budget for re-reading the installation section after a major bump rather than assuming the snippet you copied still applies.

Neorg is licensed GPL-3.0, and the LICENSE file sits at the repository root. That is a copyleft licence, which matters if you plan to redistribute a modified version or bundle the plugin into something you ship. The README does not discuss licence implications for downstream users, so treat this as a flag to check with whoever handles licensing on your side rather than as settled guidance.

Editorial conclusion

Adopt Neorg if you already live in Neovim, are willing to install luarocks, and want notes, tasks and documents on one text format you can parse yourself. Skip it if you need a graphical outliner, a mobile client, or an editor you can configure without Lua. Verify two things before committing: that your Neovim is 0.10 or above, and that :checkhealth neorg reports a clean setup after your chosen plugin manager has pulled the rocks dependencies. Then pin a release tag and read the 9.0.0 breaking-change post before your first update.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. nvim-neorg/neorg on GitHub
4. README
5. Releases