Capture: file a note from anywhere

A TODO entry with a timestamp, a link back and the Visual selection.

t = { description = "Task", template = "* TODO %?\n  %U\n  %a\n  %i", target = "inbox.org" },

• * TODO %? : an entry (a headline) in the TODO state; you type the title.
• %U : the current date and time as an inactive timestamp.
• %a : a link to where you were when you pressed <prefix>c. From an org headline that is a file:...::*Heading search link.
• %i : the text selected in Visual mode (empty otherwise). Because the line is = %i=, every line of the selection gets the same two-space indent.
• target = "inbox.org" and nothing else: the entry is appended at the end of the file, as a level-1 headline.

Try: put the cursor on the heading "Task (t)" above, press <prefix>c t, type Call the plumber, <Esc>, <C-c><C-c>. Expect: at the end of inbox.org:

* TODO Call the plumber
  [2026-09-28 Mon HH:MM]
  [[file:~/Workspace/orgmode/examples/11-capture.org::*Task (t)][Task (t)]]

(with the path of your checkout; ~ when it is under your home). The link points back to this heading: <CR> on it in inbox.org brings you here. The %i line was dropped because it was empty and trailing.

Try: select the two lines below with Vj, press <prefix>c t, type Quote, then <Esc> and :w.

line one of the selection
line two of the selection

Expect: the entry ends with the two selected lines, each indented by two spaces (the leading =: = comes along since it is part of the text):

: line one of the selection
: line two of the selection

A TODO entry under a headline that is created when missing.

w = "Work",  -- a group label: the menu shows "w Work", then t and m
wt = { description = "Work task", template = "* TODO %? :work:",
       target = "work.org", headline = "Inbox" },

• headline = "Inbox" files the entry as the last child of the first headline titled "Inbox" (its TODO keyword, priority and tags are ignored when matching). If there is none, "* Inbox" is created at the end of the file when the capture starts. The file itself is created too.
• An entry template's stars are adjusted: * TODO becomes ** TODO one level below "Inbox".
• The literal :work: after %? is just text: the tag ends up after what you type (it is not re-aligned).

Try: <prefix>c w t, type Send the report, <Esc>, <C-c><C-c>. Expect: work.org now contains

* Inbox
** TODO Send the report :work:

An outline path, a prompt, tags, and the clock.

wm = { description = "Meeting", template = "* %^{Who} %^g\n  %T\n  %?",
       target = "work.org", olp = { "Meetings" }, clock_in = true },

• olp = { "Meetings" } is an outline path (Emacs file+olp): every headline of the path must already exist, so a first try fails with "Heading not found on level 1: Meetings". This is like Emacs.
• %^{Who} asks "Who: " before the window opens and inserts the answer.
• %^g asks for tags (completing the tags already used in work.org); type them separated by :. Tags on a headline are aligned.
• %T inserts the current date and time as an active timestamp, so the meeting shows up in the agenda.
• clock_in = true starts the clock on the new entry while you type (stopping a running clock), and logs the time when you finish.

Try: <prefix>c w m. Expect: the warning "Heading not found on level 1: Meetings". Now make the node: 4<prefix>c w t jumps to "Inbox" in work.org; press G, o, type * Meetings, <Esc>, :w, and come back with <C-o>.

Try: <prefix>c w m, answer Alice for "Who", work:meeting for the tags, type Agreed on the plan, wait a minute, <Esc>, <C-c><C-c>. Expect: in work.org, under "Meetings":

** Alice                                                  :work:meeting:
:LOGBOOK:
CLOCK: [2026-09-28 Mon HH:MM]--[2026-09-28 Mon HH:MM] =>  0:01
:END:
  <2026-09-28 Mon HH:MM>
  Agreed on the plan

The clock ran while the capture window was open.

An entry in a date tree.

j = { description = "Journal", template = "* %<%H:%M> %?",
      target = "journal.org", datetree = true },

• datetree = true files the entry under year / month / day headlines, creating the missing ones in date order (Emacs file+olp+datetree).
• %<%H:%M> is a strftime format: the current hour and minute.
• The date is today, unless you start the capture with 1<prefix>c (asks for the date) or with K from the agenda (the agenda day).

Try: <prefix>c j, type Wrote the capture examples, <Esc>, :w. Then capture a second journal entry the same way. Expect: journal.org (a new file starts with an empty line, like Emacs):

* 2026
** 2026-09 September
*** 2026-09-28 Monday
**** HH:MM Wrote the capture examples
**** HH:MM ...your second entry

