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 description.
If the headline has a ‘CUSTOM_ID’ property, store a link to this
custom ID. In addition or alternatively, depending on the value of
org-id-link-to-org-use-id, create and/or use a globally unique
‘ID’ property for the link28. 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. The ‘ID’ property can be either a UUID (default) or a
timestamp, depending on
org-id-method. 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-link-email-description-format. By default, it refers to the
addressee and the subject.
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
org-irc-link-to-logs is non-
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 in File Links) 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 link29. 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 text30. 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 types31. 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
org-file-apps. If 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 window32.
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.
(with-eval-after-load 'org (define-key org-mode-map (kbd "M-n") #'org-next-link) (define-key org-mode-map (kbd "M-p") #'org-previous-link))
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
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
:complete property of a link