org.nvim

Extensions

Extensions are optional features modelled on popular third-party Emacs Org packages. They ship with org.nvim but nothing is loaded until you list one in extensions:

require("org").setup({
  extensions = {
    roam = { directory = "~/roam" }, -- options merged over its defaults
    present = true,                  -- enable with the defaults
    ics = false,                     -- off (same as leaving it out)
  },
})

false or { enabled = false } keeps an extension off. An extension's resolved options are in require("org.config").opts.extensions.<name>, and require("org.extensions").enabled(name) tells whether it is on.

An enabled extension can add actions (usable in mappings and :Org), :Org subcommands and default keys. A default key never replaces one you set; set it to false in mappings to remove it. :checkhealth org lists the enabled extensions and checks what each needs.

Stability

Each extension is marked as one of:

stableused daily and well covered by specs; its options, actions and keys only change with a note in the release notes
experimentalworks and is tested, but has seen less real use, so it is prone to change: its options, commands, keys and output (such as the JSON of org-extensions-cli) can change in any release. Read the release notes before you upgrade if a config or a script relies on one.
Stable:ql, super_agenda, present, roam, quickadd, ics, kanban, sidebar, merge, transclusion, heatmap
Experimental:review, pomodoro, drill, cli, diagrams, code, literate, lsp, timeline, hugo, journal, src_lsp, caldav

Bug reports about experimental extensions are just as welcome.

An experimental extension becomes stable once it meets measurable criteria (specs and line coverage, an edge-case spec, every option documented, a health check, a few minor releases and a month since it was added, a few minor releases without a breaking change to its options, no open bug reports), checked at every release; the release notes say when one is promoted. :checkhealth org shows the stability of each enabled extension. The criteria are in CONTRIBUTING.md ("Promoting an extension").

Writing an extension

An extension is a module lua/org/extensions/<name>.lua (or <name>/init.lua) returning a table with any of these fields:

defaultsoption defaults; the user's table is merged over them
actions{ name = { module, fn, desc = ... } }, as in org.actions
commands:Org subcommands taking arguments, as in org.commands
mappingsdefault keys by section: { global = { name = lhs } }
groupswhich-key labels for key groups under mappings.prefix: { { "m", "roam" } }
setupfunction(opts), called after the above are registered
healthfunction(h, opts), adds checks to :checkhealth org (org-health) under the extension's name: h is vim.health. Keep it fast and quiet: look for programs with executable(), stat paths, bound any file scan; no network, no prompts, no slow commands
teardownfunction(again), undoes setup when a later setup() turns the extension off or sets it up again (again is true then); require("org.extensions").opts(name) still gives the options it was set up with
stability"stable" or "experimental", as above. A built-in extension without it is experimental; :checkhealth org shows it for a third-party extension that sets it