Installation

Requires Neovim 0.11 or later. Optional tools:

  pandoc               DOCX, EPUB, RST, ... export
  LibreOffice          ODT conversion (export.odt.preferred_output_format)
  unzip                ODT styles taken from an .odt/.ott file
  latexmk / pdflatex   native PDF export
  makeinfo             Info export (Texinfo files need nothing)
  interpreters         whatever languages Babel should run

lazy.nvim / LazyVim:

{
  "xheisenbugx/org.nvim",       -- or: dir = "~/path/to/checkout", name = "org.nvim"
  main = "org",
  lazy = false,
  opts = {
    org_directory = "~/org",
    agenda_files = { "~/org/**/*.org" },
    default_notes_file = "~/org/refile.org",
  },
}

Other plugin managers: add the plugin to 'runtimepath' and call:

require("org").setup({ ... })

Option defaults follow Emacs Org 9.8 (see org-config): with no agenda_files the agenda and refile see only the current file until you add some (<C-c>[ adds the current file), todo_keywords is TODO | DONE, nothing is logged on DONE and files open fully expanded. A common starting point closer to many Emacs setups:

require("org").setup({
  agenda_files = { "~/org" },
  default_notes_file = "~/org/refile.org",
  todo_keywords = { "TODO(t) NEXT(n) | DONE(d)" },
  log_done = "time",
  log_into_drawer = true,
  startup_folded = "overview",
})

If setup() is never called, the defaults are used the first time an org buffer is opened or :Org is run.

:Org version shows the org.nvim release, its git version and where it is installed (org-version); with a count it inserts that at the cursor. The release is the latest vX.Y.Z git tag of the checkout, or "unreleased" when there is none (or org.nvim isn't a git checkout).

Run :checkhealth org to check paths and external tools, and to list
options given to setup() that org.nvim doesn't know (typos, or action names
in mappings that don't exist). Inside tmux,
Ghostty, kitty, WezTerm or Alacritty it also checks that the terminal can
send the keys org maps:
- <C-CR>, <S-CR>, <C-,> and the like need extended keys (CSI u), which tmux
  passes on only with set -s extended-keys on and a terminal-features
  entry with extkeys for the outer terminal (read when a client attaches)
- the terminal's keybinds must not take a mapped key: Ghostty's ctrl+tab,
  kitty's ctrl+shift+enter and ctrl+shift+arrows, WezTerm's ALT+Enter
  and CTRL+SHIFT+arrows, ... (read from the terminal itself when its CLI
  is installed, else from its config file and the known defaults)
- on macOS, Option must send Alt for the <M-...> keys
Inside tmux the terminal is the one of the attached client.

Windows

org.nvim runs on Windows as on Linux and macOS; the test suite runs on Windows in CI. Paths may use \ or /, a drive (C:\notes) or a UNC share (\\server\share); org.nvim works with / internally and writes files with LF line endings. ~ is $HOME when set, else %USERPROFILE%. What differs:

• Desktop notifications (org-notifications, pomodoro) are toasts shown through powershell.exe (Windows PowerShell, part of Windows); their sender is "Windows PowerShell".
• yank_media reads images and files copied or cut in Explorer from the clipboard through powershell.exe.
• The org command line is bin\org.cmd, and :Org cli_install writes an org.cmd launcher into its directory (symlinks need administrator rights). The git merge driver is bin\org-merge.cmd.
• The ics extension converts time zones with a bundled table of each zone's current rule, as Windows has no zoneinfo files: times far in the past may use today's rule of a zone that changed since.
• TZ with a zone name ("Europe/Berlin") has no effect: the Windows C library only takes the old "EST5EDT" form. org.nvim uses the system's time zone.
• :tangle-mode and :shebang can't make a file executable: Windows has no Unix file modes.
• org-crypt needs GnuPG for Windows (or Gpg4win) on %PATH%. The gpg of Git for Windows can't ask for passphrases outside its own terminal; a call that hangs is stopped after a minute.
• Babel runs sh/bash blocks with the sh or bash on %PATH% (Git for Windows, MSYS2, WSL's bash.exe), like Emacs.