docs/manual/guide/09-links.org
342 lines · 18512 bytes
1#+TITLE: Links
2#+DESCRIPTION: Link syntax, the link types Orgstar follows, storing and inserting links, IDs, backlinks and inline images.
3#+LEDE: Write links as Org does, follow them with a key or a click, and see which headings link to the one you are reading.
4
5* Link syntax
6
7Orgstar reads links the way =org-element-link-parser= does. There are three forms.
8
9| Form | Example | Notes |
10|---------------+-------------------------------------------+-------------------------------------------------------------|
11| Bracket link | =[[https://orgmode.org][Org website]]= | Any link type. The description after =][= is optional. |
12| Angle link | =<https://orgmode.org>= | For =http=, =https=, =mailto=, =file=, =id=, =doi=, =ftp=, =news=, =shell=, =elisp=, =info=, =help= and =attachment=. |
13| Plain link | =https://orgmode.org= | Only =https://=, =http://=, =mailto:= and =file:= are recognized in running text. |
14
15Inside a bracket link, a target that starts with =/=, =~=, =./= or =../= is a file
16link. A target in parentheses, =(name)=, is a coderef. One that starts with =#= is a
17custom ID. Anything without a known =type:= prefix is a search for text in the
18current file (a "fuzzy" link). A link may run over a line break; the break and
19surrounding blanks read as one space.
20
21Backslashes before brackets are escaped as in =org-link-escape=: when Orgstar writes
22a link it doubles backslashes that come before a bracket or the end, and it reads them
23back the same way.
24
25* How links display
26
27With View ▸ Show Markup off (the default, =⇧⌘M= toggles it), a link with a
28description shows only its description, and its brackets and target are hidden. This
29is =org-link-descriptive=. The full text appears on the line that holds the caret, so
30you can edit it. With Show Markup on, every link shows as written. The setting is
31=show-markup= under =[orgstar]= in the config file (see
32[[file:13-configuration.org][Configuration]]).
33
34Links without a description show their target, with the brackets hidden in the same
35way. Radio targets (=<<<words>>>=) turn every other occurrence of those words in the
36file into a link, matched case-insensitively, as in Org.
37
38* Following links
39
40=org-open-at-point= follows the link at the caret, or opens the agenda for a timestamp.
41
42| Preset | Key |
43|--------+---------------------------------------------------------------------------------------|
44| Emacs | =C-c C-o= |
45| Mac | =⌃⌘O= |
46| Doom | =C-c C-o= in any state; =RET= in normal state follows a link before doing anything else |
47| All | =⌘=-click on the link; =o= at the start of a heading line when speed commands are on |
48
49A message in the echo area explains a link that can't be followed.
50
51** What each link type does
52
53| Link | Example | Result |
54|----------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------------------|
55| =http=, =https=, =ftp=, =news=, =mailto= | =[[mailto:me@example.com]]= | Opened by macOS in your default browser or mail app. |
56| =doi= | =[[doi:10.1000/182]]= | Opens =https://doi.org/= followed by the DOI. |
57| =file= (also =file+sys:=, =file+emacs:=) | =[[file:notes.org::*Ideas]]= | See /File links/ below. |
58| =id= | =[[id:6a3c…]]= | Opens the file with the heading whose =ID= property matches, and moves to the heading. |
59| Custom ID | =[[#setup]]= | Moves to the heading in this file whose =CUSTOM_ID= property is =setup=. |
60| Heading | =[[*Weekly review]]= | Moves to the heading in this file with that title. |
61| Text | =[[budget table]]= | Searches this file: a =<<budget table>>= target, then =#+NAME: budget table=, then a heading. |
62| Coderef | =[[(ref)]]= | Not supported. The echo area says so. |
63| =shell=, =elisp= | =[[shell:ls]]= | Not run. Orgstar never executes these links. |
64| =attachment= | =[[attachment:scan.pdf]]= | Opens the file in the entry's attachment folder; see /Attachment links/ below. |
65| Radio link | Text matching a =<<<radio target>>>= | Moves to the radio target. |
66| =info=, =help=, others | | Not followed. The echo area says Orgstar can't open the type. |
67
68The text search follows =org-link-search=. A dedicated =<<target>>= matches its words
69case-insensitively, with any run of blanks between them. A heading matches when its
70title, with statistics cookies such as =[2/5]= and a leading =COMMENT= removed, has the
71same words as the link, ignoring case. A search that starts with =*= looks at headings
72only. Regular-expression searches (=/re/=) are not supported.
73
74Following a radio link moves to its =<<<radio target>>>=, matching the words without
75regard to case, as =org-link--search-radio-target= does. When the target is gone, the
76echo area shows =No match for radio target:= and the text.
77
78** File links
79
80A relative path is resolved against the folder of the file that holds the link, as
81Org does; =~= is your home folder; an absolute path is used as written. Links between
82files in different sidebar folders work the same way, for example
83=[[file:../work/projects.org]]= or =[[file:~/Documents/org/inbox.org]]=.
84
85What happens depends on the file:
86
87- An =.org= or =.org_archive= file opens as a buffer in Orgstar.
88- Another text file opens in Orgstar as a plain buffer.
89- Anything else (images, PDFs, archives, media) is handed to macOS, which opens it in
90 the default app for that type.
91
92If the file doesn't exist, the echo area shows =No file= and the path.
93
94After =::=, a file link can carry a search option:
95
96| Option | Example | Moves to |
97|-----------------+----------------------------------+---------------------------------------------|
98| A number | =[[file:log.txt::120]]= | Line 120. |
99| =*Title= | =[[file:notes.org::*Ideas]]= | The heading with that title. |
100| =#custom-id= | =[[file:notes.org::#setup]]= | The heading with that =CUSTOM_ID=. |
101| Other text | =[[file:notes.org::budget]]= | A target, a =#+NAME= or a heading, as above. |
102
103** Attachment links
104
105An =attachment:= link names a file in the attachment folder of the entry that holds
106the link, with org-attach's default settings. Relative folders are resolved against
107the folder of the file that holds the link:
108
1091. When the entry has a =DIR= property, or the older =ATTACH_DIR=, that folder.
1102. Otherwise, for an entry with an =ID=, the first of these folders that exists:
111 =data/= followed by the ID's first two characters, =/= and the rest of the ID;
112 =data/= followed by its first six characters, =/= and the rest;
113 =data/__/=, the ID's first character, =/= and the whole ID.
114
115When the folder does not exist, the path is relative to the file's own folder. The file then opens as a =file:= link would, and
116a search option after =::= works the same way.
117
118** id links
119
120=id:= links are resolved through the index, so the target heading must be in a file
121under one of your sidebar folders. A link to an ID that isn't indexed shows =No heading
122has the ID= followed by the ID.
123
124** Timestamps
125
126=C-c C-o= (Mac =⌃⌘O=) or =⌘=-click on a timestamp opens the agenda on that day, as
127=org-follow-timestamp-link= does. On a date range such as
128=<2026-10-05 Mon>--<2026-10-09 Fri>=, the agenda shows the whole span. See
129[[file:07-agenda.org][Agenda]].
130
131* Inserting and editing links
132
133=org-insert-link= asks for a link and a description in the echo area.
134
135| Preset | Key |
136|--------+------------------------------|
137| Emacs | =C-c C-l= |
138| Mac | =⌘K= |
139| Doom | =SPC m l l=, or =C-c C-l= |
140
141The first prompt reads =Insert link:=, or =Insert link (default …):= when you have
142stored links. It completes from:
143
144- your stored links, most recent first, and their descriptions;
145- the link abbreviations defined in the file (see /Link abbreviations/);
146- the link types =attachment=, =id=, =eww=, =rmail=, =mhe=, =irc=, =info=, =gnus=, =docview=,
147 =bibtex=, =bbdb=, =w3m=, =doi=, =file+sys=, =file+emacs=, =shell=, =news=, =mailto=,
148 =https=, =http=, =ftp=, =shortdoc=, =help=, =file= and =elisp=, each followed by =:=.
149
150Pressing Return on an empty answer inserts the most recent stored link. Choosing a
151description inserts the link it belongs to. If you choose a bare type such as =https:=,
152a second prompt, =Link (no completion support):=, asks for the rest.
153
154The next prompt, =Description:=, offers the stored link's description, or the
155selected text if you selected some before running the command. An empty description
156inserts a link without one. With text selected, the link replaces the selection.
157
158When the caret is on an existing link, the same command edits it: the =Link:= prompt
159starts with the current target and =Description:= with the current description.
160
161A stored link that you insert is removed from the stored list, as with
162=org-link-keep-stored-after-insertion= set to nil.
163
164** File paths in inserted links
165
166When the inserted link is a =file:= link, Orgstar rewrites it as
167=org-link-make-string-for-buffer= does:
168
169- A link to a heading or target in the file you are editing loses its =file:= part
170 and keeps only the search, for example =[[*Ideas]]=.
171- A path under the current file's folder becomes relative to it.
172- Any other path is written with =~= for your home folder.
173
174** Completion while typing
175
176You can also type a link by hand. With the caret right after =[[=, completion at point
177offers =attachment:=, =doi:=, =file:=, =http:=, =https:=, =id:= and =mailto:=, plus
178the file's link abbreviations. After =[[*=, it offers the headings of the current file.
179Completion at point is =C-M-i= in the Emacs preset and =C-SPC= in Doom's insert state;
180see [[file:02-the-editor.org][The editor]].
181
182* Storing links
183
184=org-store-link= remembers a link to where the caret is, for a later Insert Link.
185
186| Preset | Key |
187|--------+---------------------------------------|
188| Emacs | =C-c l= |
189| Mac | =⌃⌘L= |
190| Doom | =SPC m l s= or =SPC n l= |
191
192The stored link is a =file:= link to the current file, written with =~= for your home
193folder, followed by a search option chosen as Org does with
194=org-link-context-for-files= on:
195
1961. If the caret touches a =<<target>>= on its line, the link points at the target.
1972. Otherwise, if text is selected, the link searches for that text.
1983. Otherwise, if the caret is in an element with a =#+NAME=, the link uses the name.
1994. Otherwise, inside a heading's entry, the link uses =#custom-id= if the heading has a
200 =CUSTOM_ID= property, and =*Title= if not. The title becomes the description.
2015. Before the first heading, the link searches for the text of the current line.
202
203The echo area shows =Stored:= and the description or link. Storing the same link again
204moves it to the front of the list. Stored links last until you quit Orgstar; they
205aren't saved between sessions, as in Emacs.
206
207* IDs
208
209Org identifies headings across files with an =ID= property. Two commands manage it.
210
211| Command | Org function | Keys |
212|-----------------------+---------------------------------------+-----------------------------------|
213| Org ▸ Create ID | =org-id-get-create= | No default key |
214| Org ▸ Store ID Link | =org-id-get-create= + =org-id-store-link= | Doom =SPC m l i=; no key in Emacs or Mac |
215
216Create ID gives the heading at the caret an =ID= property if it doesn't have one. The
217ID is a new UUID in lower case, for example =6a3c2f9e-…=, as =org-id-uuid= makes them. Before the first heading,
218the property goes into the file-level property drawer.
219
220Store ID Link does the same, then stores an =id:= link to the heading with its title
221as the description. Before the first heading, the description is the =#+TITLE=, or
222the file name. If the caret is on a target or named element inside the entry, the
223link carries that search, as =id:…::search=, which mirrors =org-id-link-use-context=.
224
225=CUSTOM_ID= is a property you set yourself, with the property commands in
226[[file:04-outlines.org][Outlines]]. Link to it with =[[#name]]= in the same file or
227=[[file:other.org::#name]]= from another. Store Link uses it when the heading has one.
228
229* Targets and radio targets
230
231=<<target>>= marks a place in the text that a link with the same words reaches:
232=[[target]]=. Store Link with the caret on a target stores a link to it.
233
234=<<<radio target>>>= makes every other occurrence of its words in the file a link,
235matched case-insensitively and between non-word characters. Radio links are
236highlighted as links and exported as links to the target (see
237[[file:12-export.org][Export]]). Following one moves to the radio target.
238
239* Link abbreviations
240
241A =#+LINK:= line defines an abbreviation, as =org-link-abbrev-alist-local= does:
242
243#+BEGIN_SRC org
244,#+LINK: gh https://github.com/%s
245,#+LINK: search https://duckduckgo.com/?q=%h
246,#+LINK: wiki https://en.wikipedia.org/wiki/
247
248[[gh:orgmode/org-mode]] → https://github.com/orgmode/org-mode
249[[search:org tables]] → https://duckduckgo.com/?q=org%20tables
250[[wiki:Org-mode]] → https://en.wikipedia.org/wiki/Org-mode
251#+END_SRC
252
253In the template, =%s= is replaced by the text after the colon, =%h= by the same text
254percent-encoded, and a template with neither has the text appended. Function
255templates (=%(…)=) are not supported. Abbreviations from a =#+SETUPFILE= count too.
256When a key is defined twice, the first definition wins.
257
258* The backlinks pane
259
260View ▸ Show or Hide Backlinks shows a pane beside the editor of an org file. It has
261two sections:
262
263- *Links to* the heading at the caret, named after that heading.
264- *Links to this file*.
265
266Each row shows the linking heading and its file name; a link in the text before a
267file's first heading is listed under the file's name. Click a row to open it. The
268pane is shown by default and updates as you move the caret and edit.
269
270The pane looks at every org file in your sidebar folders, including unsaved changes
271in open buffers. A link counts when following it would lead to the heading or the
272file:
273
274- =id:= links to the heading's =ID=;
275- =file:= links and plain paths (=./=, =../=, =/=, =~/=) to the file, with no search
276 option for the file section, or with =::*Title=, =::#custom-id= or =::Title= for a
277 heading;
278- within the same file, =[[*Title]]=, =[[#custom-id]]= and =[[Title]]=.
279
280Links to targets, names and line numbers are not counted. A heading's links to itself
281are left out.
282
283* Inline images
284
285=org-toggle-inline-images= shows image links as images.
286
287| Preset | Key |
288|--------+----------------------------------------------|
289| Emacs | =C-c C-x C-v= |
290| Mac | Org ▸ Show or Hide Inline Images |
291| Doom | =C-c C-x C-v= |
292
293The echo area reports how many images are shown, or that inline display is off.
294
295A line shows an image when it holds nothing but a bracket link, without a description,
296to a file ending in =.png=, =.jpg=, =.jpeg=, =.gif=, =.svg=, =.webp=, =.tif=, =.tiff=,
297=.bmp=, =.heic= or =.avif= (in any case):
298
299#+BEGIN_SRC org
300[[file:images/diagram.png]]
301[[./photo.jpg]]
302#+END_SRC
303
304Relative paths are resolved against the file's folder. Web addresses and
305=attachment:= links are not shown as images. The link text is hidden while the image
306is shown, except on the line that holds the caret.
307
308** Sizing
309
310An image is drawn at its own width, up to the width of the text area. To set a width,
311put =#+ATTR_ORG: :width= with a number of points among the keywords above the link:
312
313#+BEGIN_SRC org
314,#+CAPTION: Network layout
315,#+ATTR_ORG: :width 300
316[[file:images/network.png]]
317#+END_SRC
318
319The height follows the image's proportions. =#+ATTR_HTML= and other exporters'
320attributes don't affect the editor.
321
322** Showing images when a file opens
323
324The config key =org-startup-with-inline-images= (default =false=) shows images in
325every file when it opens. In a file, =#+STARTUP: inlineimages= or
326=#+STARTUP: noinlineimages= overrides it.
327
328* org-protocol store-link
329
330Orgstar handles =org-protocol://store-link= URLs, in the new form
331~org-protocol://store-link?url=…&title=…~ and the old form
332=org-protocol://store-link:/URL/TITLE=. The URL is added to your stored links with
333the title as its description, and is also copied to the clipboard. Insert it with
334Insert Link. Setting up a browser bookmarklet, and =org-protocol://capture=, are in
335[[file:08-capture.org][Capture]].
336
337* On iOS
338
339The iOS app follows links: tap a link in the reader. Org files open in the app, and
340web, mail and other files go to the system. The iOS editor shows inline images as the
341Mac does; the reader doesn't. Storing and inserting links and the backlinks pane are Mac
342features. See [[file:14-ios.org][iOS]].