Org provides methods to create a link in the correct syntax, to insert it into an Org file, and to follow the link.
The main function is
org-store-link, called with M-x org-store-link. Because of its importance, we suggest to bind it
to a widely available key (see Activation). It stores a link to the
current location. The link is stored for later insertion into an Org
buffer—see below. The kind of link that is created depends on the
For Org files, if there is a ‘<<target>>’ at point, the link points to the target. Otherwise it points to the current headline, which is also the description29.
If the headline has a ‘CUSTOM_ID’ property, store a link to this
custom ID. In addition or alternatively, depending on the value
org-link-to-org-use-id, create and/or use a globally unique
‘ID’ property for the link30. So using this command in Org
buffers potentially creates two links: a human-readable link from
the custom ID, and one that is globally unique and works even if
the entry is moved from file to file. Later, when inserting the
link, you need to decide which one to use.
Pretty much all Emacs mail clients are supported. The link
points to the current article, or, in some Gnus buffers, to the
group. The description is constructed according to the variable
org-email-link-description-format. By default, it refers to
the addressee and the subject, possibly truncated.
Here the link is the current URL, with the page title as the description.
Links created in a BBDB buffer point to the current entry.
For IRC links, if the variable
nil, create a ‘file’ style link to the relevant point in
the logs for the current conversation. Otherwise store an ‘irc’
style link to the user/channel/server under the point.
For any other file, the link points to the file, with a search string (see Search Options) pointing to the contents of the current line. If there is an active region, the selected words form the basis of the search string. You can write custom Lisp functions to select the search string and perform the search for particular file types (see Custom Searches).
You can also define dedicated links to other files. See Adding Hyperlink Types.
When point is in an agenda view, the created link points to the entry referenced by the current line.
From an Org buffer, the following commands create, navigate or, more generally, act on links.
Insert a link31. This prompts for a link to be inserted into the buffer. You can just type a link, using text for an internal link, or one of the link type prefixes mentioned in the examples above. The link is inserted into the buffer, along with a descriptive text32. If some text was selected at this time, it becomes the default description.
All links stored during the current session are part of the history for this prompt, so you can access them with UP and DOWN (or M-p, M-n).
Completion with TAB helps you to insert valid link prefixes like ‘http’ or ‘ftp’, including the prefixes defined through link abbreviations (see Link Abbreviations). If you press RET after inserting only the prefix, Org offers specific completion support for some link types33. For example, if you type f i l e RET—alternative access: C-u C-c C-l, see below—Org offers file name completion, and after b b d b RET you can complete contact names.
When C-c C-l is called with a C-u prefix argument, insert a link to a file. You may use file name completion to select the name of the file. The path to the file is inserted relative to the directory of the current Org file, if the linked file is in the current directory or in a 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 prefixes.
When point 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 launches a web browser for URL (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 point is on an internal link, this command runs the
corresponding search. When point is on the tags part of a
headline, it creates the corresponding tags view (see Matching tags and properties). If point is on a timestamp, it compiles
the agenda for that date. Furthermore, it visits text and remote
files in ‘file’ links with Emacs and select a suitable
application for local non-text files. Classification of files is
based on file extension only. See option
you want to override the default application and visit the file
with Emacs, use a C-u prefix. If you want to avoid
opening in Emacs, use a C-u C-u prefix.
If point is on a headline, but not on a link, offer all links in
the headline and entry text. If you want to setup the frame
configuration for following links, customize
org-return-follows-link is set, RET also
follows the link at point.
On links, mouse-1 and mouse-2 opens the link just as C-c C-o does.
Like mouse-2, but force file links to be opened with Emacs, and internal links to be displayed in another window34.
Push the current position onto the Org mark ring, to be able to return easily. Commands 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.
Move forward/backward to the next link in the buffer. At the limit of the buffer, 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 M-n and M-p.
(add-hook 'org-load-hook (lambda () (define-key org-mode-map "\M-n" 'org-next-link) (define-key org-mode-map "\M-p" 'org-previous-link)))
If the headline contains a timestamp, it is removed from the link, which results in a wrong link—you should avoid putting a timestamp in the headline.
The Org Id library must first be loaded, either through
org-customize, by enabling
org-modules, or by adding
‘(require 'org-id)’ in your Emacs init file.
Note that you do not have to use this command to insert a link. Links in Org are plain text, and you can type or paste them straight into the buffer. By using this 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 for later use,
use a triple C-u prefix argument to C-c C-l, or
configure the option
This works if a function has been defined in the
property of a link in
See the variable