Configuration.md

[[Basalt]] can be customized using a TOML configuration file. The file does not exist by default — create it manually when you want to override the defaults.

Press ? at any time to see the active keymap for the current pane:

![[help-modal.gif]]

Configuration file location

[[Basalt]] looks for a configuration file in the following locations:

• macOS and Linux: $HOME/.basalt.toml or $XDG_CONFIG_HOME/basalt/config.toml
• Windows: %USERPROFILE%\.basalt.toml or %APPDATA%\basalt\config.toml

If configuration files exist in multiple locations, only the first one found is used, with the home directory taking precedence.

Overriding defaults

Your configuration is merged with the defaults. You only need to define the key bindings you want to change — all other defaults remain active. If you bind a key that already exists in the defaults, your binding takes precedence.

For example, to change only the quit key:

[global]
key_bindings = [
  { key = "ctrl+q", command = "quit" },
]

This adds Ctrl+Q as a quit binding while keeping all other default global bindings (?, <leader>v, etc.) intact.

Leader key

Bindings can be written against a <leader> prefix instead of a fixed key. The leader defaults to <space> and is set at the top level:

leader = ","

See [[Key mappings]] for the binding syntax.

Vim mode

Setting vim_mode = true enables a built-in keybinding preset modelled after vim. For each section it defines, the vim preset replaces the default bindings entirely rather than merging with them. Your own config is still merged on top, so individual bindings can still be overridden.

vim_mode = true

Key differences from the defaults:

Pane	Key	Command
Note editor	gg	Jump to top of note
Note editor	G	Jump to bottom of note
Note editor	w	Move cursor forward by word
Note editor	b	Move cursor backward by word
Explorer	gg	Jump to first item
Explorer	G	Jump to last item
Outline	gg	Jump to first item
Outline	G	Jump to last item
Input modal	w	Move cursor forward by word
Input modal	b	Move cursor backward by word

In the note editor, vim mode introduces Normal/Insert sub-modes within EDIT. Pressing i enters Insert mode for typing; Esc returns to Normal mode for navigation; pressing Esc again exits back to READ.

Visual selection and yank

From Normal mode you can select text and yank it to the system clipboard:

Key	Command
v	Start a charwise selection
V	Start a linewise selection
y	Yank the selection to clipboard
Esc	Cancel the selection

Motions extend the selection, a short flash marks the yanked range, and the copy uses your platform clipboard utility with an OSC 52 fallback for SSH and tmux.

![[visual-selection.gif]]

The full vim preset is defined in vim.toml. Sections not defined in the preset keep their default bindings.

Symbols

The [symbols] table controls the visual glyphs used across the interface. Basalt ships with three presets: unicode (default), ascii and nerd-font. Individual symbols can be overridden on top of any preset. See [[Symbols]] for the full reference.

[symbols]
preset = "unicode"

Themes

The theme key sets the interface colour scheme. Basalt ships with themes like gruvbox-dark, everforest-dark, catppuccin-mocha and its own causeway-dark, and you can preview them live with <leader>t or drop your own into the themes directory. See [[Themes]] for the full role reference and how to create one.

theme = "causeway-dark"

Default configuration

The full default configuration is shown below. The default exec: and spawn: commands use macOS conventions (vi, open). On Linux, replace open with xdg-open; on Windows, use start. See [[Custom commands]] for details.

# Editor is experimental
experimental_editor = false
vim_mode = false

leader = "<space>"

[global]
key_bindings = [
 { key = "q", command = "quit" },
 { key = "?", command = "help_modal_toggle" },
 { key = "<leader>v", command = "vault_selector_modal_toggle" },
 { key = "<leader>d", command = "debug_log_toggle" },
 { key = "ctrl+n", command = "tab_next" },
 { key = "ctrl+p", command = "tab_previous" },
 { key = "ctrl+w", command = "tab_close" },
 { key = "L", command = "tab_next" },
 { key = "H", command = "tab_previous" },
 { key = "]b", command = "tab_next" },
 { key = "[b", command = "tab_previous" },
 { key = "<leader>e", command = "exec:vi %note_path" },
 { key = "<leader>o", command = "spawn:open obsidian://open?vault=%vault&file=%note" },
]

[splash]
key_bindings = [
 { key = "k", command = "splash_up" },
 { key = "j", command = "splash_down" },
 { key = "up", command = "splash_up" },
 { key = "down", command = "splash_down" },
 { key = "enter", command = "splash_open" },
]

