Configuration#

Config Files#

toe reads configuration in this order:

$XDG_CONFIG_HOME defaults to ~/.config.

Later TOML values override earlier ones.

Open your user config directly: :config-open Open workspace config: :config-open-workspace Reload after editing: :config-reload

Interface Language#

toe selects English, German, French, or Italian from LC_ALL, LC_MESSAGES, then LANG. Unsupported locales use English.

Workspace Trust#

toe treats a directory with .git or .toe as a workspace. Workspace trust is the explicit opt-in that lets workspace-controlled config and tooling affect toe.

Until a workspace is trusted:

• normal file editing, :write, :write-all, and :move still work
• automatic workspace session restore/save is skipped
• workspace-local config files (.toe/config.toml and .toe/languages.toml) are not loaded
• workspace-configured language servers and formatter commands are not started from workspace config
• :config-open-workspace refuses to create or open workspace config until you trust the workspace

User config still applies in untrusted workspaces.

Trust the current workspace:

:workspace-trust

Remove trust:

:workspace-untrust

Trusted workspaces are stored in $XDG_DATA_HOME/toe/trusted_workspaces (normally ~/.local/share/toe/trusted_workspaces). If a workspace is untrusted at startup, toe shows a status message asking you to run :workspace-trust.

To bypass trust checks entirely, set in your user config:

[editor]
insecure = true

Editor Configuration#

Except for the top-level theme key, the settings below belong under [editor] in config.toml. They can also be changed for the current session with :set <key> <value>, :get <key>, and :toggle <key> for booleans, or :toggle <key> <value>... to cycle a key through the given values. Lists and tables use TOML syntax. Completion after :set shows the available keys.

Examples:

:set gutters.layout ["diagnostics", "line-numbers", "diff"]
:set statusline.left ["mode!", "file-name"]
:set whitespace.render.tab all
:set whitespace.characters.tab "→"
:set auto-pairs {"(" = ")", "[" = "]"}
:set buffer-picker.start-position previous
:toggle file-explorer.hidden
:toggle default-line-ending lf crlf

Theme#

theme = "mocha"   # frappe | latte | macchiato | mocha

General#

Display#

Scrollbar#

Each editor pane and each file preview reserves its rightmost column for a scrollbar. The thumb shows which part of the document is on screen, and markers show where the interesting lines are, so changes, problems, and matches stay visible while they are scrolled out of sight:

Each marker takes half a row. A half-row standing for a single document line draws a hairline rule, and one standing for several draws a half block, so the weight of a marker tells how much it covers. Where markers collide on one half-row, it shows the most important one, in the order above: a cursor beats a diagnostic, a diagnostic beats a diff, and a diff beats a search match.

Click the bar to scroll to that part of the document, or drag along it to scroll continuously. This works on a preview’s bar as well as an editor pane’s. Neither moves the cursor, so the view stays where it was put until the cursor moves again.

Set scrollbar to false to hide it and give the column back to the text.

Diff markers need version control, and search markers appear while search highlights are on.

Soft Wrap#

Whitespace and Indentation#

Whitespace rendering can be set separately for space, nbsp, tab, and newline, and each display character can be replaced:

[editor.whitespace]
render = { default = "none", tab = "all", newline = "all" }

[editor.whitespace.characters]
space = "·"
nbsp = "⍽"
tab = "→"
tabpad = " "
newline = "⏎"

Use whitespace.render.<type> and whitespace.characters.<type> to change individual values at runtime.

To change gutter order or visibility:

[editor.gutters]
layout = ["diagnostics", "spacer", "line-numbers", "spacer", "diff"]

[editor.gutters.line-numbers]
min-width = 3

Editing#

auto-pairs also accepts a table of custom opening and closing characters:

auto-pairs = { "(" = ")", "[" = "]", "{" = "}" }

At runtime, auto-pairs accepts a boolean or an inline table of custom pairs.

Auto-Save#

Completion#

Automatic completion is in addition to Ctrl+x, which requests completions at any time, and to the trigger characters a language server advertises.

Search#

Scrolling#

Cursor Shape#

Status Bar#

Valid statusline elements: mode, file-name, file-base-name, file-absolute-path, file-status, file-modified-indicator, read-only-indicator, file-encoding, file-line-ending, file-indent-style, file-type, diagnostics, selections, primary-selection-length, position, position-percentage, total-line-numbers, spinner, version-control, macro-recording, and pane-maximized.

file-status marks a read-only or modified document with an icon next to its name, and shows both marks when both apply. read-only-indicator and file-modified-indicator draw the same marks, one condition each, for a statusline that wants them apart. Without nerd fonts the marks fall back to ro and *.

macro-recording and pane-maximized report editor-wide state rather than the pane’s own. macro-recording draws only on the statusline in the bottom-right corner of the frame, so a split shows it once.

When the pane is too narrow, toe drops unpinned status items from the right section and then the left. Suffix an element with ! (for example "mode!" or "position!") to keep it visible.

[editor.statusline]
left = ["mode!", "file-name", "read-only-indicator", "file-modified-indicator"]
right = ["diagnostics", "selections", "position!"]

The selected register and the macro-recording indicator appear on the statusline in the bottom-right corner of the frame.

Example:

[editor.statusline]
left = ["mode", "file-name", "file-modified-indicator"]
right = ["version-control", "diagnostics", "position"]

Pickers#

Dragging a picker’s split divider adjusts its list/preview ratio, and dragging its border resizes it. Both are remembered per picker by auto-session rather than set in config.

Shell#

[editor]
shell = ["sh", "-c"]   # default on Unix; ["cmd", "/C"] on Windows

Config Example#

theme = "mocha"

[editor]
cursorline = true
soft-wrap.enable = true
auto-session = true
rulers = [80, 120]

[editor.cursor-shape]
normal = "block"
insert = "bar"

Language Config#

See Language Servers for languages.toml configuration.