docs/manual/guide/13-configuration.org

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

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.

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

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.

See Themes and Fonts below.

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.

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.

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

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

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.

These mirror the entries of org-agenda-prefix-format. The agenda's rows don't show a prefix, so the formats don't change how the agenda looks. The one effect left is that a time written in heading text leaves the title when the agenda format contains %t. See The agenda.

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

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"

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.

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

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, latexpreview, constSI and the footnote options, are accepted and ignored.

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

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 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 and custom.el in it.
4. 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.
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.

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) isn't read. Point Choose… at the config.el it tangles to.

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

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.

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.

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

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.

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.