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:
| stable | used daily and well covered by specs; its options, actions and keys only change with a note in the release notes |
| experimental | works 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:
defaults | option 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 |
mappings | default keys by section: { global = { name = lhs } } |
groups | which-key labels for key groups under mappings.prefix: { { "m", "roam" } } |
setup | function(opts), called after the above are registered |
health | function(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 |
teardown | function(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 |