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
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 will search for a headline that is exactly the link text but may also include a TODO keyword and tags29.
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 object30. 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.
|• Radio targets:||Make targets trigger links in plain text|
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.
When targeting a
#+CAPTION keyword is mandatory in order to get proper numbering
(see Images and tables).