This is the official manual for the latest Org-mode release.

Table of Contents

Next: , Previous: Link format, Up: Hyperlinks


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

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


Footnotes

[1] 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 will be offered as completions.

[2] When targeting a #+NAME keyword, #+CAPTION keyword is mandatory in order to get proper numbering (see Images and tables).