Migrating from nvim-orgmode

nvim-orgmode (https://github.com/nvim-orgmode/orgmode) and org.nvim read and write the same Org files, so your notes need no change. What changes is the plugin, its options and some keys. This chapter maps them, and :Org migrate_config converts a setup for you.

Swapping the plugin

Remove nvim-orgmode and add org.nvim. Don't keep both: they both define the org filetype and the :Org command. With lazy.nvim:

-- before
{
  "nvim-orgmode/orgmode",
  event = "VeryLazy",
  config = function()
    require("orgmode").setup({ org_agenda_files = "~/orgfiles/**/*" })
  end,
}
-- after
{
  "xheisenbugx/org.nvim",
  main = "org",
  lazy = false,
  opts = { agenda_files = { "~/orgfiles/**/*" } },
}

Other plugin managers: see org-installation. Then:

• Completion: the nvim-cmp and blink.cmp source of nvim-orgmode is orgmode; org.nvim's is org (modules org.completion.cmp and org.completion.blink, see org-completion). Omni completion (<C-x><C-o>) works as before.
• Tree-sitter: org.nvim parses and highlights Org itself and doesn't use the org tree-sitter parser of nvim-orgmode. If you added org to nvim-treesitter's ensure_installed or its highlighting, take it out so it doesn't take over the highlighting of org buffers.
• Run :checkhealth org afterwards: it lists the options it doesn't know.

Converting a setup

The file can call require("orgmode").setup({ ... }), return a lazy.nvim spec for nvim-orgmode (its opts, a table or a function, and its config function), or return the options table itself. It is run as Lua to get the options, in a sandbox: other requires get an inert stand-in, and the keymaps, autocommands, user commands, highlights and option changes it makes are ignored, so converting your whole plugin spec does no harm.

The result has:

• every option converted: renamed, or rewritten where the format differs (TODO keywords, capture templates, custom agenda commands, the time grid, windows, notifications, mappings);
• -- TODO: comments above what needs a look: a key that is also org.nvim's default for another action, a template field or block option with no equivalent, a function copied from your config whose arguments differ;
• the options with no equivalent, each with a TODO saying why and its value commented out;
• commented out at the end, nvim-orgmode's defaults that differ from org.nvim's (indentation, folding, logging, the tag column, keys): uncomment the ones whose behaviour you want to keep.

Functions in your options (a custom notifier, a capture headline function) are copied from the file when they are written in place as function(...) ... end; otherwise a TODO says where they are.

Options

nvim-orgmode options and their org.nvim names (org-config):

Defaults that differ (nvim-orgmode / org.nvim, which follows Emacs):

:Org migrate_config offers nvim-orgmode's values, commented out.

Capture templates

The fields description, template (a string or a list of lines), target, headline (a string or a function), prepend and regexp are the same (org-capture-templates). The others:

In the template text:

• %(return EXPR) (a Lua function body) is %(EXPR) (an expression, or Emacs Lisp: %(format-time-string "%Y")).
• %n is your full name (Emacs's user-full-name), not $USER; use %(os.getenv("USER")) for the old value.
• A relative target is relative to org_directory ("~/org").
• %<...> date formats in a target aren't expanded: make the target a function, target = function() return os.date("~/org/%Y-%m.org") end (:Org migrate_config writes one).
• org.nvim knows more fields: olp, id, type = "item", clock_in, immediate_finish, ... (org-capture-templates).

With no templates at all, org.nvim uses Emacs's default t template, which files tasks under a "Tasks" headline of default_notes_file.

Custom agenda commands and agenda files

org_agenda_custom_commands keeps its shape: a description and a list of blocks in types, each with a type ("agenda", "tags", "tags_todo") and a match. org.nvim accepts the org_agenda_* names in blocks, but its own are shorter (org-agenda-custom-commands):

In a tags_todo block, org.nvim (like Emacs) applies the todo_ignore_* options only with tags_todo_honor_ignore_options = true in the block; the converter adds it. Blocks may also be todo, search and stuck, and a command's settings apply to all its blocks.

Agenda files: "~/org/**/*" works as it is (only .org and .org_archive files are read). A directory without a glob adds its *.org files, not recursively, as in Emacs.

Keys

<prefix> is mappings.prefix, <Leader>o in both. Keys are set by action name under the same sections, mappings.org.<action>, mappings.agenda.<action>, ... (org-keymaps). A list of keys works; nvim-orgmode's desc doesn't (org.nvim names keys after their action). org.nvim also binds Emacs's keys (<C-c><C-t>, <C-c><C-s>, ...; org-emacs-keys).

Org buffers (nvim-orgmode mapping, key: org.nvim action, key):

Keys that do something else in org.nvim: <prefix>id inserts a drawer, <prefix>is a subheading, <prefix>A attaches a file, and }, { are Vim's paragraph motions again. <prefix>d sets the deadline: mapping <prefix>d! as well makes Vim wait 'timeoutlen' after <prefix>d.

Agenda (mappings.agenda):

In the agenda, K captures, J goes to the clocked task and R refiles.

Capture, note and edit buffers:

Text objects ih, ah, ir and ar are the same (mappings.text_objects); the ones from the root heading (Oh, OH, Or, OR) have no equivalent.

Other differences

• org.nvim follows Emacs Org 9.8: options carry Emacs's defaults and names (without the org_ prefix), and most Emacs options exist (org-config). :Org customize lists them all.
• Export is built in: HTML, LaTeX/PDF, Beamer, Markdown, ASCII, ODT, iCalendar and Texinfo run without Emacs; pandoc adds DOCX, EPUB, ... (org-export).
• Reminders (notifications.enabled) run inside Neovim; there is no cron mode. Plain timestamps with a time get reminders too.
• Log notes open a small *Org Note* window: <C-c><C-c> stores the note, <C-c><C-k> cancels it.
• <CR> on a link opens it; in Insert mode, <CR> in a table moves to the next row.
• Menus (the agenda dispatcher, capture, export) are org.nvim's own key menus, which Esc closes (org-key-menus).