Configuration

Configuration

File locations

Global files live in Electron's userData directory:

Platform	Directory
Linux	${XDG_CONFIG_HOME:-~/.config}/folea/
macOS	~/Library/Application Support/folea/
Windows	%APPDATA%\folea\

Path	Purpose
<userData>/prefs.config	Global preferences
<userData>/keys.config	Global key remaps
<userData>/state.json	Internal recent-vault state; not configuration
<vault>/.folea/prefs.config	Per-vault preference overrides
<vault>/.folea/state.json	Internal reading state
<vault>/.folea/render-cache/	Persistent rendered-note cache

There is no vault-local keys.config.

Preferences

prefs.config is a small key = value format. It is not full INI or TOML.

Copy-pasteable defaults:

search.vaultCaseSensitive = false
search.inFileCaseSensitive = false
theme = system
editor.command =

Key	Accepted values	Default
search.vaultCaseSensitive	true, false, 1, 0	false
search.inFileCaseSensitive	true, false, 1, 0	false
theme	system, light, dark	system
editor.command	Command string	Empty; use the VS Code fallback

Global and vault preferences are merged one key at a time. A value in <vault>/.folea/prefs.config wins over the same global key. An empty vault-local editor.command = also wins and restores the default VS Code command.

Parser rules:

• Blank lines and lines starting with # are ignored.
• Spaces around keys and values are trimmed.
• Lines without = are ignored.
• Keys are case-sensitive.
• Boolean and theme values are case-insensitive.
• Unknown keys produce a warning and are ignored.
• Invalid booleans or themes fall back to an inherited or default value.
• The last valid duplicate value wins.
• editor.command keeps the remaining text for later command parsing.

Only the first accumulated configuration warning appears in the status line.

Themes

The choices are system, light, and dark. system follows the operating-system color preference and updates while folea is running.

Palette commands:

theme.useSystem
theme.useLight
theme.useDark
theme.cycle

theme.cycle uses this order:

system → light → dark → system

When a vault is open, a theme command writes <vault>/.folea/prefs.config. With no vault open, it writes global prefs.config. Other lines are preserved; theme = ... is replaced or added.

There is no custom color-theme file.

External editor

Press Ctrl+e or run editor.open.

Selection order

On Linux and macOS, folea first checks for an existing vault-specific Neovim socket. If nvim --server <socket> --remote <file> succeeds, that running Neovim receives the note and no configured command is started.

Otherwise, command selection is:

1. FOLEA_EDITOR_CMD
2. resolved editor.command
3. code --reuse-window <absolute-note-path>

Windows skips the Neovim-socket preflight.

Placeholders

• %FILE% becomes the absolute note path.
• %SOCK% becomes a vault-specific Neovim socket path.
• Every exact token is replaced.
• If %FILE% is omitted, folea does not append a file argument.

Placeholders must be complete command tokens. For example, %FILE% is replaced here:

editor.command = code --reuse-window %FILE%

but not inside --file=%FILE%.

Examples

VS Code:

editor.command = code --reuse-window %FILE%

Neovim in kitty, with a reusable vault-specific socket:

editor.command = kitty -e nvim --listen %SOCK% %FILE%

Quoted argument:

editor.command = editor --label "My Notes" %FILE%

Environment override:

FOLEA_EDITOR_CMD='nvim %FILE%' folea

This last example requires an installation that provides the folea command. Source installs do not provide that command on every platform.

Parsing and platform notes

folea splits the executable and arguments without a shell (shell: false). Single quotes, double quotes, and escaped spaces are supported. Pipes, shell substitutions, globbing, and environment-variable expansion do not run.

An unterminated quote reports:

editor.command contains an unterminated quote

A blank parsed command reports:

editor.command must include an executable

On macOS, folea asks the login shell for PATH before launching. Executable spawn failures are logged as [folea] editor launch failed: ... and may not appear in the UI.

Key remapping

Create global <userData>/keys.config. Each non-comment line is:

<command-id> <chord>

Copy-pasteable example:

# My bindings
view.toggleTree t
editor.open e
zoom.fitPage F8
cache.clearApplication C

# Replace both Ctrl+d and Space with Ctrl+f.
document.scrollHalfDown <C-f>

# Add a second binding for the same command.
document.scrollHalfDown J

The command ID already contains its namespace, such as document.scrollHalfDown. You do not choose a separate context in the file.

Accepted chords

Form	Examples
Printable character	j, G, %, +, :
Concatenated sequence	gg, gd, zM
Named key	Enter, Escape, Backspace, Space, Tab, arrows, Home, End, PageUp, PageDown, Delete, Insert, F1–F12
Ctrl chord	<C-p>, <C-7>, <C-enter>
Shifted space	<S-Space>

Plain named keys are case-sensitive. Named keys inside Ctrl notation must be lowercase: <C-enter> is valid, while <C-Enter> is rejected.

There is no Alt or Meta/Cmd syntax. Chords cannot contain spaces, and a literal < cannot be a printable chord.

Blank lines and full-line # comments are allowed. Inline comments are not:

view.toggleTree t # invalid

Replacement rules

• The first line for a command removes all of that command's defaults, then adds the new chord.
• Later lines for the same command add more chords.
• A command present in several contexts is remapped in all of them. editor.open e, for example, replaces <C-e> in document, caret, and visual contexts.
• If two commands claim one chord in the same context, the later assignment wins and produces a warning.
• Unknown commands, internal commands, malformed lines, and invalid chords are ignored with warnings. Other valid lines still apply.
• Action commands with no default can be bound. Their context is inferred from the command namespace.

Namespace inference matters. cache.clearApplication C is placed in the global map, and zoom.fitPage F8 is placed in the document map. A current limitation is that unbound search.openGlobal is inferred into the search overlay map, not the global map.

Action and navigation commands are remappable. Internal commands such as vaultDialog.* and tree.searchAppend are not. The command palette lists action IDs only; use Keyboard Reference for navigation IDs.

Runtime sequence support has limits even when a sequence parses. The first key event must be a single character. gEnter can work, while Enterg and sequences needing more than one pending prefix do not.

When changes take effect

Change	Reload behavior
Edit keys.config	Restart folea
Edit preference search/theme values by hand	Restart, or close and reopen the vault
Edit editor.command	Read again on the next editor.open
Run a theme palette command	Applied and saved immediately
OS color scheme with theme = system	Applied immediately

There are no config file watchers.