Skip to content

Configuring Fern

Config file locations

Fern has two layers of configuration:

File Scope
~/.config/fern/config.toml (or $XDG_CONFIG_HOME/fern/config.toml) Global - applies to all vaults
{vault}/.fern/config.toml Vault-level - overrides global for that vault only

Both files are created automatically on first run with all options present and commented out. Uncomment and change any line to override the default.

On Windows the global config path follows %APPDATA%\fern\config.toml if XDG_CONFIG_HOME is not set.

Editing the config

You can open either config file in any text editor. Changes take effect the next time you start Fern (or reload the vault with :vaultSwitch).

Some settings can also be changed without editing a file directly. For example, the active theme can be switched through the command palette (ctrl+p, search "theme") and the change is written to the vault's .fern/config.toml automatically.

Configuration reference

Notes and files

Key Default Description
ext md File extension for notes
note_frontmatter true Scaffold new notes with YAML frontmatter (title, date, tags)
link_format markdown Inserted link style: wiki or markdown

Journals

Key Default Description
start_journal (none) Comma-separated list of journal periods to open on startup: day, week, month, year
auto_journal_periods false Auto-open period logs when today is a period boundary (start of week, month, year). Requires a template for each period.
week_start monday First day of the week for weekly journals: monday or sunday

Editor

Key Default Description
start_mode edit Mode when a note opens: edit (Normal mode) or view (View mode)
fold_level 0 Initial fold depth for markdown headings (0 = all expanded, 1-6 = fold from that heading level)
tab_spaces 4 Spaces used to represent a tab character for display
expand_tabs false When true, the Tab key inserts shift_width spaces instead of a literal tab
shift_width 4 Number of spaces inserted by Tab when expand_tabs = true (1-16)
checkbox_states (two-state) Comma-separated list of bracket characters for checkbox cycling. An empty leading item represents the unchecked state. Example: ,~,x gives three states: unchecked, in-progress, done.
checkbox_todo (space) The checkbox symbol that task-todo: search matches. Must be one of the characters in checkbox_states.
checkbox_done x The checkbox symbol that task-done: search matches. Must be one of the characters in checkbox_states.
spell_check false Enable live spell-check highlighting in Insert and Replace modes (requires Hunspell).
spell_lang en_US Hunspell dictionary name to use for spell checking.
Key Default Description
search_fuzzy false When true, bare search terms get a * suffix appended for prefix matching

Display

Key Default Description
show_sidebar true Show the sidebar on startup
theme dark Name of the active theme (see Themes)

Keybindings

All keybindings can be remapped in the global config file. The following keys are configurable at the application level:

Config key Default Action
sidebar ctrl+b Toggle sidebar
close_tab ctrl+w Close active tab
next_tab ] Next tab
prev_tab [ Previous tab
move_tab_left { Move tab left
move_tab_right } Move tab right
palette ctrl+p Open command palette

Viewer/editor keybindings live under the [keybindings.viewer] section. For example, to remap "move down" to ctrl+j in addition to j:

[keybindings.viewer]
move_down = "j,down,ctrl+j"

Multiple keys are separated by commas. The full list of viewer keybindings is shown (commented out) in the auto-generated config file.

Example: a minimal custom config

# ~/.config/fern/config.toml
theme = "nord"
start_mode = "view"
link_format = "wiki"
week_start = "monday"
start_journal = ["day"]
expand_tabs = true
shift_width = 2

Vault-level override example

To use a different theme for a specific vault without changing your global config:

# ~/work-notes/.fern/config.toml
theme = "github-light"
start_mode = "view"

See Themes for the full list of built-in theme names.