A link that does not look like a URL—i.e., does not start with a known scheme or a file name—refers to the current document. You can follow it with
C-c C-o when point is on the link, or with a mouse click (see Handling Links).
Org provides several refinements to internal navigation within a document. Most notably, a construct like ‘
[[#my-custom-id]]’ specifically targets the entry with the ‘
CUSTOM_ID’ property set to ‘
my-custom-id’. Also, an internal link looking like ‘
[[*Some section]]’ points to a headline with the name ‘
When the link does not belong to any of the cases above, Org looks for a dedicated target: the same string in double angular brackets, like ‘
If no dedicated target exists, the link tries to match the exact name of an element within the buffer. Naming is done, unsurprisingly, with the ‘
NAME’ keyword, which has to be put in the line before the element it refers to, as in the following example
#+NAME: My Target
| a | table |
| of | four cells |
Ultimately, if none of the above succeeds, Org searches for a headline that is exactly the link text but may also include a TODO keyword and tags, or initiates a plain text search, according to the value of
Note that you must make sure custom IDs, dedicated targets, and names are unique throughout the document. Org provides a linter to assist you in the process, if needed. See Org Syntax.
During export, internal links are used to mark objects and assign them a number. Marked objects are then referenced by links pointing to them. In particular, links without a description appear as the number assigned to the marked object2. In the following excerpt from an Org buffer
1. one item
2. <<target>>another item
Here we refer to item [[target]].
The last sentence will appear as ‘
Here we refer to item 2’ when exported.
In non-Org files, the search looks for the words in the link text. In the above example the search would be for ‘
Following a link pushes a mark onto Org’s own mark ring. You can return to the previous position with
C-c &. Using this command several times in direct succession goes back to positions recorded earlier.
- To insert a link targeting a headline, in-buffer completion can be used. Just type a star followed by a few optional letters into the buffer and press
M-TAB. All headlines in the current buffer are offered as completions.↩
- When targeting a ‘
NAME’ keyword, the ‘
CAPTION’ keyword is mandatory in order to get proper numbering (see Captions).↩