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 selects 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 opens the Customize buffer for this complex variable.
A short string describing the template, shown during selection.
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 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 default template.
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
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.
Filing as child of this entry, or in the body of the entry.
Fast configuration if the target heading is unique in the file.
For non-unique headings, the full path is safer.
Use a regular expression to position point.
This target84 creates a heading in a date tree85 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 the
below for additional options.
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. You may also get this template string from a file86, or dynamically, from a function using either syntax:
(file "/path/to/template-file") (function FUNCTION-RETURNING-THE-TEMPLATE)
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 changes 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.
When set, jump to the captured entry when finished.
Set this to the number of lines to insert before and after the new item. Default 0, and the only other common value is 1.
Set this to the number of lines that should be inserted after the
new item. Overrides
:empty-lines for the number of lines
Set this to the number of lines that should be inserted before the
new item. Overrides
:empty-lines for the number lines inserted
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-resume. When setting both to non-
the current clock will run and the previous one will not be
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 calling
a C-1 prefix argument.
week to make a week tree instead of the month-day tree,
i.e., place the headings for each day under a heading with the
current ISO week. Use
month to group entries by month
only. Default is to group entries by day.
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 should be a string like ‘II-3’ meaning that the new line should become the third line before the second horizontal separator line.
If the target file was not yet visited when capture was invoked, kill the buffer again after capture is completed.
Do not save the target file after finishing the capture.
Org used to offer four different targets for date/week tree
capture. Now, Org automatically translates these to use
file+olp+datetree, applying the
properties. Please rewrite your date/week-tree targets using
file+olp+datetree since the older targets are now deprecated.
A date tree is an outline structure with years on the highest level, months or ISO weeks as sublevels and then dates on the lowest level. Tags are allowed in the tree structure.
When the file name is not absolute, Org assumes it is relative