Completion
Completes (like Emacs org-pcomplete):
- TODO keywords after stars
- tags after
:on a headline (not the ones already set) or in#+FILETAGS #+keywords,#+STARTUPand#+OPTIONSvalues,#+begin_srclanguages, then header arguments and switches (also on#+HEADER:)#+BEGIN: clocktableparameters- entities after
\(\alpha) - in a property drawer, property names the entry doesn't have yet; elsewhere drawer names used in the buffer, after
:at line start - link types, stored links, headlines (
[[*) and custom IDs ([[#)
Omnifunc: <C-x><C-o> (set automatically). blink.cmp:
sources = {
per_filetype = { org = { inherit_defaults = true, "org" } },
providers = { org = { name = "Org", module = "org.completion.blink" } },
}
nvim-cmp:
require("cmp").register_source("org", require("org.completion.cmp").new())
Pickers
The pick_* actions open a fuzzy picker: headlines show their outline path, TODO keyword, priority and tags with the Org highlights, and the preview shows the entry in its file (in its buffer, unsaved changes and all, when the file is loaded). Confirming jumps there (and opens the folds around it). The picker option chooses the picker:
| "auto" | LazyVim's picker when it is installed (vim.g.lazyvim_picker, or with its "auto" the picker extra enabled in :LazyExtras), else the first installed of the ones below, else "select" (default) |
| "snacks" | snacks.nvim (Snacks.picker) |
| "fzf-lua" | fzf-lua (fzf_exec, the builtin previewer) |
| "telescope" | telescope.nvim |
| "mini" | mini.pick, once require("mini.pick").setup() has run |
| "select" | vim.ui.select(): one item, no preview |
None of these plugins is required: a picker is looked for (with require) when an action runs, never at startup, and one that isn't installed falls back to "select" with a warning.
| pick_headline | a headline of this file |
| pick_headline_all | a headline of the agenda files (and this file) |
| pick_tag | a tag of the agenda files (with how many headlines carry it), then a headline with it, its own or inherited |
| pick_set_tags | the tags of the headline at the cursor: the tags chosen (several with multi-select) are toggled, ✓ marks the ones it has; text that matches no tag is added as new tags (a:b adds two). mini.pick lists "+ New tags: <text>" below the matches; with "select", "+ New tags…" asks for the text. |
| pick_agenda | an entry of today's agenda |
| pick_agenda_week | an entry of the agenda of the next 7 days |
| pick_todo | an open TODO entry (the global TODO list, in the order of its view: agenda.sorting) |
| pick_agenda_file | an agenda file |
| pick_capture_template | a capture template, then capture with it (from the agenda, at the date at the cursor with capture.use_agenda_date, as the capture menu) |
Multi-select: <Tab> in snacks.nvim, fzf-lua and telescope, <C-x> then <M-CR> in mini.pick. The actions have no default keys; bind them in any action section (org-keymaps), e.g.
mappings = {
global = { pick_headline_all = "<leader>fo", pick_todo = "<leader>ft" },
}
or run :Org pick_todo. telescope.nvim also gets an extension:
require("telescope").load_extension("org")
then :Telescope org headlines (also headlines_all, tags, set_tags, agenda, agenda_week, todo, agenda_files, capture_templates; :Telescope org alone is headlines_all). These use telescope whatever picker says. The roam extension's node finder uses the same pickers (org-extensions-roam).
Opening in a window
In the pickers that go to a place (pick_headline, pick_headline_all, the headlines of pick_tag, pick_agenda, pick_agenda_week, pick_todo, pick_agenda_file) <C-s> opens it in a split, <C-v> in a vertical split and <C-t> in a new tab page, in every picker but vim.ui.select. picker_keys changes them, in Vim's key notation (fzf-lua gets "ctrl-s" for "<C-s>", "alt-x" for "<M-x>"); false turns one off:
picker_keys = { split = "<C-x>", vsplit = "<C-v>", tab = false },
In mini.pick they replace its own choose_in_split / vsplit / tabpage keys there; in telescope its select_horizontal / vertical / tab actions (<C-x>, <C-v>, <C-t>) do the same.
A picker that can take a new entry (a roam node, the new tags of pick_set_tags) takes the typed text when <CR> matches nothing. When existing entries match it, <M-CR> (picker_keys' query) takes the typed text instead of the entry under the cursor, like vertico's M-RET (vertico-exit-input) or ivy's C-M-j (ivy-immediate-done) in Emacs: type "Meeting" and press <M-CR> to create a node "Meeting" while "Meeting notes" exists. It works in snacks.nvim, fzf-lua (alt-enter) and telescope. mini.pick keeps <M-CR> (choose_marked) and lists "+ New: <text>" below the matches for this; vim.ui.select has no typed text (use its "+ New" entry). false turns it off.
Several entries can be chosen there too (multi-select, above). <CR> puts them in the quickfix list, titled after the picker, and opens it; <C-s>, <C-v> and <C-t> open each in a window of its own. <C-q> (picker_keys' qflist) puts the selected entries in the quickfix list, even just one, or with none selected every entry matching the typed text, like snacks.nvim's own <C-q>. In fzf-lua it takes the selection or the entry under the cursor, like fzf-lua's own alt-q: fzf can't say that nothing is selected. Select every match first with toggle-all (alt-a) there. In telescope its own send_to_qflist (<C-q>) does the same, and send_selected_to_qflist (<M-q>) takes the selection or the entry under the cursor. From there :cdo / :cfdo edit them all, and plugins reading the quickfix list take them: grug-far.nvim searches and replaces in their files with <qflist> as its paths, trouble.nvim and quicker.nvim show them.
Picker options
picker_opts gives each picker plugin options of your own, merged over the ones org.nvim passes:
picker_opts = {
["fzf-lua"] = { winopts = { height = 0.5, width = 0.6 } },
snacks = { layout = { preset = "ivy" } },
telescope = require("telescope.themes").get_dropdown(),
mini = { window = { config = { width = 60 } } },
},
They are fzf-lua's fzf_exec options, Snacks.picker() options, telescope's picker options and MiniPick.start() options. What org.nvim needs to show its items and act on the choice is kept: the items and their format, the preview, the fzf_opts that hide the index of an entry, fzf-lua's actions (use picker_keys), snacks.nvim's confirm and the picker_keys actions, telescope's finder, and the items and functions of mini.pick's source. An on_close of yours (fzf-lua's winopts.on_close, snacks.nvim's on_close) runs too, and a telescope attach_mappings runs after org.nvim's. :Telescope org headlines theme=dropdown and other options on that command line go over picker_opts.telescope.
Resuming (Snacks.picker.resume(), :FzfLua resume, :Telescope resume, :Pick resume) reopens the last picker as it was left, and choosing there acts again: jumps, toggles the tags, captures. A resumed roam node finder closes without effect.
From Lua, require("org.pickers").pick(spec) shows any list: spec.items are { display = { { text, hl_group }, ... }, filename?, bufnr?, lnum?, value? } and spec.on_choice(items, query) gets the chosen ones; with spec.split = true the picker keys choose too, and on_choice gets "split", "vsplit" or "tab" as its third argument, which require("org.pickers").jump(item, how) takes; see lua/org/pickers/init.lua.
Outline, breadcrumb and symbol plugins
Plugins that show a buffer's structure (outline windows, breadcrumbs, symbol pickers) usually ask tree-sitter or a language server for it. org.nvim has its own parser instead of a tree-sitter one, and gives its outline to them in three ways:
- aerial.nvim and outline.nvim: a backend / provider made from that parser, nothing else to enable (below);
- plugins that speak LSP (nvim-navic, dropbar.nvim, the snacks.nvim, fzf-lua and telescope symbol pickers, trouble.nvim, and the LSP providers of aerial and outline.nvim): the document symbols of the
lspextension, an in-process server (org-extensions-lsp); - your own code:
api.symbols()andapi.symbol_path()(org-api-symbols).
All three give the same symbols: every headline, its range the whole subtree and its name the title, with TODO keyword, priority and tags as detail; plain, TODO and done headlines get their own kind (Namespace, Event, Constant). Named src blocks (Function) and named tables (Struct) are children of their entry, <<targets>> (Key) too when asked for.
aerial.nvim: add the "org" backend for org buffers:
require("aerial").setup({ backends = { org = { "org" } } })
It updates update_delay ms (300, aerial's org = { update_delay = N }) after aerial's update_events, and shows every symbol: filter_kind only applies to aerial's LSP and tree-sitter backends. With the "lsp" backend instead, set filter_kind = { org = false } (its own default list leaves out the kinds headlines have).
outline.nvim: add "org" to the providers:
require("outline").setup({
providers = { priority = { "lsp", "coc", "markdown", "norg", "man", "org" } },
})
LSP plugins need the lsp extension. For the outline alone, leave the rest of it off:
require("org").setup({
extensions = {
lsp = {
features = {
diagnostics = false, hover = false, definition = false,
references = false, rename = false, code_actions = false,
document_links = false,
},
},
},
})
Then:
| nvim-navic | attach it from the extension's on_attach (LazyVim does that for every server with document symbols): on_attach = function(client, bufnr) require("nvim-navic").attach(client, bufnr) end |
| dropbar.nvim | nothing to do: without a tree-sitter parser its default sources take the LSP symbols. |
| pickers | Snacks.picker.lsp_symbols(), :FzfLua lsp_document_symbols, :Telescope lsp_document_symbols, and the workspace symbol pickers for the headlines of every workspace file. Pickers that filter by kind leave TODO and done headlines out: in snacks.nvim set filter = { org = true } for lsp_symbols, in LazyVim kind_filter = { org = false }. org.nvim's own pickers need no server (org-pickers). |
| trouble.nvim | :Trouble symbols. |
The extension's symbol_kinds changes the kinds (for icons or filters).
Breadcrumbs and sticky headings: nvim-treesitter-context needs a tree-sitter parser, so it shows nothing in org buffers; org.nvim's own sticky context (org-context) keeps the headlines above the screen in view. api.symbol_path() gives the headlines around the cursor cheaply enough for a 'winbar':
function _G.org_breadcrumbs()
local path = require("org.api").symbol_path({ win = vim.g.statusline_winid }) or {}
local names = vim.tbl_map(function(s) return s.name end, path)
return (table.concat(names, " > "):gsub("%%", "%%%%"))
end
vim.api.nvim_create_autocmd("FileType", {
pattern = "org",
callback = function()
vim.wo.winbar = "%{%v:lua.org_breadcrumbs()%}"
end,
})
Text objects and motions: nvim-treesitter-textobjects needs a parser too. org.nvim's own keys (org-textobj, org-elements) cover its usual captures:
@class.outer / @class.inner | ar / ir: the subtree |
@function.outer / @function.inner | ah / ih: the entry without its children |
@block.outer | <prefix>v on the block (the element) |
next / previous @class.outer | ]] / [[ (visible headlines), ][ / [] (siblings), g{ (parent) |
next / previous @block.outer | <C-c><M-f> / <C-c><M-b> |
Folding needs no helper: org.nvim folds org buffers itself (org-folding), and the lsp extension also answers textDocument/foldingRange.
Text objects, scopes and jumps
mini.ai, snacks.nvim's scopes and flash.nvim's tree-sitter jump ask tree-sitter for the nodes around the cursor. In org buffers they get org.nvim's structure instead: the headline subtrees, the elements around the cursor (org-elements: blocks, drawers, lists and items, tables, paragraphs, ...) and the links, timestamps and emphasis on its line. When an org buffer is set up and the plugin is loaded (or lazy.nvim loads it later), org.nvim hooks itself in; nothing to configure, and a plugin that isn't installed is never loaded. integrations in setup() turns each one off:
require("org").setup({
integrations = { mini_ai = true, snacks_scope = true, flash = true },
})
mini.ai: org buffers get these custom_textobjects (in vim.b.miniai_config, kept with any the buffer already has):
h | the headline and its section, up to the first child (ih: the section without the headline line) |
r | the subtree (ir: below the headline line) |
e | the element at the cursor (ie: a block's or drawer's contents) |
B | a #+BEGIN_..#+END_ or dynamic block (iB: its contents; mini.ai's b stays the brackets) |
- | a list item and its children (i-: its text after the bullet and checkbox, charwise) |
T | a table (#+TBLFM: lines included) |
L | a link (iL: its description) |
d | a timestamp or range (id: inside its brackets) |
m | emphasis: *bold*, /italic/, _underline_, +strike+, =verbatim=, ~code~ (im: the text inside the markers) |
The letters follow org.nvim's own text objects (org-textobj), whose buffer keys (ah, ir, ...) stay first; mini.ai adds the "next" and "last" variants (anB, ilL), its counts and its g[ / g] motions. A table instead of true gives other letters, false leaves one out:
integrations = { mini_ai = { block = "o", emphasis = false } }
With the option off, add them to mini.ai yourself, for example only for org buffers:
vim.api.nvim_create_autocmd("FileType", {
pattern = "org",
callback = function()
vim.b.miniai_config = {
custom_textobjects = require("org.integrations.mini_ai").spec({ block = "o" }),
}
end,
})
snacks.nvim: Snacks.scope has no way to plug in another source, so org.nvim wraps Snacks.scope.get for org buffers (other buffers are left to snacks). The scope at the cursor is the innermost element of two lines or more (snacks' min_size), then each enclosing element and subtree, so Snacks.indent's scope guide, the ii / ai text objects and the [i / ]i jumps follow the org structure. ai takes the whole block, item or subtree; ii its contents (inside the #+BEGIN and #+END lines, below the headline or the item's first line); repeating them in Visual mode grows the selection. The guide is drawn at the element's indentation, so it shows only beside indented lines. Nothing to set up beyond snacks' own:
require("snacks").setup({ indent = { enabled = true }, scope = { enabled = true } })
flash.nvim: in org windows, flash's tree-sitter jump labels the emphasis, link or timestamp at the cursor, the elements around it and the subtrees; a label selects one, or with an operator acts on it (yS + label). The key LazyVim and flash's README bind,
vim.keymap.set({ "n", "x", "o" }, "S", function() require("flash").treesitter() end)
works unchanged. require("org.integrations.flash").jump(opts) does the same even with integrations.flash = false, and is flash's own jump outside org buffers. flash's remote tree-sitter search (treesitter_search) still needs a parser.