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
Experimental: review, pomodoro, drill, merge, cli, diagrams,
              code, literate, lsp, transclusion, timeline,
              heatmap

Bug reports about experimental extensions are just as welcome.

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
  teardown   function(), undoes setup when a later setup() turns
               the extension off or sets it up again