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