Org recognizes plain URIs, possibly wrapped within angle

brackets¹⁰, and activates them as clickable links.

The general link format, however, looks like this:

[[#link][DESCRIPTION]]

or alternatively

[[#link][LINK]]

Some \, [ and ] characters in the LINK part need to be "escaped", i.e., preceded by another \ character. More specifically, only the following characters must be escaped:

1. all [ and ] characters,
2. every \ character preceding either ] or [,
3. every \ character at the end of the link.

Functions inserting links (see Handling Links) properly escape ambiguous characters. You only need to bother about the rules above when inserting directly, or yanking, a URI within square brackets. When in doubt, you may use the function org-link-escape, which turns a link string into its escaped form.

Once a link in the buffer is complete, with all brackets present, Org changes the display so that DESCRIPTION is displayed instead of [[#link][DESCRIPTION]] and LINK is displayed instead of [[#link][LINK]]. Links are highlighted in the org-link face, which, by default, is an underlined face.

You can directly edit the visible part of a link. This can be either the LINK part, if there is no description, or the DESCRIPTION part otherwise. To also edit the invisible LINK part, use C-c C-l with point on the link (see Handling Links).

If you place point at the beginning or just behind the end of the displayed text and press BS, you remove the—invisible—bracket at that location(note: More accurately, the precise behavior depends on how point arrived there—see Invisible Text.). This makes the link incomplete and the internals are again displayed as plain text. Inserting the missing bracket hides the link internals again. To show the internal structure of all links, use the menu: Org → Hyperlinks → Literal links, customize org-link-descriptive, or use the literallinks startup option.

A link that does not look like a URL—i.e., does not start with a known scheme or a file name—refers to the current document. You can follow it with C-c C-o when point is on the link, or with a mouse click (see Handling Links).

Org provides several refinements to internal navigation within a document. Most notably, a construct like [[#my-custom-id]] specifically targets the entry with the CUSTOM_ID property set to my-custom-id. Also, an internal link looking like =[[*Some

section]]= points to a headline with the name Some section ¹¹.

When the link does not belong to any of the cases above, Org looks for a dedicated target: the same string in double angular brackets, like <<My Target>>.

If no dedicated target exists, the link tries to match the exact name of an element within the buffer. Naming is done, unsurprisingly, with the NAME keyword, which has to be put in the line before the element it refers to, as in the following example

#+NAME: My Target
| a  | table      |
|----+------------|
| of | four cells |

Ultimately, if none of the above succeeds, Org searches for a headline that is exactly the link text but may also include a TODO keyword and tags, or initiates a plain text search, according to the value of org-link-search-must-match-exact-headline.

Note that you must make sure custom IDs, dedicated targets, and names are unique throughout the document. Org provides a linter to assist you in the process, if needed. See Org Syntax.

During export, internal links are used to mark objects and assign them a number. Marked objects are then referenced by links pointing to them. In particular, links without a description appear as the number assigned to the marked object(note: When targeting a NAME keyword, the CAPTION keyword is mandatory in order to get proper numbering (see Captions).). In the following excerpt from an Org buffer

1. one item
#+html: <span id="target"></span>
2. another item
Here we refer to item [[#target][target]].

The last sentence will appear as Here we refer to item 2 when exported.

In non-Org files, the search looks for the words in the link text. In the above example, the search would be for target.

Following a link pushes a mark onto Org's own mark ring. You can return to the previous position with C-c &. Using this command several times in direct succession goes back to positions recorded earlier.

Org can automatically turn any occurrences of certain target names in normal text into a link. So without explicitly creating a link, the text connects to the target radioing its position. Radio targets are enclosed by triple angular brackets. For example, a target <<<My Target>>> causes each occurrence of my target in normal text to become activated as a link. The Org file is scanned automatically for radio targets only when the file is first loaded into Emacs. To update the target list during editing, press C-c C-c with point on or at a target.

Org supports links to files, websites, Usenet and email messages, BBDB database entries and links to both IRC conversations and their logs. External links are URL-like locators. They start with a short identifying string followed by a colon. There can be no space after the colon.

Here is the full set of built-in link types:

file

File links. File name may be remote, absolute, or relative. As a special case, the "file" prefix may be omitted if the file name is complete, e.g., it starts with ./ or /.

attachment

Same as file links but for files and folders attached to the current node (see Attachments). Attachment links are intended to behave exactly as file links but for files relative to the attachment directory.

bbdb

Link to a BBDB record, with possible regexp completion.

docview

Link to a document opened with DocView mode. You may specify a page number.

doi

Link to an electronic resource, through its handle.

elisp

Execute an Elisp command upon activation.

gnus, rmail, mhe

Link to messages or folders from a given Emacs MUA.

help

Display documentation of a symbol in *Help* buffer.

http, https

Web links.

id

Link to a specific headline by its ID property, in an Org file.

info

Link to an Info manual, or to a specific node.

irc

Link to an IRC channel.

mailto

Link to message composition.

news

Usenet links.

shell

Execute a shell command upon activation.

shortdoc

Link to short documentation summary for an Emacs Lisp function group. (note: You can run M-x shortdoc-display-group to list all known documentation groups.) For more information, see Name Help and Documentation Groups.

For file: and id: links, you can additionally specify a line number, or a text search string, separated by ::. In Org files, you may link to a headline name, a custom ID, or a code reference instead.

The following table illustrates the link types above, along with their options:

On top of these built-in link types, additional ones are available through the org-contrib repository (see Installation). For example, these links to VM or Wanderlust messages are available when you load the corresponding libraries from the org-contrib repository:

For information on customizing Org to add new link types, see Adding Hyperlink Types.

A link should be enclosed in double brackets and may contain descriptive text to be displayed instead of the URL (see Link Format), for example:

[[https://www.gnu.org/software/emacs/][GNU Emacs]]

If the description is a file name or URL that points to an image, HTML export (see HTML Export) inlines the image as a clickable button. If there is no description at all and the link points to an image, that image is inlined into the exported HTML file.

Org also recognizes external links amid normal text and activates them as links. If spaces must be part of the link (for example in bbdb:R.*Stallman), or if you need to remove ambiguities about the end of the link, enclose the link in square or angular brackets.

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 binding 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 current buffer:

Org mode buffers

For Org files, if there is a = at point, the link points to the target. If there is a named block (using =#+name:) at point, the link points to that name. 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 link(note: The org-id library must first be loaded, either through org-customize, by enabling id in org-modules, or by adding (require 'org-id) in your Emacs init file.). 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.

When org-id-link-consider-parent-id is t~(note: Also, ~org-link-context-for-files and org-id-link-use-context should be both enabled (which they are, by default).), parent ID properties are considered. This allows linking to specific targets, named blocks, or headlines (which may not have a globally unique ID themselves) within the context of a parent headline or file which does.

For example, given this org file:

* Parent
:PROPERTIES:
:ID: abc
:END:
** Child 1
** Child 2

Storing a link with point at "Child 1" will produce a link <id:abc::*Child 1>, which precisely links to the "Child 1" headline even though it does not have its own ID.

Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus

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.

Web browsers: W3M and EWW

Here the link is the current URL, with the page title as the description.

Contacts: BBDB

Links created in a BBDB buffer point to the current entry.

Chat: IRC

For IRC links, if the variable org-irc-link-to-logs is non-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.

Other files

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.

Agenda view

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.

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 is inserted into the buffer, along with

a descriptive text¹⁴. If some text was selected at this time, it 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, M-n).

Completion support

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 types(note: This works if a function has been defined in the :complete property of a link in org-link-parameters.). 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.

C-u C-c C-l

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 subdirectory 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 point on existing link)

When point 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 launches a web browser for URL (using browse-url-at-point), runs VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for the corresponding links, and executes 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 selects 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, Org offers all links in the headline and entry text. If you want to set up the frame configuration for following links, customize org-link-frame-setup.

RET

When org-return-follows-link is set, RET also follows the link at point.

mouse-2 or mouse-1

On links, mouse-1 and mouse-2 open the link just as C-c C-o does.

mouse-3

Like mouse-2, but force file links to be opened with Emacs, and internal links to be displayed in another window(note: See the variable org-link-use-indirect-buffer-for-internals.).

C-c % (org-mark-ring-push)

Push the current position onto the Org 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/previous 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))

You can insert and follow links that have Org syntax not only in Org, but in any Emacs buffer. For this, Org provides two functions: org-insert-link-global and org-open-at-point-global.

You might want to bind them to globally available keys. See Activation for some advice.

Long URLs can be cumbersome to type, and often many similar links are needed in a document. For this you can use link abbreviations. An abbreviated link looks like this

[[linkword:tag][description]]

where the tag is optional. The linkword must be a word, starting with a letter, followed by letters, numbers, -, and _. Abbreviations are resolved according to the information in the variable org-link-abbrev-alist that relates the linkwords to replacement text. Here is an example:

(setq org-link-abbrev-alist
      '(("bugzilla"        . "https://10.1.2.9/bugzilla/show_bug.cgi?id=")
        ("Nu Html Checker" . "https://validator.w3.org/nu/?doc=%h")
        ("duckduckgo"      . "https://duckduckgo.com/?q=%s")
        ("omap"            . "https://nominatim.openstreetmap.org/search?q=%s&polygon=1")
        ("ads"             . "https://ui.adsabs.harvard.edu/search/q=%20author%3A\"%s\"")))

If the replacement text contains the string %s, it is replaced with the tag. Using %h instead of %s percent-encodes the tag (see the example above, where we need to encode the URL parameter). Using %(my-function) passes the tag to a custom Lisp function, and replaces it by the resulting string.

If the replacement text does not contain any specifier, it is simply appended to the string in order to create the link.

Instead of a string, you may also specify a Lisp function to create the link. Such a function will be called with the tag as the only argument.

With the above setting, you could link to a specific bug with [[bugzilla:129]], search the web for OrgMode with [[duckduckgo:OrgMode]], show the map location of the Free Software Foundation [[omap:31 Milk Street, Boston]] or of Carsten's office [[omap:Science Park 904, Amsterdam, The Netherlands]] and find out what the Org author is doing besides Emacs hacking with [[ads:Dominik,C]].

If you need special abbreviations just for a single Org buffer, you can define them in the file with

#+LINK: bugzilla  https://10.1.2.9/bugzilla/show_bug.cgi?id=
#+LINK: duckduckgo https://duckduckgo.com/?q=%s
#+LINK: "Nu Html Checker" https://validator.w3.org/nu/?doc=%h

The abbreviations containing spaces must be quoted.

In-buffer completion (see Completion) can be used after [ to complete link abbreviations. You may also define a Lisp function that implements special (e.g., completion) support for inserting such a link with C-c C-l. Such a function should not accept any arguments, and should return the full link with a prefix. You can set the link completion function like this:

(org-link-set-parameter "type" :complete #'some-completion-function)

File links can contain additional information to make Emacs jump to a particular location in the file when following a link. This can be a line number or a search option after a double colon(note: For backward compatibility, line numbers can also follow a single colon.). For example, when the command org-store-link creates a link (see Handling Links) to a file, it encodes the words in the current line as a search string that can be used to find this line back later when following the link with C-c C-o.

Note that all search options apply for Attachment and ID links in the same way that they apply for File links.

Here is the syntax of the different ways to attach a search to a file link, together with explanations for each:

[[file:~/code/main.c::255]]
[[file:~/xx.org::My Target]]
[[file:~/xx.org::*My Target]]
[[file:~/xx.org::#my-custom-id]]
[[file:~/xx.org::/regexp/]]
[[attachment:main.c::255]]

255

Jump to line 255.

My Target

Search for a link target <<My Target>>, or do a text search for my target, similar to the search in internal links, see Internal Links. In HTML export (see HTML Export), such a file link becomes an HTML reference to the corresponding named anchor in the linked file.

*My Target

In an Org file, restrict search to headlines.

#my-custom-id

Link to a heading with a CUSTOM_ID property

/REGEXP/

Do a regular expression search for REGEXP (see Regular Expressions). This uses the Emacs command occur to list all matches in a separate window. If the target file is in Org mode, org-occur is used to create a sparse tree with the matches.

As a degenerate case, a file link with an empty file name can be used to search the current file. For example, [[file:::find me]] does a search for find me in the current file, just as [[#find-me][find me]] would.

The default mechanism for creating search strings and for doing the actual search related to a file link may not work correctly in all cases. For example, BibTeX database files have many entries like year="1993" which would not result in good search strings, because the only unique identification for a BibTeX entry is the citation key.

If you come across such a problem, you can write custom functions to set the right search string for a particular file type, and to do the search for the string in the file. Using add-hook, these functions need to be added to the hook variables org-create-file-search-functions and org-execute-file-search-functions. See the docstring for these variables for more information. Org actually uses this mechanism for BibTeX database files, and you can use the corresponding code as an implementation example. See the file ol-bibtex.el.

1. 10

   Plain URIs are recognized only for a well-defined set of schemes. See External Links. Unlike URI syntax, they cannot contain parenthesis or white spaces, either. URIs within angle brackets have no such limitation.

   Backrefs: 1

2. 11

   To insert a link targeting a headline, in-buffer completion can be used. Just type a star followed by a few optional letters into the buffer and press M-TAB. All headlines in the current buffer are offered as completions.

   Backrefs: 1

3. 12

   The actual behavior of the search depends on the value of the variable org-link-search-must-match-exact-headline. If its value is nil, then a fuzzy text search is done. If it is t, then only the exact headline is matched, ignoring spaces and statistic cookies. If the value is query-to-create, then an exact headline is searched; if it is not found, then the user is queried to create it.

   Backrefs: 1

4. 13

   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.

   Backrefs: 1

5. 14

   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 org-link-keep-stored-after-insertion.

   Backrefs: 1