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³⁸.

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³⁹. 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 (see 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⁴⁰. 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⁴¹, 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 (see Link abbreviations). If you press RET after inserting only the prefix, Org will offer specific completion support for some link types⁴² 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⁴³.

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⁴⁴.

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)))