krz/orgstar

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

guide/13-configuration.html

pages
orgstar/guide/13-configuration.html history · blame · raw

601 lines · 77174 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>Configuration &middot; Orgstar</title>
  7<meta name="description" content="The Settings window, the files in ~/.config/orgstar, in-file settings, importing from Emacs, themes and fonts.">
  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>Configuration</h1>
 24<p class="lede">Every setting lives in a text file you can edit, and most of them also appear in the Settings window.</p>
 25<nav class="toc" aria-label="On this page">
 26<h2>On this page</h2>
 27<ul>
 28<li><a href="#where-settings-live">Where settings live</a>
 29<ul>
 30<li><a href="#opening-config-toml">Opening config.toml</a></li>
 31<li><a href="#problems-in-the-files">Problems in the files</a></li>
 32</ul></li>
 33<li><a href="#the-settings-window">The Settings window</a>
 34<ul>
 35<li><a href="#general">General</a></li>
 36<li><a href="#editing">Editing</a></li>
 37<li><a href="#appearance">Appearance</a></li>
 38<li><a href="#agenda">Agenda</a></li>
 39<li><a href="#capture">Capture</a></li>
 40<li><a href="#settings-only-in-config-toml">Settings only in config.toml</a></li>
 41</ul></li>
 42<li><a href="#config-toml-reference">config.toml reference</a>
 43<ul>
 44<li><a href="#top-level">Top level</a></li>
 45<li><a href="#org-agenda-prefix-format">[org-agenda-prefix-format]</a></li>
 46<li><a href="#theme">[theme]</a></li>
 47<li><a href="#orgstar">[orgstar]</a></li>
 48<li><a href="#an-example">An example</a></li>
 49<li><a href="#names-from-earlier-versions">Names from earlier versions</a></li>
 50</ul></li>
 51<li><a href="#keymap-toml-and-capture-toml">keymap.toml and capture.toml</a></li>
 52<li><a href="#in-file-settings">In-file settings</a>
 53<ul>
 54<li><a href="#keywords-orgstar-reads">Keywords Orgstar reads</a></li>
 55<li><a href="#startup-options">#+STARTUP options</a></li>
 56<li><a href="#setup-files">Setup files</a></li>
 57</ul></li>
 58<li><a href="#import-from-emacs">Import from Emacs</a>
 59<ul>
 60<li><a href="#running-it">Running it</a></li>
 61<li><a href="#doom-emacs">Doom Emacs</a></li>
 62<li><a href="#what-it-reads">What it reads</a></li>
 63<li><a href="#how-variables-map">How variables map</a></li>
 64<li><a href="#limits-of-the-lisp-reader">Limits of the Lisp reader</a></li>
 65</ul></li>
 66<li><a href="#themes">Themes</a>
 67<ul>
 68<li><a href="#theme-files">Theme files</a></li>
 69<li><a href="#color-keys">Color keys</a></li>
 70</ul></li>
 71<li><a href="#appearance">Appearance</a></li>
 72<li><a href="#fonts">Fonts</a></li>
 73</ul>
 74</nav>
 75<h2 id="where-settings-live">Where settings live</h2>
 76<p>Orgstar keeps its settings in a configuration folder:</p>
 77<ul>
 78<li><code class="verbatim">$XDG_CONFIG_HOME/orgstar</code> when <code class="verbatim">XDG_CONFIG_HOME</code> is set and not empty,</li>
 79<li>otherwise <code class="verbatim">~/.config/orgstar</code>.</li>
 80</ul>
 81<p>The environment variable <code class="verbatim">ORGSTAR_CONFIG_DIR</code> overrides both. If a file is missing from the configuration folder but exists in <code class="verbatim">~/Library/Application Support/Orgstar</code> (where earlier versions kept it), Orgstar reads it from there, and reloads it when you edit it there.</p>
 82<p>The folder holds these files:</p>
 83<table>
 84<thead>
 85<tr><th>File</th><th>What it holds</th><th>Written by Orgstar</th></tr>
 86</thead>
 87<tbody>
 88<tr><td><code class="verbatim">config.toml</code></td><td>Every setting of the Settings window, and the theme</td><td>Yes, when you change a setting</td></tr>
 89<tr><td><code class="verbatim">keymap.toml</code></td><td>Your key bindings, on top of the preset</td><td>Only by Import from Emacs</td></tr>
 90<tr><td><code class="verbatim">capture.toml</code></td><td>Capture templates</td><td>Only by Import from Emacs</td></tr>
 91<tr><td><code class="verbatim">views.toml</code></td><td>Saved agenda views</td><td>No</td></tr>
 92<tr><td><code class="verbatim">default-theme.toml</code></td><td>The default theme's colors, for reference</td><td>Yes, at every launch</td></tr>
 93</tbody>
 94</table>
 95<p><code class="verbatim">config.toml</code> is the source of truth. The Settings window writes each change into it, keeping your comments and the order of lines, and edits you make to the file apply while Orgstar runs. If the file doesn't exist at launch, Orgstar creates it with every setting at its current value and a comment after each one.</p>
 96<p>When you add the folder to a dotfiles repository, keep <code class="verbatim">default-theme.toml</code> out of it or ignore its changes: Orgstar rewrites it whenever its contents differ from the built-in theme.</p>
 97<h3 id="opening-config-toml">Opening config.toml</h3>
 98<ul>
 99<li>Orgstar ▸ Edit Config File (<code class="verbatim">⌥⌘,</code>) opens <code class="verbatim">config.toml</code> as a buffer in the main window. The command palette has the same command as Edit Config File.</li>
