4.4 External Links
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.
Additionally, you can specify a line number, or a text search. In Org files, you may link to a headline name, a custom ID, or a code reference instead.
As a special case, “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.
The following table illustrates the link types above, along with their options:
| Link Type | Example |
|---|---|
| http | ‘http://staff.science.uva.nl/c.dominik/’ |
| https | ‘https://orgmode.org/’ |
| doi | ‘doi:10.1000/182’ |
| file | ‘file:/home/dominik/images/jupiter.jpg’ |
‘/home/dominik/images/jupiter.jpg’ (same as above) | |
‘file:papers/last.pdf’ | |
‘./papers/last.pdf’ (same as above) | |
‘file:/ssh:me@some.where:papers/last.pdf’ (remote) | |
‘/ssh:me@some.where:papers/last.pdf’ (same as above) | |
‘file:sometextfile::NNN’ (jump to line number) | |
‘file:projects.org’ | |
‘file:projects.org::some words’ (text search)1 | |
‘file:projects.org::*task title’ (headline search) | |
‘file:projects.org::#custom-id’ (headline search) | |
| attachment | ‘attachment:projects.org’ |
‘attachment:projects.org::some words’ (text search) | |
| docview | ‘docview:papers/last.pdf::NNN’ |
| id | ‘id:B7423F4D-2E8A-471B-8810-C40F074717E9’ |
| news | ‘news:comp.emacs’ |
| mailto | ‘mailto:adent@galaxy.net’ |
| mhe | ‘mhe:folder’ (folder link) |
‘mhe:folder#id’ (message link) | |
| rmail | ‘rmail:folder’ (folder link) |
‘rmail:folder#id’ (message link) | |
| gnus | ‘gnus:group’ (group link) |
‘gnus:group#id’ (article link) | |
| bbdb | ‘bbdb:R.*Stallman’ (record with regexp) |
| irc | ‘irc:/irc.com/#emacs/bob’ |
| help | ‘help:org-store-link’ |
| info | ‘info:org#External links’ |
| shell | ‘shell:ls *.org’ |
| elisp | ‘elisp:(find-file "Elisp.org")’ (Elisp form to evaluate) |
‘elisp:org-agenda’ (interactive Elisp command) |
On top of these built-in link types, additional ones are available through the ‘contrib/’ directory (see Installation). For example, these links to VM or Wanderlust messages are available when you load the corresponding libraries from the ‘contrib/’ directory:
‘vm:folder’ | VM folder link |
‘vm:folder#id’ | VM message link |
‘vm://myself@some.where.org/folder#id’ | VM on remote machine |
‘vm-imap:account:folder’ | VM IMAP folder link |
‘vm-imap:account:folder#id’ | VM IMAP message link |
‘wl:folder’ | Wanderlust folder link |
‘wl:folder#id’ | Wanderlust message link |
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:
[[http://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.
- The actual behavior of the search depends on the value of the variable
org-link-search-must-match-exact-headline. If its value isnil, then a fuzzy text search is done. If it ist, then only the exact headline is matched, ignoring spaces and statistic cookies. If the value isquery-to-create, then an exact headline is searched; if it is not found, then the user is queried to create it.↩