Internal Links (The Org Manual)

Next: Radio Targets, Previous: Link Format, 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 tags25.

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

#### Footnotes

### (25)

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.

### (26)

When targeting a ‘`NAME`’ keyword, the ‘`CAPTION`’ keyword is mandatory in order to get proper numbering (see Captions).

Next: Radio Targets, Previous: Link Format, Up: Hyperlinks [Contents][Index]