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