Try: 1<prefix>c j; in the calendar press i, type oct 15, <CR>. Type Planned ahead, <Esc>, :w. Expect: a new branch ** 2026-10 October / *** 2026-10-15 Thursday after the September one, with **** 00:00 Planned ahead under it: a picked day other than today starts at extend_today_until o'clock (0 by default), so %<%H:%M> gives 00:00.

A checkbox item in a list.

s = { description = "Shopping item", type = "checkitem", template = "[ ] %?",
      target = "inbox.org", headline = "Shopping" },

• type = "checkitem" adds a checkbox item to the first plain list of the target entry (creating the list when there is none). An item template without a bullet gets "- ".

Try: <prefix>c s, type Milk, :w; again with Eggs. Expect: in inbox.org:

* Shopping
- [ ] Milk
- [ ] Eggs

A table row, stored without opening a window.

x = { description = "Expense", type = "table-line",
      template = "| %u | %^{Amount} | %^{What} |",
      target = "inbox.org", headline = "Expenses", immediate_finish = true },

• type = "table-line" appends a row to the first table of the entry. When there is no table yet, one is created with an empty header row, like Emacs.
• immediate_finish = true stores the text right after the prompts: no capture window opens.
• %u is today's date as an inactive timestamp.

Try: <prefix>c x, answer 12.50 and Lunch. Then again, 3 and Bus. Expect: no capture window; in inbox.org:

* Expenses
|                  |       |       |
|------------------+-------+-------|
| [2026-09-28 Mon] | 12.50 | Lunch |
| [2026-09-28 Mon] |     3 | Bus   |

%^{Who|Bob|Alice|Carol} asks "Who [Bob]: ", offers Alice and Carol as completions, and takes Bob for an empty answer.

Note: %% is not an escape (like Emacs). To write a literal percent sign before an escape letter, use a backslash: \%t stays %t.

The ea template is

* %^{Who|Bob|Alice|Carol} called about %^{Topic}
  Call %\1 back about %\2.
  %U

• %^{Who|Bob|Alice|Carol}: the prompt "Who [Bob]: " completes Alice and Carol; an empty answer takes the default Bob.
• %\1 and %\2 repeat the first and second answers.

Try: <prefix>c e a, press <CR> at "Who [Bob]", type the invoice at "Topic", then :w in the capture window. Expect: under * Inbox of the playground:

** Bob called about the invoice
  Call Bob back about the invoice.
  [2026-09-28 Mon HH:MM]

The eg template is * TODO %^{Task} %^{Effort|0:30}p%^g with immediate_finish. %^{Effort|0:30}p asks for the Effort property (an empty answer takes 0:30) and puts it in a :PROPERTIES: drawer; when the target entry has an Effort_ALL property its values are offered. %^g asks for tags, completing the tags of the target file; separate several with :.

Try: <prefix>c e g, answer Write the docs, <CR> (for the default effort) and work:urgent. Expect: no window, and in the playground under * Inbox:

** TODO Write the docs                                        :work:urgent:
:PROPERTIES:
:Effort:   0:30
:END:

Put %^g at the end of the headline: tags only count as tags at the end of a heading, so text after them keeps them from being aligned or found. A prompt that follows %^g on the same line is still asked, as in Emacs.

The ef template shows most non-interactive escapes at once:

* Captured from %f
  weekday: %<%A>  iso: %<%Y-%m-%d>
  %t %u %T %U
  a: %a
  l: %l
  L: %L
  F: %F
  %?

Try: with the cursor on the heading "Dates, files and links (ef)", press <prefix>c e f and look at the capture window before finishing with :w. Expect:

* Captured from 11-capture.org
  weekday: Monday  iso: 2026-09-28
  <2026-09-28 Mon> [2026-09-28 Mon] <2026-09-28 Mon HH:MM> [2026-09-28 Mon HH:MM]
  a: [[file:~/.../examples/11-capture.org::*Dates, files and links (=ef=)][Dates, files and links (=ef=)]]
  l: [[file:~/.../examples/11-capture.org::*Dates, files and links (=ef=)]]
  L: file:~/.../examples/11-capture.org::*Dates, files and links (=ef=)
  F: /full/path/to/examples/11-capture.org

(On another day, the dates and weekday are those of that day.)

• %i is the text selected when you pressed <prefix>c in Visual mode (see the t template above).
• %c is the last yank, %x the system clipboard.

Try: put the cursor on the word banana in this sentence and yank it with yiw; then <prefix>c e y and :w. Expect: the capture window, and then the playground, show ** Yanked: banana.

