Yehowshua/ZIm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add visual customization section to documentation (#33133)

Browse source 
Release Notes:

- Improved settings documentation for [visual customization](https://zed.dev/docs/visual-customization/)
This commit is contained in:
Peter Tripp 2025-06-21 22:55:53 -04:00 • committed by GitHub
parent 3cb4342a76
commit 8d05f6fdd3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 585 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

44
assets/settings/default.json
View file

@ -80,6 +80,7 @@
"inactive_opacity": 1.0
},
// Layout mode of the bottom dock. Defaults to "contained"
// choices: contained, full, left_aligned, right_aligned
"bottom_dock_layout": "contained",
// The direction that you want to split panes horizontally. Defaults to "up"
"pane_split_direction_horizontal": "up",
@ -94,11 +95,9 @@
// workspace when the centered layout is used.
"right_padding": 0.2
},
// All settings related to the image viewer.
// Image viewer settings
"image_viewer": {
// The unit for image file sizes.
// By default we're setting it to binary.
// The second option is decimal.
// The unit for image file sizes: "binary" (KiB, MiB) or decimal (KB, MB)
"unit": "binary"
},
// Determines the modifier to be used to add multiple cursors with the mouse. The open hover link mouse gestures will adapt such that it do not conflict with the multicursor modifier.
@ -119,7 +118,14 @@
"hover_popover_delay": 300,
// Whether to confirm before quitting Zed.
"confirm_quit": false,
// Whether to restore last closed project when fresh Zed instance is opened.
// Whether to restore last closed project when fresh Zed instance is opened
// May take 3 values:
// 1. All workspaces open during last session
// "restore_on_startup": "last_session"
// 2. The workspace opened
// "restore_on_startup": "last_workspace",
// 3. Do not restore previous workspaces
// "restore_on_startup": "none",
"restore_on_startup": "last_session",
// Whether to attempt to restore previous file's state when opening it again.
// The state is stored per pane.
@ -132,7 +138,9 @@
"restore_on_file_reopen": true,
// Whether to automatically close files that have been deleted on disk.
"close_on_file_delete": false,
// Size of the drop target in the editor.
// Relative size of the drop target in the editor that will open dropped file as a split pane (0-0.5)
// E.g. 0.25 == If you drop onto the top/bottom quarter of the pane a new vertical split will be used
// If you drop onto the left/right quarter of the pane a new horizontal split will be used
"drop_target_size": 0.2,
// Whether the window should be closed when using 'close active item' on a window with no tabs.
// May take 3 values:
@ -485,7 +493,7 @@
},
// Whether the editor will scroll beyond the last line.
"scroll_beyond_last_line": "one_page",
// The number of lines to keep above/below the cursor when scrolling.
// The number of lines to keep above/below the cursor when scrolling with the keyboard
"vertical_scroll_margin": 3,
// Whether to scroll when clicking near the edge of the visible text area.
"autoscroll_on_clicks": false,
@ -701,15 +709,14 @@
"default_width": 360,
// Style of the git status indicator in the panel.
//
// Choices: label_color, icon
// Default: icon
"status_style": "icon",
// What branch name to use if init.defaultBranch
// is not set
// What branch name to use if `init.defaultBranch` is not set
//
// Default: main
"fallback_branch_name": "main",
// Whether to sort entries in the panel by path
// or by status (the default).
// Whether to sort entries in the panel by path or by status (the default).
//
// Default: false
"sort_by_path": false,
@ -720,8 +727,9 @@
"scrollbar": {
// When to show the scrollbar in the git panel.
//
// Choices: always, auto, never, system
// Default: inherits editor scrollbar settings
"show": null
// "show": null
}
},
"message_editor": {
@ -999,8 +1007,7 @@
// Removes any lines containing only whitespace at the end of the file and
// ensures just one newline at the end.
"ensure_final_newline_on_save": true,
// Whether or not to perform a buffer format before saving
//
// Whether or not to perform a buffer format before saving: [on, off, prettier, language_server]
// Keep in mind, if the autosave with delay is enabled, format_on_save will be ignored
"format_on_save": "on",
// How to perform a buffer format. This setting can take 4 values:
@ -1181,6 +1188,12 @@
// 2. Display predictions inline only when holding a modifier key (alt by default).
// "mode": "subtle"
"mode": "eager",
// Copilot-specific settings
// "copilot": {
// "enterprise_uri": "",
// "proxy": "",
// "proxy_no_verify": false
// },
// Whether edit predictions are enabled when editing text threads.
// This setting has no effect if globally disabled.
"enabled_in_text_threads": true
@ -1346,6 +1359,8 @@
// the terminal will default to matching the buffer's font fallbacks.
// This will be merged with the platform's default font fallbacks
// "font_fallbacks": ["FiraCode Nerd Fonts"],
// The weight of the editor font in standard CSS units from 100 to 900.
// "font_weight": 400
// Sets the maximum number of lines in the terminal's scrollback buffer.
// Default: 10_000, maximum: 100_000 (all bigger values set will be treated as 100_000), 0 disables the scrolling.
// Existing terminals will not pick up this change until they are recreated.
@ -1802,6 +1817,7 @@
"debugger": {
"stepping_granularity": "line",
"save_breakpoints": true,
"dock": "bottom",
"button": true
}
}

