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’. Such custom IDs are very good for HTML export (see HTML export) where they produce pretty section links. 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. Targets may be located anywhere; sometimes it is convenient to put them into a comment line. For example

     # <<My Target>>

In HTML export (see HTML export), such targets will become named anchors for direct access through ‘http’ links1.

If no dedicated target exists, Org will search for a headline that is exactly the link text but may also include a TODO keyword and tags2. 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.


[1] Note that text before the first headline is usually not exported, so the first such target should be after the first headline, or in the line directly before the first headline.

[2] 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.