%(...) evaluates an expression after the other escapes are replaced. It is Emacs Lisp by default (a small built-in interpreter that knows the common string and number functions, and emacs --batch for the rest when Emacs is installed); a form that is valid Lua is run as Lua. The result must be a string (or nil).

* %(upcase "shout") %(number-to-string (+ 40 2)) %(string.rep("ab", 3))

Try: <prefix>c e l, then :w. Expect: ** SHOUT 42 ababab.

With %(+ 40 2) instead, you get the warning "Capture template sexp `(+ 40 2)' must evaluate to string or nil" and nothing is inserted there, as in Emacs.

template may be a Lua function returning the template text (escapes in it are still expanded), a list of lines, or { file = "path" } to read it from a file relative to org_directory.

Try: <prefix>c e F, type done, :w. Expect: ** Built by Lua followed by = done=.

Try: <prefix>c e i, type A second idea, :w. Expect: the list under * Ideas becomes

- The first idea
- A second idea

The item takes the bullet and indentation of the existing list.

"plain" text goes at the end of the entry's own text, before its children. The ep template is %U %?.

Try: <prefix>c e p, type appended text, :w. Expect:

* Notes
Some text of the Notes entry.
[2026-09-28 Mon HH:MM] appended text
** A child of Notes

Entries normally become the last child of the target. prepend = true makes them the first.

Try: <prefix>c e P, type !, :w. Expect: right under * Inbox, before "An older note":

* Inbox
** Newest note !
** An older note

olp = { "Projects", "Neovim" } (or the string "Projects/Neovim") finds "Neovim" under "Projects". Every node must exist.

Try: <prefix>c e o, type Write the plugin, :w. Expect:

** Neovim
*** TODO An existing task
*** TODO Write the plugin

datetree = true makes a day tree (j above). tree_type changes the levels: "day" (year, month, day), "week" (year, ISO week, day), "month" (year, month), or a list of "year", "quarter", "month", "week", "day". With olp or headline, the tree is built under that headline; without, at the top level of the file.

Try: <prefix>c e w, type Week entry, :w. Expect: under * Log:

* Log
** 2026
*** 2026-W40
**** 2026-09-28 Monday
***** Week entry

Try: <prefix>c e m, type Month entry, :w. Expect: at the end of the playground (a top-level tree):

* 2026
** 2026-09 September
*** 28 Month entry

regexp is a Vim regexp; the text goes where the first match ends (where it starts, with prepend). When the match is on a headline, an entry becomes its child and an item goes into its list.

Try: <prefix>c e r, answer Dune. Expect: no window (immediate_finish), and

* Reading list
- [ ] Dune

table_line_pos = "II-1" means "the line just before the 2nd horizontal rule", so the row lands above the Total line. "I+1" would put it right after the first rule (the top of the data).

Try: <prefix>c e t, answer 4.20 and Tea. Expect:

| Date             | Amount | What         |
|------------------+--------+--------------|
| [2026-09-01 Tue] |   9.00 | Coffee beans |
| [2026-09-28 Mon] |   4.20 | Tea          |
|------------------+--------+--------------|
| Total            |        |              |

target = "clock" files under whatever task is being clocked; %k is its title and %K a link to it.

Try: first <prefix>c e k with no clock running. Expect: the warning "No running clock that could be used as capture target".

Try: 4<prefix>c e o (jumps to "Neovim" in the playground), go down to "An existing task", clock in with <prefix>xi, come back with <C-o>. Then <prefix>c e k, type remember this, :w. Clock out later with <prefix>xo (on the task) or <C-c><C-x><C-o>. Expect: a child of the clocked task:

**** Note about An existing task
  [[file:...playground.org::*An existing task][An existing task]]
  remember this

Try: <prefix>c e R, answer Saved with a property. Expect: no window; Neovim jumps to the new entry in the playground:

** Saved with a property
:PROPERTIES:
:SOURCE:   capture
:END:

With time_prompt, the calendar opens first. The picked date replaces "now" for %t, %T, %u, %U and the date tree.

Try: <prefix>c e T; in the calendar press i, type fri 14:30, <CR>. Type at the dentist, :w. Expect:

** Appointment at the dentist
  <2026-10-02 Fri 14:30>

An unnarrowed capture inserts the text into the target buffer right away and shows the whole target file in the capture window, cursor at %?. <C-c><C-c> finishes and saves; <C-c><C-k> removes exactly what the capture inserted; :w only writes the file.

Try: <prefix>c e u, look around the whole playground, type ok, <Esc>, <C-c><C-c>. Expect: ** Seen in context ok as the last child of * Inbox.