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

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 links 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 point is on the link, or with a mouse click (see Handling Links). Links to custom IDs 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 tries to match the exact name of an element within the buffer. Naming is done 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 |

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 tags26.

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 object27. 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 ‘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.



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).

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