1
docs/src/SUMMARY.md
View file

@ -19,6 +19,7 @@
- [Snippets](./snippets.md)
- [Themes](./themes.md)
- [Icon Themes](./icon-themes.md)
- [Visual Customization](./visual-customization.md)
- [Vim Mode](./vim.md)
<!-- - [Globs](./globs.md) -->

537
docs/src/visual-customization.md Normal file
View file

@ -0,0 +1,537 @@
# Visual Customization
Various aspects of Zed's visual layout can be configured via Zed settings.json which you can access via {#action zed::OpenSettings} ({#kb zed::OpenSettings}).
See [Configuring Zed](./configuring-zed.md) for additional information and other non-visual settings.
## Themes
Use may install zed extensions providing [Themes](./themes.md) and [Icon Themes](./icon-themes.md) via {#action zed::Extensions} from the command palette or menu.
You can preview/choose amongsts your installed themes and icon themes with {#action theme_selector::Toggle} ({#kb theme_selector::Toggle}) and ({#action icon_theme_selector::Toggle}) which will modify the following settings:
```json
{
"theme": "One Dark",
"icon_theme": "Zed (Default)"
}
```
If you would like to use distinct themes for light mode/dark mode that can be set with:
```json
{
"theme": {
"dark": "One Dark"
"light": "One Light",
// Mode to use (dark, light) or "system" to follow the OS's light/dark mode (default)
"mode": "system",
},
"icon_theme": {
"dark": "Zed (Default)"
"light": "Zed (Default)",
// Mode to use (dark, light) or "system" to follow the OS's light/dark mode (default)
"mode": "system",
}
}
```
## Fonts
```json
// UI Font. Use ".SystemUIFont" to use the default system font (SF Pro on macOS)
"ui_font_family": "Zed Plex Sans",
"ui_font_weight": 400, // Font weight in standard CSS units from 100 to 900.
"ui_font_size": 16,
// Buffer Font - Used by editor buffers
"buffer_font_family": "Zed Plex Mono", // Font name for editor buffers
"buffer_font_size": 15, // Font size for editor buffers
"buffer_font_weight": 400, // Font weight in CSS units [100-900]
// Line height "comfortable" (1.618), "standard" (1.3) or custom: `{ "custom": 2 }`
"buffer_line_height": "comfortable",
// Terminal Font Settings
"terminal": {
"font_family": "Zed Plex Mono",
"font_size": 15,
// Terminal line height: comfortable (1.618), standard(1.3) or `{ "custom": 2 }`
"line_height": "comfortable",
},
// Agent Panel Font Settings
"agent_font_size": 15
```
### Font ligatures
By default Zed enable font ligatures which will visually combines certain adjacent characters.
For example `=>` will be displayed as `→` and `!=` will be `≠`. This is purely cosmetic and the individual characters remain unchanged.
To disable this behavior use:
```json
{
"buffer_font_features": {
"calt": false // Disable ligatures
}
}
```
### Status Bar
```json
{
// Whether to show full labels in line indicator or short ones
// - `short`: "2 s, 15 l, 32 c"
// - `long`: "2 selections, 15 lines, 32 characters"
"line_indicator_format": "long"
// Individual status bar icons can be hidden:
// "project_panel": {"button": false },
// "outline_panel": {"button": false },
// "collaboration_panel": {"button": false },
// "chat_panel": {"button": "never" },
// "git_panel": {"button": false },
// "notification_panel": {"button": false },
// "agent": {"button": false },
// "debugger": {"button": false },
// "diagnostics": {"button": false },
// "search": {"button": false },
}
```
### Titlebar
```json
// Control which items are shown/hidden in the title bar
"title_bar": {
"show_branch_icon": false, // Show/hide branch icon beside branch switcher
"show_branch_name": true, // Show/hide branch name
"show_project_items": true, // Show/hide project host and name
"show_onboarding_banner": true, // Show/hide onboarding banners
"show_user_picture": true, // Show/hide user avatar
"show_sign_in": true // Show/hide sign-in button
},
```
## Workspace
```json
{
// Whether to use the system provided dialogs for Open and Save As (true) or
// Zed's built-in keyboard-first pickers (false)
"use_system_path_prompts": true,
// Active pane styling settings.
"active_pane_modifiers": {
// Inset border size of the active pane, in pixels.
"border_size": 0.0,
// Opacity of the inactive panes. 0 means transparent, 1 means opaque.
"inactive_opacity": 1.0
},
// Layout mode of the bottom dock: contained, full, left_aligned, right_aligned
"bottom_dock_layout": "contained",
// Whether to resize all the panels in a dock when resizing the dock.
// Can be a combination of "left", "right" and "bottom".
"resize_all_panels_in_dock": ["left"]
}
```
<!--
TBD: Centered layout related settings
```json
"centered_layout": {
// The relative width of the left padding of the central pane from the
// workspace when the centered layout is used.
"left_padding": 0.2,
// The relative width of the right padding of the central pane from the
// workspace when the centered layout is used.
"right_padding": 0.2
},
```
-->
## Editor
```json
// Whether the cursor blinks in the editor.
"cursor_blink": true,
// Cursor shape for the default editor: bar, block, underline, hollow
"cursor_shape": null,
// Highlight the current line in the editor: none, gutter, line, all
"current_line_highlight": "all",
// When does the mouse cursor hide: never, on_typing, on_typing_and_movement
"hide_mouse": "on_typing_and_movement",
// Whether to highlight all occurrences of the selected text in an editor.
"selection_highlight": true,
// Visually show tabs and spaces (none, all, selection, boundary, trailing)
"show_whitespaces": "selection",
"unnecessary_code_fade": 0.3, // How much to fade out unused code.
// Hide the values of in variables from visual display in private files
"redact_private_values": false,
// Soft-wrap and rulers
"soft_wrap": "none", // none, editor_width, preferred_line_length, bounded
"preferred_line_length": 80, // Column to soft-wrap
"show_wrap_guides": true, // Show/hide wrap guides (vertical rulers)
"wrap_guides": [], // Where to position wrap_guides (character counts)
// Gutter Settings
"gutter": {
"line_numbers": true, // Show/hide line numbers in the gutter.
"runnables": true, // Show/hide runnables buttons in the gutter.
"breakpoints": true, // Show/hide show breakpoints in the gutter.
"folds": true, // Show/hide show fold buttons in the gutter.
"min_line_number_digits": 4 // Reserve space for N digit line numbers
},
"relative_line_numbers": false, // Show relative line numbers in gutter
// Indent guides
"indent_guides": {
"enabled": true,
"line_width": 1, // Width of guides in pixels [1-10]
"active_line_width": 1, // Width of active guide in pixels [1-10]
"coloring": "fixed", // disabled, fixed, indent_aware
"background_coloring": "disabled" // disabled, indent_aware
}
```
### Git Blame {#editor-blame}
```json
"git": {
"inline_blame": {
"enabled": true, // Show/hide inline blame
"delay": 0, // Show after delay (ms)
"min_column": 0, // Minimum column to inline display blame
"show_commit_summary": false // Show/hide commit summary
},
"hunk_style": "staged_hollow" // staged_hollow, unstaged_hollow
}
```
### Editor Toolbar
```json
// Editor toolbar related settings
"toolbar": {
"breadcrumbs": true, // Whether to show breadcrumbs.
"quick_actions": true, // Whether to show quick action buttons.
"selections_menu": true, // Whether to show the Selections menu
"agent_review": true, // Whether to show agent review buttons
"code_actions": false // Whether to show code action buttons
}
```
### Editor Scrollbar and Minimap {#editor-scrollbar}
```json
// Scrollbar related settings
"scrollbar": {
// When to show the scrollbar in the editor (auto, system, always, never)
"show": "auto",
"cursors": true, // Show cursor positions in the scrollbar.
"git_diff": true, // Show git diff indicators in the scrollbar.
"search_results": true, // Show buffer search results in the scrollbar.
"selected_text": true, // Show selected text occurrences in the scrollbar.
"selected_symbol": true, // Show selected symbol occurrences in the scrollbar.
"diagnostics": "all", // Show diagnostics (none, error, warning, information, all)
"axes": {
"horizontal": true, // Show/hide the horizontal scrollbar
"vertical": true // Show/hide the vertical scrollbar
}
},
// Minimap related settings
"minimap": {
"show": "never", // When to show (auto, always, never)
"display_in": "active_editor", // Where to show (active_editor, all_editor)
"thumb": "always", // When to show thumb (always, hover)
"thumb_border": "left_open", // Thumb border (left_open, right_open, full, none)
"max_width_columns": 80 // Maximum width of minimap
"current_line_highlight": null // Highlight current line (null, line, gutter)
},
// Control Editor scroll beyond the last line: off, one_page, vertical_scroll_margin
"scroll_beyond_last_line": "one_page",
// Lines to keep above/below the cursor when scrolling with the keyboard
"vertical_scroll_margin": 3,
// The number of characters to keep on either side when scrolling with the mouse
"horizontal_scroll_margin": 5,
// Scroll sensitivity multiplier
"scroll_sensitivity": 1.0,
// Scroll sensitivity multiplier for fast scrolling (hold alt while scrolling)
"fast_scroll_sensitivity": 4.0,
```
### Editor Tabs
```json
// Maximum number of tabs per pane. Unset for unlimited.
"max_tabs": null,
// Customize the tab bar appearance
"tab_bar": {
"show": true, // Show/hide the tab bar
"show_nav_history_buttons": true, // Show/hide history buttons on tab bar
"show_tab_bar_buttons": true // Show hide buttons (new, split, zoom)
},
"tabs": {
"git_status": false, // Color to show git status
"close_position": "right", // Close button position (left, right, hidden)
"show_close_button": "hover", // Close button shown (hover, always, hidden)
"file_icons": false, // Icon showing file type
// Show diagnostics in file icon (off, errors, all). Requires file_icons=true
"show_diagnostics": "off"
}
```
### Multibuffer
```json
{
// The default number of lines to expand excerpts in the multibuffer by.
"expand_excerpt_lines": 5
}
```
### Editor Completions, Snippets, Actions, Diagnostics {#editor-lsp}
```json
"snippet_sort_order": "inline", // Snippets completions: top, inline, bottom
"show_completions_on_input": true, // Show completions while typing
"show_completion_documentation": true, // Show documentation in completions
"auto_signature_help": false, // Show method signatures inside parentheses
// Whether to show the signature help after completion or a bracket pair inserted.
// If `auto_signature_help` is enabled, this setting will be treated as enabled also.
"show_signature_help_after_edits": false,
// Whether to show code action button at start of buffer line.
"inline_code_actions": true,
// Which level to use to filter out diagnostics displayed in the editor:
"diagnostics_max_severity": null, // off, error, warning, info, hint, null (all)
// How to render LSP `textDocument/documentColor` colors in the editor.
"lsp_document_colors": "inlay", // none, inlay, border, background
```
### Edit Predictions {#editor-ai}
```json
"edit_predictions": {
"mode": "eager", // Automatically show (eager) or hold-alt (subtle)
"enabled_in_text_threads": true // Show/hide predictions in agent text threads
},
"show_edit_predictions": true // Show/hide predictions in editor
```
### Editor Inlay Hints
```json
{
"inlay_hints": {
"enabled": false,
// Toggle certain types of hints on and off, all switched on by default.
"show_type_hints": true,
"show_parameter_hints": true,
"show_other_hints": true,
// Whether to show a background for inlay hints (theme `hint.background`)
"show_background": false, //
// Time to wait after editing before requesting hints (0 to disable debounce)
"edit_debounce_ms": 700,
// Time to wait after scrolling before requesting hints (0 to disable debounce)
"scroll_debounce_ms": 50,
// A set of modifiers which, when pressed, will toggle the visibility of inlay hints.
"toggle_on_modifiers_press": {
"control": false,
"shift": false,
"alt": false,
"platform": false,
"function": false
}
}
}
```
## File Finder
```json
// File Finder Settings
"file_finder": {
"file_icons": true, // Show/hide file icons
"modal_max_width": "small", // Horizontal size: small, medium, large, xlarge, full
"git_status": true, // Show the git status for each entry
"include_ignored": null // gitignored files in results: true, false, null
},
```
## Project Panel
Project panel can be shown/hidden with {#action project_panel::ToggleFocus} ({#kb project_panel::ToggleFocus}) or with {#action pane::RevealInProjectPanel} ({#kb pane::RevealInProjectPanel}).
```json
// Project Panel Settings
"project_panel": {
"button": true, // Show/hide button in the status bar
"default_width": 240, // Default panel width
"dock": "left", // Position of the dock (left, right)
"entry_spacing": "comfortable", // Vertical spacing (comfortable, standard)
"file_icons": true, // Show/hide file icons
"folder_icons": true, // Show/hide folder icons
"git_status": true, // Indicate new/updated files
"indent_size": 20, // Pixels for each successive indent
"auto_reveal_entries": true, // Show file in panel when activating its buffer
"auto_fold_dirs": true, // Fold dirs with single subdir
"scrollbar": { // Project panel scrollbar settings
"show": null // Show/hide: (auto, system, always, never)
},
"show_diagnostics": "all", //
// Settings related to indent guides in the project panel.
"indent_guides": {
// When to show indent guides in the project panel. (always, never)
"show": "always"
},
// Whether to hide the root entry when only one folder is open in the window.
"hide_root": false
}.
```
## Agent Panel
```json
"agent": {
"version": "2",
"enabled": true, // Enable/disable the agent
"button": true, // Show/hide the icon in the status bar
"dock": "right", // Where to dock: left, right, bottom
"default_width": 640, // Default width (left/right docked)
"default_height": 320, // Default height (bottom dockeed)
},
"agent_font_size": 16
```
See [Zed AI Documentation](./ai/overview.md) for additional non-visual AI settings.
## Terminal Panel
```json
// Terminal Panel Settings
"terminal": {
"dock": "bottom", // Where to dock: left, right, bottom
"button": true, // Show/hide status bar icon
"default_width": 640, // Default width (left/right docked)
"default_height": 320, // Default height (bottom dockeed)
// Set the cursor blinking behavior in the terminal (on, off, terminal_controlled)
"blinking": "terminal_controlled",
// Default cursor shape for the terminal (block, bar, underline, hollow)
"cursor_shape": "block",
// Environment variables to add to terminal's process environment
"env": {
// "KEY": "value"
},
// Terminal scrollbar
"scrollbar": {
"show": null // Show/hide: (auto, system, always, never)
},
// Terminal Font Settings
"font_family": "Zed Plex Mono",
"font_size": 15,
"font_weight": 400,
// Terminal line height: comfortable (1.618), standard(1.3) or `{ "custom": 2 }`
"line_height": "comfortable",
"max_scroll_history_lines": 10000, // Scrollback history (0=disable, max=100000)
}
```
See [Terminal settings](./configuring-zed.md#terminal) for additional non-visual customization options.
### Other Panels
```json
// Git Panel
"git_panel": {
"button": true, // Show/hide status bar icon
"dock": "left", // Where to dock: left, right
"default_width": 360, // Default width of the git panel.
"status_style": "icon", // label_color, icon
"sort_by_path": false, // Sort by path (false) or status (true)
"scrollbar": {
"show": null // Show/hide: (auto, system, always, never)
}
},
// Debugger Panel
"debugger": {
"dock": "bottom", // Where to dock: left, right, bottom
"button": true // Show/hide status bar icon
},
// Outline Panel
"outline_panel": {
"button": true, // Show/hide status bar icon
"default_width": 300, // Default width of the git panel
"dock": "left", // Where to dock: left, right
"file_icons": true, // Show/hide file_icons
"folder_icons": true, // Show file_icons (true), chevrons (false) for dirs
"git_status": true, // Show git status
"indent_size": 20, // Indentation for nested items (pixels)
"indent_guides": {
"show": "always" // Show indent guides (always, never)
},
"auto_reveal_entries": true, // Show file in panel when activating its buffer
"auto_fold_dirs": true, // Fold dirs with single subdir
"scrollbar": { // Project panel scrollbar settings
"show": null // Show/hide: (auto, system, always, never)
}
}
```
## Collaboration Panels
```json
{
// Collaboration Panel
"collaboration_panel": {
"button": true, // Show/hide status bar icon
"dock": "left", // Where to dock: left, right
"default_width": 240 // Default width of the collaboration panel.
},
"show_call_status_icon": true, // Shown call status in the OS status bar.
// Chat Panel
"chat_panel": {
"button": "when_in_call", // status bar icon (true, false, when_in_call)
"dock": "right", // Where to dock: left, right
"default_width": 240 // Default width of the chat panel
},
// Notification Panel
"notification_panel": {
// Whether to show the notification panel button in the status bar.
"button": true,
// Where to dock the notification panel. Can be 'left' or 'right'.
"dock": "right",
// Default width of the notification panel.
"default_width": 380
}
```

17
docs/src/workspace-persistence.md
View file

@ -12,3 +12,20 @@ The naming convention of these databases takes on the form of `0-<zed_channel>`:
- Preview: `0-preview`
**If you encounter workspace persistence issues in Zed, deleting the database and restarting Zed often resolves the problem, as the database may have been corrupted at some point.** If your issue continues after restarting Zed and regenerating a new database, please [file an issue](https://github.com/zed-industries/zed/issues/new?template=10_bug_report.yml).
## Settings
You can customize workspace restoration behavior with the following settings:
```json
{
// Workspace restoration behavior.
// All workspaces ("last_session"), last workspace ("last_workspace") or "none"
"restore_on_startup": "last_session",
// Whether to attempt to restore previous file's state when opening it again.
// E.g. for editors, selections, folds and scroll positions are restored
"restore_on_file_reopen": true,
// Whether to automatically close files that have been deleted on disk.
"close_on_file_delete": false
}
```