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

Store a link to the current location. This is a global command 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). For Org files, if there is a ‘<<target>>’ at the cursor, the link points to the target. Otherwise it points to the current headline, either by text, or, if org-id.el is loaded, by ID property. For VM, Rmail, Wanderlust, MH-E, Gnus and BBDB buffers, the link will indicate the current article/entry. For W3 and W3M buffers, the link goes to the current URL. For IRC links, if you set the variable org-irc-link-to-logs to non-nil then C-c l will store a ‘file:/’ style link to the relevant point in the logs for the current conversation. Otherwise an ‘irc:/’ style link to the user/channel/server under the point will be stored. 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.

C-c C-l

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. 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, on the other hand, will help you to insert valid link prefixes like ‘http:’ or ‘ftp:’, including the prefixes defined through link abbreviations (see Link abbreviations). 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.
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.

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

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 commands 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 time stamp, 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.

mouse-2

mouse-1

On links, mouse-2 will open the link just as C-c C-o would. Under Emacs 22, also mouse-1 will 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 %

Push the current position onto the mark ring, to be able to return easily. Commands following an internal link do this automatically.

C-c &

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