Configuration

Every setting lives in a text file you can edit, and most of them also appear in the Settings window.

Where settings live

orgstar keeps its settings in a configuration folder:

• $XDG_CONFIG_HOME/orgstar when XDG_CONFIG_HOME is set and not empty,
• otherwise ~/.config/orgstar.

The 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.

The folder holds these files:

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.

When 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.

Opening config.toml

• 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.
• Settings ▸ General has three buttons for the file: Edit in orgstar, Open with Default App, and Show in Finder.

Saving the buffer applies the file, the same as saving it from another editor.

Problems in the files

If 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:

• config.toml: unknown setting editor.foo
• config.toml: org-log-done must be one of nil, time, note
• config.toml: org-agenda-start-day must look like "-3d" or "+0d"
• config.toml: theme.light.background must be a color such as "#1f2328"

A 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.

The Settings window

Open 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.

General

Automatic saving writes a file one second after you stop typing. The keymap presets and keymap.toml are covered in Keys and commands.

Editing

The 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.

The Tags picker offers two values. config.toml accepts any integer; with a value other than -77 or 0 the picker shows no selection.

The long-lines switch applies to files as they open; View ▸ Truncate or Wrap Long Lines switches the file in front.

Default 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.

The two dependency switches are described under Dependencies in TODOs and tags.

Language

orgstar's menus, settings and agenda are in English and German, and follow the language chosen in System Settings ▸ General ▸ Language & Region on the Mac and Settings ▸ General ▸ Language & Region on iOS (or the app's own language there). What orgstar writes into your files, such as clock tables, is in the language Org would use: a clock table's :lang, else org-export-default-language. Exports use the file's #+LANGUAGE:; see Export.

Appearance

See Themes and Fonts below.

Agenda

An entry's APPT_WARNTIME property overrides the lead time. The agenda is covered in The agenda.

The calendar checkboxes appear once Show events from Calendar is on and orgstar may read your calendars; turning the switch on asks for that access. While every calendar is checked, calendar-event-calendars is empty, so calendars you add later show too. The last checked calendar can't be unchecked; turn off Show events from Calendar instead. The Reminders list checkboxes work the same way. See The agenda.

Turning 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 Dates and clocking.

Capture

The footer shows the path of capture.toml. Templates are covered in Capture.

Settings only in config.toml

These settings have no control in the Settings window. Some are in the View menu.

config.toml reference

Settings 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], the sorting strategies in [org-agenda-sorting-strategy], the time grid in [org-agenda-time-grid], stuck projects in [org-stuck-projects], type and theme in [theme], and the settings Emacs has no variable for in [orgstar].

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.

Top level

The default org-todo-keywords is the first sequence of Doom Emacs's default:

org-todo-keywords = "TODO(t) PROJ(p) LOOP(r) STRT(s) WAIT(w) HOLD(h) IDEA(i) | DONE(d) KILL(k)"

The 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.

[org-agenda-prefix-format]

These mirror the entries of org-agenda-prefix-format. Rows show the category, time and leader in their own places; the rest of the format, such as %e or %b, shows after the category. A time written in heading text leaves the title when the agenda format contains %t. A view in views.toml can set its own with prefix-format. See The agenda.

[org-agenda-sorting-strategy]

These mirror the entries of org-agenda-sorting-strategy, keys separated by spaces. Unknown keys are ignored. A view in views.toml can set its own with sorting-strategy. The keys are listed in The agenda.

[org-stuck-projects]

These mirror the four elements of org-stuck-projects. See The agenda.

[org-agenda-time-grid]

These mirror the first two elements of org-agenda-time-grid. when takes daily (views of one day), today, weekly (every day), require-timed (only days with a timed entry) and remove-match (no line at a time an entry has). orgstar draws the lines itself, so Emacs's third and fourth elements, the strings for the lines, have no equivalent.

[org-structure-template-alist]

Block templates for Insert Structure Template (C-c C-,) and < completion, each a key and the block type it inserts. They go over Org's default org-structure-template-alist: a key Org has (s, q, …) gets the new type, and other keys are added after Org's.

[org-structure-template-alist]
el = "src emacs-lisp"
py = "src python"

Keys are letters, digits, _ and -. Without the table, Org's templates apply. Emacs import adds entries here and so does nothing else in the app; remove one by deleting its line.

publish

Publishing projects, one table each, as org-publish-project-alist has them. They're read when you publish; see Publishing for the keys. The Settings window leaves them as they are.

[theme]

Any other key in [theme] is a color; see Themes below.

[orgstar]

The default ignored-folders is:

ignored-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"

An example

fill-column = 72
org-tags-column = 0
org-todo-keywords = "TODO(t) NEXT(n) WAIT(w@/!) | DONE(d!) CANCELED(c@)"
org-log-done = "time"
org-log-into-drawer = "LOGBOOK"
org-startup-truncated = true
org-agenda-span = 7
org-agenda-start-day = "+0d"

[theme]
font = "JetBrains Mono"
font-size = 14
link = "#0a7ea4"

