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’. 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 the words in the link. In the above example the search would be for ‘my target’. Links starting with a star like ‘*My Target’ restrict the search to headlines2. When searching, Org-mode will first try an exact match, but then move on to more and more lenient searches. For example, the link ‘[[*My Targets]]’ will find any of the following: 

     ** My targets
     ** TODO my targets are bright
     ** my 20 targets are

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] 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. See Handling links, for more commands creating links.