Chapter 4: Hyperlinks
string. If the automatically created link is not working correctly or accurately
enough, you can write custom functions to select the search string and to do the
search for particular ﬁle types—seeSection4.8[Customsearches],page45. The
key binding C-c l is only a suggestion—seeSection1.2[Installation],page2.
When the cursor is in an agenda view, the created link points to the entry
referenced by the current line.
Insert a link
. This prompts for a link to be inserted into the buﬀer. You can
just type a link, using text for an internal link, or one of the link type preﬁxes
mentioned in the examples above. The link will be inserted into the buﬀer
along with a descriptive text. If some text was selected when this command is
called, the selected text becomes the default description.
Inserting stored links
Alllinks storedduring thecurrent session are part of thehistory for this prompt,
so you can access them with up and down (or M-p/n).
Completion with TAB will help you to insert valid link preﬁxes like ‘http:’ or
‘ftp:’, including the preﬁxes deﬁnedthrough link abbreviations (seeSection4.6
[Link abbreviations], page 44). IfyoupressRETafterinsertingonlythepreﬁx,
Org will oﬀer speciﬁc completion support for some link types
For example, if
you type file RET, ﬁle name completion (alternative access: C-u C-c C-l, see
below) will be oﬀered, and after bbdb RET you can complete contact names.
C-u C-c C-l
When C-c C-l is called with a C-u preﬁx argument, a link to a ﬁle will be
inserted and you may use ﬁle name completion to select the name of the ﬁle.
The path to the ﬁle is inserted relative to the directory of the current Org ﬁle, if
the linked ﬁle is inthe current directory or ina sub-directory of it, or if the path
is written relative to the current directory using ‘../’. Otherwise an absolute
path is used, if possible with ‘~/’ for your home directory. You can force an
absolute path with two C-u preﬁxes.
C-c C-l (with cursor on existing link)
When the cursor is on an existing link, C-c C-l allows you to edit the link and
description parts of the link.
Open link at point. This will launch a web browser for URLs (using
browse-url-at-point), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
the corresponding links, and execute the command in a shell link. When the
Note that you don’t have to use this command to insert a link. Links in Orgare plain text, and you can
type or paste them straight into the buﬀer. By usingthis command, the links are automatically enclosed
in double brackets, and you will be asked for the optional descriptive text.
After insertion of a stored link, the link will be removed from the list of stored links. To keep it in the
list later use, use a triple C-u preﬁx argument to C-c C-l, or conﬁgure the option org-keep-stored-
This works by calling a special function org-PREFIX-complete-link.
Chapter 4: Hyperlinks
cursor is on an internal link, this command runs the corresponding search.
When the cursor is on a TAG list in a headline, it creates the corresponding
TAGS view. If the cursor is on a timestamp, it compiles the agenda for that
date. Furthermore, it will visit text and remote ﬁles in ‘file:’ links with
Emacs and select a suitable application for local non-text ﬁles. Classiﬁcation
of ﬁles is based on ﬁle extension only. See option org-file-apps. If you want
to override the default application and visit the ﬁle with Emacs, use a C-u
preﬁx. If you want to avoid opening in Emacs, use a C-u C-u preﬁx.
If the cursor is on a headline, but not on a link, oﬀer all links in the headline
and entry text. If you want to setup the frame conﬁguration for following
links, customize org-link-frame-setup.
When org-return-follows-link is set, RET will also follow the link at point.
On links, mouse-2 will open the link just as C-c C-o would. Under Emacs 22
and later, mouse-1 will also follow a link.
Like mouse-2, but force ﬁle links to be opened with Emacs, and internal links
to be displayed in another window
C-c C-x C-v
Toggle the inline display of linked images. Normally this will only inline images
that have no description part in the link, i.e., images that will also be inlined
during export. When called with a preﬁx argument, also display images that
do have a link description. You can ask for inline images to be displayed at
startup by conﬁguring the variable org-startup-with-inline-images
Push the current position onto the mark ring, to be able to return easily. Com-
mands following an internal link do this automatically.
Jump back to a recorded position. A position is recorded by the commands
following internal links, and by C-c %. Using this command several times in
direct succession moves through a ring of previously recorded positions.
C-c C-x C-n
C-c C-x C-p
Move forward/backward to the next link in the buﬀer. At the limit of the
buﬀer, the search fails once, and then wraps around. The key bindings for this
are really too long; you might want to bind this also to C-n and C-p
(define-key org-mode-map "\C-n" 'org-next-link)
(define-key org-mode-map "\C-p" 'org-previous-link)))
See the option org-display-internal-link-with-indirect-buffer
with corresponding #+STARTUP keywords inlineimages and noinlineimages
Chapter 4: Hyperlinks
4.5 Using links outside Org
You can insert and follow links that have Org syntax not only in Org, but in any Emacs
buﬀer. For this, you should create two global commands, like this (please select suitable
global keys yourself):
(global-set-key "\C-c L" 'org-insert-link-global)
(global-set-key "\C-c o" 'org-open-at-point-global)
4.6 Link abbreviations
Long URLs can be cumbersome to type, and often many similar links are needed in a
document. For this you can use link abbreviations. An abbreviated link looks like this
where the tag is optional. The linkword must be a word, starting with a letter, followed by
letters, numbers, ‘-’, and ‘_’. Abbreviations are resolved according to the information in
the variable org-link-abbrev-alist that relates the linkwords to replacement text. Here
is an example:
'(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
If the replacement text contains the string ‘%s’, it will be replaced with the tag. Using
‘%h’ instead of ‘%s’ will url-encode the tag (see the example above, where we need to encode
the URL parameter.) Using ‘%(my-function)’ will pass the tag to a custom function, and
replace it by the resulting string.
If the replacement text doesn’t contain any speciﬁer, it will simply be appended to the
string in order to create the link.
Instead of a string, you may also specify a function that will be called with the tag as
the only argument to create the link.
With the above setting, you could link to a speciﬁc bug with [[bugzilla:129]],
search the web for ‘OrgMode’ with [[google:OrgMode]], show the map location of the
Free Software Foundation [[gmap:51 Franklin Street, Boston]] or of Carsten oﬃce
[[omap:Science Park 904, Amsterdam, The Netherlands]] and ﬁnd out what the Org
author is doing besides Emacs hacking with [[ads:Dominik,C]].
If you need special abbreviations just for a single Org buﬀer, you can deﬁne them in the
#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
In-buﬀer completion (see e Section 15.1 [Completion], page 224) can be used after ‘[’ to
complete link abbreviations. You may also deﬁne a function org-PREFIX-complete-link
that implements special (e.g., completion) support for inserting such a link with C-c C-l.
Such a function should not accept any arguments, and return the full link with preﬁx.
Chapter 4: Hyperlinks
4.7 Search options in ﬁle links
File links cancontainadditional informationto make Emacs jump toa particular locationin
the ﬁle when following a link. This can be a line number or a search option after a double
colon. For example, when the command C-c l creates a link (see e Section4.4[Handling
links], page 41)toaﬁle,itencodesthewordsinthecurrentlineasasearchstringthatcan
be used to ﬁnd this line back later when following the link with C-c C-o.
Here is the syntax of the diﬀerent ways to attach a search to a ﬁle link, together with
Jump to line 255.
My Target Search for a link target ‘<<My Target>>’, or do a text search for ‘my target’,
similar to the searchin internallinks, seeSection4.2[Internallinks],page38. In
HTML export (seeSection12.6[HTMLexport],page149), such a ﬁle link will
become an HTML reference to the corresponding named anchor in the linked
In an Org ﬁle, restrict search to headlines.
Link to a heading with a CUSTOM_ID property
/regexp/ Do a regular expression search for regexp. This uses the Emacs command
occur to list all matches in a separate window. If the target ﬁle is in Org
mode, org-occur is used to create a sparse tree with the matches.
As a degenerate case, a ﬁle link with an empty ﬁle name can be used to search the
current ﬁle. For example, [[file:::find me]] does a search for ‘find me’ in the current
ﬁle, just as ‘[[find me]]’ would.
4.8 Custom Searches
The default mechanism for creating search strings and for doing the actual search related
to a ﬁle link may not work correctly in all cases. For example, BibT
Xdatabase ﬁles have
many entries like ‘year="1993"’ which would not result in good search strings, because the
only unique identiﬁcation for a BibT
Xentry is the citation key.
If you come across such a problem, you can write custom functions to set the right
search string for a particular ﬁle type, and to do the search for the string in the ﬁle.
Using add-hook, these functions need to be added to the hook variables org-create-
file-search-functions and org-execute-file-search-functions. See the docstring
for these variables for more information. Org actually uses this mechanism for BibT
database ﬁles, and you can use the corresponding code as an implementation example. See
the ﬁle org-bibtex.el.
For backward compatibility, line numbers can also follow a single colon.
Chapter 5: TODO items
5 TODO items
Org mode does not maintain TODO lists as separate documents
. Instead, TODO items
are an integral part of the notes ﬁle, because TODO items usually come up while taking
notes! With Org mode, simply mark any entry in a tree as being a TODO item. In this way,
information is not duplicated, and the entire context from which the TODO item emerged
is always present.
Of course, this technique for managing TODO items scatters them throughout your
notes ﬁle. Org mode compensates for this by providing methods to give you an overview of
all the things that you have to do.
5.1 Basic TODO functionality
Any headline becomes a TODO item when it starts with the word ‘TODO’, for example:
*** TODO Write letter to Sam Fortune
The most important commands to work with TODO entries are:
Rotate the TODO state of the current item among
,-> (unmarked) -> TODO -> DONE --.
If TODOkeywords have fast access keys (seeSection5.2.4[FastaccesstoTODO
states], page 49), you u will be prompted for a TODO keyword through the
fast selection interface; this is the default behavior when org-use-fast-todo-
selection is non-nil.
The same rotation can also be done “remotely” from the timeline and agenda
buﬀers with the t command key (see e Section 10.5 [Agenda commands],
C-u C-c C-t
When TODO keywords have no selection keys, select a speciﬁc keyword using
completion; otherwise force cycling through TODO states with no prompt.
When org-use-fast-todo-selection is set to prefix, use the fast selection
S-right / S-left
Select the following/preceding TODO state, similar to cycling. Useful mostly if
more than two TODO states are possible (seeSection5.2[TODOextensions],
page 47). Seealso Section 15.10.2 [Conﬂicts], page 234,foradiscussionofthe
interaction with shift-selection-mode. See also the variable org-treat-S-
C-c / t
View TODO items in a sparse tree (seeSection2.6[Sparse trees],page 11).
Folds the entire buﬀer, but shows all TODO items (with not-DONE state) and
Of course, you can make a document that contains only long lists of TODO items, but this is not
Chapter 5: TODO items
the headings hierarchy above them. With a preﬁx argument (or by using C-c
/T), search for a speciﬁc TODO. You will be prompted for the keyword, and
you can also give a list of keywords like KWD1|KWD2|... to list entries that
match any one of these keywords. With a numeric preﬁx argument N, show the
tree for the Nth keyword in the option org-todo-keywords. With two preﬁx
arguments, ﬁnd all TODO states, both un-done and done.
C-c a t
Show the global TODO list. Collects the TODO items (with not-DONE
states) from all agenda ﬁles (see Chapter 10[Agenda views], , page100) into
a single buﬀer. The new buﬀer will be in agenda-mode, which provides
commands to examine and manipulate the TODO entries from the new buﬀer
(seeSection10.5[Agendacommands], page 113). See e Section 10.3.2 [Global
TODO list], page 104,formoreinformation.
Insert a new TODO entry below the current one.
Changing a TODO state can also trigger tag changes. See the docstring of the option
org-todo-state-tags-triggers for details.
5.2 Extended use of TODO keywords
By default, marked TODO entries have one of only two states: TODO and DONE. Org
mode allows you to classify TODO items in more complex ways with TODO keywords
(stored in org-todo-keywords). With special setup, the TODO keyword system can work
diﬀerently in diﬀerent ﬁles.
Note that tags are another way to classify headlines in general and TODO items in
5.2.1 TODO keywords as workﬂow states
You can use TODO keywords to indicate diﬀerent sequential states in the process of working
on an item, for example
'((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
The vertical bar separates the TODO keywords (states that need action) from the DONE
states (which need no further action). If you don’t provide the separator bar, the last state
is used as the DONE state. With this setup, the command C-c C-t will cycle an entry
from TODO to FEEDBACK, then to VERIFY, and ﬁnally to DONE and DELEGATED.
You may also use a numeric preﬁx argument to quickly select a speciﬁc state. For example
C-3 C-c C-t will change the state immediately to VERIFY. Or you can use S-left to
go backward through the sequence. If you deﬁne many keywords, you can use in-buﬀer
completion (see Section15.1[Completion], page 224) or even a special one-key selection
scheme (seeSection5.2.4[FastaccesstoTODOstates],page49) to insert these words into
the buﬀer. Changing a TODO state can be logged with a timestamp, see e Section5.3.2
[Tracking TODO state changes], page 52,formoreinformation.
Changing this variable only becomes eﬀective after restarting Org mode in a buﬀer.
Chapter 5: TODO items
5.2.2 TODO keywords as types
The second possibility is to use TODO keywords to indicate diﬀerent types of action items.
For example, you might want to indicate that items are for “work” or “home”. Or, when
you work with several people on a single project, you might want to assign action items
directly to persons, by using their names as TODO keywords. This would be set up like
(setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
In this case, diﬀerent keywords do not indicate a sequence, but rather diﬀerent types.
So the normal work ﬂow would be to assign a task to a person, and later to mark it DONE.
Org mode supports this style by adapting the workings of the command C-c C-t
used several times in succession, it will still cycle through all names, in order to ﬁrst select
the right type for a task. But when you return to the item after some time and execute
C-c C-t again, it will switch from any name directly to DONE. Use preﬁx arguments or
completion to quickly select a speciﬁc name. You can also review the items of a speciﬁc
TODO type in a sparse tree by using a numeric preﬁx to C-c / t. For example, to see all
things Lucy has to do, you would use C-3 C-c / t. To collect Lucy’s items from all agenda
ﬁles into a single buﬀer, you would use the numeric preﬁx argument as well when creating
the global TODO list: C-3 C-c a t.
5.2.3 Multiple keyword sets in one ﬁle
Sometimes you may want to use diﬀerent sets of TODO keywords in parallel. For example,
you may want to have the basic TODO/DONE, but also a workﬂow for bug ﬁxing, and a
separate state indicating that an item has been canceled (so it is not DONE, but also does
not require action). Your setup would then look like this:
'((sequence "TODO" "|" "DONE")
(sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
(sequence "|" "CANCELED")))
The keywords should all be diﬀerent, this helps Org mode to keep track of which sub-
sequence should be used for a given entry. In this setup, C-c C-t only operates within a
subsequence, so it switches from DONE to (nothing) to TODO, and from FIXED to (nothing)
to REPORT. Therefore you need a mechanism to initially select the correct sequence. Be-
sides the obvious ways like typing a keyword or using completion, you may also apply the
C-u C-u C-c C-t
C-S-left These keys jump from one TODO subset to the next. In the above example,
C-u C-u C-c C-t or C-S-right would jump from TODO or DONE to REPORT, and
any of the words in the second row to CANCELED. Note that the C-S- key
binding conﬂict with shift-selection-mode (see e Section15.10.2[Conﬂicts],
This is also true for the t command in the timeline and agenda buﬀers.
Chapter 5: TODO items
S-left and S-right andwalk throughall keywords from allsets, so for example
S-right would switch from DONE to REPORT in the example above. See also
Section 15.10.2 [Conﬂicts], page 234, for r adiscussion n of the interactionwith
5.2.4 Fast access to TODO states
If you would like to quickly change an entry to an arbitrary TODO state instead of cycling
through the states, you can set up keys for single-letter access to the states. This is done
by adding the selection character after each keyword, in parentheses
. For example:
'((sequence "TODO(t)" "|" "DONE(d)")
(sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
(sequence "|" "CANCELED(c)")))
If you then press C-c C-t followed by the selection key, the entry will be switched to
this state. SPC can be used to remove any TODO keyword from an entry.
5.2.5 Setting up keywords for individual ﬁles
It can be very useful to use diﬀerent aspects of the TODO mechanism in diﬀerent ﬁles.
For ﬁle-local settings, you need to add special lines to the ﬁle which set the keywords and
interpretation for that ﬁle only. For example, to set one of the two examples discussed
above, you need one of the following lines anywhere in the ﬁle:
#+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
(you may also write #+SEQ_TODO to be explicit about the interpretation, but it means the
same as #+TODO), or
#+TYP_TODO: Fred Sara Lucy Mike | DONE
Asetup for using several sets in parallel would be:
#+TODO: TODO | DONE
#+TODO: REPORT BUG KNOWNCAUSE | FIXED
#+TODO: | CANCELED
To make sure you are using the correct keyword, type ‘#+’ into the buﬀer and then use
Remember that the keywords after the vertical bar (or the last keyword if no bar is
there) must always mean that the item is DONE (although you may use a diﬀerent word).
After changing one of these lines, use C-c C-c with the cursor still in the line to make the
changes known to Org mode
All characters are allowed except @^!, which have a special meaning here.
Check also theoption org-fast-tag-selection-include-todo, it allows you to change the TODO state
through the tags interface (seeSection 6.2[Settingtags],page59), in case you like to mingle the two
concepts. Note that this means you need to come up with unique keys across both sets of keywords.
Org mode parses these lines only when Org mode is activated after visiting a ﬁle. C-c C-c with the
cursor in a line starting with ‘#+’ is simply restarting Org mode for the current buﬀer.
Documents you may be interested
Documents you may be interested