This is the official manual for the latest Org-mode release.
Table of Contents
188.8.131.52 Template elements
Now lets look at the elements of a template definition. Each entry in
org-capture-templates is a list with the following items:
- The keys that will select the template, as a string, characters
only, for example
"a" for a template to be selected with a
single key, or
"bt" for selection with two keys. When using
several keys, keys using the same prefix key must be sequential
in the list and preceded by a 2-element entry explaining the
prefix key, for example
("b" "Templates for marking stuff to buy")
If you do not define a template for the C key, this key will
be used to open the customize buffer for this complex variable.
- A short string describing the template, which will be shown during
- The type of entry, a symbol. Valid values are:
- An Org mode node, with a headline. Will be filed as the child of the target
entry or as a top-level entry. The target file should be an Org mode file.
- A plain list item, placed in the first plain list at the target
location. Again the target file should be an Org file.
- A checkbox item. This only differs from the plain list item by the
- a new line in the first table at the target location. Where exactly the
line will be inserted depends on the properties
:table-line-pos (see below).
- Text to be inserted as it is.
- Specification of where the captured item should be placed. In Org mode
files, targets usually define a node. Entries will become children of this
node. Other types will be added to the table or list in the body of this
node. Most target specifications contain a file name. If that file name is
the empty string, it defaults to
org-default-notes-file. A file can
also be given as a variable or as a function called with no argument. When
an absolute path is not specified for a target, it is taken as relative to
Valid values are:
- Text will be placed at the beginning or end of that file.
(id "id of existing org entry")
- Filing as child of this entry, or in the body of the entry.
(file+headline "path/to/file" "node headline")
- Fast configuration if the target heading is unique in the file.
(file+olp "path/to/file" "Level 1 heading" "Level 2" ...)
- For non-unique headings, the full path is safer.
(file+regexp "path/to/file" "regexp to find location")
- Use a regular expression to position the cursor.
- Will create a heading in a date tree for today's date1.
- Will create a heading in a date tree, but will prompt for the date.
- Will create a heading in a week tree for today's date. Week trees are sorted
by week and not by month unlike datetrees.
- Will create a heading in a week tree, but will prompt for the date.
(file+function "path/to/file" function-finding-location)
- A function to find the right location in the file.
- File to the entry that is currently being clocked.
- Most general way: write your own function which both visits
the file and moves point to the right location.
- The template for creating the capture item. If you leave this empty, an
appropriate default template will be used. Otherwise this is a string with
escape codes, which will be replaced depending on time and context of the
capture call. The string with escapes may be loaded from a template file,
using the special syntax
(file "path/to/template"). See below for
- The rest of the entry is a property list of additional options.
Recognized properties are:
- Normally new captured information will be appended at
the target location (last child, last table line, last list item...).
Setting this property will change that.
- When set, do not offer to edit the information, just
file it away immediately. This makes sense if the template only needs
information that can be added automatically.
- Set this to the number of lines to insert
before and after the new item. Default 0, only common other value is 1.
- Start the clock in this item.
- Keep the clock running when filing the captured entry.
- If starting the capture interrupted a clock, restart that clock when finished
with the capture. Note that
:clock-keep has precedence over
:clock-resume. When setting both to
t, the current clock will
run and the previous one will not be resumed.
- Do not narrow the target buffer, simply show the full buffer. Default is to
narrow it so that you only see the new material.
- Specification of the location in the table where the new line should be
inserted. It can be a string, a variable holding a string or a function
returning a string. The string should look like
"II-3" meaning that
the new line should become the third line before the second horizontal
- If the target file was not yet visited when capture was invoked, kill the
buffer again after capture is completed.