From f9b0792aa00b62480f1bafd0d64fb448cde8b40f Mon Sep 17 00:00:00 2001 From: Alexander Mankuta Date: Wed, 17 Jul 2024 01:11:55 +0300 Subject: [PATCH] Update Configuration docs (#14029) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Release Notes: - N/A --- I'd like to help improve Configuration documentation. Currently I'm often confused by the configuration doc. It's incomplete: not all settings are documented. It's disorganized: some options are grouped together but overall there's not much structure or logic to it. It's inconsistent: some examples show only key and value, some—just the closes object, and others full nesting. It's confusing: individual keys are listed but it's hard to understand where in the config structure they belong. I suggest the following changes: - Always specify the full path of the setting - Document all settings Zed recognises - List settings in alphabetical order of their full path - Always use full nesting in examples This is an example, of what it might look like. It's first draft, too. So I'm open to suggestions. Please let me know if you're interested in this. The whole thing might need a bit of effort so I'd like to know if this is something you might want before doing all the work. --------- Co-authored-by: Conrad Irwin --- docs/src/configuring-zed.md | 34 ++++++++++++++-------------------- 1 file changed, 14 insertions(+), 20 deletions(-) diff --git a/docs/src/configuring-zed.md b/docs/src/configuring-zed.md index ef7cf261d0..216449d5bb 100644 --- a/docs/src/configuring-zed.md +++ b/docs/src/configuring-zed.md @@ -1,32 +1,26 @@ # Configuring Zed -## Folder-specific settings +Zed is designed to be configured: we want to fit your workflow and preferences exactly. We provide default settings that are designed to be a comfortable starting point for as many people as possible, but we hope you will enjoy tweaking it to make it feel incredible. -Folder-specific settings are used to override Zed's global settings for files within a specific directory in the project panel. To get started, create a `.zed` subdirectory and add a `settings.json` within it. It should be noted that folder-specific settings don't need to live only at a project's root, but can be defined at multiple levels in the project hierarchy. In setups like this, Zed will find the configuration nearest to the file you are working in and apply those settings to it. In most cases, this level of flexibility won't be needed and a single configuration for all files in a project is all that is required; the `Zed > Settings > Open Local Settings` menu action is built for this case. Running this action will look for a `.zed/settings.json` file at the root of the first top-level directory in your project panel. If it does not exist, it will create it. +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). -The following global settings can be overridden with a folder-specific configuration: +## Settings files -- `inline_completions` -- `enable_language_server` -- `ensure_final_newline_on_save` -- `format_on_save` -- `formatter` -- `hard_tabs` -- `languages` -- `preferred_line_length` -- `remove_trailing_whitespace_on_save` -- `soft_wrap` -- `tab_size` -- `show_inline_completions` -- `show_whitespaces` +Your settings file can be opened with `cmd-,` (on macOS) or `ctrl-,` (on Linux). 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. -_See the Global settings section for details about these settings_ +This configuration is merged with any local configuration inside your projects. You can open the project settings by running `zed: Open Local Settings` from the command palette. This will create a `.zed` directory containing`.zed/settings.json`. -## Global settings +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 behaviour of the editor and language tooling. For example you can set `tab_size`, `formatter` etc. but not `theme`, `vim_mode` and similar. -To get started with editing Zed's global settings, open `~/.config/zed/settings.json` via `⌘` + `,`, the command palette (`zed: open settings`), or the `Zed > Settings > Open Settings` application menu item. +The syntax for configuration files is a super-set of JSON that allows `//` comments. -Here are all the currently available settings. +## Default settings + +You can find the default settings for your current Zed by running `zed: Open Default Settings` from the command palette. + +Extensions that provide language servers may also provide default settings for those language servers. + +# Settings ## Active Pane Magnification