Configuration Overview

Learn how to configure Fresh text editor through config.json and customize your editing experience

Configuration File Location

Fresh stores its configuration in a JSON file located at:

~/.config/fresh/config.json

The configuration file controls all aspects of the editor including themes, keybindings, editor behavior, language settings, and LSP servers.

Configuration Structure

The configuration file is organized into these main sections:

Editor Settings

Tab size, line numbers, syntax highlighting, auto-save, and display options

Keyboard & Keymaps

Keybinding styles (default, emacs, vscode, macos) and custom key mappings

Themes

Built-in themes and color customization

Language Settings

Per-language configuration for formatters, LSP servers, and indentation

Example Configuration

Here’s a minimal configuration file:

config.json

{
  "theme": "high-contrast",
  "check_for_updates": true,
  "active_keybinding_map": "default",
  "editor": {
    "tab_size": 4,
    "line_numbers": true,
    "line_wrap": true,
    "syntax_highlighting": true,
    "auto_indent": true
  }
}

Opening the Settings Editor

Fresh provides a visual settings editor for easy configuration:

1. Open Settings

   Press Ctrl+, or use the command palette (Ctrl+P) and type >settings

2. Browse Settings

   Settings are organized by category: Display, Editing, LSP, Performance, etc.

3. Edit Values

   Click on any setting to modify it. Changes are saved automatically to config.json

Configuration Categories

Top-Level Settings

Setting	Type	Default	Description
theme	string	"high-contrast"	Active color theme name
locale	string | null	null	UI language (null = auto-detect from environment)
check_for_updates	boolean	true	Check for new versions on startup
active_keybinding_map	string	"default" (macOS: "macos")	Active keybinding map

Editor Configuration

The editor object controls editing behavior, display settings, LSP features, and performance:

{
  "editor": {
    "tab_size": 4,
    "auto_indent": true,
    "line_numbers": true,
    "line_wrap": true,
    "syntax_highlighting": true,
    "enable_inlay_hints": true,
    "auto_save_enabled": false,
    "auto_save_interval_secs": 30
  }
}

See Settings Reference for all available options.

File Explorer

Configure the file tree sidebar:

{
  "file_explorer": {
    "respect_gitignore": true,
    "show_hidden": false,
    "show_gitignored": false,
    "width": 0.3
  }
}

Clipboard

Control which clipboard methods are used:

{
  "clipboard": {
    "use_osc52": true,
    "use_system_clipboard": true
  }
}

If you experience clipboard hangs in certain terminals (like PuTTY), disable use_osc52.

Terminal

Configure integrated terminal behavior:

{
  "terminal": {
    "jump_to_end_on_output": true
  }
}

Language-Specific Configuration

Override settings per language:

{
  "languages": {
    "rust": {
      "tab_size": 4,
      "use_tabs": false,
      "formatter": {
        "command": "rustfmt",
        "args": [],
        "stdin": true
      },
      "format_on_save": true
    },
    "go": {
      "tab_size": 8,
      "use_tabs": true,
      "show_whitespace_tabs": false
    }
  }
}

Language Configuration Options

Option	Type	Description
extensions	string[]	File extensions (e.g., ["rs"])
filenames	string[]	Exact filename matches (e.g., ["Makefile"])
grammar	string	Tree-sitter grammar name
comment_prefix	string	Comment syntax (e.g., "//")
tab_size	number	Spaces per tab (overrides global)
use_tabs	boolean	Insert tab characters instead of spaces
auto_indent	boolean	Auto-indent new lines
formatter	object	Formatter configuration
format_on_save	boolean	Run formatter on save

LSP Server Configuration

Configure language servers:

{
  "lsp": {
    "rust": {
      "command": "rust-analyzer",
      "args": [],
      "enabled": true,
      "auto_start": false,
      "process_limits": {
        "max_memory_percent": 50,
        "max_cpu_percent": 90,
        "enabled": true
      },
      "initialization_options": {
        "checkOnSave": false,
        "diagnostics": {"enable": true}
      }
    }
  }
}

LSP Configuration Options

Option	Type	Description
command	string	LSP server executable
args	string[]	Command-line arguments
enabled	boolean	Enable this language server
auto_start	boolean	Start server automatically when opening files
initialization_options	object	Server-specific initialization options
process_limits	object	Memory and CPU limits

Reloading Configuration

Fresh automatically reloads config.json when it changes. You can also:

• Restart the editor: Changes take effect immediately
• Use the settings UI: Changes are applied in real-time
• Reload manually: >reload config in the command palette

Configuration Schema

Fresh provides JSON schema validation for config.json. Enable schema validation in your editor:

config.json

{
  "$schema": "/path/to/fresh/plugins/config-schema.json"
}

Migration

Fresh supports configuration migrations through the version field:

{
  "version": 0,
  "theme": "high-contrast"
}

Configurations without a version field are treated as version 0.

Example: Complete Configuration

View complete config.example.json

{
  "theme": "high-contrast",
  "check_for_updates": true,
  "editor": {
    "tab_size": 4,
    "auto_indent": true,
    "line_numbers": true,
    "relative_line_numbers": false,
    "scroll_offset": 3,
    "syntax_highlighting": true,
    "line_wrap": true,
    "highlight_timeout_ms": 5,
    "snapshot_interval": 100,
    "large_file_threshold_bytes": 1048576,
    "estimated_line_length": 80,
    "enable_inlay_hints": true,
    "enable_semantic_tokens_full": false,
    "auto_save_enabled": true,
    "auto_save_interval_secs": 30,
    "recovery_enabled": true,
    "auto_recovery_save_interval_secs": 2,
    "highlight_context_bytes": 10000,
    "mouse_hover_enabled": true,
    "mouse_hover_delay_ms": 500,
    "double_click_time_ms": 500,
    "auto_revert_poll_interval_ms": 2000,
    "file_tree_poll_interval_ms": 3000
  },
  "file_explorer": {
    "respect_gitignore": true,
    "show_hidden": false,
    "show_gitignored": false,
    "custom_ignore_patterns": [],
    "width": 0.3
  },
  "clipboard": {
    "use_osc52": true,
    "use_system_clipboard": true
  },
  "terminal": {
    "jump_to_end_on_output": true
  },
  "keybindings": [],
  "active_keybinding_map": "default"
}

Next Steps

Settings Reference

Complete list of all editor settings

Keyboard Configuration

Customize keybindings and keymaps

Theme System

Built-in themes and color customization