krz/orgstar

A native macOS editor for org-mode files. editor org-mode swift

guide/09-links.html

pages
orgstar/guide/09-links.html history · blame · raw

269 lines · 29359 bytes

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