[theme.todo]
WAIT = "#bf8700"

[orgstar]
keymap = "doom"
save = "explicit"

Names from earlier versions

Earlier 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.

keymap.toml and capture.toml

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 Keys and commands.

[[bind]]
keys = "C-c a"
command = "app.agenda"

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 Capture.

views.toml holds [[view]] tables for the agenda; see The agenda.

In-file settings

Keyword 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.

Keywords orgstar reads

#+TODO: TODO(t) NEXT(n) WAIT(w@/!) | DONE(d!) CANCELED(c@)
#+PRIORITIES: A E C
#+STARTUP: content logdrawer
#+FILETAGS: :work:
#+CATEGORY: acme

After 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.

#+STARTUP options

After the startup visibility, orgstar applies each heading's VISIBILITY property and folds subtrees tagged ARCHIVE, unless showeverything is set.

Completion offers every option of org-startup-options. Options not in the table above, such as odd, entitiespretty, constSI and the footnote options, are accepted and ignored.

Setup files

#+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:

• 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.
• A setup file can name further setup files; each is read once, and a file never reads itself.
• URLs (anything starting with scheme://) aren't fetched.
• A setup file that can't be read, or isn't UTF-8, is skipped without a message.

Keywords 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.

Import from Emacs

Import from Emacs reads your Emacs or Doom Emacs configuration and offers to carry its org settings, folders, capture templates, key bindings and agenda views over. Nothing changes until you choose Import.

Running it

1. Open Settings ▸ General and click Import from Emacs…, or run Import from Emacs… from the command palette (⇧⌘P).
2. 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, config.org or custom.el. Doom's own installation folder (one with lisp/doom.el) is skipped.
3. To read another configuration, click Choose… and pick a file or a folder. For a folder, orgstar reads init.el, config.el (or config.org when there is no config.el) and custom.el in it.
4. The sheet lists what it found under Settings, Folders, Capture templates, Key bindings, Structure templates and Agenda views, each with the line it came from (config.el:27, or Doom default). Everything is selected; clear what you don't want.
5. Click Import. The sheet then summarizes what was imported and any problems.

What Import does with each kind of item:

• Settings are written to config.toml.
• Folders are added to the sidebar if they exist and aren't there already.
• Capture templates are appended to capture.toml, except those whose key is already in the file.
• 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.
• Agenda views are appended to views.toml, except those whose name is already in the file.

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.

A literate configuration (config.org) is read as org-babel-load-file and Doom tangle it: its emacs-lisp and elisp blocks, except blocks whose :tangle is no (set on the block, in a #+HEADER: line, in a header-args property or in #+PROPERTY:) and blocks under a COMMENT or :ARCHIVE: heading. Items show the line of config.org they came from. When the folder also has a config.el, it is read instead, as the file config.org tangles to.

On iOS, Settings ▸ Import from Emacs reads a configuration folder you choose; see iOS.

Doom Emacs

A 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.

A Doom configuration, or any configuration that enables evil, adds keymap = "doom".

What it reads

orgstar reads the configuration as Lisp data; it never runs it. It looks at these forms:

When 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.

orgstar 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.

Only 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.

How variables map

Any other org- or appt- variable is listed as having no equivalent.

Capture 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.

Key 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.

Limits of the Lisp reader

• Comments (;) are skipped. Strings understand \n, \t, \" and line continuations; other escapes give the character itself.
• #' reads as function. Other # syntax is read as a symbol, so forms using it aren't understood.
• 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.
• 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.

Themes

orgstar has one built-in theme, the default theme, with light and dark colors after GitHub's light and dark themes for text and code. TODO keywords, priorities and the agenda's statuses use the system's red, orange, blue and green, as iOS and macOS show them. You change it by setting colors in config.toml, or by keeping a theme in its own file.

Colors are strings in the form "#rrggbb" or "#rrggbbaa". They go in these tables:

[theme]
heading-1 = "#005cc5"

[theme.dark]
background = "#1e1e1e"
foreground = "#d4d4d4"

[theme.todo]
WAIT = "#bf8700"
PROJ = "#8250df"

[theme.category]
work = "#0a66d8"

A keyword without its own color takes its class's color. Case doesn't matter in these lists:

The classes color keywords in the editors, the iOS reader, the agenda and its widgets.

A category without its own color gets a hue worked out from its name, the same on every run and device, at a lightness that reads on the appearance's background.

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.

Theme files

To keep a theme in its own file, put it in the configuration folder with the same tables ([theme], [theme.light], [theme.dark], [theme.todo], [theme.category]) and name it in config.toml:

[theme]
theme-file = "solarized.toml"

The 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.

Color keys

The 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.

An 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.

Appearance

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 [theme] rather than [theme.light] or [theme.dark].

Fonts

The editor uses one font for everything: body text, headings, code and tables. Choose it in Settings ▸ Appearance or with font under [theme].

• 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.
• font-size is the body size, at least 6 points.
• 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.
• line-spacing adds space between lines, in points.

On 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 iPhone and iPad.