Next: , Previous: Internal links, Up: Hyperlinks

4.3 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. The following list shows examples for each link type.             on the web
     doi:10.1000/182                              DOI for an electronic resource
     file:/home/dominik/images/jupiter.jpg        file, absolute path
     /home/dominik/images/jupiter.jpg             same as above
     file:papers/last.pdf                         file, relative path
     ./papers/last.pdf                            same as above
     file:/ssh:myself@some.where:papers/last.pdf  file, path on remote machine
     /ssh:myself@some.where:papers/last.pdf       same as above
     file:sometextfile::NNN                       file, jump to line number                            another Org file words                text search in Org file1*task title               heading search in Org file2
     docview:papers/last.pdf::NNN                 open in doc-view mode at page
     id:B7423F4D-2E8A-471B-8810-C40F074717E9      Link to heading by ID
     news:comp.emacs                              Usenet link                      Mail link
     mhe:folder                                   MH-E folder link
     mhe:folder#id                                MH-E message link
     rmail:folder                                 RMAIL folder link
     rmail:folder#id                              RMAIL message link
     gnus:group                                   Gnus group link
     gnus:group#id                                Gnus article link
     bbdb:R.*Stallman                             BBDB link (with regexp)
     irc:/                      IRC link
     info:org#External links                      Info node or index link
     shell:ls *.org                               A shell command
     elisp:org-agenda                             Interactive Elisp command
     elisp:(find-file-other-frame "")    Elisp form to evaluate

On top of these built-in link types, some 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://         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 customizing Org to add new link types Adding hyperlink types.

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

     [[][GNU Emacs]]

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

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


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

[2] Headline searches always match the exact headline, ignoring spaces and cookies. If the headline is not found and the value of the option org-link-search-must-match-exact-headline is query-to-create, then the user will be queried to create it.