4.7 Link Abbreviations

Long URL 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 replace it by the resulting string.

If the replacement text do 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)