100<li>Settings ▸ General has three buttons for the file: Edit in Orgstar, Open with Default App, and Show in Finder.</li>
101</ul>
102<p>Saving the buffer applies the file, the same as saving it from another editor.</p>
103<h3 id="problems-in-the-files">Problems in the files</h3>
104<p>If <code class="verbatim">config.toml</code> has a line Orgstar can't use, the problem shows in the message line under the editor, with a count when there are more. Each problem names the file and the key:</p>
105<ul>
106<li><code class="verbatim">config.toml: unknown setting editor.foo</code></li>
107<li><code class="verbatim">config.toml: org-log-done must be one of nil, time, note</code></li>
108<li><code class="verbatim">config.toml: org-agenda-start-day must look like "-3d" or "+0d"</code></li>
109<li><code class="verbatim">config.toml: theme.light.background must be a color such as "#1f2328"</code></li>
110</ul>
111<p>A file that isn't valid TOML is reported with its parse error, and none of it applies. <code class="verbatim">keymap.toml</code>, <code class="verbatim">capture.toml</code> and <code class="verbatim">views.toml</code> report their problems the same way when they are read.</p>
112<h2 id="the-settings-window">The Settings window</h2>
113<p>Open it with Orgstar ▸ Settings (<code class="verbatim">⌘,</code>). It has five panes. Each control writes the <code class="verbatim">config.toml</code> key named in the tables below; the config.toml reference below gives the type and the Emacs variable.</p>
114<h3 id="general">General</h3>
115<table>
116<thead>
117<tr><th>Control</th><th>Choices</th><th>Default</th><th>Key</th></tr>
118</thead>
119<tbody>
120<tr><td>config.toml: Edit in Orgstar</td><td>Opens the file in the main window</td><td></td><td></td></tr>
121<tr><td>config.toml: Open with Default App</td><td>Opens the file in the app macOS uses for <code class="verbatim">.toml</code></td><td></td><td></td></tr>
122<tr><td>config.toml: Show in Finder</td><td>Selects the file in Finder</td><td></td><td></td></tr>
123<tr><td>Emacs: Import from Emacs…</td><td>Opens the import sheet; see Import from Emacs below</td><td></td><td></td></tr>
124<tr><td>Save files</td><td>Automatically, when typing stops; Only with File ▸ Save (<code class="verbatim">⌘S</code>)</td><td>Automatically</td><td><code class="verbatim">save</code></td></tr>
125<tr><td>Keys</td><td>Emacs; Mac; Doom (Vim keys)</td><td>Emacs</td><td><code class="verbatim">keymap</code></td></tr>
126<tr><td>Show hidden files and folders</td><td>On or off</td><td>On</td><td><code class="verbatim">show-hidden-files</code></td></tr>
127<tr><td>Option as Meta</td><td>Left Option; Right Option; Both; Neither</td><td>Left Option</td><td><code class="verbatim">option-as-meta</code></td></tr>
128</tbody>
129</table>
130<p>Automatic saving writes a file one second after you stop typing. The keymap presets and <code class="verbatim">keymap.toml</code> are covered in <a href="03-keys.html">Keys and commands</a>.</p>
131<h3 id="editing">Editing</h3>
132<table>
133<thead>
134<tr><th>Control</th><th>Choices or range</th><th>Default</th><th>Key</th></tr>
135</thead>
136<tbody>
137<tr><td>Tags</td><td>Aligned to end at column 77; One space after the title</td><td>Aligned (<code class="verbatim">-77</code>)</td><td><code class="verbatim">org-tags-column</code></td></tr>
138<tr><td>M-RET adds the new heading after the subtree</td><td>On or off</td><td>On</td><td><code class="verbatim">org-insert-heading-respect-content</code></td></tr>
139<tr><td>M-RET splits the line at the caret</td><td>On or off</td><td>Off</td><td><code class="verbatim">org-M-RET-may-split-line</code></td></tr>
140<tr><td>Lists can use letters (a. b. c.)</td><td>On or off</td><td>On</td><td><code class="verbatim">org-list-allow-alphabetical</code></td></tr>
141<tr><td>M-q fills to column N</td><td>40 to 200</td><td>80</td><td><code class="verbatim">fill-column</code></td></tr>
142<tr><td>Long lines run off the edge instead of wrapping (org-startup-truncated)</td><td>On or off</td><td>Off</td><td><code class="verbatim">org-startup-truncated</code></td></tr>
143<tr><td>Emacs hides emphasis markers (org-hide-emphasis-markers)</td><td>On or off</td><td>On</td><td><code class="verbatim">org-hide-emphasis-markers</code></td></tr>
144<tr><td>Emacs shows entities as characters (org-pretty-entities)</td><td>On or off</td><td>On</td><td><code class="verbatim">org-pretty-entities</code></td></tr>
145<tr><td>Default TODO keywords</td><td>Text in <code class="verbatim">#+TODO</code> syntax, one sequence per line</td><td>See below</td><td><code class="verbatim">org-todo-keywords</code></td></tr>
146</tbody>
147</table>
148<p>The two "Emacs hides" and "Emacs shows" switches describe your Emacs, not Orgstar's display. Tag alignment, table alignment and <code class="verbatim">M-q</code> measure text the way your Emacs displays it, so a file edited in both keeps the same layout. Set them to match your Emacs configuration. They also control whether Orgstar hides markers and shows entities when markup is hidden.</p>
149<p>The Tags picker offers two values. <code class="verbatim">config.toml</code> accepts any integer; with a value other than <code class="verbatim">-77</code> or <code class="verbatim">0</code> the picker shows no selection.</p>
150<p>The long-lines switch applies to files as they open; View ▸ Truncate or Wrap Long Lines switches the file in front.</p>
151<p>Default TODO keywords apply to files without a <code class="verbatim">#+TODO</code> line. Orgstar reads them at launch, so a change takes effect after you quit and reopen Orgstar.</p>
152<h3 id="appearance">Appearance</h3>
153<table>
154<thead>
155<tr><th>Control</th><th>Range</th><th>Default</th><th>Key</th></tr>
156</thead>
157<tbody>
158<tr><td>Font</td><td>System monospaced, or any installed monospaced family</td><td>System monospaced</td><td><code class="verbatim">font</code></td></tr>
159<tr><td>Size</td><td>8 to 36 pt</td><td>13 pt</td><td><code class="verbatim">font-size</code></td></tr>
160<tr><td>Line spacing</td><td>0 to 16 pt</td><td>2 pt</td><td><code class="verbatim">line-spacing</code></td></tr>
161<tr><td>Headings grow by N pt a level</td><td>0 to 8 pt</td><td>1 pt</td><td><code class="verbatim">heading-size-step</code></td></tr>
162<tr><td>Colors: Edit in config.toml</td><td>Opens <code class="verbatim">config.toml</code></td><td></td><td></td></tr>
163<tr><td>Colors: Show Default Theme</td><td>Opens <code class="verbatim">default-theme.toml</code></td><td></td><td></td></tr>
164</tbody>
165</table>
166<p>See Themes and Fonts below.</p>
167<h3 id="agenda">Agenda</h3>
168<table>
169<thead>
170<tr><th>Control</th><th>Range</th><th>Default</th><th>Key</th></tr>
171</thead>
172<tbody>
173<tr><td>Agenda shows N days</td><td>1 to 366</td><td>10</td><td><code class="verbatim">org-agenda-span</code></td></tr>
174<tr><td>Agenda starts N days before today</td><td>0 to 14 days before</td><td>3 days</td><td><code class="verbatim">org-agenda-start-day</code></td></tr>
175<tr><td>Include files in subfolders</td><td>On or off</td><td>Off</td><td><code class="verbatim">agenda-include-subfolders</code></td></tr>
176<tr><td>Notify before timed agenda entries</td><td>On or off</td><td>On</td><td><code class="verbatim">reminders</code></td></tr>
177<tr><td>N minutes before</td><td>0 to 120</td><td>12</td><td><code class="verbatim">appt-message-warning-time</code></td></tr>
178<tr><td>Ask what to do with idle time while clocked in</td><td>On or off</td><td>Off</td><td><code class="verbatim">org-clock-idle-time</code></td></tr>
179<tr><td>After N minutes without keyboard or mouse input</td><td>1 to 240</td><td>15 when turned on</td><td><code class="verbatim">org-clock-idle-time</code></td></tr>
180<tr><td>Remember N recently clocked entries</td><td>1 to 35</td><td>5</td><td><code class="verbatim">org-clock-history-length</code></td></tr>
181</tbody>
182</table>
183<p>An entry's <code class="verbatim">APPT_WARNTIME</code> property overrides the lead time. The agenda is covered in <a href="07-agenda.html">The agenda</a>.</p>
184<p>Turning on the idle question sets <code class="verbatim">org-clock-idle-time</code> to 15 minutes; turning it off sets it to <code class="verbatim">0</code>. The minutes stepper is disabled while the question is off. Idle time and the clock history are covered in <a href="06-dates-and-clocking.html">Dates and clocking</a>.</p>
185<h3 id="capture">Capture</h3>
186<table>
187<thead>
188<tr><th>Control</th><th>Default</th><th>Key</th></tr>
189</thead>
190<tbody>
191<tr><td>⌃⌥Space opens Capture from any app</td><td>On</td><td><code class="verbatim">global-capture-hotkey</code></td></tr>
192</tbody>
193</table>
194<p>The footer shows the path of <code class="verbatim">capture.toml</code>. Templates are covered in <a href="08-capture.html">Capture</a>.</p>
195<h3 id="settings-only-in-config-toml">Settings only in config.toml</h3>
196<p>These settings have no control in the Settings window. Some are in the View menu.</p>
197<table>
198<thead>
199<tr><th>Key</th><th>Also in</th></tr>
200</thead>
201<tbody>
202<tr><td><code class="verbatim">org-log-done</code></td><td></td></tr>
203<tr><td><code class="verbatim">org-log-reschedule</code></td><td></td></tr>
204<tr><td><code class="verbatim">org-log-redeadline</code></td><td></td></tr>
205<tr><td><code class="verbatim">org-log-into-drawer</code></td><td></td></tr>
206<tr><td><code class="verbatim">org-startup-indented</code></td><td></td></tr>
207<tr><td><code class="verbatim">org-hide-leading-stars</code></td><td></td></tr>
208<tr><td><code class="verbatim">org-startup-align-all-tables</code></td><td></td></tr>
209<tr><td><code class="verbatim">org-startup-with-inline-images</code></td><td></td></tr>
210<tr><td><code class="verbatim">org-cycle-hide-drawer-startup</code></td><td></td></tr>
211<tr><td><code class="verbatim">org-cycle-hide-block-startup</code></td><td></td></tr>
212<tr><td><code class="verbatim">org-use-speed-commands</code></td><td></td></tr>
213<tr><td><code class="verbatim">spell-check</code></td><td></td></tr>
214<tr><td><code class="verbatim">electric-pair-mode</code></td><td></td></tr>
215<tr><td><code class="verbatim">display-line-numbers-type</code></td><td>View ▸ Show Line Numbers (<code class="verbatim">⇧⌘L</code>)</td></tr>
216<tr><td><code class="verbatim">tab-bar</code></td><td>View ▸ Show Tab Bar</td></tr>
217<tr><td><code class="verbatim">show-markup</code></td><td>View ▸ Show Markup (<code class="verbatim">⇧⌘M</code>)</td></tr>
218<tr><td><code class="verbatim">ignored-folders</code></td><td></td></tr>
219<tr><td><code class="verbatim">[org-agenda-prefix-format]</code></td><td></td></tr>
220<tr><td><code class="verbatim">theme-file</code></td><td></td></tr>
221</tbody>
222</table>
223<h2 id="config-toml-reference">config.toml reference</h2>
224<p>Settings that mirror an Emacs variable sit at the top of the file under that variable's name. The agenda prefix formats are in <code class="verbatim">[org-agenda-prefix-format]</code>, type and theme in <code class="verbatim">[theme]</code>, and the settings Emacs has no variable for in <code class="verbatim">[orgstar]</code>.</p>
225<p>A key you remove from the file goes back to its default. A key that isn't in the table below is reported as unknown.</p>
226<h3 id="top-level">Top level</h3>
227<table>
228<thead>
229<tr><th>Key</th><th>Type</th><th>Default</th><th>Effect</th></tr>
230</thead>
231<tbody>
232<tr><td><code class="verbatim">fill-column</code></td><td>integer</td><td><code class="verbatim">80</code></td><td>The column <code class="verbatim">M-q</code> fills to. Mirrors <code class="verbatim">fill-column</code>.</td></tr>
233<tr><td><code class="verbatim">org-tags-column</code></td><td>integer</td><td><code class="verbatim">-77</code></td><td>Negative: tags end at that column. <code class="verbatim">0</code>: one space between title and tags. Mirrors <code class="verbatim">org-tags-column</code>.</td></tr>
234<tr><td><code class="verbatim">org-insert-heading-respect-content</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td><code class="verbatim">M-RET</code> adds the new heading after the current subtree. Mirrors <code class="verbatim">org-insert-heading-respect-content</code>.</td></tr>
235<tr><td><code class="verbatim">org-M-RET-may-split-line</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td><code class="verbatim">M-RET</code> in the middle of a line splits it at the caret. Mirrors the <code class="verbatim">default</code> entry of <code class="verbatim">org-M-RET-may-split-line</code>.</td></tr>
236<tr><td><code class="verbatim">org-list-allow-alphabetical</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td><code class="verbatim">a.</code>, <code class="verbatim">b)</code>, <code class="verbatim">A.</code> are list bullets. Mirrors <code class="verbatim">org-list-allow-alphabetical</code>.</td></tr>
237<tr><td><code class="verbatim">org-hide-emphasis-markers</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Your Emacs hides <code class="verbatim">*bold*</code> and <code>=code=</code> markers; Orgstar hides them when markup is hidden and measures text without them. Mirrors <code class="verbatim">org-hide-emphasis-markers</code>.</td></tr>
238<tr><td><code class="verbatim">org-pretty-entities</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Your Emacs shows <code class="verbatim">\alpha</code> as α and lowers <code class="verbatim">x_{1}</code>; Orgstar does the same when markup is hidden. Mirrors <code class="verbatim">org-pretty-entities</code>.</td></tr>
239<tr><td><code class="verbatim">org-todo-keywords</code></td><td>string</td><td>see below</td><td>Keywords for files without <code class="verbatim">#+TODO</code>, in <code class="verbatim">#+TODO</code> syntax; separate sequences with <code class="verbatim">\n</code>. Letters in parentheses turn on fast selection. Read at launch. Mirrors <code class="verbatim">org-todo-keywords</code>.</td></tr>
240<tr><td><code class="verbatim">org-log-done</code></td><td>string</td><td><code class="verbatim">"nil"</code></td><td><code class="verbatim">nil</code>, <code class="verbatim">time</code> (a <code class="verbatim">CLOSED</code> timestamp) or <code class="verbatim">note</code> (<code class="verbatim">CLOSED</code> and a note). Mirrors <code class="verbatim">org-log-done</code>.</td></tr>
241<tr><td><code class="verbatim">org-log-reschedule</code></td><td>string</td><td><code class="verbatim">"nil"</code></td><td><code class="verbatim">nil</code>, <code class="verbatim">time</code> or <code class="verbatim">note</code>: log changing or removing a <code class="verbatim">SCHEDULED</code> date. Mirrors <code class="verbatim">org-log-reschedule</code>.</td></tr>
242<tr><td><code class="verbatim">org-log-redeadline</code></td><td>string</td><td><code class="verbatim">"nil"</code></td><td><code class="verbatim">nil</code>, <code class="verbatim">time</code> or <code class="verbatim">note</code>: log changing or removing a <code class="verbatim">DEADLINE</code>. Mirrors <code class="verbatim">org-log-redeadline</code>.</td></tr>
243<tr><td><code class="verbatim">org-log-into-drawer</code></td><td>string</td><td><code class="verbatim">""</code></td><td>The drawer state notes go in. <code class="verbatim">"LOGBOOK"</code> is Emacs's <code class="verbatim">t</code>; <code class="verbatim">""</code> puts them under the heading. Mirrors <code class="verbatim">org-log-into-drawer</code>.</td></tr>
244<tr><td><code class="verbatim">org-startup-indented</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Indent bodies under their headings, as <code class="verbatim">org-indent-mode</code>. <code class="verbatim">#+STARTUP: indent</code> / <code class="verbatim">noindent</code> override it. Mirrors <code class="verbatim">org-startup-indented</code>.</td></tr>
245<tr><td><code class="verbatim">org-hide-leading-stars</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Show only a heading's last star, without indentation. <code class="verbatim">#+STARTUP: hidestars</code> / <code class="verbatim">showstars</code> override it. Mirrors <code class="verbatim">org-hide-leading-stars</code>.</td></tr>
246<tr><td><code class="verbatim">org-startup-align-all-tables</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Align every table when a file opens. <code class="verbatim">#+STARTUP: align</code> / <code class="verbatim">noalign</code> override it. Mirrors <code class="verbatim">org-startup-align-all-tables</code>.</td></tr>
247<tr><td><code class="verbatim">org-startup-truncated</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Long lines run off the right edge instead of wrapping. Mirrors <code class="verbatim">org-startup-truncated</code>.</td></tr>
248<tr><td><code class="verbatim">spell-check</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Check spelling while typing, outside code, links, dates, tags and keywords.</td></tr>
249<tr><td><code class="verbatim">electric-pair-mode</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Type brackets, <code class="verbatim">&lt;&gt;</code> and quotes in pairs. Mirrors <code class="verbatim">electric-pair-mode</code>.</td></tr>
250<tr><td><code class="verbatim">org-startup-with-inline-images</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Show image links as images when a file opens. <code class="verbatim">#+STARTUP: inlineimages</code> / <code class="verbatim">noinlineimages</code> override it. Mirrors <code class="verbatim">org-startup-with-inline-images</code>.</td></tr>
251<tr><td><code class="verbatim">org-use-speed-commands</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Single keys at the start of a heading line run commands (<code class="verbatim">n</code>, <code class="verbatim">p</code>, <code class="verbatim">t</code>, <code class="verbatim">c</code>, …). Mirrors <code class="verbatim">org-use-speed-commands</code>.</td></tr>
252<tr><td><code class="verbatim">org-cycle-hide-drawer-startup</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Fold drawers when a file opens. <code class="verbatim">#+STARTUP: hidedrawers</code> / <code class="verbatim">nohidedrawers</code> override it. Mirrors <code class="verbatim">org-cycle-hide-drawer-startup</code>.</td></tr>
253<tr><td><code class="verbatim">org-cycle-hide-block-startup</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Fold blocks when a file opens. <code class="verbatim">#+STARTUP: hideblocks</code> / <code class="verbatim">nohideblocks</code> override it. Mirrors <code class="verbatim">org-cycle-hide-block-startup</code>.</td></tr>
254<tr><td><code class="verbatim">display-line-numbers-type</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Line numbers in the editor's gutter. Orgstar numbers lines absolutely; there is no relative or visual mode.</td></tr>
255<tr><td><code class="verbatim">org-agenda-span</code></td><td>integer</td><td><code class="verbatim">10</code></td><td>Days the agenda shows. Mirrors <code class="verbatim">org-agenda-span</code>.</td></tr>
256<tr><td><code class="verbatim">org-agenda-start-day</code></td><td>string</td><td><code class="verbatim">"-3d"</code></td><td>The agenda's first day relative to today, as <code class="verbatim">"-3d"</code> or <code class="verbatim">"+0d"</code>. Only day offsets are accepted. Mirrors <code class="verbatim">org-agenda-start-day</code>.</td></tr>
257<tr><td><code class="verbatim">appt-message-warning-time</code></td><td>integer</td><td><code class="verbatim">12</code></td><td>Minutes of warning before timed entries. An entry's <code class="verbatim">APPT_WARNTIME</code> property overrides it. Mirrors <code class="verbatim">appt-message-warning-time</code>.</td></tr>
258<tr><td><code class="verbatim">org-clock-idle-time</code></td><td>integer</td><td><code class="verbatim">0</code></td><td>Minutes without keyboard or mouse input, with a clock running, before Orgstar asks what to do with the idle time. <code class="verbatim">0</code> never asks (Emacs's <code class="verbatim">nil</code>). Mac only. Mirrors <code class="verbatim">org-clock-idle-time</code>.</td></tr>
259<tr><td><code class="verbatim">org-clock-history-length</code></td><td>integer</td><td><code class="verbatim">5</code></td><td>How many recently clocked entries Orgstar remembers. Mirrors <code class="verbatim">org-clock-history-length</code>.</td></tr>
260</tbody>
261</table>
262<p>The default <code class="verbatim">org-todo-keywords</code> is the first sequence of Doom Emacs's default:</p>
263<pre><code class="language-toml highlight"><span class="source toml"><span class="variable other key toml">org-todo-keywords</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>TODO(t) PROJ(p) LOOP(r) STRT(s) WAIT(w) HOLD(h) IDEA(i) | DONE(d) KILL(k)<span class="punctuation definition string end toml">&quot;</span></span></span></code></pre>
264<p>The startup settings (<code class="verbatim">org-startup-*</code>, <code class="verbatim">org-hide-leading-stars</code>, <code class="verbatim">org-cycle-hide-*-startup</code>) apply when a file opens. Files already open keep their state until you open them again.</p>
265<h3 id="org-agenda-prefix-format">[org-agenda-prefix-format]</h3>
266<table>
267<thead>
268<tr><th>Key</th><th>Type</th><th>Default</th><th>Effect</th></tr>
269</thead>
270<tbody>
271<tr><td><code class="verbatim">agenda</code></td><td>string</td><td><code class="verbatim">" %i %-12:c%?-12t% s"</code></td><td>Prefix of lines in the day view</td></tr>
272<tr><td><code class="verbatim">todo</code></td><td>string</td><td><code class="verbatim">" %i %-12:c"</code></td><td>Prefix of lines in the TODO list</td></tr>
273<tr><td><code class="verbatim">tags</code></td><td>string</td><td><code class="verbatim">" %i %-12:c"</code></td><td>Prefix of tag and property matches</td></tr>
274</tbody>
275</table>
276<p>These mirror the entries of <code class="verbatim">org-agenda-prefix-format</code>. In the format, <code class="verbatim">%c</code> is the category, <code class="verbatim">%t</code> the time, <code class="verbatim">%s</code> the scheduled or deadline note, <code class="verbatim">%e</code> the effort, <code class="verbatim">%l</code> the level, <code class="verbatim">%b</code> the outline path, <code class="verbatim">%T</code> the item's last tag (inherited tags included), and a number such as <code class="verbatim">%-12</code> pads. See <a href="07-agenda.html">The agenda</a>.</p>
277<h3 id="theme">[theme]</h3>
278<table>
279<thead>
280<tr><th>Key</th><th>Type</th><th>Default</th><th>Effect</th></tr>
281</thead>
282<tbody>
283<tr><td><code class="verbatim">font</code></td><td>string</td><td><code class="verbatim">""</code></td><td>A font family. <code class="verbatim">""</code> uses the system's monospaced font.</td></tr>
284<tr><td><code class="verbatim">font-size</code></td><td>integer</td><td><code class="verbatim">13</code></td><td>Points.</td></tr>
285<tr><td><code class="verbatim">line-spacing</code></td><td>integer</td><td><code class="verbatim">2</code></td><td>Points between lines.</td></tr>
286<tr><td><code class="verbatim">heading-size-step</code></td><td>integer</td><td><code class="verbatim">1</code></td><td>Points a heading is larger than the level below. Level 4 and deeper are body size.</td></tr>
287<tr><td><code class="verbatim">theme-file</code></td><td>string</td><td><code class="verbatim">""</code></td><td>A theme in its own file in the configuration folder, applied under the colors in <code class="verbatim">config.toml</code>.</td></tr>
288</tbody>
289</table>
290<p>Any other key in <code class="verbatim">[theme]</code> is a color; see Themes below.</p>
291<h3 id="orgstar">[orgstar]</h3>
292<table>
293<thead>
294<tr><th>Key</th><th>Type</th><th>Default</th><th>Effect</th></tr>
295</thead>
296<tbody>
297<tr><td><code class="verbatim">save</code></td><td>string</td><td><code class="verbatim">"automatic"</code></td><td><code class="verbatim">automatic</code> (one second after typing stops) or <code class="verbatim">explicit</code> (only with <code class="verbatim">⌘S</code>).</td></tr>
298<tr><td><code class="verbatim">keymap</code></td><td>string</td><td><code class="verbatim">"emacs"</code></td><td><code class="verbatim">emacs</code>, <code class="verbatim">mac</code> or <code class="verbatim">doom</code>. Your own bindings go in <code class="verbatim">keymap.toml</code>.</td></tr>
299<tr><td><code class="verbatim">option-as-meta</code></td><td>string</td><td><code class="verbatim">"left"</code></td><td>Which Option key is Meta: <code class="verbatim">left</code>, <code class="verbatim">right</code>, <code class="verbatim">both</code> or <code class="verbatim">none</code>.</td></tr>
300<tr><td><code class="verbatim">tab-bar</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>A tab for each open buffer above the editor.</td></tr>
301<tr><td><code class="verbatim">show-markup</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Show link brackets and emphasis markers.</td></tr>
302<tr><td><code class="verbatim">show-hidden-files</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>List dotfiles and dot folders in your folders.</td></tr>
303<tr><td><code class="verbatim">ignored-folders</code></td><td>string</td><td>see below</td><td>Folder names never listed or searched, separated by spaces.</td></tr>
304<tr><td><code class="verbatim">agenda-include-subfolders</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>The agenda reads org files in subfolders too.</td></tr>
305<tr><td><code class="verbatim">reminders</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Notify before timed entries.</td></tr>
306<tr><td><code class="verbatim">global-capture-hotkey</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td><code class="verbatim">⌃⌥Space</code> opens Capture from any app.</td></tr>
307</tbody>
308</table>
309<p>The default <code class="verbatim">ignored-folders</code> is:</p>
310<pre><code class="language-toml highlight"><span class="source toml"><span class="variable other key toml">ignored-folders</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>.Spotlight-V100 .Trash .build .bzr .cache .fseventsd .git .gradle .hg .jj .mypy_cache .next .pytest_cache .stfolder .stversions .svn .terraform .tox .venv node_modules<span class="punctuation definition string end toml">&quot;</span></span></span></code></pre>
311<h3 id="an-example">An example</h3>
312<pre><code class="language-toml highlight"><span class="source toml"><span class="variable other key toml">fill-column</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">72</span>
313<span class="variable other key toml">org-tags-column</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">0</span>
314<span class="variable other key toml">org-todo-keywords</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>TODO(t) NEXT(n) WAIT(w@/!) | DONE(d!) CANCELED(c@)<span class="punctuation definition string end toml">&quot;</span></span>
315<span class="variable other key toml">org-log-done</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>time<span class="punctuation definition string end toml">&quot;</span></span>
316<span class="variable other key toml">org-log-into-drawer</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>LOGBOOK<span class="punctuation definition string end toml">&quot;</span></span>
317<span class="variable other key toml">org-startup-truncated</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">true</span>
318<span class="variable other key toml">org-agenda-span</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">7</span>
319<span class="variable other key toml">org-agenda-start-day</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>+0d<span class="punctuation definition string end toml">&quot;</span></span>
320
321<span class="punctuation definition table toml">[</span><span class="entity name section toml">theme</span><span class="punctuation definition table toml">]</span>
322<span class="variable other key toml">font</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>JetBrains Mono<span class="punctuation definition string end toml">&quot;</span></span>
323<span class="variable other key toml">font-size</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">14</span>
324<span class="variable other key toml">link</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>#0a7ea4<span class="punctuation definition string end toml">&quot;</span></span>
325
326<span class="punctuation definition table toml">[</span><span class="entity name section toml">theme.todo</span><span class="punctuation definition table toml">]</span>
327<span class="variable other key toml">WAIT</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>#bf8700<span class="punctuation definition string end toml">&quot;</span></span>
328
329<span class="punctuation definition table toml">[</span><span class="entity name section toml">orgstar</span><span class="punctuation definition table toml">]</span>
330<span class="variable other key toml">keymap</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>doom<span class="punctuation definition string end toml">&quot;</span></span>
331<span class="variable other key toml">save</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>explicit<span class="punctuation definition string end toml">&quot;</span></span></span></code></pre>
332<h3 id="names-from-earlier-versions">Names from earlier versions</h3>
333<p>Earlier versions used keys such as <code class="verbatim">editor.fill-column</code> and <code class="verbatim">agenda.span</code>. Orgstar still reads them. At launch, each such key in the file is renamed in place to its current name and moved to its current section; the rest of the file, and the comments on those lines, stay as they are. When a setting is in the file under both names, the current name wins and the old line is removed. A section the move leaves empty is removed. A file that lacks a whole section (such as <code class="verbatim">[theme]</code>) gets that section added at the end.</p>
334<h2 id="keymap-toml-and-capture-toml">keymap.toml and capture.toml</h2>
335<p><code class="verbatim">keymap.toml</code> holds <code class="verbatim">[[bind]]</code> tables with <code class="verbatim">keys</code>, <code class="verbatim">command</code>, and optionally <code class="verbatim">mode</code> and <code class="verbatim">when</code>. They layer over the preset chosen in Keys. Orgstar reloads the file when it changes. See <a href="03-keys.html">Keys and commands</a>.</p>
336<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span>
337<span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>C-c a<span class="punctuation definition string end toml">&quot;</span></span>
338<span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>app.agenda<span class="punctuation definition string end toml">&quot;</span></span></span></code></pre>
339<p><code class="verbatim">capture.toml</code> holds <code class="verbatim">[[template]]</code> tables. Without the file, Orgstar uses two templates: <code class="verbatim">t</code> (Personal todo, under <code class="verbatim">Inbox</code> in <code class="verbatim">todo.org</code>) and <code class="verbatim">n</code> (Personal notes, under <code class="verbatim">Inbox</code> in <code class="verbatim">notes.org</code>). See <a href="08-capture.html">Capture</a>.</p>
340<p><code class="verbatim">views.toml</code> holds <code class="verbatim">[[view]]</code> tables for the agenda; see <a href="07-agenda.html">The agenda</a>.</p>
341<h2 id="in-file-settings">In-file settings</h2>
342<p>Keyword lines in a file set options for that file, as in Emacs. Orgstar reads them outside blocks; for <code class="verbatim">#+STARTUP</code> only keyword lines count, so a <code class="verbatim">#+STARTUP</code> line inside a paragraph or a block changes nothing: not folding, logging or inline images.</p>
343<h3 id="keywords-orgstar-reads">Keywords Orgstar reads</h3>
344<table>
345<thead>
346<tr><th>Keyword</th><th>Effect</th></tr>
347</thead>
348<tbody>
349<tr><td><code class="verbatim">#+TODO</code>, <code class="verbatim">#+SEQ_TODO</code></td><td>A TODO sequence: active keywords, a bar, then done keywords. Without the bar, the last word is the done state. <code class="verbatim">NAME(k)</code> gives a fast-selection key, <code class="verbatim">NAME(k!/@)</code> logging on entering and leaving. Any TODO line replaces the default keywords.</td></tr>
350<tr><td><code class="verbatim">#+TYP_TODO</code></td><td>A type sequence. As in Org, type sequences come first, then <code class="verbatim">#+TODO</code>, then <code class="verbatim">#+SEQ_TODO</code>.</td></tr>
351<tr><td><code class="verbatim">#+PRIORITIES</code></td><td>Three values: highest, lowest, default, as <code class="verbatim">A C B</code> or <code class="verbatim">1 5 3</code>. The default is <code class="verbatim">A C B</code>.</td></tr>
352<tr><td><code class="verbatim">#+STARTUP</code></td><td>Startup options; see below.</td></tr>
353<tr><td><code class="verbatim">#+TAGS</code></td><td>Tags for fast tag selection with <code class="verbatim">C-c C-q</code>, with keys as <code class="verbatim">work(w)</code>, groups in <code class="verbatim">{ }</code> and tag groups in <code class="verbatim">[ ]</code>. Without <code class="verbatim">#+TAGS</code>, <code class="verbatim">C-c C-q</code> offers the tags used in the file.</td></tr>
354<tr><td><code class="verbatim">#+FILETAGS</code></td><td>Tags every heading in the file inherits, as <code class="verbatim">:work:project:</code>.</td></tr>
355<tr><td><code class="verbatim">#+PROPERTY</code></td><td>A file-wide property, as <code class="verbatim">#+PROPERTY: header-args :results output</code>. <code class="verbatim">NAME+</code> appends to the value.</td></tr>
356<tr><td><code class="verbatim">#+CATEGORY</code></td><td>The file's category in the agenda. Without it the category is the file name.</td></tr>
357<tr><td><code class="verbatim">#+ARCHIVE</code></td><td>Where <code class="verbatim">C-c C-x C-a</code> archives to. The default is <code class="verbatim">%s_archive::</code>.</td></tr>
358<tr><td><code class="verbatim">#+COLUMNS</code></td><td>The default column view format.</td></tr>
359<tr><td><code class="verbatim">#+LINK</code></td><td>A link abbreviation, as <code class="verbatim">#+LINK: gh https://github.com/%s</code>.</td></tr>
360<tr><td><code class="verbatim">#+CONSTANTS</code></td><td>Constants for table formulas, as <code class="verbatim">#+CONSTANTS: c=299792458 pi=3.14</code>.</td></tr>
361<tr><td><code class="verbatim">#+SETUPFILE</code></td><td>A file whose keyword lines count as this file's; see below.</td></tr>
362<tr><td><code class="verbatim">#+TITLE</code>, <code class="verbatim">#+AUTHOR</code>, <code class="verbatim">#+DESCRIPTION</code></td><td>Used by export, Quick Look and Spotlight.</td></tr>
363<tr><td><code class="verbatim">#+OPTIONS</code>, <code class="verbatim">#+MACRO</code>, <code class="verbatim">#+INCLUDE</code>, <code class="verbatim">#+EXCLUDE_TAGS</code>, <code class="verbatim">#+SELECT_TAGS</code></td><td>Export settings; see <a href="12-export.html">Export</a>.</td></tr>
364</tbody>
365</table>
366<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+TODO:</span><span class="string unquoted org"> TODO(t) NEXT(n) WAIT(w@/!) | DONE(d!) CANCELED(c@)</span>
367<span class="keyword other keyword org">#+PRIORITIES:</span><span class="string unquoted org"> A E C</span>
368<span class="keyword other keyword org">#+STARTUP:</span><span class="string unquoted org"> content logdrawer</span>
369<span class="keyword other keyword org">#+FILETAGS:</span><span class="string unquoted org"> :work:</span>
370<span class="keyword other keyword org">#+CATEGORY:</span><span class="string unquoted org"> acme</span></span></code></pre>
371<p>After you change a keyword line, press <code class="verbatim">C-c C-c</code> on it to read the file's settings again, as <code class="verbatim">org-mode-restart</code> does in Emacs. Changes to <code class="verbatim">#+TODO</code>, <code class="verbatim">#+SEQ_TODO</code>, <code class="verbatim">#+TYP_TODO</code> and <code class="verbatim">#+PRIORITIES</code> apply as you type.</p>
372<h3 id="startup-options">#+STARTUP options</h3>
373<table>
374<thead>
375<tr><th>Option</th><th>Effect</th></tr>
376</thead>
377<tbody>
378<tr><td><code class="verbatim">overview</code>, <code class="verbatim">fold</code></td><td>Only top-level headings show when the file opens.</td></tr>
379<tr><td><code class="verbatim">content</code></td><td>All headings show, no bodies.</td></tr>
380<tr><td><code class="verbatim">showall</code>, <code class="verbatim">nofold</code></td><td>Everything shows.</td></tr>
381<tr><td><code class="verbatim">show2levels</code> … <code class="verbatim">show5levels</code> (any <code class="verbatim">showNlevels</code>)</td><td>Headings down to level N show.</td></tr>
382<tr><td><code class="verbatim">showeverything</code></td><td>Everything shows, including drawers and blocks; <code class="verbatim">VISIBILITY</code> properties are ignored.</td></tr>
383<tr><td><code class="verbatim">hidedrawers</code>, <code class="verbatim">nohidedrawers</code></td><td>Fold or don't fold drawers at startup.</td></tr>
384<tr><td><code class="verbatim">hideblocks</code>, <code class="verbatim">nohideblocks</code></td><td>Fold or don't fold blocks at startup.</td></tr>
385<tr><td><code class="verbatim">indent</code>, <code class="verbatim">noindent</code></td><td>Virtual indentation on or off.</td></tr>
386<tr><td><code class="verbatim">hidestars</code>, <code class="verbatim">showstars</code></td><td>Hide leading stars or show them.</td></tr>
387<tr><td><code class="verbatim">align</code>, <code class="verbatim">noalign</code></td><td>Align every table when the file opens, or don't.</td></tr>
388<tr><td><code class="verbatim">inlineimages</code>, <code class="verbatim">noinlineimages</code></td><td>Show image links as images, or don't.</td></tr>
389<tr><td><code class="verbatim">shrink</code></td><td>Shrink table columns that have a width cookie.</td></tr>
390<tr><td><code class="verbatim">logdone</code>, <code class="verbatim">lognotedone</code>, <code class="verbatim">nologdone</code></td><td>Record a time, a note, or nothing when an entry becomes done.</td></tr>
391<tr><td><code class="verbatim">logrepeat</code>, <code class="verbatim">lognoterepeat</code>, <code class="verbatim">nologrepeat</code></td><td>The same, when a repeating entry is completed.</td></tr>
392<tr><td><code class="verbatim">logreschedule</code>, <code class="verbatim">lognotereschedule</code>, <code class="verbatim">nologreschedule</code></td><td>The same, when a scheduled date changes.</td></tr>
393<tr><td><code class="verbatim">logredeadline</code>, <code class="verbatim">lognoteredeadline</code>, <code class="verbatim">nologredeadline</code></td><td>The same, when a deadline changes.</td></tr>
394<tr><td><code class="verbatim">logdrawer</code>, <code class="verbatim">nologdrawer</code></td><td>Notes go in <code class="verbatim">LOGBOOK</code>, or under the heading.</td></tr>
395</tbody>
396</table>
397<p>After the startup visibility, Orgstar applies each heading's <code class="verbatim">VISIBILITY</code> property and folds subtrees tagged <code class="verbatim">ARCHIVE</code>, unless <code class="verbatim">showeverything</code> is set.</p>
398<p>Completion offers every option of <code class="verbatim">org-startup-options</code>. Options not in the table above, such as <code class="verbatim">odd</code>, <code class="verbatim">entitiespretty</code>, <code class="verbatim">latexpreview</code>, <code class="verbatim">constSI</code> and the footnote options, are accepted and ignored.</p>
399<h3 id="setup-files">Setup files</h3>
400<p><code class="verbatim">#+SETUPFILE: path</code> reads the keyword lines of another file and treats them as if they were in this file, before its own lines. This follows <code class="verbatim">org--collect-keywords-1</code> in Org:</p>
401<ul>
402<li>A relative path is relative to the folder of the file that names it. <code class="verbatim">~</code> expands to your home folder. Quotes around the path are removed.</li>
403<li>A setup file can name further setup files; each is read once, and a file never reads itself.</li>
404<li>URLs (anything starting with <code class="verbatim">scheme://</code>) aren't fetched.</li>
405<li>A setup file that can't be read, or isn't UTF-8, is skipped without a message.</li>
406</ul>
407<p>Keywords from setup files count for TODO keywords, priorities, <code class="verbatim">#+STARTUP</code>, <code class="verbatim">#+TAGS</code>, <code class="verbatim">#+FILETAGS</code>, <code class="verbatim">#+PROPERTY</code>, <code class="verbatim">#+CATEGORY</code>, <code class="verbatim">#+ARCHIVE</code>, <code class="verbatim">#+COLUMNS</code>, <code class="verbatim">#+LINK</code>, <code class="verbatim">#+CONSTANTS</code> and export. Orgstar reads setup files when a file opens, when you press <code class="verbatim">C-c C-c</code> on a keyword line, and when the file changes on disk. If you edit only the setup file, press <code class="verbatim">C-c C-c</code> on a keyword line of each open file that uses it.</p>
408<h2 id="import-from-emacs">Import from Emacs</h2>
409<p>Import from Emacs reads your Emacs or Doom Emacs configuration and offers to carry its org settings, folders, capture templates and key bindings over. Nothing changes until you choose Import.</p>
410<h3 id="running-it">Running it</h3>
411<ol>
412<li>Open Settings ▸ General and click Import from Emacs…, or run Import from Emacs… from the command palette (<code class="verbatim">⇧⌘P</code>).</li>
413<li>Orgstar looks for a configuration in these places, in order, and reads the first it finds: <code class="verbatim">$DOOMDIR</code>, <code class="verbatim">~/.config/doom</code>, <code class="verbatim">~/.doom.d</code>, <code class="verbatim">~/.config/emacs</code>, <code class="verbatim">~/.emacs.d</code>, <code class="verbatim">~/.emacs</code>. A folder counts when it holds <code class="verbatim">init.el</code>, <code class="verbatim">config.el</code> or <code class="verbatim">custom.el</code>. Doom's own installation folder (one with <code class="verbatim">lisp/doom.el</code>) is skipped.</li>
414<li>To read another configuration, click Choose… and pick a file or a folder. For a folder, Orgstar reads <code class="verbatim">init.el</code>, <code class="verbatim">config.el</code> and <code class="verbatim">custom.el</code> in it.</li>
415<li>The sheet lists what it found under Settings, Folders, Capture templates and Key bindings, each with the line it came from (<code class="verbatim">config.el:27</code>, or <code class="verbatim">Doom default</code>). Everything is selected; clear what you don't want.</li>
416<li>Click Import. The sheet then summarizes what was imported and any problems.</li>
417</ol>
418<p>What Import does with each kind of item:</p>
419<ul>
420<li>Settings are written to <code class="verbatim">config.toml</code>.</li>
421<li>Folders are added to the sidebar if they exist and aren't there already.</li>
422<li>Capture templates are appended to <code class="verbatim">capture.toml</code>, except those whose key is already in the file.</li>
423<li>Key bindings are appended to <code class="verbatim">keymap.toml</code>, except those already in the file with the same keys, command and state. Running the import again adds no duplicates.</li>
424</ul>
425<p>The Not imported section lists what Orgstar read but can't use, with the reason: settings it has no equivalent for, values it can't work out without running Emacs, bindings to code rather than a command, and files it couldn't read. The footer counts variables that aren't about org, which are left alone.</p>
426<p>A literate configuration (<code class="verbatim">config.org</code>) isn't read. Point Choose… at the <code class="verbatim">config.el</code> it tangles to.</p>
427<h3 id="doom-emacs">Doom Emacs</h3>
428<p>A configuration counts as Doom when it contains <code class="verbatim">(doom!</code>, <code class="verbatim">(map! = or =(after! =. Orgstar then also reads Doom's own org defaults, from the Doom installation in =$EMACSDIR</code>, <code class="verbatim">~/.config/emacs</code> or <code class="verbatim">~/.emacs.d</code>: <code class="verbatim">modules/lang/org/config.el</code> and <code class="verbatim">lisp/doom-emacs.el</code>. Your configuration overrides them. Doom defaults Orgstar has no use for are counted in the footer rather than listed.</p>
429<p>A Doom configuration, or any configuration that enables <code class="verbatim">evil</code>, adds <code class="verbatim">keymap = "doom"</code>.</p>
430<h3 id="what-it-reads">What it reads</h3>
431<p>Orgstar reads the configuration as Lisp data; it never runs it. It looks at these forms:</p>
432<table>
433<thead>
434<tr><th>Form</th><th>What Orgstar takes</th></tr>
435</thead>
436<tbody>
437<tr><td><code class="verbatim">setq</code>, <code class="verbatim">setq-default</code>, <code class="verbatim">setq!</code>, <code class="verbatim">setopt</code>, <code class="verbatim">csetq</code></td><td>Each variable and value</td></tr>
438<tr><td><code class="verbatim">defvar</code>, <code class="verbatim">defcustom</code></td><td>The value, below every other assignment</td></tr>
439<tr><td><code class="verbatim">custom-set-variables</code></td><td>Each quoted <code class="verbatim">(variable value)</code></td></tr>
440<tr><td><code class="verbatim">after!</code>, <code class="verbatim">with-eval-after-load</code>, <code class="verbatim">eval-after-load</code></td><td>The forms inside, ranked above plain assignments</td></tr>
441<tr><td><code class="verbatim">use-package</code>, <code class="verbatim">use-package!</code></td><td>Forms in <code class="verbatim">:config</code> and <code class="verbatim">:init</code>, and pairs in <code class="verbatim">:custom</code></td></tr>
442<tr><td><code class="verbatim">progn</code>, <code class="verbatim">when</code>, <code class="verbatim">unless</code>, <code class="verbatim">if</code>, <code class="verbatim">let</code>, <code class="verbatim">let*</code>, <code class="verbatim">with-no-warnings</code></td><td>The forms inside. Conditions aren't evaluated, so every branch is read.</td></tr>
443<tr><td><code class="verbatim">map!</code> (Doom)</td><td>Bindings, with <code class="verbatim">:leader</code> (<code class="verbatim">SPC</code>), <code class="verbatim">:localleader</code> (<code class="verbatim">SPC m</code>), <code class="verbatim">:prefix</code>, and state keywords such as <code class="verbatim">:n</code>, <code class="verbatim">:i</code>, <code class="verbatim">:v</code>, <code class="verbatim">:nv</code></td></tr>
444<tr><td><code class="verbatim">define-key</code>, <code class="verbatim">keymap-set</code>, <code class="verbatim">global-set-key</code>, <code class="verbatim">keymap-global-set</code></td><td>Bindings</td></tr>
445<tr><td><code class="verbatim">evil-define-key</code>, <code class="verbatim">evil-define-key*</code></td><td>Bindings in the <code class="verbatim">normal</code>, <code class="verbatim">insert</code> or <code class="verbatim">visual</code> state</td></tr>
446</tbody>
447</table>
448<p>When a variable is set more than once, the last assignment wins, with assignments inside <code class="verbatim">after!</code> and similar forms winning over plain ones, and those over Doom's defaults.</p>
449<p>Orgstar works out a value when it is a literal, a quoted or backquoted form (with <code class="verbatim">,</code> and <code class="verbatim">,@</code>), a variable set earlier in the configuration, or a call to <code class="verbatim">list</code>, <code class="verbatim">concat</code>, <code class="verbatim">expand-file-name</code>, <code class="verbatim">file-name-concat</code> or <code class="verbatim">file-name-as-directory</code> on such values. Anything else, such as a function call or a value computed from the environment, is listed under Not imported as worked out when Emacs runs.</p>
450<p>Only variables whose names start with <code class="verbatim">org-</code>, <code class="verbatim">appt-</code>, <code class="verbatim">display-line-numbers</code>, <code class="verbatim">fill-column</code>, <code class="verbatim">evil-</code>, <code class="verbatim">doom-font</code>, <code class="verbatim">doom-variable-pitch-font</code>, <code class="verbatim">doom-theme</code> or <code class="verbatim">calendar-week-start-day</code> are considered.</p>
451<h3 id="how-variables-map">How variables map</h3>
452<table>
453<thead>
454<tr><th>Emacs variable</th><th>Becomes</th></tr>
455</thead>
456<tbody>
457<tr><td><code class="verbatim">fill-column</code>, <code class="verbatim">org-tags-column</code>, <code class="verbatim">appt-message-warning-time</code></td><td>The same key, when the value is a number</td></tr>
458<tr><td><code class="verbatim">org-insert-heading-respect-content</code>, <code class="verbatim">org-list-allow-alphabetical</code>, <code class="verbatim">org-hide-emphasis-markers</code>, <code class="verbatim">org-pretty-entities</code>, <code class="verbatim">org-cycle-hide-drawer-startup</code>, <code class="verbatim">org-cycle-hide-block-startup</code>, <code class="verbatim">org-use-speed-commands</code>, <code class="verbatim">org-startup-with-inline-images</code>, <code class="verbatim">org-startup-indented</code>, <code class="verbatim">org-hide-leading-stars</code>, <code class="verbatim">org-startup-align-all-tables</code>, <code class="verbatim">org-startup-truncated</code></td><td>The same key: <code class="verbatim">nil</code> or an empty list is <code class="verbatim">false</code>, anything else <code class="verbatim">true</code></td></tr>
459<tr><td><code class="verbatim">org-hide-drawer-startup</code>, <code class="verbatim">org-hide-block-startup</code></td><td><code class="verbatim">org-cycle-hide-drawer-startup</code>, <code class="verbatim">org-cycle-hide-block-startup</code></td></tr>
460<tr><td><code class="verbatim">org-M-RET-may-split-line</code></td><td><code class="verbatim">org-M-RET-may-split-line</code>, from the <code class="verbatim">default</code> entry of an alist; other per-context entries aren't supported</td></tr>
461<tr><td><code class="verbatim">org-agenda-prefix-format</code></td><td><code class="verbatim">[org-agenda-prefix-format]</code>: a string sets all three views; an alist sets <code class="verbatim">agenda</code>, <code class="verbatim">todo</code> and <code class="verbatim">tags</code></td></tr>
462<tr><td><code class="verbatim">org-log-done</code>, <code class="verbatim">org-log-reschedule</code>, <code class="verbatim">org-log-redeadline</code></td><td>The same key: <code class="verbatim">nil</code>, <code class="verbatim">time</code> (also <code class="verbatim">t</code>) or <code class="verbatim">note</code></td></tr>
463<tr><td><code class="verbatim">org-log-into-drawer</code></td><td>A string as given; <code class="verbatim">t</code> becomes <code class="verbatim">"LOGBOOK"</code>; <code class="verbatim">nil</code> becomes <code class="verbatim">""</code></td></tr>
464<tr><td><code class="verbatim">display-line-numbers-type</code></td><td><code class="verbatim">true</code> unless <code class="verbatim">nil</code>; <code class="verbatim">relative</code> and <code class="verbatim">visual</code> become absolute numbers</td></tr>
465<tr><td><code class="verbatim">org-agenda-span</code></td><td>A number, or <code class="verbatim">day</code> (1), <code class="verbatim">week</code> (7), <code class="verbatim">fortnight</code> (14), <code class="verbatim">month</code> (30), <code class="verbatim">year</code> (365)</td></tr>
466<tr><td><code class="verbatim">org-clock-idle-time</code></td><td>Minutes; <code class="verbatim">nil</code> becomes <code class="verbatim">0</code> (never)</td></tr>
467<tr><td><code class="verbatim">org-clock-history-length</code></td><td>The same key, when the value is a positive number</td></tr>
468<tr><td><code class="verbatim">org-agenda-start-day</code></td><td>A day offset such as <code class="verbatim">"-3d"</code>; <code class="verbatim">nil</code> becomes <code class="verbatim">"+0d"</code>. Other forms aren't supported.</td></tr>
469<tr><td><code class="verbatim">org-todo-keywords</code></td><td><code class="verbatim">org-todo-keywords</code>, one line per sequence. Keywords with spaces are left out; <code class="verbatim">type</code> sequences are read as sequences.</td></tr>
470<tr><td><code class="verbatim">org-directory</code></td><td>A folder to add</td></tr>
471<tr><td><code class="verbatim">org-agenda-files</code></td><td>A folder for each entry; for a <code class="verbatim">.org</code> file, its folder</td></tr>
472<tr><td><code class="verbatim">org-capture-templates</code></td><td>Templates for <code class="verbatim">capture.toml</code>; see below</td></tr>
473<tr><td><code class="verbatim">doom-font</code></td><td><code class="verbatim">font</code> and <code class="verbatim">font-size</code>, from <code class="verbatim">(font-spec :family … :size …)</code> or <code class="verbatim">"Family-14"</code></td></tr>
474<tr><td><code class="verbatim">doom-variable-pitch-font</code></td><td>Not imported: Orgstar uses one font</td></tr>
475<tr><td><code class="verbatim">doom-theme</code></td><td>Not imported: set colors under <code class="verbatim">[theme]</code></td></tr>
476<tr><td><code class="verbatim">evil-mode</code> in use, or Doom</td><td><code class="verbatim">keymap = "doom"</code></td></tr>
477</tbody>
478</table>
479<p>Any other <code class="verbatim">org-</code> or <code class="verbatim">appt-</code> variable is listed as having no equivalent.</p>
480<p>Capture templates are imported when their type is <code class="verbatim">entry</code>, <code class="verbatim">item</code>, <code class="verbatim">checkitem</code>, <code class="verbatim">plain</code> or <code class="verbatim">table-line</code>, their template is a string, and their target is <code class="verbatim">file</code>, <code class="verbatim">file+headline</code>, <code class="verbatim">file+olp</code>, <code class="verbatim">file+olp+datetree</code>, <code class="verbatim">file+datetree</code>, <code class="verbatim">file+weektree</code>, <code class="verbatim">id</code> or <code class="verbatim">clock</code>. The properties <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>, <code class="verbatim">:empty-lines</code>, <code class="verbatim">:empty-lines-before</code>, <code class="verbatim">:empty-lines-after</code>, <code class="verbatim">:tree-type</code> (<code class="verbatim">day</code>, <code class="verbatim">week</code>, <code class="verbatim">month</code>) and <code class="verbatim">:table-line-pos</code> carry over; others are listed as left out. Template groups (a key and a name only) are skipped.</p>
481<p>Key bindings are imported when the command is one Orgstar has a counterpart for, such as <code class="verbatim">org-todo</code>, <code class="verbatim">org-schedule</code>, <code class="verbatim">org-refile</code>, <code class="verbatim">org-capture</code> or <code class="verbatim">save-buffer</code>. The clock commands <code class="verbatim">org-clock-in</code>, <code class="verbatim">org-clock-out</code>, <code class="verbatim">org-clock-cancel</code>, <code class="verbatim">org-clock-goto</code>, <code class="verbatim">org-clock-in-last</code>, <code class="verbatim">org-resolve-clocks</code> and <code class="verbatim">org-clock-mark-default-task</code> map to Clock In, Clock Out, Cancel Clock, Go to Clocked Entry, Clock In to Last Entry, Resolve Open Clocks… and Mark as Default Clock Task. Keys must be a string or <code class="verbatim">(kbd "…")</code>; bindings with key vectors such as <code class="verbatim">[f5]</code> are skipped. In a Doom configuration, bindings without a state go to the <code class="verbatim">normal</code> state.</p>
482<h3 id="limits-of-the-lisp-reader">Limits of the Lisp reader</h3>
483<ul>
484<li>Comments (<code class="verbatim">;</code>) are skipped. Strings understand <code class="verbatim">\n</code>, <code class="verbatim">\t</code>, <code class="verbatim">\"</code> and line continuations; other escapes give the character itself.</li>
485<li><code class="verbatim">#'</code> reads as <code class="verbatim">function</code>. Other <code class="verbatim">#</code> syntax is read as a symbol, so forms using it aren't understood.</li>
486<li>A syntax error anywhere in a file, such as an unclosed parenthesis, stops that file from being read at all. The error and its line show under Not imported.</li>
487<li>Macros other than those in the table above are not expanded, and functions are not called. Settings made by code you wrote (a <code class="verbatim">defun</code> that calls <code class="verbatim">setq</code>, a hook) aren't found.</li>
488</ul>
489<h2 id="themes">Themes</h2>
490<p>Orgstar has one built-in theme, the default theme, with light and dark colors after GitHub's light and dark themes. You change it by setting colors in <code class="verbatim">config.toml</code>, or by keeping a theme in its own file.</p>
491<p>Colors are strings in the form <code class="verbatim">"#rrggbb"</code> or <code class="verbatim">"#rrggbbaa"</code>. They go in these tables:</p>
492<table>
493<thead>
494<tr><th>Table</th><th>Effect</th></tr>
495</thead>
496<tbody>
497<tr><td><code class="verbatim">[theme]</code></td><td>Sets a color for both light and dark appearance</td></tr>
498<tr><td><code class="verbatim">[theme.light]</code></td><td>Sets a color for light appearance only</td></tr>
499<tr><td><code class="verbatim">[theme.dark]</code></td><td>Sets a color for dark appearance only</td></tr>
500<tr><td><code class="verbatim">[theme.todo]</code></td><td>Colors TODO keywords by name, in both appearances, as <code class="verbatim">org-todo-keyword-faces</code></td></tr>
501</tbody>
502</table>
503<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">theme</span><span class="punctuation definition table toml">]</span>
504<span class="variable other key toml">heading-1</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>#005cc5<span class="punctuation definition string end toml">&quot;</span></span>
505
506<span class="punctuation definition table toml">[</span><span class="entity name section toml">theme.dark</span><span class="punctuation definition table toml">]</span>
507<span class="variable other key toml">background</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>#1e1e1e<span class="punctuation definition string end toml">&quot;</span></span>
508<span class="variable other key toml">foreground</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>#d4d4d4<span class="punctuation definition string end toml">&quot;</span></span>
509
510<span class="punctuation definition table toml">[</span><span class="entity name section toml">theme.todo</span><span class="punctuation definition table toml">]</span>
511<span class="variable other key toml">WAIT</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>#bf8700<span class="punctuation definition string end toml">&quot;</span></span>
512<span class="variable other key toml">PROJ</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>#8250df<span class="punctuation definition string end toml">&quot;</span></span></span></code></pre>
513<p>A keyword without its own color uses <code class="verbatim">todo</code> or <code class="verbatim">done</code>.</p>
514<p><code class="verbatim">default-theme.toml</code> in the configuration folder lists every color key with the default theme's values, light and dark. Settings ▸ Appearance ▸ Show Default Theme opens it. Copy lines from it into <code class="verbatim">config.toml</code>; edits to <code class="verbatim">default-theme.toml</code> itself are overwritten at the next launch.</p>
515<h3 id="theme-files">Theme files</h3>
516<p>To keep a theme in its own file, put it in the configuration folder with the same tables (<code class="verbatim">[theme]</code>, <code class="verbatim">[theme.light]</code>, <code class="verbatim">[theme.dark]</code>, <code class="verbatim">[theme.todo]</code>) and name it in <code class="verbatim">config.toml</code>:</p>
517<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">theme</span><span class="punctuation definition table toml">]</span>
518<span class="variable other key toml">theme-file</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>solarized.toml<span class="punctuation definition string end toml">&quot;</span></span></span></code></pre>
519<p>The colors stack in this order, each over the one before: the default theme, the theme file, then the colors in <code class="verbatim">config.toml</code>. The path is relative to the configuration folder and may name a subfolder, as <code class="verbatim">themes/solarized.toml</code>. Orgstar reloads the theme file when it changes. Only colors are read from a theme file; <code class="verbatim">font</code> and the other type keys in its <code class="verbatim">[theme]</code> table are ignored.</p>
520<h3 id="color-keys">Color keys</h3>
521<table>
522<thead>
523<tr><th>Key</th><th>Colors</th></tr>
524</thead>
525<tbody>
526<tr><td><code class="verbatim">background</code></td><td>the editor's background</td></tr>
527<tr><td><code class="verbatim">foreground</code></td><td>body text</td></tr>
528<tr><td><code class="verbatim">cursor</code></td><td>the caret</td></tr>
529<tr><td><code class="verbatim">selection</code></td><td>selected text's background</td></tr>
530<tr><td><code class="verbatim">heading-1</code> … <code class="verbatim">heading-7</code></td><td>headings of that level</td></tr>
531<tr><td><code class="verbatim">heading-8</code></td><td>level 8 and deeper headings</td></tr>
532<tr><td><code class="verbatim">todo</code></td><td>TODO keywords not yet done</td></tr>
533<tr><td><code class="verbatim">done</code></td><td>DONE keywords</td></tr>
534<tr><td><code class="verbatim">priority</code></td><td><code class="verbatim">[#A]</code> cookies</td></tr>
535<tr><td><code class="verbatim">tags</code></td><td><code class="verbatim">:tags:</code></td></tr>
536<tr><td><code class="verbatim">link</code></td><td>links</td></tr>
537<tr><td><code class="verbatim">timestamp</code></td><td>timestamps</td></tr>
538<tr><td><code class="verbatim">code</code></td><td><code class="verbatim">~code~</code> and inline source</td></tr>
539<tr><td><code class="verbatim">verbatim</code></td><td><code>=verbatim=</code></td></tr>
540<tr><td><code class="verbatim">inline-background</code></td><td>behind <code class="verbatim">~code~</code> and <code>=verbatim=</code></td></tr>
541<tr><td><code class="verbatim">markup</code></td><td>link brackets and emphasis markers</td></tr>
542<tr><td><code class="verbatim">comment</code></td><td>comments</td></tr>
543<tr><td><code class="verbatim">keyword</code></td><td><code class="verbatim">#+KEYWORD</code> lines</td></tr>
544<tr><td><code class="verbatim">metadata</code></td><td>planning lines, drawers, properties and clocks</td></tr>
545<tr><td><code class="verbatim">special</code></td><td>footnotes, statistics cookies, targets, macros and LaTeX</td></tr>
546<tr><td><code class="verbatim">block-background</code></td><td>the band behind blocks</td></tr>
547<tr><td><code class="verbatim">block-delimiter</code></td><td><code class="verbatim">#+begin_</code> and <code class="verbatim">#+end_</code> lines</td></tr>
548<tr><td><code class="verbatim">table</code></td><td>tables</td></tr>
549<tr><td><code class="verbatim">line-number</code></td><td>line numbers</td></tr>
550<tr><td><code class="verbatim">line-number-current</code></td><td>the caret's line number</td></tr>
551<tr><td><code class="verbatim">syntax-keyword</code></td><td>code: keywords</td></tr>
552<tr><td><code class="verbatim">syntax-string</code></td><td>code: strings</td></tr>
553<tr><td><code class="verbatim">syntax-comment</code></td><td>code: comments</td></tr>
554<tr><td><code class="verbatim">syntax-function</code></td><td>code: functions</td></tr>
555<tr><td><code class="verbatim">syntax-type</code></td><td>code: types and modules</td></tr>
556<tr><td><code class="verbatim">syntax-number</code></td><td>code: numbers, constants and escapes</td></tr>
557<tr><td><code class="verbatim">syntax-property</code></td><td>code: properties, attributes and tags</td></tr>
558<tr><td><code class="verbatim">syntax-label</code></td><td>code: labels</td></tr>
559<tr><td><code class="verbatim">sidebar-background</code></td><td>the folder sidebar and the outline</td></tr>
560<tr><td><code class="verbatim">sidebar-foreground</code></td><td>file and heading names there</td></tr>
561<tr><td><code class="verbatim">sidebar-header</code></td><td>folder names there</td></tr>
562<tr><td><code class="verbatim">modeline-background</code></td><td>the modeline and message line</td></tr>
563<tr><td><code class="verbatim">modeline-foreground</code></td><td>modeline text</td></tr>
564<tr><td><code class="verbatim">modeline-highlight</code></td><td>the outline path and the clock in the modeline</td></tr>
565<tr><td><code class="verbatim">state-normal</code></td><td>the NORMAL tag (Doom keys)</td></tr>
566<tr><td><code class="verbatim">state-insert</code></td><td>the INSERT tag</td></tr>
567<tr><td><code class="verbatim">state-visual</code></td><td>the VISUAL and V-LINE tags</td></tr>
568<tr><td><code class="verbatim">agenda-background</code></td><td>the agenda and board</td></tr>
569<tr><td><code class="verbatim">agenda-date</code></td><td>agenda day headers</td></tr>
570<tr><td><code class="verbatim">agenda-today</code></td><td>today's header and the current time</td></tr>
571<tr><td><code class="verbatim">agenda-time</code></td><td>times and the time grid</td></tr>
572<tr><td><code class="verbatim">agenda-category</code></td><td>categories</td></tr>
573<tr><td><code class="verbatim">agenda-deadline</code></td><td>deadlines due</td></tr>
574<tr><td><code class="verbatim">agenda-upcoming</code></td><td>deadlines coming up</td></tr>
575<tr><td><code class="verbatim">agenda-scheduled</code></td><td>scheduled items</td></tr>
576<tr><td><code class="verbatim">agenda-scheduled-past</code></td><td>items scheduled on an earlier day</td></tr>
577<tr><td><code class="verbatim">habit-clear</code></td><td>habit graph: not due yet</td></tr>
578<tr><td><code class="verbatim">habit-ready</code></td><td>habit graph: due</td></tr>
579<tr><td><code class="verbatim">habit-alert</code></td><td>habit graph: due today, last chance</td></tr>
580<tr><td><code class="verbatim">habit-overdue</code></td><td>habit graph: overdue</td></tr>
581</tbody>
582</table>
583<p>The default theme leaves <code class="verbatim">sidebar-background</code>, <code class="verbatim">sidebar-foreground</code>, <code class="verbatim">sidebar-header</code>, <code class="verbatim">modeline-background</code>, <code class="verbatim">modeline-foreground</code> and <code class="verbatim">agenda-background</code> unset, so those parts keep the standard macOS look. Set them to color those parts too. In the views around the editor (sidebar, modeline, agenda), a color you set for one appearance only leaves the other appearance to the system. In the editor, a color set for one appearance only takes the default theme's color in the other.</p>
584<p>An unknown color key, a value that isn't a color, or an unknown table such as <code class="verbatim">[theme.solarized]</code> is reported as a problem and skipped.</p>
585<h2 id="appearance">Appearance</h2>
586<p>Orgstar follows the system's light or dark appearance (System Settings ▸ Appearance). There is no setting to fix one appearance; to use the same colors in both, set them under <code class="verbatim">[theme]</code> rather than <code class="verbatim">[theme.light]</code> or <code class="verbatim">[theme.dark]</code>.</p>
587<h2 id="fonts">Fonts</h2>
588<p>The editor uses one font for everything: body text, headings, code and tables. Choose it in Settings ▸ Appearance or with <code class="verbatim">font</code> under <code class="verbatim">[theme]</code>.</p>
589<ul>
590<li>The Font menu lists installed monospaced families. <code class="verbatim">config.toml</code> accepts any family name; a family that isn't installed falls back to the system's monospaced font. Tags and tables line up in columns, so a proportional font misaligns them.</li>
591<li><code class="verbatim">font-size</code> is the body size, at least 6 points.</li>
592<li>Headings are bold. Level 1 is <code class="verbatim">font-size</code> plus three times <code class="verbatim">heading-size-step</code>, level 2 plus two times, level 3 plus one time; level 4 and deeper are body size. Set <code class="verbatim">heading-size-step = 0</code> for one size throughout.</li>
593<li><code class="verbatim">line-spacing</code> adds space between lines, in points.</li>
594</ul>
595<p>On iPhone and iPad, the editor and reader use the same theme, read from the synced configuration folder. <code class="verbatim">font</code> applies when the family is installed on the device, otherwise the system's monospaced font is used, and <code class="verbatim">font-size</code> is the size at the default Dynamic Type setting, scaled with the size chosen on the device. The <code class="verbatim">selection</code> color and the <code class="verbatim">syntax-*</code> colors aren't used there. See <a href="14-ios.html">iPhone and iPad</a>.</p>
596</main>
597<footer class="site">
598Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>.
599</footer>
600</body>
601</html>