[explorer]
key_bindings = [
 { key = "k", command = "explorer_up" },
 { key = "j", command = "explorer_down" },
 { key = "up", command = "explorer_up" },
 { key = "down", command = "explorer_down" },
 { key = "t", command = "explorer_toggle" },
 { key = "h", command = "explorer_hide_pane" },
 { key = "l", command = "explorer_expand_pane" },
 { key = "left", command = "explorer_hide_pane" },
 { key = "right", command = "explorer_expand_pane" },
 { key = "s", command = "explorer_sort" },
 { key = "r", command = "explorer_toggle_input_rename" },
 { key = "tab", command = "explorer_switch_pane_next" },
 { key = "shift+backtab", command = "explorer_switch_pane_previous" },
 { key = "enter", command = "explorer_open" },
 { key = "ctrl+b", command = "explorer_toggle" },
 { key = "ctrl+u", command = "explorer_scroll_up_half_page" },
 { key = "ctrl+d", command = "explorer_scroll_down_half_page" },
 { key = "ctrl+o", command = "explorer_toggle_outline" },
 { key = "ctrl+shift+up", command = "explorer_scroll_to_top" },
 { key = "ctrl+shift+down", command = "explorer_scroll_to_bottom" },
]

[outline]
key_bindings = [
 { key = "k", command = "outline_up" },
 { key = "j", command = "outline_down" },
 { key = "up", command = "outline_up" },
 { key = "down", command = "outline_down" },
 { key = "ctrl+o", command = "outline_toggle" },
 { key = "ctrl+b", command = "outline_toggle_explorer" },
 { key = "t", command = "outline_toggle_explorer" },
 { key = "tab", command = "outline_switch_pane_next" },
 { key = "shift+backtab", command = "outline_switch_pane_previous" },
 { key = "enter", command = "outline_expand" },
 { key = "g", command = "outline_select" },
 { key = "ctrl+shift+up", command = "explorer_scroll_to_top" },
 { key = "ctrl+shift+down", command = "explorer_scroll_to_bottom" },
]

[note_editor]
key_bindings = [
 { key = "k", command = "note_editor_cursor_up" },
 { key = "j", command = "note_editor_cursor_down" },
 { key = "up", command = "note_editor_cursor_up" },
 { key = "down", command = "note_editor_cursor_down" },
 { key = "t", command = "note_editor_toggle_explorer" },
 { key = "tab", command = "note_editor_switch_pane_next" },
 { key = "shift+backtab", command = "note_editor_switch_pane_previous" },
 { key = "ctrl+b", command = "note_editor_toggle_explorer" },
 { key = "ctrl+u", command = "note_editor_scroll_up_half_page" },
 { key = "ctrl+d", command = "note_editor_scroll_down_half_page" },
 { key = "ctrl+o", command = "note_editor_toggle_outline" },
 { key = "ctrl+shift+up", command = "note_editor_scroll_to_top" },
 { key = "ctrl+shift+down", command = "note_editor_scroll_to_bottom" },

 # Experimental editor
 { key = "i", command = "note_editor_experimental_set_edit_view" },
 { key = "ctrl+e", command = "note_editor_experimental_toggle_view" },
 { key = "shift+r", command = "note_editor_experimental_set_read_view" },
 { key = "ctrl+x", command = "note_editor_experimental_save" },
 { key = "esc", command = "note_editor_experimental_exit" },
 { key = "h", command = "note_editor_experimental_cursor_left" },
 { key = "l", command = "note_editor_experimental_cursor_right" },
 { key = "left", command = "note_editor_experimental_cursor_left" },
 { key = "right", command = "note_editor_experimental_cursor_right" },
 { key = "alt+f", command = "note_editor_experimental_cursor_word_forward" },
 { key = "alt+b", command = "note_editor_experimental_cursor_word_backward" },
]

[input_modal]
key_bindings = [
 { key = "esc", command = "input_modal_cancel" },
 { key = "enter", command = "input_modal_accept" },
 { key = "i", command = "input_modal_edit_mode" },
 { key = "h", command = "input_modal_left" },
 { key = "l", command = "input_modal_right" },
 { key = "left", command = "input_modal_left" },
 { key = "right", command = "input_modal_right" },
 { key = "alt+f", command = "input_modal_word_forward" },
 { key = "alt+b", command = "input_modal_word_backward" },
]

[help_modal]
key_bindings = [
 { key = "esc", command = "help_modal_close" },
 { key = "k", command = "help_modal_scroll_up_one" },
 { key = "j", command = "help_modal_scroll_down_one" },
 { key = "up", command = "help_modal_scroll_up_one" },
 { key = "down", command = "help_modal_scroll_down_one" },
 { key = "ctrl+u", command = "help_modal_scroll_up_half_page" },
 { key = "ctrl+d", command = "help_modal_scroll_down_half_page" },
]

[vault_selector_modal]
key_bindings = [
 { key = "k", command = "vault_selector_modal_up" },
 { key = "j", command = "vault_selector_modal_down" },
 { key = "up", command = "vault_selector_modal_up" },
 { key = "down", command = "vault_selector_modal_down" },
 { key = "enter", command = "vault_selector_modal_open" },
 { key = "esc", command = "vault_selector_modal_close" },
]