This is the official manual for the latest Org-mode release.
Table of Contents
220.127.116.11 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.
(file+olp+datetree "path/to/file" [ "Level 1 heading" ....])
- This target1
will create a heading in a date tree2
for today's date. If the optional outline path is given, the tree will be
built under the node it is pointing to, instead of at top level. Check out
:tree-type properties below for additional
(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.
- Prompt for a date/time to be used for date/week trees and when filling the
template. Without this property, capture uses the current date and time.
Even if this property has not been set, you can force the same behavior by
org-capture with a C-1 prefix argument.
- When `week', make a week tree instead of the month tree, i.e. place the
headings for each day under a heading with the current iso week.
- 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.