guide/08-capture.html
340 lines · 49334 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>Capture · Orgstar</title>
7<meta name="description" content="Capture templates, the capture window, date trees, org-protocol, Shortcuts and the iOS share sheet.">
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>Capture</h1>
24<p class="lede">Capture files a note, task or link into the right place in your org files without leaving what you are doing.</p>
25<nav class="toc" aria-label="On this page">
26<h2>On this page</h2>
27<ul>
28<li><a href="#starting-a-capture">Starting a capture</a></li>
29<li><a href="#the-capture-window">The capture window</a></li>
30<li><a href="#capture-templates">Capture templates</a>
31<ul>
32<li><a href="#keys">Keys</a></li>
33<li><a href="#targets">Targets</a></li>
34<li><a href="#template-types">Template types</a></li>
35<li><a href="#clocking-while-capturing">Clocking while capturing</a></li>
36</ul></li>
37<li><a href="#template-escapes">Template escapes</a>
38<ul>
39<li><a href="#inserted-values">Inserted values</a></li>
40<li><a href="#prompts">Prompts</a></li>
41<li><a href="#escaping-and-unsupported-escapes">Escaping and unsupported escapes</a></li>
42</ul></li>
43<li><a href="#date-trees">Date trees</a></li>
44<li><a href="#org-protocol">org-protocol</a>
45<ul>
46<li><a href="#capture">capture</a></li>
47<li><a href="#store-link">store-link</a></li>
48<li><a href="#bookmarklets">Bookmarklets</a></li>
49</ul></li>
50<li><a href="#shortcuts">Shortcuts</a></li>
51<li><a href="#capture-on-ios">Capture on iOS</a>
52<ul>
53<li><a href="#the-share-sheet">The share sheet</a></li>
54</ul></li>
55<li><a href="#importing-templates-from-emacs">Importing templates from Emacs</a></li>
56</ul>
57</nav>
58<h2 id="starting-a-capture">Starting a capture</h2>
59<p>Capture mirrors <code class="verbatim">org-capture</code>. Start it from anywhere in the app:</p>
60<table>
61<thead>
62<tr><th>Preset</th><th>Key</th></tr>
63</thead>
64<tbody>
65<tr><td>Mac</td><td><code class="verbatim">⇧⌘N</code> (File ▸ Capture…)</td></tr>
66<tr><td>Emacs</td><td><code class="verbatim">C-c c</code> or <code class="verbatim">⇧⌘N</code></td></tr>
67<tr><td>Doom</td><td><code class="verbatim">SPC X</code> (normal state), <code class="verbatim">C-c c</code> or <code class="verbatim">⇧⌘N</code></td></tr>
68</tbody>
69</table>
70<p><code class="verbatim">⌃⌥Space</code> opens the capture window from any app, with Orgstar in the background. Turn it off in Settings ▸ Capture, or in <code class="verbatim">config.toml</code>:</p>
71<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">orgstar</span><span class="punctuation definition table toml">]</span>
72<span class="variable other key toml">global-capture-hotkey</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">false</span></span></code></pre>
73<p>The shortcut is registered as a system hot key and needs no accessibility permission.</p>
74<p>Captures can also arrive from a browser through org-protocol, from Shortcuts, and on iOS from the share sheet; see the sections below.</p>
75<h2 id="the-capture-window">The capture window</h2>
76<p>A capture goes through up to three steps.</p>
77<ol>
78<li><strong>Choose a template.</strong> The window lists your templates with their keys and targets. Type a template's key, or click it. For a key of several characters, such as <code class="verbatim">wb</code>, each character you type narrows the list to the templates whose keys start with what you typed, and the header shows the keys so far (<code class="verbatim">Capture: w</code>). <code class="verbatim">Delete</code> removes the last key typed. The template is chosen as soon as the keys match one.</li>
79<li><strong>Answer its questions.</strong> If the template has prompts (<code class="verbatim">%^{…}</code>, <code class="verbatim">%^g</code>, <code class="verbatim">%^t</code> and the others below), they appear as a form. Leave a field empty for its default. Press Return (Continue) to go on.</li>
80<li><strong>Edit and file.</strong> The filled template appears in an editor, headed with the template's name and target, with the cursor where <code class="verbatim">%?</code> was. Press <code class="verbatim">⌘Return</code> (File It) to file it.</li>
81</ol>
82<p>Press Esc (Cancel) at any step to close the window without filing anything, as <code class="verbatim">org-capture-kill</code> does.</p>
83<p>Filing, the equivalent of <code class="verbatim">org-capture-finalize</code>, places the text in its target and saves it through the open buffer if the file is open, or into the file otherwise. A target file that doesn't exist is created, with its folders. The status line in the main window then says where the entry went.</p>
84<p>If filing fails, for example because a heading on an <code class="verbatim">olp</code> path is missing, the window stays open with your text and shows the error in red below it, so you can try again after fixing the file or cancel.</p>
85<p>Limits compared with Emacs:</p>
86<ul>
87<li>The editor is a plain text editor. Org editing commands and keys such as <code class="verbatim">C-c C-c</code> and <code class="verbatim">C-c C-k</code> don't work in it; use <code class="verbatim">⌘Return</code> and Esc.</li>
88<li>There is no refile from the capture window (<code class="verbatim">C-c C-w</code> in an Emacs capture buffer). Capture to an inbox heading and refile from the agenda or the editor.</li>
89<li>The target is not shown while you edit (the capture buffer in Emacs is narrowed to the new entry in the target file).</li>
90</ul>
91<h2 id="capture-templates">Capture templates</h2>
92<p>Templates live in <code class="verbatim">capture.toml</code> in the configuration folder (<code class="verbatim">~/.config/orgstar/capture.toml</code> by default; see <a href="13-configuration.html">Configuration</a>). Settings ▸ Capture shows its path. Each template is a <code class="verbatim">[[template]]</code> table:</p>
93<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">template</span><span class="punctuation definition table array toml">]]</span>
94<span class="variable other key toml">key</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>t<span class="punctuation definition string end toml">"</span></span>
95<span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Personal todo<span class="punctuation definition string end toml">"</span></span>
96<span class="variable other key toml">type</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>entry<span class="punctuation definition string end toml">"</span></span>
97<span class="variable other key toml">file</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>todo.org<span class="punctuation definition string end toml">"</span></span>
98<span class="variable other key toml">headline</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Inbox<span class="punctuation definition string end toml">"</span></span>
99<span class="variable other key toml">template</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>* TODO %?<span class="constant character escape toml">\n</span>%i<span class="constant character escape toml">\n</span>%a<span class="punctuation definition string end toml">"</span></span>
100<span class="variable other key toml">prepend</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">false</span></span></code></pre>
101<p>The file is read each time the capture window opens. If it doesn't exist, or none of its templates is valid, these two built-in templates are used:</p>
102<table>
103<thead>
104<tr><th>Key</th><th>Name</th><th>Target</th><th>Template</th></tr>
105</thead>
106<tbody>
107<tr><td><code class="verbatim">t</code></td><td>Personal todo</td><td><code class="verbatim">todo.org</code>, heading <code class="verbatim">Inbox</code></td><td><code class="verbatim">* TODO %?\n%i\n%a</code></td></tr>
108<tr><td><code class="verbatim">n</code></td><td>Personal notes</td><td><code class="verbatim">notes.org</code>, heading <code class="verbatim">Inbox</code></td><td><code class="verbatim">* %u %?\n%i\n%a</code></td></tr>
109</tbody>
110</table>
111<p>A problem in the file, such as a table without a key, shows in red at the bottom of the window; the other templates still load.</p>
112<p>Templates are a flat list. Keys of several characters are typed one character at a time, as in Emacs, but Emacs's template groups (an entry with only a key and a description) have no equivalent: the list shows every template whose key starts with what you typed.</p>
113<h3 id="keys">Keys</h3>
114<table>
115<thead>
116<tr><th>Key</th><th>Value</th><th>Meaning</th><th>Org property</th></tr>
117</thead>
118<tbody>
119<tr><td><code class="verbatim">key</code></td><td>string, required</td><td>What you press to choose the template</td><td>key</td></tr>
120<tr><td><code class="verbatim">name</code></td><td>string</td><td>The name in the list; the key when omitted</td><td>description</td></tr>
121<tr><td><code class="verbatim">type</code></td><td>string</td><td><code class="verbatim">entry</code> (the default), <code class="verbatim">item</code>, <code class="verbatim">checkitem</code>, <code class="verbatim">plain</code> or <code class="verbatim">table-line</code></td><td>type</td></tr>
122<tr><td><code class="verbatim">template</code></td><td>string, required</td><td>The text to fill; see <a href="#template-escapes">Template escapes</a></td><td>template</td></tr>
123<tr><td><code class="verbatim">file</code></td><td>string</td><td>The target file; required except with <code class="verbatim">id</code> or <code class="verbatim">clock</code></td><td>target</td></tr>
124<tr><td><code class="verbatim">headline</code></td><td>string</td><td>A heading in <code class="verbatim">file</code></td><td><code class="verbatim">file+headline</code></td></tr>
125<tr><td><code class="verbatim">olp</code></td><td>string</td><td>An outline path in <code class="verbatim">file</code>, titles separated by <code class="verbatim">/</code></td><td><code class="verbatim">file+olp</code></td></tr>
126<tr><td><code class="verbatim">datetree</code></td><td>boolean</td><td>Today's entry in a date tree in <code class="verbatim">file</code>, under <code class="verbatim">olp</code> if given</td><td><code class="verbatim">file+olp+datetree</code></td></tr>
127<tr><td><code class="verbatim">tree-type</code></td><td>string</td><td><code class="verbatim">day</code> (the default), <code class="verbatim">week</code> or <code class="verbatim">month</code>, for <code class="verbatim">datetree</code></td><td><code class="verbatim">:tree-type</code></td></tr>
128<tr><td><code class="verbatim">id</code></td><td>string</td><td>The heading with this <code class="verbatim">ID</code> property, in any file</td><td><code class="verbatim">id</code></td></tr>
129<tr><td><code class="verbatim">clock</code></td><td>boolean</td><td>The entry the clock is running in</td><td><code class="verbatim">clock</code></td></tr>
130<tr><td><code class="verbatim">prepend</code></td><td>boolean</td><td>Put the text first rather than last</td><td><code class="verbatim">:prepend</code></td></tr>
131<tr><td><code class="verbatim">immediate-finish</code></td><td>boolean</td><td>File without showing the editor</td><td><code class="verbatim">:immediate-finish</code></td></tr>
132<tr><td><code class="verbatim">empty-lines</code></td><td>integer</td><td>Blank lines before and after the captured text</td><td><code class="verbatim">:empty-lines</code></td></tr>
133<tr><td><code class="verbatim">empty-lines-before</code></td><td>integer</td><td>Blank lines before; overrides <code class="verbatim">empty-lines</code></td><td><code class="verbatim">:empty-lines-before</code></td></tr>
134<tr><td><code class="verbatim">empty-lines-after</code></td><td>integer</td><td>Blank lines after; overrides <code class="verbatim">empty-lines</code></td><td><code class="verbatim">:empty-lines-after</code></td></tr>
135<tr><td><code class="verbatim">jump-to-captured</code></td><td>boolean</td><td>Show the new entry in the editor after filing</td><td><code class="verbatim">:jump-to-captured</code></td></tr>
136<tr><td><code class="verbatim">clock-in</code></td><td>boolean</td><td>Clock in to the captured entry</td><td><code class="verbatim">:clock-in</code></td></tr>
137<tr><td><code class="verbatim">clock-keep</code></td><td>boolean</td><td>With <code class="verbatim">clock-in</code>, keep the clock running after filing</td><td><code class="verbatim">:clock-keep</code></td></tr>
138<tr><td><code class="verbatim">clock-resume</code></td><td>boolean</td><td>With <code class="verbatim">clock-in</code>, restart the clock that was running before</td><td><code class="verbatim">:clock-resume</code></td></tr>
139<tr><td><code class="verbatim">table-line-pos</code></td><td>string</td><td>Where a <code class="verbatim">table-line</code> goes, such as <code class="verbatim">"II-3"</code></td><td><code class="verbatim">:table-line-pos</code></td></tr>
140</tbody>
141</table>
142<p><code class="verbatim">capture.toml</code> uses a subset of TOML: basic strings in double quotes, literal strings in single quotes, booleans and integers. Multi-line strings (<code class="verbatim">"""…"""</code>) are not supported, so write a newline in a template as <code class="verbatim">\n</code> inside a double-quoted string. A double-quoted string accepts only the escapes <code class="verbatim">\"</code>, <code class="verbatim">\\</code>, <code class="verbatim">\n</code>, <code class="verbatim">\t</code>, <code class="verbatim">\uXXXX</code> and <code class="verbatim">\UXXXXXXXX</code>; any other backslash is an error. A template backslash, as in <code class="verbatim">%\1</code> or <code class="verbatim">\%</code>, is therefore written <code class="verbatim">%\\1</code> or <code class="verbatim">\\%</code> in double quotes, or as it is in a single-quoted string, which has no escapes and no <code class="verbatim">\n</code>.</p>
143<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">template</span><span class="punctuation definition table array toml">]]</span>
144<span class="variable other key toml">key</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>m<span class="punctuation definition string end toml">"</span></span>
145<span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Meeting<span class="punctuation definition string end toml">"</span></span>
146<span class="variable other key toml">file</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>work.org<span class="punctuation definition string end toml">"</span></span>
147<span class="variable other key toml">olp</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Meetings<span class="punctuation definition string end toml">"</span></span>
148<span class="variable other key toml">template</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>* %^{Topic} :meeting:<span class="constant character escape toml">\n</span>%U<span class="constant character escape toml">\n</span>- Attendees: %^{Attendees}<span class="constant character escape toml">\n</span>- Topic again: %<span class="constant character escape toml">\\</span>1<span class="constant character escape toml">\n</span>%?<span class="punctuation definition string end toml">"</span></span></span></code></pre>
149<h3 id="targets">Targets</h3>
150<p>The target keys are checked in this order: <code class="verbatim">id</code>, <code class="verbatim">clock</code>, <code class="verbatim">datetree</code>, <code class="verbatim">headline</code>, <code class="verbatim">olp</code>; with none of them the target is <code class="verbatim">file</code> itself.</p>
151<table>
152<thead>
153<tr><th>Target</th><th>Where the text goes</th></tr>
154</thead>
155<tbody>
156<tr><td><code class="verbatim">file</code> alone</td><td>The file's top level: an <code class="verbatim">entry</code> becomes a top-level heading at the end (or start, with <code class="verbatim">prepend</code>)</td></tr>
157<tr><td><code class="verbatim">headline = "Inbox"</code></td><td>Under the first heading with that exact title, at any level. If there is none, <code class="verbatim">* Inbox</code> is added at the end of the file</td></tr>
158<tr><td><code class="verbatim">olp = "Projects/Work"</code></td><td>Under <code class="verbatim">Work</code>, a child of <code class="verbatim">Projects</code>. Every heading on the path must exist; otherwise filing fails with <code class="verbatim">Heading not found on outline path</code></td></tr>
159<tr><td><code class="verbatim">datetree = true</code></td><td>Under today's heading in a date tree; see <a href="#date-trees">Date trees</a></td></tr>
160<tr><td><code class="verbatim">id = "…"</code></td><td>Under the heading with that <code class="verbatim">ID</code>, found through the workspace index. Fails with <code class="verbatim">Cannot find target ID</code> if no heading has it</td></tr>
161<tr><td><code class="verbatim">clock = true</code></td><td>Under the heading the running clock is in. Fails with <code class="verbatim">No running clock</code> when no clock runs</td></tr>
162</tbody>
163</table>
164<p><code class="verbatim">file</code> may be absolute (<code class="verbatim">/Users/me/org/todo.org</code>), start with <code class="verbatim">~/</code>, or be relative. A relative path is relative to the first folder in the sidebar (your home folder if you have none). Heading titles match the title text without its TODO keyword, priority or tags. Because <code class="verbatim">olp</code> uses <code class="verbatim">/</code> as its separator, a heading whose title contains <code class="verbatim">/</code> can't be on an outline path; use <code class="verbatim">headline</code> or <code class="verbatim">id</code> for it.</p>
165<p>Emacs's <code class="verbatim">file+regexp</code>, <code class="verbatim">file+function</code> and <code class="verbatim">function</code> targets, and templates read from a file (<code class="verbatim">(file "…")</code>), are not supported.</p>
166<h3 id="template-types">Template types</h3>
167<table>
168<thead>
169<tr><th>Type</th><th>What is inserted</th></tr>
170</thead>
171<tbody>
172<tr><td><code class="verbatim">entry</code></td><td>An Org entry. If the text has no heading, <code class="verbatim">* = is added. Its level is adjusted to be one below the target heading, or 1 at the top level. Placed as the last child (first with =prepend</code>). Text whose first heading isn't its highest is refused: <code class="verbatim">Template is not a valid Org entry or tree</code></td></tr>
173<tr><td><code class="verbatim">item</code></td><td>A list item. A =- = bullet is added if the text has none. Goes after the last item of the first list in the target entry (or the file), with that list's indentation; if there is no list, at the end of the entry's text</td></tr>
174<tr><td><code class="verbatim">checkitem</code></td><td>As <code class="verbatim">item</code>, with a <code class="verbatim">[ ]</code> checkbox added if there is none</td></tr>
175<tr><td><code class="verbatim">plain</code></td><td>The text as it is, at the end of the entry's body (with <code class="verbatim">prepend</code>, right after the heading line)</td></tr>
176<tr><td><code class="verbatim">table-line</code></td><td>A table row, in the first table in the target entry (or the file); a new table is made if there is none</td></tr>
177</tbody>
178</table>
179<p>For <code class="verbatim">table-line</code>, a text that doesn't start with a vertical bar gets one. The row goes at the end of the table. With <code class="verbatim">prepend</code> it goes before the first data row after the first rule. With <code class="verbatim">table-line-pos</code>, <code class="verbatim">II-3</code> means three lines above the second horizontal rule and <code class="verbatim">I+1</code> the first line below the first rule; an impossible position fails with <code class="verbatim">Invalid table line specification</code>. After the row is placed, the table is aligned and its formulas recomputed; a table whose formulas need Emacs makes the capture fail with a message that says so (see <a href="10-tables.html">Tables</a>).</p>
180<p>Placement follows <code class="verbatim">org-capture-place-entry</code> and its siblings, including how blank lines are kept: without <code class="verbatim">empty-lines</code> options, a new heading gets a blank line before it when its neighbors have one (<code class="verbatim">org-blank-before-new-entry</code> <code class="verbatim">(heading . auto)</code>). Within an existing list, at most one blank line goes between items.</p>
181<h3 id="clocking-while-capturing">Clocking while capturing</h3>
182<p>With <code class="verbatim">clock-in = true</code>, the captured entry gets a clock entry from when the template was filled to when you filed it, as Emacs clocks in while the capture buffer is open and out on finalize. With <code class="verbatim">clock-keep = true</code> as well, the clock keeps running in the new entry. With <code class="verbatim">clock-resume = true</code>, the clock that was running before the capture starts again after filing. See <a href="06-dates-and-clocking.html">Dates, scheduling and clocking</a>.</p>
183<h2 id="template-escapes">Template escapes</h2>
184<p>These follow <code class="verbatim">org-capture-fill-template</code>. Escapes that need no answer are filled first; prompts are then asked in order.</p>
185<h3 id="inserted-values">Inserted values</h3>
186<table>
187<thead>
188<tr><th>Escape</th><th>Inserts</th></tr>
189</thead>
190<tbody>
191<tr><td><code class="verbatim">%?</code></td><td>Nothing; the cursor goes here</td></tr>
192<tr><td><code class="verbatim">%i</code></td><td>The initial text: the selection in the editor, or the body from org-protocol, Shortcuts or the share sheet. Later lines get the indentation of the line <code class="verbatim">%i</code> is on</td></tr>
193<tr><td><code class="verbatim">%a</code></td><td>A link to where capture started, <code class="verbatim">[[target][description]]</code></td></tr>
194<tr><td><code class="verbatim">%A</code></td><td>The same link, asking for its description</td></tr>
195<tr><td><code class="verbatim">%l</code></td><td>The link as <code class="verbatim">[[target]]</code>, without description</td></tr>
196<tr><td><code class="verbatim">%L</code></td><td>The link target alone</td></tr>
197<tr><td><code class="verbatim">%c</code>, <code class="verbatim">%x</code></td><td>The clipboard's text</td></tr>
198<tr><td><code class="verbatim">%f</code></td><td>The name of the file capture started from</td></tr>
199<tr><td><code class="verbatim">%F</code></td><td>The full path of that file</td></tr>
200<tr><td><code class="verbatim">%n</code></td><td>Your full name from macOS</td></tr>
201<tr><td><code class="verbatim">%k</code></td><td>The title of the entry the clock is running in</td></tr>
202<tr><td><code class="verbatim">%K</code></td><td>A link to that entry</td></tr>
203<tr><td><code class="verbatim">%t</code></td><td>Today's date as an active timestamp, <code class="verbatim"><2026-10-07 Wed></code></td></tr>
204<tr><td><code class="verbatim">%T</code></td><td>Active timestamp with the current time</td></tr>
205<tr><td><code class="verbatim">%u</code></td><td>Inactive timestamp, <code class="verbatim">[2026-10-07 Wed]</code></td></tr>
206<tr><td><code class="verbatim">%U</code></td><td>Inactive timestamp with the current time</td></tr>
207<tr><td><code class="verbatim">%<…></code></td><td>The current time formatted with a <code class="verbatim">format-time-string</code> pattern, such as <code class="verbatim">%<%Y-%m-%d %H:%M></code></td></tr>
208<tr><td><code class="verbatim">%:name</code></td><td>A link property; see below</td></tr>
209</tbody>
210</table>
211<p>From the Mac capture window, <code class="verbatim">%a</code> links to the heading at the cursor in the open file, as <code class="verbatim">[[file:~/org/work.org::*Heading][Heading]]</code>, or to the file itself before the first heading. It is empty with no file open.</p>
212<p><code class="verbatim">%<…></code> understands <code class="verbatim">%Y</code>, <code class="verbatim">%m</code>, <code class="verbatim">%d</code>, <code class="verbatim">%e</code>, <code class="verbatim">%H</code>, <code class="verbatim">%M</code>, <code class="verbatim">%S</code>, <code class="verbatim">%a</code>, <code class="verbatim">%A</code>, <code class="verbatim">%b</code>, <code class="verbatim">%B</code>, <code class="verbatim">%F</code>, <code class="verbatim">%R</code> and <code class="verbatim">%%</code>, with English day and month names. Other <code class="verbatim">format-time-string</code> codes are left in the text as they are.</p>
213<p><code class="verbatim">%:name</code> inserts a property of the link being captured. From org-protocol these are <code class="verbatim">%:link</code>, <code class="verbatim">%:description</code> (the page title), <code class="verbatim">%:type</code> (the link's scheme, such as <code class="verbatim">https</code>), <code class="verbatim">%:annotation</code> (the same as <code class="verbatim">%a</code>) and <code class="verbatim">%:initial</code> (the same as <code class="verbatim">%i</code>). Without org-protocol, <code class="verbatim">%:annotation</code> and <code class="verbatim">%:initial</code> still work and other names insert nothing.</p>
214<h3 id="prompts">Prompts</h3>
215<table>
216<thead>
217<tr><th>Escape</th><th>Asks for</th></tr>
218</thead>
219<tbody>
220<tr><td><code class="verbatim">%^{Prompt}</code></td><td>A line of text</td></tr>
221<tr><td><code class="verbatim">%^g</code></td><td>Tags, offering the tags used in the target file</td></tr>
222<tr><td><code class="verbatim">%^G</code></td><td>Tags, offering every tag in your folders</td></tr>
223<tr><td><code class="verbatim">%^t</code>, <code class="verbatim">%^T</code></td><td>A date, inserted as an active timestamp; <code class="verbatim">%^T</code> always includes a time</td></tr>
224<tr><td><code class="verbatim">%^u</code>, <code class="verbatim">%^U</code></td><td>The same as an inactive timestamp</td></tr>
225<tr><td><code class="verbatim">%^C</code></td><td>Text, offering the initial text and the clipboard</td></tr>
226<tr><td><code class="verbatim">%^L</code></td><td>As <code class="verbatim">%^C</code>, inserted as a link</td></tr>
227<tr><td><code class="verbatim">%^{NAME}p</code></td><td>A value for the property <code class="verbatim">NAME</code>, set in the entry's property drawer</td></tr>
228</tbody>
229</table>
230<p><code class="verbatim">%^{Prompt|default|a|b}</code> asks for text with a default and suggested choices, separated by vertical bars.</p>
231<p>A name in braces before any of the keyed forms becomes its prompt: <code class="verbatim">%^{Start}T</code>, <code class="verbatim">%^{Context}g</code>. Leave a text answer empty for the default. Tags are typed separated by colons (<code class="verbatim">work:urgent</code>); on a heading line they are aligned to <code class="verbatim">org-tags-column</code>. A date takes the same input as the editor's date prompt, such as <code class="verbatim">+2d</code>, <code class="verbatim">fri</code> or <code class="verbatim">fri 14:00</code> (see <a href="06-dates-and-clocking.html">Dates, scheduling and clocking</a>); an empty answer is today, or now for <code class="verbatim">%^T</code> and <code class="verbatim">%^U</code>. A time in the answer makes <code class="verbatim">%^t</code> include it.</p>
232<p>After the prompts are answered, <code class="verbatim">%\1</code>, <code class="verbatim">%\2</code> and so on insert the answer to the first, second, … text prompt (<code class="verbatim">%^{…}</code> only), and <code class="verbatim">%\*1</code>, <code class="verbatim">%\*2</code> the answer to the first, second, … prompt of any kind.</p>
233<h3 id="escaping-and-unsupported-escapes">Escaping and unsupported escapes</h3>
234<p>Put a backslash before <code class="verbatim">%</code> to keep it literally: <code class="verbatim">\%t</code> inserts <code class="verbatim">%t</code> (in a double-quoted TOML string, write <code class="verbatim">\\%t</code>). Two backslashes insert one backslash followed by the escape's value.</p>
235<p><code class="verbatim">%(…)</code> runs Emacs Lisp in Org and is not supported; a template that contains it fails with a message saying so. <code class="verbatim">%[file]</code> (insert a file's contents) is not supported either. Any other <code class="verbatim">%</code> sequence is left as it is.</p>
236<h2 id="date-trees">Date trees</h2>
237<p>With <code class="verbatim">datetree = true</code>, the entry goes under today's date in a tree of headings, as <code class="verbatim">org-datetree-find-create-entry</code> builds it. Missing levels are created in date order among their siblings.</p>
238<table>
239<thead>
240<tr><th><code class="verbatim">tree-type</code></th><th>Levels</th></tr>
241</thead>
242<tbody>
243<tr><td><code class="verbatim">day</code></td><td><code class="verbatim">* 2026</code>, <code class="verbatim">** 2026-10 October</code>, <code class="verbatim">*** 2026-10-07 Wednesday</code></td></tr>
244<tr><td><code class="verbatim">week</code></td><td><code class="verbatim">* 2026</code>, <code class="verbatim">** 2026-W41</code>, <code class="verbatim">*** 2026-10-07 Wednesday</code> (ISO week and its year)</td></tr>
245<tr><td><code class="verbatim">month</code></td><td><code class="verbatim">* 2026</code>, <code class="verbatim">** 2026-10 October</code></td></tr>
246</tbody>
247</table>
248<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">template</span><span class="punctuation definition table array toml">]]</span>
249<span class="variable other key toml">key</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>j<span class="punctuation definition string end toml">"</span></span>
250<span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Journal<span class="punctuation definition string end toml">"</span></span>
251<span class="variable other key toml">file</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>journal.org<span class="punctuation definition string end toml">"</span></span>
252<span class="variable other key toml">datetree</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">true</span>
253<span class="variable other key toml">template</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>* %<%H:%M> %?<span class="constant character escape toml">\n</span>%i<span class="punctuation definition string end toml">"</span></span></span></code></pre>
254<p>With <code class="verbatim">olp</code>, the tree goes under that outline path, one level down, instead of at the top of the file. The date is the day you file the capture. There is no <code class="verbatim">:time-prompt</code> to choose another day.</p>
255<h2 id="org-protocol">org-protocol</h2>
256<p>Orgstar registers the <code class="verbatim">org-protocol:</code> URL scheme and handles the two handlers browser bookmarklets use, as <code class="verbatim">org-protocol.el</code> does in Org 9.8.7. Both the <code class="verbatim">?key=value</code> form and the older <code class="verbatim">:/a/b/c</code> form work.</p>
257<h3 id="capture">capture</h3>
258<pre><code class="language-text">org-protocol://capture?template=w&url=https%3A%2F%2Fexample.com&title=Example&body=Selected%20text</code></pre>
259<p>This opens the capture window with:</p>
260<ul>
261<li><code class="verbatim">template</code> chosen. Without <code class="verbatim">template</code>, the template list shows. A key with no template reports <code class="verbatim">No capture template "w"</code>.</li>
262<li><code class="verbatim">%a</code> and <code class="verbatim">%:annotation</code> set to <code class="verbatim">[[url][title]]</code> (the URL as its own description when the title is blank; the title alone when there is no URL).</li>
263<li><code class="verbatim">%i</code> and <code class="verbatim">%:initial</code> set to <code class="verbatim">body</code>.</li>
264<li><code class="verbatim">%:link</code> set to the URL, <code class="verbatim">%:description</code> to the title, and <code class="verbatim">%:type</code> to the URL's scheme.</li>
265</ul>
266<p>In the query form, <code class="verbatim">+</code> stands for a space, as in Org; encode a literal <code class="verbatim">+</code> as <code class="verbatim">%2B</code>.</p>
267<h3 id="store-link">store-link</h3>
268<pre><code class="language-text">org-protocol://store-link?url=https%3A%2F%2Fexample.com&title=Example</code></pre>
269<p>This stores the link, so <code class="verbatim">C-c C-l</code> in the editor offers it (see <a href="09-links.html">Links</a>), and puts the URL on the clipboard.</p>
270<p>Other handlers, such as <code class="verbatim">open-source</code>, report that Orgstar handles only capture and store-link. On iOS only <code class="verbatim">capture</code> links are handled.</p>
271<h3 id="bookmarklets">Bookmarklets</h3>
272<p>Bookmarklets written for Emacs's org-protocol work unchanged. Add a bookmark with one of these as its address:</p>
273<pre><code class="language-js highlight"><span class="source js"><span class="entity name label js">javascript</span><span class="punctuation separator js">:</span><span class="variable other object js">location</span><span class="punctuation accessor js">.</span><span class="meta property object js">href</span><span class="keyword operator assignment js">=</span><span class="string quoted single js"><span class="punctuation definition string begin js">'</span>org-protocol://capture?template=w&url=<span class="punctuation definition string end js">'</span></span><span class="keyword operator arithmetic js">+</span><span class="meta function-call js"><span class="support function js">encodeURIComponent</span><span class="meta group js"><span class="punctuation section group js">(</span><span class="variable other object js">location</span><span class="punctuation accessor js">.</span><span class="meta property object js">href</span></span><span class="meta group js"><span class="punctuation section group js">)</span></span></span><span class="keyword operator arithmetic js">+</span><span class="string quoted single js"><span class="punctuation definition string begin js">'</span>&title=<span class="punctuation definition string end js">'</span></span><span class="keyword operator arithmetic js">+</span><span class="meta function-call js"><span class="support function js">encodeURIComponent</span><span class="meta group js"><span class="punctuation section group js">(</span><span class="support type object dom js">document</span><span class="punctuation accessor js">.</span><span class="meta property object js">title</span></span><span class="meta group js"><span class="punctuation section group js">)</span></span></span><span class="keyword operator arithmetic js">+</span><span class="string quoted single js"><span class="punctuation definition string begin js">'</span>&body=<span class="punctuation definition string end js">'</span></span><span class="keyword operator arithmetic js">+</span><span class="meta function-call js"><span class="support function js">encodeURIComponent</span><span class="meta group js"><span class="punctuation section group js">(</span><span class="support type object dom js">window</span><span class="punctuation accessor js">.</span><span class="meta function-call method js"><span class="variable function js">getSelection</span><span class="meta group js"><span class="punctuation section group js">(</span></span><span class="meta group js"><span class="punctuation section group js">)</span></span></span></span><span class="meta group js"><span class="punctuation section group js">)</span></span></span></span></code></pre>
274<pre><code class="language-js highlight"><span class="source js"><span class="entity name label js">javascript</span><span class="punctuation separator js">:</span><span class="variable other object js">location</span><span class="punctuation accessor js">.</span><span class="meta property object js">href</span><span class="keyword operator assignment js">=</span><span class="string quoted single js"><span class="punctuation definition string begin js">'</span>org-protocol://store-link?url=<span class="punctuation definition string end js">'</span></span><span class="keyword operator arithmetic js">+</span><span class="meta function-call js"><span class="support function js">encodeURIComponent</span><span class="meta group js"><span class="punctuation section group js">(</span><span class="variable other object js">location</span><span class="punctuation accessor js">.</span><span class="meta property object js">href</span></span><span class="meta group js"><span class="punctuation section group js">)</span></span></span><span class="keyword operator arithmetic js">+</span><span class="string quoted single js"><span class="punctuation definition string begin js">'</span>&title=<span class="punctuation definition string end js">'</span></span><span class="keyword operator arithmetic js">+</span><span class="meta function-call js"><span class="support function js">encodeURIComponent</span><span class="meta group js"><span class="punctuation section group js">(</span><span class="support type object dom js">document</span><span class="punctuation accessor js">.</span><span class="meta property object js">title</span></span><span class="meta group js"><span class="punctuation section group js">)</span></span></span></span></code></pre>
275<p>A matching web capture template:</p>
276<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">template</span><span class="punctuation definition table array toml">]]</span>
277<span class="variable other key toml">key</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>w<span class="punctuation definition string end toml">"</span></span>
278<span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Web page<span class="punctuation definition string end toml">"</span></span>
279<span class="variable other key toml">file</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>inbox.org<span class="punctuation definition string end toml">"</span></span>
280<span class="variable other key toml">headline</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Web<span class="punctuation definition string end toml">"</span></span>
281<span class="variable other key toml">template</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>* %:description<span class="constant character escape toml">\n</span>:PROPERTIES:<span class="constant character escape toml">\n</span>:URL: %:link<span class="constant character escape toml">\n</span>:END:<span class="constant character escape toml">\n</span>%U<span class="constant character escape toml">\n</span>%i<span class="constant character escape toml">\n</span>%?<span class="punctuation definition string end toml">"</span></span></span></code></pre>
282<h2 id="shortcuts">Shortcuts</h2>
283<p>The Shortcuts action Capture to Orgstar files text with a template, without the capture window. It has two parameters:</p>
284<table>
285<thead>
286<tr><th>Parameter</th><th>Meaning</th></tr>
287</thead>
288<tbody>
289<tr><td>Text</td><td>The text, inserted as <code class="verbatim">%i</code></td></tr>
290<tr><td>Template Key</td><td>A template's <code class="verbatim">key</code> in <code class="verbatim">capture.toml</code>; the first template when empty</td></tr>
291</tbody>
292</table>
293<p>Every prompt in the template takes its default (an empty answer: today for dates, no tags), and <code class="verbatim">%?</code> is ignored. <code class="verbatim">%a</code> is empty. On the Mac, <code class="verbatim">%c</code> is the clipboard and <code class="verbatim">%n</code> your name; on iOS both are empty, because reading the pasteboard would ask for permission on every run. The action returns a message, <code class="verbatim">Captured to …</code> with the target on the Mac and <code class="verbatim">Captured with …</code> with the template name on iOS, or fails with the same messages as the capture window. You can also say "Capture to Orgstar" to Siri.</p>
294<p>On the Mac, the action opens Orgstar if it isn't running and waits up to five seconds for it to be ready.</p>
295<h2 id="capture-on-ios">Capture on iOS</h2>
296<p>The Capture button (a square with a pencil) at the top of the Agenda and Folders tabs opens the capture sheet. The templates come from the <code class="verbatim">capture.toml</code> in your synced configuration folder (see <a href="14-ios.html">iOS</a>).</p>
297<p>The sheet works as on the Mac, in a form:</p>
298<ul>
299<li>The Template picker chooses the template; it starts on the first one.</li>
300<li>Prompts appear as fields. Date prompts have a date picker; choices and tags appear as buttons, and tapping a tag adds it.</li>
301<li>Continue fills the template and shows the text to edit; File files it; Cancel discards it.</li>
302</ul>
303<p>Differences from the Mac: there is no selection, clipboard, current file, user name or clock link to insert, so <code class="verbatim">%i</code> and <code class="verbatim">%a</code> are empty unless the capture came from a link or the share sheet, and <code class="verbatim">%c</code>, <code class="verbatim">%x</code>, <code class="verbatim">%f</code>, <code class="verbatim">%F</code>, <code class="verbatim">%n</code>, <code class="verbatim">%k</code> and <code class="verbatim">%K</code> are empty. An org-protocol link naming a template key that doesn't exist opens the sheet on the first template and shows <code class="verbatim">No capture template "x"</code> with the key.</p>
304<h3 id="the-share-sheet">The share sheet</h3>
305<p>In another app, share a web page or text and choose Orgstar. The share form has:</p>
306<ul>
307<li>a Template picker, with the templates the app read the last time it ran;</li>
308<li>for a link, its title (editable) and address;</li>
309<li>a Text field, filled with shared text.</li>
310</ul>
311<p>Capture saves the item in the app group's capture inbox. The next time you open Orgstar, it opens the capture sheet with the item as an org-protocol capture: the link becomes <code class="verbatim">%a</code> and <code class="verbatim">%:link</code>, the title <code class="verbatim">%:description</code>, and the text <code class="verbatim">%i</code>. Several waiting items open one after another, oldest first. If the extension says Orgstar's shared folder isn't available, the app group is missing from the build and nothing can be saved.</p>
312<p>The share form lists no templates until Orgstar has run once with your configuration folder; the capture sheet then starts on the first template.</p>
313<h2 id="importing-templates-from-emacs">Importing templates from Emacs</h2>
314<p>Import from Emacs (see <a href="13-configuration.html">Configuration</a> and <a href="15-alongside-emacs.html">Alongside Emacs</a>) reads <code class="verbatim">org-capture-templates</code> and appends a <code class="verbatim">[[template]]</code> table to <code class="verbatim">capture.toml</code> for each template whose key isn't there already.</p>
315<table>
316<thead>
317<tr><th>Emacs</th><th>Imported as</th></tr>
318</thead>
319<tbody>
320<tr><td>types <code class="verbatim">entry</code>, <code class="verbatim">item</code>, <code class="verbatim">checkitem</code>, <code class="verbatim">plain</code>, <code class="verbatim">table-line</code></td><td><code class="verbatim">type</code></td></tr>
321<tr><td><code class="verbatim">(file "f")</code></td><td><code class="verbatim">file</code></td></tr>
322<tr><td><code class="verbatim">(file+headline "f" "H")</code></td><td><code class="verbatim">file</code>, <code class="verbatim">headline</code></td></tr>
323<tr><td><code class="verbatim">(file+olp "f" "A" "B")</code></td><td><code class="verbatim">file</code>, <code class="verbatim">olp = "A/B"</code></td></tr>
324<tr><td><code class="verbatim">(file+olp+datetree "f" …)</code></td><td><code class="verbatim">file</code>, <code class="verbatim">datetree</code>, <code class="verbatim">olp</code> if a path is given</td></tr>
325<tr><td><code class="verbatim">(file+datetree "f")</code></td><td><code class="verbatim">file</code>, <code class="verbatim">datetree</code></td></tr>
326<tr><td><code class="verbatim">(file+weektree "f")</code></td><td><code class="verbatim">file</code>, <code class="verbatim">datetree</code>, <code class="verbatim">tree-type = "week"</code></td></tr>
327<tr><td><code class="verbatim">(id "…")</code></td><td><code class="verbatim">id</code></td></tr>
328<tr><td><code class="verbatim">(clock)</code></td><td><code class="verbatim">clock</code></td></tr>
329<tr><td><code class="verbatim">:prepend</code>, <code class="verbatim">:immediate-finish</code>, <code class="verbatim">:jump-to-captured</code>, <code class="verbatim">:clock-in</code>, <code class="verbatim">:clock-keep</code>, <code class="verbatim">:clock-resume</code></td><td>the boolean of the same name</td></tr>
330<tr><td><code class="verbatim">:empty-lines</code>, <code class="verbatim">:empty-lines-before</code>, <code class="verbatim">:empty-lines-after</code>, <code class="verbatim">:table-line-pos</code>, <code class="verbatim">:tree-type</code></td><td>the key of the same name</td></tr>
331</tbody>
332</table>
333<p>A file name given as a variable or a simple form is evaluated where the importer can. The import report lists what it left out: other targets, templates that aren't strings, unknown <code class="verbatim">:tree-type</code> values, and other properties such as <code class="verbatim">:time-prompt</code>, <code class="verbatim">:kill-buffer</code> or <code class="verbatim">:unnarrowed</code>. Template groups are skipped.</p>
334<p>Emacs resolves relative target files against <code class="verbatim">org-directory</code>; Orgstar resolves them against the first folder in the sidebar. If <code class="verbatim">org-directory</code> isn't your first folder, edit the imported <code class="verbatim">file</code> values or make them absolute.</p>
335</main>
336<footer class="site">
337Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>.
338</footer>
339</body>
340</html>