Next: , Up: Hyperlinks   [Contents][Index]


4.1 Link Format

Org recognizes plain URIs, possibly wrapped within angle brackets23, and activate them as clickable links.

The general link format, however, looks like this:

[[LINK][DESCRIPTION]]

or alternatively

[[LINK]]

Some ‘\’ and ‘]’ characters in the LINK part need to be “escaped”, i.e., preceded by another ‘\’ character. More specifically, the following character categories, and only them, must be escaped, in order:

  1. all consecutive ‘\’ characters at the end of the link,
  2. any ‘]’ character at the very end of the link,
  3. all consecutive ‘\’ characters preceding ‘][’ or ‘]]’ patterns,
  4. any ‘]’ character followed by either ‘[’ or ‘]’.

Org takes for granted that such links are correctly escaped. Functions inserting links (see Handling Links) take care of this. You only need to bother about those rules 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 properly 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]]’. 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 location24. 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.


Footnotes

(23)

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.

(24)

More accurately, the precise behavior depends on how point arrived there—see (elisp)Invisible Text.


Next: , Up: Hyperlinks   [Contents][Index]