Extras: help, completion, lint, speed keys, inline tasks, crypt ...

This file collects the features of org.nvim that don't belong to one of the other example files: finding help, completion, the syntax checker (org-lint), speed keys, inline tasks, encryption, special edit buffers, element commands, structure templates, display options, setup files, the Emacs keys, and the integrations (org-protocol, feeds, MobileOrg, the Lua API).

• The file starts folded (#+STARTUP: overview). Put the cursor on a heading and press <Tab> to open it; <S-Tab> cycles the whole buffer.
• Nothing breaks if you make a mess: u undoes, and git checkout examples/22-extras.org restores the file.
• g? lists every key of the buffer (see the next section).
• <prefix> means <leader>o, the default mappings.prefix. With examples/minimal_init.lua the leader is <Space>, so <prefix>' is <Space>o'.
• Lines starting with Try: are exercises with the exact keys to press; Expect: says what you should see afterwards.
• Lines starting with # followed by a space are Org comments that annotate the examples. They are dimmed and never exported.

Start Neovim from the repository root with the bundled init file, so your own config is not involved:

nvim -u examples/minimal_init.lua examples/22-extras.org

examples/minimal_init.lua sets the leader keys (<Space> and \), points the agenda at examples/*.org, sends captures to a scratch org_directory under stdpath("state"), and defines a few capture templates and custom agenda commands. Everything this file talks about is left at its default, so several sections show how to turn a feature on for the current session with a :lua command. Those changes last until you quit Neovim.

You never need to leave Neovim to find a key or a command.

:checkhealth org checks everything org.nvim depends on and prints what it found, in five parts:

org.nvim

Neovim version, org_directory, agenda files, notes file, TODO keywords

external tools

pandoc, makeinfo, LaTeX, and the interpreter of every Babel language

image and LaTeX previews

which image backend draws previews (see 21-images-latex)

completion

omnifunc, blink.cmp or nvim-cmp

terminal keys

whether tmux and the terminal pass the keys org maps

The last part matters more than it seems: keys such as <C-CR>, <S-CR>, <C-,>, <M-S-CR> only reach Neovim when the terminal sends "extended keys" (CSI u). Inside tmux you need set -s extended-keys on and a terminal-features entry with extkeys. The check also reads the keybinds of Ghostty, kitty and WezTerm and warns when one of them takes a key org.nvim maps (Ghostty's ctrl+tab, kitty's ctrl+shift+enter, …). On macOS, Option must send Alt for the <M-...> keys.

Try: run :checkhealth org. Expect: a line "OK N agenda file(s) found" (the .org files of examples/ plus those in the scratch directory), one line per Babel language saying whether its interpreter was found, and a "terminal keys" part listing the keys that need CSI u.

If a key does nothing, test it: in Insert mode press <C-v> and then the key. Neovim inserts what it received: <C-CR> should give <C-CR>, not a plain ^M.

org.nvim completes Org syntax as you type, like Emacs org-pcomplete (M-TAB). The same candidates are available three ways:

• the built-in omnifunc, <C-x><C-o> in Insert mode. It is set automatically in every org buffer, nothing to configure;
• a blink.cmp source;
• an nvim-cmp source.

The blink.cmp source, in your blink.cmp options:

sources = {
  per_filetype = { org = { inherit_defaults = true, "org" } },
  providers = { org = { name = "Org", module = "org.completion.blink" } },
}

The nvim-cmp source:

require("cmp").register_source("org", require("org.completion.cmp").new())
-- and add { name = "org" } to the sources of cmp.setup.filetype("org", ...)

Blocks (#+begin_src, #+begin_quote …) are tedious to type. Two helpers insert them.

<prefix>' (Emacs C-c ', org-edit-special) opens the element at the cursor in a separate buffer with the right filetype, so you get the syntax, indentation and LSP of that language. Save it back:

• <prefix>' (or <C-c>') in the edit buffer saves and closes it,
• :w saves without closing,
• <C-c><C-k> throws the changes away (the edit_src.abort key).

It works on:

Anywhere else it says "No special environment to edit here".

If the file changed under an open edit buffer, :w refuses to overwrite the conflicting region; look at both versions and use :w! to force it.

Org calls the parts of an entry's text elements: paragraphs, plain lists and their items, blocks, drawers, tables, fixed-width areas, keywords and comments. The blank lines after an element belong to it. Some commands work on whole elements, like Emacs' M-}, M-h, C-M-t:

Emacs' M-h is <M-h> (promote) in org.nvim, so select is <prefix>v. The commands always act on whole lines.

Speed keys (Emacs org-use-speed-commands) are single letters that run a command when you type them at the very start of a headline, before the first star. Anywhere else the letter is inserted as usual. They are off by default.

In org.nvim they work in Insert mode, with the cursor in column 0 of a headline (in Normal mode those letters are Vim commands). So I (or 0i) on a headline, then letters. After each command the cursor goes back to column 0 of the headline it ends on, still in Insert mode, so you can type several in a row. <Esc> leaves.

Turn them on in your config with use_speed_commands = true, and add or change keys with speed_commands:

require("org").setup({
  use_speed_commands = true,
  -- an action name, a function, or false to drop a key:
  speed_commands = { x = "archive_subtree", n = false },
})

use_speed_commands may also be a function that returns true where speed keys should apply.

An inline task (the Emacs org-inlinetask module) is a TODO item in the middle of an entry's text, which does not start a new entry: the text after it still belongs to the entry above. It is a headline with at least inlinetask_min_level stars (Emacs uses 15), optionally closed by a line with the same stars and END:

* Meeting notes
We discussed the budget.
*************** TODO Send the slides to Ana
Details of the task can go here.
*************** END
And the notes continue: this line is still part of "Meeting notes".

Inline tasks are off by default, as in Emacs without the module (inlinetask_min_level = false). While they are off, a line of 15 stars is simply a very deep headline. When they are on:

• they don't count as entries: folding, motions, ar and the agenda see the text around them as part of the entry above,
• <Tab> on one folds it up to its END line,
• << / >> promote and demote the task and its END line together, never below the minimum level,
• only their last two stars are shown,
• <C-c><C-x>t (org-inlinetask-insert-task) inserts one below the cursor, or around the Visual selection. It gets inlinetask_default_state as keyword unless you give a count.
• export writes them as a small box (export.with_inlinetasks).

org-crypt encrypts the text of an entry with GnuPG, in the same format as Emacs, so files encrypted in one editor decrypt in the other. It needs the gpg program (crypt.gpg_program) installed and working; gpg --version in a shell tells you.

• Entries tagged :crypt: (crypt.tag_matcher, a match expression) are the ones the "entries" commands and encrypt-on-save act on.
• The headline, the planning line, the property drawer, clock lines and the LOGBOOK stay readable. The rest of the entry, children included, becomes a -----BEGIN PGP MESSAGE----- block.
• The key: the CRYPTKEY property, else crypt.key, is looked up in your public keyring. When nothing matches (crypt.key is "" by default, which never matches) the entry is encrypted symmetrically, with a passphrase you type. crypt.key = false always encrypts symmetrically.
• Passphrases are read with inputsecret() (twice when encrypting) and handed to gpg with --pinentry-mode loopback.

There are no default keys, as in Emacs. Use the commands (Emacs M-x org-encrypt-entry and friends), or map the actions yourself:

require("org").setup({
  crypt = { key = "you@example.com", encrypt_on_save = true },
  -- keep the tag on the entries that carry it, as Emacs recommends:
  tags_exclude_from_inheritance = { "crypt" },
  mappings = { org = {
    crypt_encrypt_entry = "<prefix>xc",
    crypt_decrypt_entry = "<prefix>xC",
  } },
})

With crypt.encrypt_on_save = true, the :crypt: entries are encrypted before every write, and stay encrypted in the buffer afterwards (decrypt again to keep working), like Emacs' org-crypt-use-before-save-magic.

Leaks. Decrypted text can reach the disk through the swap file and a persistent undo file. Before decrypting in a buffer with either, crypt.disable_auto_save ("ask" by default) asks whether to turn them off for that buffer. examples/minimal_init.lua already sets noswapfile, so you won't be asked here. Yanked text goes to registers, which shada may save: see :h org-crypt-leaks.

These options change how the buffer looks, not the file. Most have a #+STARTUP: word for one file and a ui option for all files. See 02-markup for emphasis and entities, and 21-images-latex for images and formulas.

Options under ui in your setup:

num

number headlines: 1, 1.1, 1.2 … (#+STARTUP: num / nonum; toggle: :Org num_mode)

indent_mode

indent text under its headline (org-indent-mode) (#+STARTUP: indent / noindent)

hide_leading_stars

show only the last star (#+STARTUP: hidestars / showstars)

pretty_entities

\alpha shows as α, x^2 as x² (#+STARTUP: entitiespretty / entitiesplain; toggle: <C-c><C-x>\)

conceal_links

show only link descriptions (toggle: <prefix>lt)

hide_emphasis_markers

hide the * / _ … markers

bullets

symbols in place of the stars

checkboxes

icons for [ ] [-] [X]

todo_keyword_faces, priority_faces, tag_faces

colours per keyword / priority / tag

examples/minimal_init.lua sets bullets (◉ ○ ✸ ✿) and checkboxes, which is why the stars of this file look the way they do.

Headline numbering follows the org-num options: num_max_level, num_skip_commented, num_skip_tags, num_skip_unnumbered (a subtree with an UNNUMBERED property) and num_format_function.

Try: :Org num_mode, then <S-Tab> until you see every headline. Expect: "Org-Num mode enabled", and the headlines of this file are numbered: "How to use this file" is 1, its child "Keys in this file" is 1.1, "Getting help inside Neovim" is 2 and so on. :Org num_mode again removes the numbers.

Try: change the #+STARTUP: line at the top of this file to #+STARTUP: overview indent, press <C-c><C-c> on it and reload with :e. Expect: the body text of each entry is indented under its headline (only on screen: the file is unchanged) and only one star of each headline shows. Put the line back afterwards.

Try: press <C-c><C-x>\ on this line: α → β, E = mc^2. Expect: with pretty entities on you see α → β and mc². Press it again to see the text as written.

Highlight groups (OrgTodo, OrgTags, OrgLink, OrgHeadlineLevel1 …) are listed in :h org-highlights; set them with nvim_set_hl().

Several files can share their settings (#+TODO:, #+TAGS:, #+LINK:, #+PROPERTY:, #+OPTIONS: …) through a setup file:

#+SETUPFILE: "~/org/setup/common.org"

Only the settings of that file are imported, never its headings. Paths are relative to the file that names them; quotes allow spaces; setup files may name other setup files (cycles are stopped). <prefix>' on the line visits the file.

Try: add this line at the top of this file, below #+TAGS:, and press <C-c><C-c> on it:

#+SETUPFILE: tutorial.org

Then put the cursor on any headline of this file and press <prefix>S. Expect: the TODO keyword menu now offers TODO, NEXT, WAITING, DONE and CANCELLED: the #+TODO: line of tutorial.org was imported. Press <Esc>, delete the line again and press <C-c><C-c> on the #+TAGS: line to refresh.

A missing setup file is ignored when the file is read; :Org lint reports it (see the next section).

:Org lint (Emacs M-x org-lint) looks for mistakes that make Org read your text differently from what you meant: a link to a heading that doesn't exist, a footnote without its definition, a #+begin_src without a language, a misspelt header argument … It lists what it finds in the location list (:lopen), titled "org-lint". Each entry is checker: message; E marks the reliable checks ("high trust"), W the heuristics ("low trust"). It has no default key, as in Emacs.

• :Org lint runs every checker.
• :Org lint duplicate-name invalid-fuzzy-link runs only those (<Tab> completes the checker names), like Emacs' C-u C-u M-x org-lint.
• :lnext / :lprev (or ]l / [l in Neovim 0.11+) walk the list.
• From Lua: require("org.lint").lint(0) returns the reports as a list of { lnum, col, checker, message, trust }.

Every checker of Org 9.8 is implemented; :h org-lint lists them.

The rest of this file is clean. The subtree below is full of mistakes on purpose. It is marked COMMENT, so it is never exported and the agenda ignores its TODO entries and dates, but org-lint still checks it.

Try: run :Org lint, then :lopen. Expect: 28 entries, all in "COMMENT Lint playground", in the order of the list below. <CR> on an entry jumps to its line.

Try: :Org lint duplicate-name. Expect: exactly two entries, duplicate-name: Duplicate NAME "twice", on the two #+NAME: twice lines.

Try: fix one mistake (for example add sh after the bare #+begin_src), run :Org lint again. Expect: that entry is gone and the others remain.

Each mistake of the playground and the entry it produces, in file order:

two headings with CUSTOM_ID: same-id

duplicate-custom-id: Duplicate CUSTOM_ID property "same-id" (twice)

[[*No such heading]]

invalid-fuzzy-link: Unknown fuzzy location "No such heading"

[[#no-such-id]]

invalid-custom-id-link: Unknown custom ID "no-such-id"

[[id:...]] to an unknown ID

invalid-id-link: Unknown ID "00000000-..."

[[file:does-not-exist.org]]

link-to-local-file: Link to non-existent local file "does-not-exist.org"

a link followed by a stray ]

trailing-bracket-after-link: Trailing ']' after link end

#+begin_src with no language

missing-language-in-src-block: Missing language in source block

:foo bar on a src block

wrong-header-argument: Unknown header argument ":foo"

:results maybe

wrong-header-value: Unknown value "maybe" for header ":results"

#+TBLNAME:

obsolete-affiliated-keywords: Obsolete affiliated keyword: "TBLNAME". Use "NAME" instead

#+BEGIN_HTML block

deprecated-export-blocks: Deprecated syntax for export block. Use "BEGIN_EXPORT HTML" instead

#+NAME: with nothing after it

orphaned-affiliated-keywords: Orphaned affiliated keyword: "NAME"

[fn:nodef] without a definition

undefined-footnote-reference: Missing definition for footnote [nodef]

[fn:unused] definition, no reference

unreferenced-footnote-definition: No reference for footnote definition [unused]

:EFFORT: lots

invalid-effort-property: Invalid effort duration format: "lots"

:TODO: in a property drawer

special-property-in-properties-drawer: Special property "TODO" found in a properties drawer

SCHEDULED: after body text

misplaced-planning-info: Misplaced planning info line

SCHEDULED: [inactive date]

planning-inactive: Inactive timestamp in SCHEDULED will not appear in agenda.

<2026-12-03 Fri> (it's a Thursday)

timestamp-syntax: Potentially malformed timestamp <2026-12-03 Fri>. Parsed as: <2026-12-03 Thu>

[#Z]

priority: Out-of-bounds priority 'Z'

a list numbered 1., 3.

item-number: Bullet counter "3. " is not the same with item position 2. Consider adding manual [@3] counter.

tags ::work::

spurious-colons: Tags contain a spurious colon

two #+NAME: twice

duplicate-name: Duplicate NAME "twice" (twice)

#+ATTR_HTML :width 10 (no colon)

invalid-keyword-syntax: Possible missing colon in keyword "ATTR_HTML"

#+SETUPFILE: no-such-setup.org

non-existent-setupfile-parameter: Non-existent setup file "no-such-setup.org"

#+begin_quote never closed

invalid-block: Possible incomplete block "#+begin_quote"

Coming from Emacs? Org's own keys (org-mode-map) work on top of the Vim-style keys, so muscle memory keeps working. They live in three sections of mappings, each of which can be turned off:

require("org").setup({
  mappings = {
    emacs = false,        -- C-c ... keys in Normal mode
    emacs_insert = false, -- <C-CR>, <C-S-CR> in Insert mode
    emacs_global = false, -- <C-c>a agenda, <C-c>c capture, <C-c>l store link
  },
})

• C-c keys are Normal-mode only: in Insert mode <C-c> still leaves Insert mode.
• Emacs' C-u prefix is a Vim count: 4<C-c>. is C-u C-c ., 16<C-c><C-t> is C-u C-u C-c C-t.
• Keys marked "(ctx)" in :h org-emacs-keys depend on the cursor, like in Emacs: <C-c>- inserts a table rule in a table, cycles the bullet on a list item, and toggles an item elsewhere.
• Emacs keys that Vim needs are moved: M-h (mark element) is <prefix>v, C-x n s / C-x n b (narrow) are <prefix>hn / <prefix>nb.

The Emacs key is typed as written, in Vim's key notation: C-c C-t is <C-c><C-t>, C-c . is <C-c>., M-RET is <M-CR>. The most used ones and their Vim-style equivalents:

Try: on the headline "Emacs practice" below, press <C-c><C-t>. Expect: it becomes "TODO Emacs practice" (this file has only TODO and DONE, so the key cycles). Press <C-c><C-t> twice more to get DONE and then no keyword.

Try: on the same headline press <C-c>;. Expect: "COMMENT Emacs practice". Again to remove it.

• :h org the whole manual; :h org-keymaps every key; :h org-commands every :Org subcommand; :h org-config every option.
• :h org-completion, :h org-lint, :h org-speed-commands, :h org-inlinetask, :h org-crypt, :h org-crypt-leaks.
• :h org-babel-edit-special (special edit buffers), :h org-elements, :h org-tempo, :h org-appearance, :h org-highlights.
• :h org-setupfile, :h org-in-buffer-settings.
• :h org-emacs-keys, :h org-differences.
• :h org-protocol, :h org-feed, :h org-mobile, :h org-api.
• The other example files: 00-index.