Introduction
org.nvim implements Emacs Org mode in pure Lua. It reads and writes the same plain-text format, so files can be shared with Emacs.
It covers the parts of Org you use every day:
- Outlines with Emacs-style folding, cycling, motions and text objects.
- TODO workflows with logging, repeaters, priorities, tags and properties.
- An agenda with a time grid, habits, custom commands and bulk actions.
- Capture templates that file notes from any buffer.
- Clocking, effort estimates, clock tables and column view.
- Spreadsheet tables with
#+TBLFMformulas. - Source blocks that run asynchronously (Babel), and tangling.
- Export to HTML, LaTeX/PDF, Beamer, Markdown, ASCII, Org, ODT, iCalendar and Texinfo/Info, publishing projects, plus more formats via pandoc.
There are no dependencies: no tree-sitter parser, external binary or companion plugin.
Quick start:
- Open
~/org/todo.organd type* TODO Buy milk. - Press
<prefix>sto schedule it for today. - Press
<prefix>athenato open the weekly agenda. - Press
<prefix>cthentin any buffer to capture a task. - Press
g?to list every keymap.
New to Org? Run :Org tutor for a guided lesson with exercises that are checked as you do them (org-tutor).
For a hands-on tour, open examples/tutorial.org from the plugin directory. It has a section with exercises for every feature. To try it with a throwaway config (agenda and capture included), run from the plugin directory:
nvim -u examples/minimal_init.lua examples/tutorial.org
examples/00-index.org links to one file per feature area, each with many examples, exercises and the result they should produce.
Conventions used in this manual:
| <prefix> | The value of mappings.prefix (default <leader>o). |
| (ctx) | A context-sensitive key. When it does not apply at the cursor, the key falls back to its normal Vim behaviour (for example >> indents plain text and <C-a> increments numbers), or to your global mapping of the key, run as Vim would: keys from a noremap or <script> mapping are not remapped. |
| target | Many Lua functions accept { bufnr = n, lnum = l } to act on a headline other than the one at the cursor. |
Press g? in an org or agenda buffer for a list of active keymaps, grouped by topic. Each row lists every key of one command; i_ marks Insert-mode keys. / searches the list and { / } jump between sections.
Tutor
| :Org tutor [lesson] [reset] | A guided lesson in the spirit of vimtutor, in an org buffer of its own, so every org key works in it. The lessons make a course, from basics (1: the outline, TODO items, tags, dates, lists, tables and links) and workflow (2: capture, the agenda and clocking) on, at three levels: Beginner, Daily workflow and Power user. :Org tutor without a lesson lists them, each with its number, title, level and progress (exercises done in your saved copy, or "not started"): j/k and <CR> (or the key shown) open one, <Esc> or q closes the list. :Org tutor {lesson} opens a lesson directly. (Before, :Org tutor alone opened basics; that is now :Org tutor basics.) |
Each lesson is in small numbered sections. An exercise is a headline whose title starts with its number (1.2 Insert a headline): once you have done what it asks, a ✓ shows at the end of that headline (✗ until then), and the first line counts the exercises done. The marks are checked from the outline as org.nvim parses it ("this headline is DONE", "has the tag :work:", "the table is aligned"), a moment after each change, including changes made from the agenda. A few exercises are about what a window shows (folding a subtree, following a link): they are checked when the cursor moves or rests, and stay done once done. When every exercise is done, the lesson names the next one under its last line.
| :Org tutor_hint | In a lesson: show the keys that solve the exercise at the cursor (the cursor anywhere in the exercise's text). |
The lesson is a copy: :Org tutor writes it to stdpath("data")/org/tutor/{lesson}.org and opens that file, never the one shipped with the plugin. It is an ordinary file outside your notes, so saving, the agenda (press < in the agenda menu to restrict it to the lesson), capture (:Org capture_here) and the clock work in it without touching them. Clocking in on a lesson task clocks out the task you were clocked in on, as anywhere. The keys in the text are those of your mappings when the copy is made (:Org {action} for an action without a key).
Running :Org tutor {lesson} again opens the same copy: what you saved with :w is kept. reset starts the lesson over from a fresh copy (the buffer, when it is loaded, keeps its undo history: u brings back what you had). Completion lists the lessons.
The playground of the website, https://org-nvim.com/playground.html, plays a recording of each lesson done exercise by exercise, with the default keys and captions, and a follow-along mode where you press the keys yourself.
ui.tutor_marks sets the marks (default { done = "✓", todo = "✗" }), and the highlight groups OrgTutorDone, OrgTutorTodo and OrgTutorProgress (the count on the first line) their colors.
A lesson is tutor/org/{lesson}.org on 'runtimepath', so a plugin or your config can add one. Keywords before its first headline place it in the course (they are left out of the copy):
#+TITLE: org.nvim tutor 3: writing
#+TUTOR_ORDER: 3
#+TUTOR_LEVEL: Beginner
#+TUTOR_TOPICS: markup, lists, footnotes
#+TUTOR_ORDER: is its number (lessons without one come last), #+TUTOR_LEVEL: one of Beginner, Daily workflow or Power user, #+TUTOR_TOPICS: what it teaches, comma-separated. Its checks and hints, if any, are a Lua table returned by the module org.tutor.lessons.{lesson}, keyed by exercise number:
return {
checks = {
["1.2"] = { heading = "Pears", parent = "Fruit" },
["2.1"] = { heading = "Buy milk", todo = "DONE" },
["6.1"] = { table_aligned = true },
},
hints = {
["1.2"] = "On Apples press {{org.meta_return}}, type Pears, <Esc>.",
},
}
(A module that returns the checks table alone still works.) Each check is a condition, or a list of conditions that must all hold, on the exercise's subtree. A condition tests the headline heading of the subtree (by its title without keyword, priority or tags; the exercise headline when not given) for todo, priority, tags, parent, depth (levels below the exercise), children (titles in order), scheduled, deadline, clocked, min_headings and folded (folded in a window); or the subtree's text for item (a list item), checked (a checked item), table_aligned, table_row (first field of a row) and contains; cursor is the title of a headline of the file a window has the cursor on; fn(ctx) returns a boolean for anything else. {{org.cycle}} in the lesson text and in hints is replaced by the key of mappings.org.cycle (any mappings section works), {{leader}} by the leader key, {{done}} and {{todo}} by the ui.tutor_marks.