Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Hyperlinks

Notes become far more useful once they point at each other and at the material they talk about. An Org file can link to another headline in the same file, to a line in a source file, to a web page, to an email, or to a section of an Info manual, and the syntax is the same for all of them. A single command follows any of these links, and a single pair of commands creates them.

This chapter starts with the link syntax, then covers links inside one document, links to the outside world, and the everyday cycle of storing, inserting and following links. It ends with the tools for heavy users: abbreviations, search options, stable IDs that survive refiling, and link types of your own.

A link in Org is a piece of text that Org recognizes as a reference and makes clickable. The general form uses double square brackets:

[[LINK][DESCRIPTION]]
[[LINK]]

The first part, LINK, says where the link goes. The optional second part, DESCRIPTION, is the text a reader sees. Once both closing brackets are present, Org hides the brackets and the target and shows only the description (or the target itself, when there is no description). The visible text uses the org-link face, which is underlined by default.

Figure 5.1: Everything before ][ tells Org where to go, and only the description is shown once the link is complete.

The link part itself has up to three components:

ComponentExampleMeaning
Typefile:Which handler resolves the link. Without a known type, the link is internal.
Pathprojects.orgWhat the handler should open: a file name, a URL, an ID, and so on.
Search option::#redesignWhere to go inside the target. Valid for file:, attachment: and id: links.

Org also activates plain URLs that appear in running text, such as https://orgmode.org, without any brackets. You can wrap them in angle brackets (<https://orgmode.org>) when the end of the URL would otherwise be ambiguous, for example when it is followed by punctuation or when it contains spaces.

Because the target is hidden, editing a link needs a little care. You can edit the visible text directly. To change the hidden target, put point on the link and press C-c C-l: Org prompts for the link and then for the description, both prefilled with the current values.

If you delete one of the hidden closing brackets (pressing backspace just after the link does this), the link becomes incomplete and Org shows the raw text again. Typing the bracket back hides it once more. To see every link in its literal form, toggle the display with M-x org-toggle-link-display, set org-link-descriptive to nil, or put the startup option in the file:

#+STARTUP: literallinks

Escaping brackets

A link target can contain square brackets, for example a file name like [draft] plan.org. Inside the link part, every [ and ] must be preceded by a backslash, and so must any backslash that comes before a bracket or at the end of the link.

The link commands do this for you; you only need to think about it when you type or paste a raw link. The function org-link-escape produces the escaped form. Evaluated in Emacs 31.1 with Org 9.8.13:

(org-link-escape "file:notes/[draft] plan.org")
(org-link-make-string "file:notes/[draft] plan.org" "Draft plan")
file:notes/\[draft\] plan.org
[[file:notes/\[draft\] plan.org][Draft plan]]

An internal link is a link whose target does not start with a known link type. It refers to something in the current document. Internal links let a long document cross-reference itself, and on export they become anchors and, where it makes sense, numbers.

Org offers four precise kinds of internal target and one fallback:

You writeIt targets
[[#install]]The entry whose CUSTOM_ID property is install.
[[*Troubleshooting]]The headline whose text is Troubleshooting.
[[verify]]A dedicated target <<verify>> anywhere in the file, or else an element named verify with #+NAME:.
[[Installation]]If neither a target nor a name matches, a headline with this text.

A dedicated target is a string in double angle brackets, such as <<verify>>. It marks an exact spot (a list item, a sentence in a paragraph) that has no headline of its own. A named element is an element (a table, a code block, an image) preceded by a #+NAME: keyword.

The following file uses all of these. Note that <<verify>> is invisible in the buffer; Org shows only the text that follows it.

#+TITLE: Release notes
#+OPTIONS: toc:nil num:t author:nil date:nil

* Installation
:PROPERTIES:
:CUSTOM_ID: install
:END:
Follow the steps below.

1. Download the archive.
2. <<verify>>Check the signature.
3. Extract the files.

If step [[verify]] fails, read [[*Troubleshooting]] or the
[[#install][installation notes]].  The supported platforms are listed
in [[platforms]].

#+NAME: platforms
#+CAPTION: Supported platforms
| OS      | Status |
|---------+--------|
| Linux   | tier 1 |
| macOS   | tier 2 |

* Troubleshooting
See [[Installation]] again.

Exporting this file to plain text (C-c C-e t A) shows what happens to links without a description: each one becomes the number of the thing it points to. The target in the second list item becomes “2”, the headlines become their section numbers, and the named table becomes “1” because it is the first table with a caption.

                            _______________

                             RELEASE NOTES
                            _______________


1 Installation
==============

  Follow the steps below.

  1. Download the archive.
  2. Check the signature.
  3. Extract the files.

  If step 2 fails, read 2 or the [installation notes].  The supported
  platforms are listed in 1.

   OS     Status
  ---------------
   Linux  tier 1
   macOS  tier 2
  Table 1: Supported platforms


[installation notes] See section 1


2 Troubleshooting
=================

  See 1 again.

The HTML exporter turns the same links into anchors. A CUSTOM_ID becomes the anchor name directly, which is why it is the best choice for any section you want to link to from outside the document: the generated IDs (like org620893d below) change between exports.

If step <a href="#org620893d">2</a> fails, read <a href="#orgde999d6">2</a> or the
<a href="#install">installation notes</a>.  The supported platforms are listed
in <a href="#org2b3f7a5">1</a>.

Two practical rules follow from this behavior. First, a numbered reference to a named element works only when the element has a #+CAPTION:; without one, there is nothing to number. Second, custom IDs, targets and names must be unique in the document. M-x org-lint reports duplicates, which is worth running before an export.

When you follow a link, Org first checks whether the text before the first colon is a known link type. If it is, the type’s handler takes over. If it is not, Org treats the whole text as a search in the current buffer and tries the possibilities in a fixed order. The order comes from the function org-link-search in ol.el.

flowchart TD
  A["Follow link (C-c C-o)"] --> B{"Known type before the colon?"}
  B -- "yes" --> H["Type handler: file, id, https, ..."]
  B -- "no" --> C{"Starts with a hash sign?"}
  C -- "yes" --> D["Entry with that CUSTOM_ID"]
  C -- "no" --> E{"Wrapped in parentheses or slashes?"}
  E -- "parentheses" --> F["Code reference in a block"]
  E -- "slashes" --> G["Regexp search as a sparse tree"]
  E -- "neither" --> I["Dedicated target, then NAME keyword"]
  I -- "no match" --> J["Headline with the same text"]
  J -- "no match" --> K["Offer to create the headline, or fail"]

Figure 5.2: A link without a known type is a search, and Org tries the most specific kinds of target before it falls back to headline text.

A leading * skips the target and name steps and looks only at headlines. Headline matching ignores TODO keywords, priority cookies, statistics cookies, tags and extra white space, and it is not case-sensitive.

The last step is controlled by org-link-search-must-match-exact-headline. Its default, query-to-create, asks whether to create the missing headline, which is convenient when you write links to sections you plan to add later. Set it to t to get an error instead, or to nil to fall back to a plain text search in the file.

Following an internal link pushes the old position onto Org’s own mark ring. Press C-c & to jump back, and repeat it to go back further. You can push a position yourself with C-c %.

Radio targets

Sometimes you want every occurrence of a term to link to its definition, without writing a link each time. A radio target does this. Write the term in triple angle brackets where it is defined, and Org turns every other occurrence of the same words in normal text into a link to that spot, ignoring case.

#+OPTIONS: toc:nil num:nil
* Glossary
A <<<backlog>>> is the ordered list of work that has not started yet.

* Planning
Each Monday the team reviews the backlog and picks three items.

On export, the definition becomes an anchor and the later mention becomes a link to it:

A <a id="orgd0ac0f7">backlog</a> is the ordered list of work that has not started yet.
...
Each Monday the team reviews the <a href="#orgd0ac0f7">backlog</a> and picks three items.

Org scans the file for radio targets when it opens the file. After you add a new radio target, press C-c C-c on it so that Org activates the new term in the rest of the buffer. Use radio targets sparingly: a common word as a radio target turns half of the document into links.

An external link starts with a type name and a colon, such as https: or file:, with no space after the colon. Org ships with these types:

TypeExampleWhat it does
http, httpshttps://orgmode.org/Opens a web page with browse-url.
filefile:papers/last.pdfVisits a file. A path starting with / or ./ needs no prefix.
attachmentattachment:diagram.pngA file in the entry’s attachment directory. See Capture, Refile, Archive and Attachments.
idid:84b874ac-...The entry with this ID property, in any known file.
doidoi:10.1000/182A document through its DOI handle.
docviewdocview:papers/last.pdf::3A page of a document in DocView mode.
infoinfo:org#External linksA node of an Info manual.
helphelp:org-store-linkThe documentation of a symbol in the *Help* buffer.
shortdocshortdoc:text-propertiesAn Emacs short documentation group.
mailtomailto:someone@example.orgStarts composing a message.
newsnews:comp.emacsA Usenet group.
gnus, rmail, mhegnus:group#idA message or folder in an Emacs mail reader.
bbdbbbdb:R.*StallmanA contact in BBDB, found by regexp.
ircirc:/irc.libera.chat/#emacsAn IRC channel.
shellshell:ls *.orgRuns a shell command.
elispelisp:org-agendaEvaluates a Lisp form or calls a command.

Two of these types run code. Because a link in a file you received from someone else could run any command, Org asks for confirmation before it follows a shell: or elisp: link. The questions come from org-link-shell-confirm-function and org-link-elisp-confirm-function, both yes-or-no-p by default. Keep them that way unless you only ever open your own files.

File links deserve a closer look because they are the type you will use most. The path can be absolute, relative to the current file, or remote through TRAMP:

[[file:~/notes/projects.org][Projects]]
[[./papers/last.pdf]]
[[/ssh:me@build.example.org:logs/today.log]]

When you follow a file link, C-c C-o decides how to open the file from its extension, according to org-file-apps. Text files and directories open in Emacs; other files go to the application your system associates with them. A prefix argument changes the choice: C-u C-c C-o forces Emacs, and C-u C-u C-c C-o avoids Emacs.

On export to HTML, a link to an image without a description becomes an inline image, and a link whose description is an image becomes a clickable image. Displaying images inside the Emacs buffer is a separate feature called link previews; see Markup for Rich Contents.

Typing link targets by hand works for URLs, but for anything inside Emacs it is slow and error-prone. Org’s answer is a three-step cycle: store a link where you are, insert it where you need it, and follow it later.

flowchart LR
  S["Any Emacs buffer"] -- "org-store-link" --> L["List of stored links"]
  L -- "C-c C-l, choose with M-p or M-n" --> O["Org buffer: link text"]
  O -- "C-c C-o or mouse-1" --> T["Target buffer or application"]

Figure 5.3: Storing captures a location as a link, inserting turns a stored link into text, and following resolves that text back into the location.

The command org-store-link creates a link to the current location and keeps it in a list for later. It has no default key because it is useful from every buffer, not only from Org buffers. The manual suggests a global binding:

(global-set-key (kbd "C-c l") #'org-store-link)

What the stored link points to depends on where you are:

Where point isWhat gets stored
On a <<target>> in an Org fileA link to the target.
In a block named with #+NAME:A link to the name.
Elsewhere in an Org entryA link to the headline, or to its CUSTOM_ID if it has one; possibly an id: link (see below).
In any other fileA file: link with a search string built from the current line, or from the active region.
In a mail or news readerA link to the current message.
In an EWW or W3M bufferThe page URL, with the page title as description.
In the agendaA link to the entry on the current line.

In an Org buffer, C-c C-l (org-insert-link) prompts for a link. All links stored in this session are in the prompt’s history, so M-p and M-n (or the up and down arrows) cycle through them. Pressing RET on a stored link inserts it, and Org then asks for a description, offering a default.

The prompt also completes link types with TAB. If you type only a type and press RET, some types offer their own completion: after file you get file name completion, and after id (since Org 9.8) you can choose among known IDs.

C-u C-c C-l jumps straight to inserting a file link. The path is relative when the file lives in or below the current directory, and absolute (using ~ for your home directory where possible) otherwise; C-u C-u C-c C-l forces an absolute path. The variable org-link-file-path-type controls this choice for all file links.

If text is selected when you press C-c C-l, that text becomes the default description, which makes it quick to turn an existing phrase into a link.

A worked example

Suppose projects.org contains this:

* Projects
** Website redesign
:PROPERTIES:
:CUSTOM_ID: redesign
:END:
** Data migration

Running org-store-link on each of the two subheadings, and once more on “Data migration” with org-id-link-to-org-use-id set to t, stores three links. Inserting them with C-c C-l into journal.org in the same directory produces:

[[file:projects.org::#redesign][Website redesign]]
[[file:projects.org::*Data migration][Data migration]]
[[id:84b874ac-34c4-423d-9988-83374cfeb3df][Data migration]]

The first link uses the custom ID because the entry has one. The second falls back to a headline search. The third needed an ID, so Org created one and wrote it into the entry:

** Data migration
:PROPERTIES:
:ID:       84b874ac-34c4-423d-9988-83374cfeb3df
:END:

The three links behave differently when the file changes. The headline link breaks if you rename the headline, and both file: links break if you move the entry to another file. The id: link survives both, which is the subject of the section on stable IDs below.

C-c C-o (org-open-at-point) follows the link at point. A click with mouse-1 or mouse-2 does the same, and mouse-3 opens file links in Emacs and internal links in another window. If you prefer to follow links with RET, set org-return-follows-link to t; inside tables, RET keeps its table meaning.

C-c C-o is context-sensitive beyond links. On a headline that is not on a link, it offers all links in the entry. On tags it builds a tags view, and on a timestamp it opens the agenda for that date. Where the target window appears is controlled by org-link-frame-setup.

To move between links, use C-c C-x C-n (org-next-link) and C-c C-x C-p (org-previous-link). These keys are long; if you navigate links often, bind shorter ones:

(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 same link syntax works in any Emacs buffer, which is handy in code comments and commit messages. The commands org-insert-link-global and org-open-at-point-global insert and follow Org links outside Org mode. Neither has a default key.

/* The retry policy is described in [[file:~/notes/design.org::#retries]]. */

If you link to the same site many times, typing the full URL becomes tedious and makes the source hard to read. A link abbreviation is a short link word that Org expands into a longer target. You define the expansion once, either for all files in org-link-abbrev-alist or for one file with the #+LINK: keyword:

#+OPTIONS: toc:nil num:nil
#+LINK: gh https://github.com/%s
#+LINK: wiki https://en.wikipedia.org/wiki/%h
#+LINK: man https://man7.org/linux/man-pages/man1/%s.1.html

See [[gh:emacs-mirror/emacs][the Emacs mirror]], [[wiki:Plain text]] and [[man:grep]].

The text after the colon is the tag. In the expansion, %s is replaced with the tag as written and %h with the tag percent-encoded, which is why “Plain text” below becomes Plain%20text. If the expansion has neither, Org appends the tag to the end. Exporting the file to HTML shows the expanded URLs:

See <a href="https://github.com/emacs-mirror/emacs">the Emacs mirror</a>, <a href="https://en.wikipedia.org/wiki/Plain%20text">https://en.wikipedia.org/wiki/Plain%20text</a> and <a href="https://man7.org/linux/man-pages/man1/grep.1.html">https://man7.org/linux/man-pages/man1/grep.1.html</a>.

The global version takes an alist. The link word must start with a letter, and an expansion can also be a function that receives the tag and returns the link, or a string containing %(my-function), which calls my-function with the tag.

(setq org-link-abbrev-alist
      '(("gh" . "https://github.com/%s")
        ("wiki" . "https://en.wikipedia.org/wiki/%h")
        ("ticket" . "https://tracker.example.org/browse/")))

With this setting, [[ticket:OPS-412]] points to https://tracker.example.org/browse/OPS-412. Abbreviations also appear in the completion of C-c C-l, so a team can share one set of link words and use them consistently.

A file link can carry a search option after a double colon, which tells Org where to go inside the file once it is open. The same options work for attachment: and id: links.

[[file:~/code/server.c::255]]
[[file:~/notes/ops.org::Backup schedule]]
[[file:~/notes/ops.org::*Backup schedule]]
[[file:~/notes/ops.org::#backups]]
[[file:~/notes/ops.org::/rsync.*--delete/]]
OptionEffect
255Jump to line 255.
Backup scheduleLook for the target <<Backup schedule>>, then fall back to a text search, exactly as for internal links.
*Backup scheduleIn an Org file, look only at headlines.
#backupsGo to the entry with this CUSTOM_ID.
/rsync.*--delete/Show all matches of the regexp: a sparse tree in Org files, an occur buffer elsewhere.

When org-store-link stores a link to a non-Org file, it writes the words of the current line as a text search, so the link usually finds the line again even after lines are inserted above it. A line number is more precise but breaks as soon as the file changes. An empty file name searches the current file: [[file:::find me]] behaves like [[find me]].

For file formats where a line of text is a poor identifier, you can define your own search. Add functions to org-create-file-search-functions (which build the search string when a link is stored) and org-execute-file-search-functions (which perform the search when it is followed). Org uses this mechanism itself for BibTeX files, where the citation key is the natural identifier; ol-bibtex.el is a working example.

The links you have seen so far depend on where things are: a file name, a headline text, a custom ID in a particular file. In a task system where entries move between files (see Capture, Refile, Archive and Attachments), such links break. The org-id library solves this by giving entries a globally unique identifier in an ID property and keeping a map from IDs to files.

An id: link names only the ID. When you follow it, Org looks up the file in its map, opens it and searches for the property. If the entry has moved, Org rescans its known files, updates the map and tries again.

Creating IDs

You can create IDs explicitly or let org-store-link create them:

  • M-x org-id-get-create adds an ID property to the current entry if it has none, and returns the ID.
  • org-id-link-to-org-use-id decides whether org-store-link uses IDs in Org files.

The second option takes these values:

ValueBehavior of org-store-link
nil (default)Never use IDs; store a headline or custom ID link.
tAlways use an ID, creating one if needed.
create-if-interactiveCreate an ID when you call the command yourself, but only reuse existing IDs when capture stores a link.
create-if-interactive-and-no-custom-idLike the previous value, unless the entry already has a CUSTOM_ID.
use-existingUse an ID if the entry already has one; never create one.

The middle values exist because capture stores a link to the current location every time it runs. With t, every entry you happen to be in when you start a capture would receive an ID. A common setup is therefore:

(require 'org-id)
(setq org-id-link-to-org-use-id 'create-if-interactive-and-no-custom-id)

New IDs are UUIDs by default. org-id-method can switch to other generators, and org-id-prefix adds a fixed prefix.

Where Org keeps the map

Org stores the ID map in org-id-locations-file, by default .org-id-locations in your Emacs directory. The map is updated whenever Org creates an ID or finds one, and written to disk when Emacs exits. If you edit files outside Emacs or synchronize them between machines, the map can become stale. M-x org-id-update-id-locations rebuilds it by scanning your agenda files and their archives, all open Org buffers, and the files already in the map; add other files through org-id-extra-files.

IDs with a search option

Since Org 9.7, an id: link can also carry a search option. This lets you point precisely at a subheading, a target or a named block that has no ID of its own, as long as an ancestor has one. Set org-id-link-consider-parent-id to t and store a link to a child heading:

* Handbook
:PROPERTIES:
:ID:       handbook-2026
:END:
** Onboarding
** Expenses

With point on “Expenses” and org-id-link-to-org-use-id set to t, org-store-link produces:

[[id:handbook-2026::*Expenses][Expenses]]

The link survives moving the whole handbook to another file, because the ID travels with it, while the child headings stay free of extra properties.

When the built-in types and abbreviations are not enough, you can register a new link type. A custom type can define how links are followed, exported, stored, completed and displayed. The entry point is org-link-set-parameters, which associates a type name with a property list of functions; the full list of properties is in the docstring of org-link-parameters.

Abbreviations only rewrite the target. Choose a custom type when the link needs behavior: a different output per export format, a special way to open, or completion of valid values.

The following file defines an rfc: link type that opens an Internet RFC in a browser and exports it as a proper link in each format:

(require 'ol)

(defun my-rfc-url (number)
  (format "https://www.rfc-editor.org/rfc/rfc%s" number))

(defun my-rfc-follow (path _arg)
  (browse-url (my-rfc-url path)))

(defun my-rfc-export (path description backend _info)
  (let ((url (my-rfc-url path))
        (text (or description (format "RFC %s" path))))
    (pcase backend
      ('html (format "<a href=\"%s\">%s</a>" url text))
      ('latex (format "\\href{%s}{%s}" url text))
      ('md (format "[%s](%s)" text url))
      (_ (format "%s <%s>" text url)))))

(org-link-set-parameters "rfc"
                         :follow #'my-rfc-follow
                         :export #'my-rfc-export
                         :face 'org-link
                         :help-echo "Open this RFC in a browser")

The :follow function receives the path (here, the RFC number) and the prefix argument. The :export function receives the path, the description (or nil), the export backend and the export settings, and returns the text to insert. Returning a string for every backend, including a fallback, keeps exports to formats you did not plan for readable.

With this code loaded, the following paragraph:

HTTP semantics are defined in [[rfc:9110]]; caching rules live in
[[rfc:9111][the caching RFC]].

exports to HTML, LaTeX, Markdown and plain text as:

<p>
HTTP semantics are defined in <a href="https://www.rfc-editor.org/rfc/rfc9110">RFC 9110</a>; caching rules live in
<a href="https://www.rfc-editor.org/rfc/rfc9111">the caching RFC</a>.
</p>

HTTP semantics are defined in \href{https://www.rfc-editor.org/rfc/rfc9110}{RFC 9110}; caching rules live in
\href{https://www.rfc-editor.org/rfc/rfc9111}{the caching RFC}.

HTTP semantics are defined in [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110); caching rules live in
[the caching RFC](https://www.rfc-editor.org/rfc/rfc9111).

HTTP semantics are defined in RFC 9110
<https://www.rfc-editor.org/rfc/rfc9110>; caching rules live in the
caching RFC <https://www.rfc-editor.org/rfc/rfc9111>.

Other useful properties are :store, which lets org-store-link create links of your type from a particular kind of buffer, :complete, which provides completion after you type the type name in C-c C-l, and :preview, which shows an inline preview for the link. Writing a store function and packaging a link type as a library are covered in Hacking and Extending Org.

Summary

  • A link is [[LINK][DESCRIPTION]]; the link part has a type, a path and an optional search option.
  • Links without a known type are searches in the current file: #custom-id, *Headline, targets, #+NAME: names, then headline text.
  • Links without a description export as numbers, so internal references stay correct when the document changes.
  • Store with org-store-link, insert with C-c C-l, follow with C-c C-o, return with C-c &.
  • Abbreviations (#+LINK:, org-link-abbrev-alist) shorten repeated URLs.
  • id: links survive renaming and refiling; configure org-id-link-to-org-use-id to create IDs when you want them.
  • org-link-set-parameters defines new link types with their own follow and export behavior.

Further reading