4.2 Internal links

If the link does not look like a URL, it is considered to be internal in the current file. The most important case is a link like ‘[[#my-custom-id]]’ which will link to the entry with the CUSTOM_ID property ‘my-custom-id’. You are responsible yourself to make sure these custom IDs are unique in a file.

Links such as ‘[[My Target]]’ or ‘[[My Target][Find my target]]’ lead to a text search in the current file.

The link can be followed with C-c C-o when the cursor is on the link, or with a mouse click (see Handling links). Links to custom IDs will point to the corresponding headline. The preferred match for a text link is a dedicated target: the same string in double angular brackets, like ‘<<My Target>>’.

If no dedicated target exists, the link will then try to match the exact name of an element within the buffer. Naming is done with the #+NAME keyword, which has to be put the line before the element it refers to, as in the following example

#+NAME: My Target
| a  | table      |
|----+------------|
| of | four cells |

If none of the above succeeds, Org will search for a headline that is exactly the link text but may also include a TODO keyword and tags³⁵.

During export, internal links will be used to mark objects and assign them a number. Marked objects will then be referenced by links pointing to them. In particular, links without a description will appear as the number assigned to the marked object³⁶. In the following excerpt from an Org buffer

- one item
- <<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 will look for the words in the link text. In the above example the search would be for ‘my target’.

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.