1# Configuring supported languages
  2
  3Zed offers powerful customization options for each programming language it supports. This guide will walk you through the various ways you can tailor your coding experience to your preferences and project requirements.
  4
  5Zed's language support is built on two main technologies:
  6
  71. Tree-sitter: This handles syntax highlighting and structure-based features like the outline panel.
  82. Language Server Protocol (LSP): This provides semantic features such as code completion and diagnostics.
  9
 10These components work together to provide Zed's language capabilities.
 11
 12In this guide, we'll cover:
 13
 14- Language-specific settings
 15- File associations
 16- Working with language servers
 17- Formatting and linting configuration
 18- Customizing syntax highlighting and themes
 19- Advanced language features
 20
 21By the end of this guide, you should know how to configure and customize supported languages in Zed.
 22
 23For a comprehensive list of languages supported by Zed and their specific configurations, see our [Supported Languages](./languages.md) page. To go further, you could explore developing your own extensions to add support for additional languages or enhance existing functionality. For more information on creating language extensions, see our [Language Extensions](./extensions/languages.md) guide.
 24
 25## Language-specific Settings
 26
 27Zed allows you to override global settings for individual languages. These custom configurations are defined in your `settings.json` file under the `languages` key.
 28
 29Here's an example of language-specific settings:
 30
 31```json [settings]
 32"languages": {
 33  "Python": {
 34    "tab_size": 4,
 35    "formatter": "language_server",
 36    "format_on_save": "on"
 37  },
 38  "JavaScript": {
 39    "tab_size": 2,
 40    "formatter": {
 41      "external": {
 42        "command": "prettier",
 43        "arguments": ["--stdin-filepath", "{buffer_path}"]
 44      }
 45    }
 46  }
 47}
 48```
 49
 50You can customize a wide range of settings for each language, including:
 51
 52- [`tab_size`](./configuring-zed.md#tab-size): The number of spaces for each indentation level
 53- [`formatter`](./configuring-zed.md#formatter): The tool used for code formatting
 54- [`format_on_save`](./configuring-zed.md#format-on-save): Whether to automatically format code when saving
 55- [`enable_language_server`](./configuring-zed.md#enable-language-server): Toggle language server support
 56- [`hard_tabs`](./configuring-zed.md#hard-tabs): Use tabs instead of spaces for indentation
 57- [`preferred_line_length`](./configuring-zed.md#preferred-line-length): The recommended maximum line length
 58- [`soft_wrap`](./configuring-zed.md#soft-wrap): How to wrap long lines of code
 59- [`show_completions_on_input`](./configuring-zed.md#show-completions-on-input): Whether or not to show completions as you type
 60- [`show_completion_documentation`](./configuring-zed.md#show-completion-documentation): Whether to display inline and alongside documentation for items in the completions menu
 61- [`colorize_brackets`](./configuring-zed.md#colorize-brackets): Whether to use tree-sitter bracket queries to detect and colorize the brackets in the editor (also known as "rainbow brackets")
 62
 63These settings allow you to maintain specific coding styles across different languages and projects.
 64
 65## File Associations
 66
 67Zed automatically detects file types based on their extensions, but you can customize these associations to fit your workflow.
 68
 69To set up custom file associations, use the [`file_types`](./configuring-zed.md#file-types) setting in your `settings.json`:
 70
 71```json [settings]
 72"file_types": {
 73  "C++": ["c"],
 74  "TOML": ["MyLockFile"],
 75  "Dockerfile": ["Dockerfile*"]
 76}
 77```
 78
 79This configuration tells Zed to:
 80
 81- Treat `.c` files as C++ instead of C
 82- Recognize files named "MyLockFile" as TOML
 83- Apply Dockerfile syntax to any file starting with "Dockerfile"
 84
 85You can use glob patterns for more flexible matching, allowing you to handle complex naming conventions in your projects.
 86
 87## Working with Language Servers
 88
 89Language servers are a crucial part of Zed's intelligent coding features, providing capabilities like auto-completion, go-to-definition, and real-time error checking.
 90
 91### What are Language Servers?
 92
 93Language servers implement the Language Server Protocol (LSP), which standardizes communication between the editor and language-specific tools. This allows Zed to support advanced features for multiple programming languages without implementing each feature separately.
 94
 95Some key features provided by language servers include:
 96
 97- Code completion
 98- Error checking and diagnostics
 99- Code navigation (go to definition, find references)
100- Code actions (Rename, extract method)
101- Hover information
102- Workspace symbol search
103
104### Managing Language Servers
105
106Zed simplifies language server management for users:
107
1081. Automatic Download: When you open a file with a matching file type, Zed automatically downloads the appropriate language server. Zed may prompt you to install an extension for known file types.
109
1102. Storage Location:
111
112   - macOS: `~/Library/Application Support/Zed/languages`
113   - Linux: `$XDG_DATA_HOME/zed/languages`, `$FLATPAK_XDG_DATA_HOME/zed/languages`, or `$HOME/.local/share/zed/languages`
114
1153. Automatic Updates: Zed keeps your language servers up-to-date, ensuring you always have the latest features and improvements.
116
117### Choosing Language Servers
118
119Some languages in Zed offer multiple language server options. You might have multiple extensions installed that bundle language servers targeting the same language, potentially leading to overlapping capabilities. To ensure you get the functionality you prefer, Zed allows you to prioritize which language servers are used and in what order.
120
121You can specify your preference using the `language_servers` setting:
122
123```json [settings]
124  "languages": {
125    "PHP": {
126      "language_servers": ["intelephense", "!phpactor", "..."]
127    }
128  }
129```
130
131In this example:
132
133- `intelephense` is set as the primary language server
134- `phpactor` is disabled (note the `!` prefix)
135- `...` expands to the rest of the language servers that are registered for PHP
136
137This configuration allows you to tailor the language server setup to your specific needs, ensuring that you get the most suitable functionality for your development workflow.
138
139### Toolchains
140
141Some language servers need to be configured with a current "toolchain", which is an installation of a specific version of a programming language compiler or/and interpreter, which can possibly include a full set of dependencies of a project.
142An example of what Zed considers a toolchain is a virtual environment in Python.
143Not all languages in Zed support toolchain discovery and selection, but for those that do, you can specify the toolchain from a toolchain picker (via {#action toolchain::Select}). To learn more about toolchains in Zed, see [`toolchains`](./toolchains.md).
144
145### Configuring Language Servers
146
147Many language servers accept custom configuration options. You can set these in the `lsp` section of your `settings.json`:
148
149```json [settings]
150  "lsp": {
151    "rust-analyzer": {
152      "initialization_options": {
153        "check": {
154          "command": "clippy"
155        }
156      }
157    }
158  }
159```
160
161This example configures the Rust Analyzer to use Clippy for additional linting when saving files.
162
163#### Nested objects
164
165When configuring language server options in Zed, it's important to use nested objects rather than dot-delimited strings. This is particularly relevant when working with more complex configurations. Let's look at a real-world example using the TypeScript language server:
166
167Suppose you want to configure the following settings for TypeScript:
168
169- Enable strict null checks
170- Set the target ECMAScript version to ES2020
171
172Here's how you would structure these settings in Zed's `settings.json`:
173
174```json [settings]
175"lsp": {
176  "typescript-language-server": {
177    "initialization_options": {
178      // These are not supported (VSCode dotted style):
179      // "preferences.strictNullChecks": true,
180      // "preferences.target": "ES2020"
181      //
182      // These is correct (nested notation):
183      "preferences": {
184        "strictNullChecks": true,
185        "target": "ES2020"
186      },
187    }
188  }
189}
190```
191
192#### Possible configuration options
193
194Depending on how a particular language server is implemented, they may depend on different configuration options, both specified in the LSP.
195
196- [initializationOptions](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#version_3_17_0)
197
198Sent once during language server startup, requires server's restart to reapply changes.
199
200For example, rust-analyzer and clangd rely on this way of configuring only.
201
202```json [settings]
203  "lsp": {
204    "rust-analyzer": {
205      "initialization_options": {
206        "checkOnSave": false
207      }
208    }
209  }
210```
211
212- [Configuration Request](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_configuration)
213
214May be queried by the server multiple times.
215Most of the servers would rely on this way of configuring only.
216
217```json [settings]
218"lsp": {
219  "tailwindcss-language-server": {
220    "settings": {
221      "tailwindCSS": {
222        "emmetCompletions": true,
223      },
224    }
225  }
226}
227```
228
229Apart of the LSP-related server configuration options, certain servers in Zed allow configuring the way binary is launched by Zed.
230
231Language servers are automatically downloaded or launched if found in your path, if you wish to specify an explicit alternate binary you can specify that in settings:
232
233```json [settings]
234  "lsp": {
235    "rust-analyzer": {
236      "binary": {
237        // Whether to fetch the binary from the internet, or attempt to find locally.
238        "ignore_system_version": false,
239        "path": "/path/to/langserver/bin",
240        "arguments": ["--option", "value"],
241        "env": {
242          "FOO": "BAR"
243        }
244      }
245    }
246  }
247```
248
249### Enabling or Disabling Language Servers
250
251You can toggle language server support globally or per-language:
252
253```json [settings]
254  "languages": {
255    "Markdown": {
256      "enable_language_server": false
257    }
258  }
259```
260
261This disables the language server for Markdown files, which can be useful for performance in large documentation projects. You can configure this globally in your `~/.config/zed/settings.json` or inside a `.zed/settings.json` in your project directory.
262
263## Formatting and Linting
264
265Zed provides support for code formatting and linting to maintain consistent code style and catch potential issues early.
266
267### Configuring Formatters
268
269Zed supports both built-in and external formatters. See [`formatter`](./configuring-zed.md#formatter) docs for more. You can configure formatters globally or per-language in your `settings.json`:
270
271```json [settings]
272"languages": {
273  "JavaScript": {
274    "formatter": {
275      "external": {
276        "command": "prettier",
277        "arguments": ["--stdin-filepath", "{buffer_path}"]
278      }
279    },
280    "format_on_save": "on"
281  },
282  "Rust": {
283    "formatter": "language_server",
284    "format_on_save": "on"
285  }
286}
287```
288
289This example uses Prettier for JavaScript and the language server's formatter for Rust, both set to format on save.
290
291To disable formatting for a specific language:
292
293```json [settings]
294"languages": {
295  "Markdown": {
296    "format_on_save": "off"
297  }
298}
299```
300
301### Setting Up Linters
302
303Linting in Zed is typically handled by language servers. Many language servers allow you to configure linting rules:
304
305```json [settings]
306"lsp": {
307  "eslint": {
308    "settings": {
309      "codeActionOnSave": {
310        "rules": ["import/order"]
311      }
312    }
313  }
314}
315```
316
317This configuration sets up ESLint to organize imports on save for JavaScript files.
318
319To run linter fixes automatically on save:
320
321```json [settings]
322"languages": {
323  "JavaScript": {
324    "formatter": {
325      "code_action": "source.fixAll.eslint"
326    }
327  }
328}
329```
330
331### Integrating Formatting and Linting
332
333Zed allows you to run both formatting and linting on save. Here's an example that uses Prettier for formatting and ESLint for linting JavaScript files:
334
335```json [settings]
336"languages": {
337  "JavaScript": {
338    "formatter": [
339      {
340        "code_action": "source.fixAll.eslint"
341      },
342      {
343        "external": {
344          "command": "prettier",
345          "arguments": ["--stdin-filepath", "{buffer_path}"]
346        }
347      }
348    ],
349    "format_on_save": "on"
350  }
351}
352```
353
354### Troubleshooting
355
356If you encounter issues with formatting or linting:
357
3581. Check Zed's log file for error messages (Use the command palette: `zed: open log`)
3592. Ensure external tools (formatters, linters) are correctly installed and in your PATH
3603. Verify configurations in both Zed settings and language-specific config files (e.g., `.eslintrc`, `.prettierrc`)
361
362## Syntax Highlighting and Themes
363
364Zed offers customization options for syntax highlighting and themes, allowing you to tailor the visual appearance of your code.
365
366### Customizing Syntax Highlighting
367
368Zed uses Tree-sitter grammars for syntax highlighting. Override the default highlighting using the `theme_overrides` setting.
369
370This example makes comments italic and changes the color of strings:
371
372```json [settings]
373"theme_overrides": {
374  "One Dark": {
375    "syntax": {
376      "comment": {
377        "font_style": "italic"
378      },
379      "string": {
380        "color": "#00AA00"
381      }
382    }
383  }
384}
385```
386
387### Selecting and Customizing Themes
388
389Change your theme:
390
3911. Use the theme selector ({#kb theme_selector::Toggle})
3922. Or set it in your `settings.json`:
393
394```json [settings]
395"theme": {
396  "mode": "dark",
397  "dark": "One Dark",
398  "light": "GitHub Light"
399}
400```
401
402Create custom themes by creating a JSON file in `~/.config/zed/themes/`. Zed will automatically detect and make available any themes in this directory.
403
404### Using Theme Extensions
405
406Zed supports theme extensions. Browse and install theme extensions from the Extensions panel ({#kb zed::Extensions}).
407
408To create your own theme extension, refer to the [Developing Theme Extensions](./extensions/themes.md) guide.
409
410## Using Language Server Features
411
412### Inlay Hints
413
414Inlay hints provide additional information inline in your code, such as parameter names or inferred types. Configure inlay hints in your `settings.json`:
415
416```json [settings]
417"inlay_hints": {
418  "enabled": true,
419  "show_type_hints": true,
420  "show_parameter_hints": true,
421  "show_other_hints": true
422}
423```
424
425For language-specific inlay hint settings, refer to the documentation for each language.
426
427### Code Actions
428
429Code actions provide quick fixes and refactoring options. Access code actions using the `editor: Toggle Code Actions` command or by clicking the lightbulb icon that appears next to your cursor when actions are available.
430
431### Go To Definition and References
432
433Use these commands to navigate your codebase:
434
435- `editor: Go to Definition` (<kbd>f12|f12</kbd>)
436- `editor: Go to Type Definition` (<kbd>cmd-f12|ctrl-f12</kbd>)
437- `editor: Find All References` (<kbd>shift-f12|shift-f12</kbd>)
438
439### Rename Symbol
440
441To rename a symbol across your project:
442
4431. Place your cursor on the symbol
4442. Use the `editor: Rename Symbol` command (<kbd>f2|f2</kbd>)
4453. Enter the new name and press Enter
446
447These features depend on the capabilities of the language server for each language.
448
449When renaming a symbol that spans multiple files, Zed will open a preview in a multibuffer. This allows you to review all the changes across your project before applying them. To confirm the rename, simply save the multibuffer. If you decide not to proceed with the rename, you can undo the changes or close the multibuffer without saving.
450
451### Hover Information
452
453Use the `editor: Hover` command to display information about the symbol under the cursor. This often includes type information, documentation, and links to relevant resources.
454
455### Workspace Symbol Search
456
457The `workspace: Open Symbol` command allows you to search for symbols (functions, classes, variables) across your entire project. This is useful for quickly navigating large codebases.
458
459### Code Completion
460
461Zed provides intelligent code completion suggestions as you type. You can manually trigger completion with the `editor: Show Completions` command. Use <kbd>tab|tab</kbd> or <kbd>enter|enter</kbd> to accept suggestions.
462
463### Diagnostics
464
465Language servers provide real-time diagnostics (errors, warnings, hints) as you code. View all diagnostics for your project using the `diagnostics: Toggle` command.