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",
},
}
Without lazy.nvim, any plugin manager works: org.nvim has no build step and no dependencies. Point it at xheisenbugx/org.nvim and call require("org").setup({ ... }).
Coming from nvim-orgmode? org-migrate maps its options and keys to org.nvim's, and :Org migrate_config converts your setup.
Neovim 0.12+ built-in manager (vim.pack), in init.lua:
vim.pack.add({ "https://github.com/xheisenbugx/org.nvim" })
require("org").setup({ ... })
rocks.nvim (LuaRocks): each release is published to luarocks.org as org.nvim:
:Rocks install org.nvim
Then call require("org").setup({ ... }). The rock doesn't include the org and org-merge command line scripts (bin/); use a git checkout for those.
No plugin manager (packages): clone the repository into a start directory, which Neovim loads at startup:
# Linux / macOS
git clone https://github.com/xheisenbugx/org.nvim \
~/.local/share/nvim/site/pack/plugins/start/org.nvim
# Windows (PowerShell)
git clone https://github.com/xheisenbugx/org.nvim `
"$env:LOCALAPPDATA\nvim-data\site\pack\plugins\start\org.nvim"
The directory is stdpath("data")/site/pack/*/start/. Call require("org").setup({ ... }) in init.lua and run :helptags ALL once so this manual is found. Update with git pull in that directory.
- A package under
pack/*/opt/is only loaded by :packadd: callvim.cmd.packadd("org.nvim")beforerequire("org"), orrequirefails with "module 'org' not found". - A zip from GitHub unpacks into an extra folder (
org.nvim-main/org.nvim-main/...);lua/,plugin/anddoc/must sit directly inside.../start/org.nvim/. :checkhealth orgruns once the plugin is found.
Option defaults follow Emacs Org 9.8 (see org-config): with no agenda_files the agenda reads no file and refile sees only the current file until you add some (<C-c>[ adds the current file; see org-faq-agenda), 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).
Health check
Run :checkhealth org to check the installation, the options and the external tools. It never prompts and starts no slow programs (no Emacs, no network), so it is quick to run. Its sections:
org.nvim
- the Neovim version (0.11 or later), the org.nvim release and where it is installed
- that
*.orgfiles get theorgfiletype (a vim.filetype.add() in your config could change that) - other plugins that also act on org buffers: nvim-orgmode (a warning: remove one of the two, and convert its setup with
:Org migrate_config, org-migrate) and headlines.nvim; and ftplugin, syntax or indent files for the org filetype from other plugins (a warning) or your own config (shown, not a warning). Neovim's ownorg.vimfiles are ignored.
org.nvim configuration
- options given to setup() that org.nvim doesn't know (typos, removed options, action names in
mappingsthat don't exist), the options of the built-in extensions included (extensions.roam.directry); a third-party extension's options aren't checked - column view options in a block of a composite custom command (org-agenda-command-columns)
- the TODO keywords, or why
todo_keywordsis invalid
org.nvim files
org_directoryexists- how many agenda files
agenda_filesgives, and for each entry that gives none why: no such file, not an .org file, a directory without .org files (directories aren't searched recursively), a glob that matches nothing; whenagenda_filesnames a list file, that file and its entry count. Agenda files that can't be read are an error. - the agenda index (org-agenda-index)
default_notes_fileexists and is writable (else it is created on the first capture)default_notes_fileis insideorg_directory: a warning otherwise, as captures without a target then land outside your notes. Its default,~/.notes(as in Emacs), is a hidden file in your home directory, whileorg_directorydefaults to~/org; set it to a file there, for exampledefault_notes_file = "~/org/refile.org"(org-capture)mobile.directory, when set, exists (org-mobile)- the session server, with
remote.enabled(org-remote)
org.nvim state files
- the ID database (
id.locations_file, org-id): its format, size and the IDs and files it lists, and a warning when files it lists no longer exist (:Org id_update_locationsrebuilds it). At most 2000 files are looked at. - the persisted clock (
clock.persist,clock.persist_file): off, not written yet, the clock it saved, or a file that isn't valid JSON
org.nvim picker
- the picker the pick_* actions use (org-pickers), and the installed ones (snacks.nvim, fzf-lua, telescope.nvim, mini.pick). A
pickerthat isn't installed or isn't a picker name is a warning: vim.ui.select is used.
org.nvim external tools
- pandoc, makeinfo and the LaTeX compiler for export
- the document viewer
docview:FILE::PAGElinks open a page with (links.docview_command): a warning only when the option names a program that isn't installed - the interpreter of each Babel language (org-babel-languages)
- the desktop notifier of reminders
- gpg (
crypt.gpg_program) for org-crypt: a warning only withcrypt.encrypt_on_save, as entries would then be saved unencrypted; openssl withmobile.use_encryption
org.nvim image and LaTeX previews
- the image backend, the terminal and what sits between them (tmux, zellij, SSH), the LaTeX preview programs and ImageMagick (org-images-troubleshooting)
org.nvim completion
- whether blink.cmp or nvim-cmp is set up with the org source (org-completion)
org.nvim terminal keys
Inside tmux, Ghostty, kitty, WezTerm or Alacritty it 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 onand aterminal-featuresentry withextkeysfor the outer terminal (read when a client attaches) - the terminal's keybinds must not take a mapped key: Ghostty's
ctrl+tab, kitty'sctrl+shift+enterandctrl+shift+arrows, WezTerm'sALT+EnterandCTRL+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.
org.nvim extensions
- each enabled extension, its stability (org-extensions-stability) and the checks of its own
healthfunction (org-extensions): the external programs it needs, its paths and options it can't use (pomodoro's durations, transclusion'smode, super_agenda'sgroups, ...) - an extension enabled in setup() that isn't loaded (a misspelt name, a module that is shared code such as
views_util, or an error in its module) is an error
org.nvim development (Emacs parity)
Shown only when Emacs is installed or ORG_EMACS / ORG_LISP_DIR is set: which Emacs, and which Org release ORG_LISP_DIR (or ORG_DIR) holds, read from its org-version.el. Only maintainers need them, for make difftest and make parity-fixtures, which compare org.nvim with Org 9.8.12.
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_mediareads images and files copied or cut in Explorer from the clipboard throughpowershell.exe.- The
orgcommand line isbin\org.cmd, and:Org cli_installwrites anorg.cmdlauncher into its directory (symlinks need administrator rights). The git merge driver isbin\org-merge.cmd. - The
icsandcaldavextensions convert 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.caldavcan't tell the name of the system's zone here: set itstimezoneoption (org-extensions-caldav). TZwith 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-modeand:shebangcan't make a file executable: Windows has no Unix file modes.- org-crypt needs GnuPG for Windows (or Gpg4win) on %PATH%. The
gpgof Git for Windows can't ask for passphrases outside its own terminal; a call that hangs is stopped after a minute. - Babel runs
sh/bashblocks with theshorbashon %PATH% (Git for Windows, MSYS2, WSL'sbash.exe), like Emacs.