org: Handling links
4.4 Handling links
==================
Org provides methods to create a link in the correct syntax, to insert
it into an Org file, and to follow the link.
‘C-c l (org-store-link)’
Store a link to the current location. This is a _global_ command
(you must create the key binding yourself) which can be used in any
buffer to create a link. The link will be stored for later
insertion into an Org buffer (see below). What kind of link will
be created depends on the current buffer:
Org mode buffers
For Org files, if there is a ‘<<target>>’ at the cursor, the link
points to the target. Otherwise it points to the current headline,
which will also be the description(1).
If the headline has a ‘CUSTOM_ID’ property, a link to this custom
ID will be stored. In addition or alternatively (depending on the
value of ‘org-id-link-to-org-use-id’), a globally unique ‘ID’
property will be created and/or used to construct a link(2). So
using this command in Org buffers will potentially create two
links: a human-readable 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.
Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus
Pretty much all Emacs mail clients are supported. The link will
point to the current article, or, in some GNUS buffers, to the
group. The description is constructed from the author and the
subject.
Web browsers: W3 and W3M
Here the link will be the current URL, with the page title as
description.
Contacts: BBDB
Links created in a BBDB buffer will point to the current entry.
Chat: IRC
For IRC links, if you set the option ‘org-irc-link-to-logs’ to ‘t’,
a ‘file:/’ style link to the relevant point in the logs for the
current conversation is created. Otherwise an ‘irc:/’ style link
to the user/channel/server under the point will be stored.
Other files
For any other files, the link will point to the file, with a search
string (
Search options) pointing to the contents of the
current line. If there is an active region, the selected words
will form the basis of the search 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 file types—see Custom searches. The
key binding ‘C-c l’ is only a suggestion—see Installation.
Agenda view
When the cursor is in an agenda view, the created link points to
the entry referenced by the current line.
‘C-c C-l (org-insert-link)’
Insert a link(3). 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 will be inserted into the buffer(4), 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
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/n’).
Completion support
Completion with <TAB> will help you to insert valid link prefixes
like ‘http:’ or ‘ftp:’, including the prefixes defined through link
abbreviations (Link abbreviations). If you press <RET>
after inserting only the PREFIX, Org will offer specific completion
support for some link types(5) For example, if you type ‘file
<RET>’, file name completion (alternative access: ‘C-u C-c C-l’,
see below) will be offered, 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’ prefix argument, a link to a
file will be inserted and 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.
‘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.
‘C-c C-o (org-open-at-point)’
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 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 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 the cursor 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-link-frame-setup’.
‘<RET>’
When ‘org-return-follows-link’ is set, ‘<RET>’ will also follow the
link at point.
‘mouse-2’
‘mouse-1’
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.
‘mouse-3’
Like ‘mouse-2’, but force file links to be opened with Emacs, and
internal links to be displayed in another window(6).
‘C-c C-x C-v (org-toggle-inline-images)’
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
prefix argument, also display images that do have a link
description. You can ask for inline images to be displayed at
startup by configuring the variable
‘org-startup-with-inline-images’(7).
‘C-c % (org-mark-ring-push)’
Push the current position onto the mark ring, to be able to return
easily. Commands following an internal link do this automatically.
‘C-c & (org-mark-ring-goto)’
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 (org-next-link)’
‘C-c C-x C-p (org-previous-link)’
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 ‘C-n’ and ‘C-p’
(add-hook 'org-load-hook
(lambda ()
(define-key org-mode-map "\C-n" 'org-next-link)
(define-key org-mode-map "\C-p" 'org-previous-link)))
---------- Footnotes ----------
(1) If the headline contains a timestamp, it will be removed from the
link and result in a wrong link—you should avoid putting timestamp in
the headline.
(2) The library ‘org-id.el’ must first be loaded, either through
‘org-customize’ by enabling ‘org-id’ in ‘org-modules’, or by adding
‘(require 'org-id)’ in your ‘.emacs’.
(3) Note that you don’t 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.
(4) 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’ prefix argument to ‘C-c C-l’, or configure the option
‘org-keep-stored-link-after-insertion’.
(5) This works by calling a special function
‘org-PREFIX-complete-link’.
(6) See the option ‘org-display-internal-link-with-indirect-buffer’
(7) with corresponding ‘#+STARTUP’ keywords ‘inlineimages’ and
‘noinlineimages’
Info Catalog
org: External links
org: Hyperlinks
org: Using links outside Org