Detailed changes
@@ -4,7 +4,16 @@ Zed is designed to be configured: we want to fit your workflow and preferences e
In addition to the settings described here, you may also want to change your [theme](./themes.md), configure your [key bindings](./key-bindings.md), set up [tasks](./tasks.md) or install [extensions](https://github.com/zed-industries/extensions).
-## Settings files
+## Settings Window
+
+You can browse through many of the supported settings by using the settings window, which can be opened with the {#kb zed::OpenSettings} keybinding, or through the `zed: open settings` action in the command palette.
+
+Through it, you can customize your local, user settings as well as project settings.
+
+> Note that not all settings that Zed supports are available through the UI yet.
+> Some more intricate ones—for example, language formatters—can only be changed through the JSON settings file.
+
+## User Settings File
<!--
TBD: Settings files. Rewrite with "remote settings" in mind (e.g. `local settings` on the remote host).
@@ -13,17 +22,34 @@ Consider renaming `zed: Open Local Settings` to `zed: Open Project Settings`.
TBD: Add settings documentation about how settings are merged as overlays. E.g. project>local>default. Note how settings that are maps are merged, but settings that are arrays are replaced and must include the defaults.
-->
-Your settings file can be opened with {#kb zed::OpenSettings}. By default it is located at `~/.config/zed/settings.json`, though if you have XDG_CONFIG_HOME in your environment on Linux it will be at `$XDG_CONFIG_HOME/zed/settings.json` instead.
+Your settings JSON file can be opened with {#kb zed::OpenSettingsFile}.
+By default it is located at `~/.config/zed/settings.json`, though if you have `XDG_CONFIG_HOME` in your environment on Linux it will be at `$XDG_CONFIG_HOME/zed/settings.json` instead.
-This configuration is merged with any local configuration inside your projects. You can open the project settings by running {#action zed::OpenProjectSettings} from the command palette. This will create a `.zed` directory containing`.zed/settings.json`.
+Whatever you have added to your user settings file gets merged with any local configuration inside your projects.
-Although most projects will only need one settings file at the root, you can add more local settings files for subdirectories as needed. Not all settings can be set in local files, just those that impact the behavior of the editor and language tooling. For example you can set `tab_size`, `formatter` etc. but not `theme`, `vim_mode` and similar.
+### Default Settings
+
+When visiting the settings UI, the values you see set are the default ones.
+You can also verify all of them in JSON form by running {#action zed::OpenDefaultSettings} from the command palette.
+
+Extensions that provide language servers may also provide default settings for those language servers.
+
+## Project Settings File
+
+Similarly to user files, you can open your project settings file by running {#action zed::OpenProjectSettings} from the command palette.
+This will create a `.zed` directory containing`.zed/settings.json`.
+
+Although most projects will only need one settings file at the root, you can add more local settings files for subdirectories as needed.
+Not all settings can be set in local files, just those that impact the behavior of the editor and language tooling.
+For example you can set `tab_size`, `formatter` etc. but not `theme`, `vim_mode` and similar.
The syntax for configuration files is a super-set of JSON that allows `//` comments.
-### Per-release channel overrides
+## Per-release Channel Overrides
-Zed reads the same `settings.json` across all release channels (Stable, Preview or Nightly). However, you can scope overrides to a specific channel by adding top-level `stable`, `preview`, `nightly` or `dev` objects. They are merged into the base configuration with settings from these keys taking precedence upon launching the specified build. For example:
+Zed reads the same `settings.json` across all release channels (Stable, Preview or Nightly).
+However, you can scope overrides to a specific channel by adding top-level `stable`, `preview`, `nightly` or `dev` objects.
+They are merged into the base configuration with settings from these keys taking precedence upon launching the specified build. For example:
```json [settings]
{
@@ -43,13 +69,9 @@ With this configuration, Stable keeps all base preferences, Preview switches to
Changing settings via the UI will always apply the change across all channels.
-## Default settings
-
-You can find the default settings for your current Zed by running {#action zed::OpenDefaultSettings} from the command palette.
-
-Extensions that provide language servers may also provide default settings for those language servers.
+---
-# Settings
+Find below an extensive run-through of many supported settings by Zed.
## Active Pane Modifiers
@@ -75,10 +75,12 @@ General highlights:
## Configure Zed
-To open your custom settings to set things like fonts, formatting settings, per-language settings, and more, use the {#kb zed::OpenSettings} keybinding.
+To make Zed feel more like home, you can use the {#kb zed::OpenSettings} keybinding to open the settings window.
+In there, you can browse through many of the customization points, including common ones like formatting settings, fonts, per-language settings, and many more.
-To see all available settings, open the Command Palette with {#kb command_palette::Toggle} and search for `zed: open default settings`.
-You can also check them all out in the [Configuring Zed](./configuring-zed.md) documentation.
+Note that, however, some settings can't yet be changed through the settings window and can only be set through the JSON file, which you can access through the {#kb zed::OpenSettingsFile} keybinding.
+
+You can also check all supported settings in the [Configuring Zed](./configuring-zed.md) documentation.
## Configure AI in Zed
@@ -2,9 +2,9 @@
Zed has a very customizable key binding system—you can tweak everything to work exactly how your fingers expect!
-## Predefined keymaps
+## Predefined Keymaps
-If you're used to a specific editor's defaults, you can set a `base_keymap` in your [settings file](./configuring-zed.md).
+If you're used to a specific editor's defaults, you can change your `base_keymap` through the settings window ({#kb zed::OpenSettings}) or directly through your `settings.json` file ({#kb zed::OpenSettingsFile}).
We currently support:
- VS Code (default)
@@ -21,18 +21,31 @@ This setting can also be changed via the command palette through the `zed: toggl
You can also enable `vim_mode` or `helix_mode`, which add modal bindings.
For more information, see the documentation for [Vim mode](./vim.md) and [Helix mode](./helix.md).
-## User keymaps
+## Keymap Editor
-Where Zed looks for your keymap:
+You can access the keymap editor through the {#kb zed::OpenKeymap} action or by running {#action zed::OpenKeymap} action from the command palette
+
+In there, you can see all of the existing actions in Zed as well as the associated keybindings set to them by default.
+
+You can also customize them right from there, either by clicking on the pencil icon that appears when you hover over a particular action, by double-clicking on the action row, or by pressing the `enter` key.
+
+Anything that you end up doing on the keymap editor also gets reflected on the `keymap.json` file.
+
+## User Keymaps
+
+The keymap file is stored in the following locations for each platform:
- macOS/Linux: `~/.config/zed/keymap.json`
- Windows: `~\AppData\Roaming\Zed/keymap.json`
-You can open the keymap with the {#action zed::OpenKeymapFile} action from the command palette, or edit it in Zed's Keymap Editor, accessible via the {#action zed::OpenKeymap} action or the {#kb zed::OpenKeymap} keybinding.
+You can open the keymap with the {#action zed::OpenKeymapFile} action from the command palette.
-The `keymap.json` file contains a JSON array of objects with `"bindings"`. If no `"context"` is set, the bindings are always active. If it is set, the binding is only active when the [context matches](#contexts).
+This file contains a JSON array of objects with `"bindings"`.
+If no `"context"` is set, the bindings are always active.
+If it is set, the binding is only active when the [context matches](#contexts).
-Within each binding section, a [key sequence](#keybinding-syntax) is mapped to [an action](#actions). If conflicts are detected, they are resolved as [described below](#precedence).
+Within each binding section, a [key sequence](#keybinding-syntax) is mapped to [an action](#actions).
+If conflicts are detected, they are resolved as [described below](#precedence).
If you are using a non-QWERTY, Latin-character keyboard, you may want to set `use_key_equivalents` to `true`. See [Non-QWERTY keyboards](#non-qwerty-keyboards) for more information.
@@ -55,15 +68,16 @@ For example:
]
```
-You can see all of Zed's default bindings in the default keymaps for:
+You can see all of Zed's default bindings for each platform in the default keymaps files:
- [macOS](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-macos.json)
- [Windows](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-windows.json)
- [Linux](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-linux.json).
-If you want to debug problems with custom keymaps, you can use `dev: Open Key Context View` from the command palette. Please file [an issue](https://github.com/zed-industries/zed) if you run into something you think should work but isn't.
+If you want to debug problems with custom keymaps, you can use `dev: Open Key Context View` from the command palette.
+Please file [an issue](https://github.com/zed-industries/zed) if you run into something you think should work but isn't.
-### Keybinding syntax
+### Keybinding Syntax
Zed has the ability to match against not just a single keypress, but a sequence of keys typed in order. Each key in the `"bindings"` map is a sequence of keypresses separated with a space.