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
 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
 60These settings allow you to maintain specific coding styles across different languages and projects.
 61
 62## File Associations
 63
 64Zed automatically detects file types based on their extensions, but you can customize these associations to fit your workflow.
 65
 66To set up custom file associations, use the [`file_types`](./configuring-zed.md#file-types) setting in your `settings.json`:
 67
 68```json
 69"file_types": {
 70  "C++": ["c"],
 71  "TOML": ["MyLockFile"],
 72  "Dockerfile": ["Dockerfile*"]
 73}
 74```
 75
 76This configuration tells Zed to:
 77
 78- Treat `.c` files as C++ instead of C
 79- Recognize files named "MyLockFile" as TOML
 80- Apply Dockerfile syntax to any file starting with "Dockerfile"
 81
 82You can use glob patterns for more flexible matching, allowing you to handle complex naming conventions in your projects.
 83
 84## Working with Language Servers
 85
 86Language servers are a crucial part of Zed's intelligent coding features, providing capabilities like auto-completion, go-to-definition, and real-time error checking.
 87
 88### What are Language Servers?
 89
 90Language 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.
 91
 92Some key features provided by language servers include:
 93
 94- Code completion
 95- Error checking and diagnostics
 96- Code navigation (go to definition, find references)
 97- Code actions (Rename, extract method)
 98- Hover information
 99- Workspace symbol search
100
101### Managing Language Servers
102
103Zed simplifies language server management for users:
104
1051. 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.
106
1072. Storage Location:
108
109   - macOS: `~/Library/Application Support/Zed/languages`
110   - Linux: `$XDG_DATA_HOME/languages`, `$FLATPAK_XDG_DATA_HOME/languages`, or `$HOME/.local/share`
111
1123. Automatic Updates: Zed keeps your language servers up-to-date, ensuring you always have the latest features and improvements.
113
114### Choosing Language Servers
115
116Some 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.
117
118You can specify your preference using the `language_servers` setting:
119
120```json
121  "languages": {
122    "PHP": {
123      "language_servers": ["intelephense", "!phpactor", "..."]
124    }
125  }
126```
127
128In this example:
129
130- `intelephense` is set as the primary language server
131- `phpactor` is disabled (note the `!` prefix)
132- `...` preserves any other default language server settings
133
134This 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.
135
136### Configuring Language Servers
137
138Many language servers accept custom configuration options. You can set these in the `lsp` section of your `settings.json`:
139
140```json
141  "lsp": {
142    "rust-analyzer": {
143      "initialization_options": {
144        "checkOnSave": {
145          "command": "clippy"
146        }
147      }
148    }
149  }
150```
151
152This example configures the Rust Analyzer to use Clippy for additional linting when saving files.
153
154When 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:
155
156Suppose you want to configure the following settings for TypeScript:
157
158- Enable strict null checks
159- Set the target ECMAScript version to ES2020
160- Configure import organization preferences
161
162Here's how you would structure these settings in Zed's `settings.json`:
163
164Here's how you might incorrectly attempt to set these options using dot notation:
165
166```json
167"lsp": {
168  "typescript-language-server": {
169    "initialization_options": {
170      // This is not supported:
171      //   "preferences.strictNullChecks": true,
172      // You express it like this:
173      "preferences": {
174        "strictNullChecks": true
175      }
176    }
177  }
178}
179```
180
181### Enabling or Disabling Language Servers
182
183You can toggle language server support globally or per-language:
184
185```json
186  "languages": {
187    "Markdown": {
188      "enable_language_server": false
189    }
190  }
191```
192
193This disables the language server for Markdown files, which can be useful for performance in large documentation projects. You can configure this globally in your `~/.zed/settings.json` or inside a `.zed/settings.json` in your project directory.
194
195## Formatting and Linting
196
197Zed provides support for code formatting and linting to maintain consistent code style and catch potential issues early.
198
199### Configuring Formatters
200
201Zed supports both built-in and external formatters. Configure formatters globally or per-language in your `settings.json`:
202
203```json
204"languages": {
205  "JavaScript": {
206    "formatter": {
207      "external": {
208        "command": "prettier",
209        "arguments": ["--stdin-filepath", "{buffer_path}"]
210      }
211    },
212    "format_on_save": "on"
213  },
214  "Rust": {
215    "formatter": "language_server",
216    "format_on_save": "on"
217  }
218}
219```
220
221This example uses Prettier for JavaScript and the language server's formatter for Rust, both set to format on save.
222
223To disable formatting for a specific language:
224
225```json
226"languages": {
227  "Markdown": {
228    "format_on_save": "off"
229  }
230}
231```
232
233### Setting Up Linters
234
235Linting in Zed is typically handled by language servers. Many language servers allow you to configure linting rules:
236
237```json
238"lsp": {
239  "eslint": {
240    "settings": {
241      "codeActionOnSave": {
242        "rules": ["import/order"]
243      }
244    }
245  }
246}
247```
248
249This configuration sets up ESLint to organize imports on save for JavaScript files.
250
251To run linter fixes automatically on save:
252
253```json
254"languages": {
255  "JavaScript": {
256    "code_actions_on_format": {
257      "source.fixAll.eslint": true
258    }
259  }
260}
261```
262
263### Integrating Formatting and Linting
264
265Zed 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:
266
267```json
268"languages": {
269  "JavaScript": {
270    "formatter": {
271      "external": {
272        "command": "prettier",
273        "arguments": ["--stdin-filepath", "{buffer_path}"]
274      }
275    },
276    "code_actions_on_format": {
277      "source.fixAll.eslint": true
278    },
279    "format_on_save": "on"
280  }
281}
282```
283
284### Troubleshooting
285
286If you encounter issues with formatting or linting:
287
2881. Check Zed's log file for error messages (Use the command palette: `zed: open log`)
2892. Ensure external tools (formatters, linters) are correctly installed and in your PATH
2903. Verify configurations in both Zed settings and language-specific config files (e.g., `.eslintrc`, `.prettierrc`)
291
292## Syntax Highlighting and Themes
293
294Zed offers customization options for syntax highlighting and themes, allowing you to tailor the visual appearance of your code.
295
296### Customizing Syntax Highlighting
297
298Zed uses Tree-sitter grammars for syntax highlighting. Override the default highlighting using the `experimental.theme_overrides` setting.
299
300This example makes comments italic and changes the color of strings:
301
302```json
303"experimental.theme_overrides": {
304  "syntax": {
305    "comment": {
306      "font_style": "italic"
307    },
308    "string": {
309      "color": "#00AA00"
310    }
311  }
312}
313```
314
315### Selecting and Customizing Themes
316
317Change your theme:
318
3191. Use the theme selector (<kbd>cmd-k cmd-t|ctrl-k ctrl-t</kbd>)
3202. Or set it in your `settings.json`:
321
322```json
323"theme": {
324  "mode": "dark",
325  "dark": "One Dark",
326  "light": "GitHub Light"
327}
328```
329
330Create custom themes by creating a JSON file in `~/.config/zed/themes/`. Zed will automatically detect and make available any themes in this directory.
331
332### Using Theme Extensions
333
334Zed supports theme extensions. Browse and install theme extensions from the Extensions panel (<kbd>cmd-shift-e|ctrl-shift-e</kbd>).
335
336To create your own theme extension, refer to the [Developing Theme Extensions](./extensions/themes.md) guide.
337
338## Using Language Server Features
339
340### Inlay Hints
341
342Inlay hints provide additional information inline in your code, such as parameter names or inferred types. Configure inlay hints in your `settings.json`:
343
344```json
345"inlay_hints": {
346  "enabled": true,
347  "show_type_hints": true,
348  "show_parameter_hints": true,
349  "show_other_hints": true
350}
351```
352
353For language-specific inlay hint settings, refer to the documentation for each language.
354
355### Code Actions
356
357Code 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.
358
359### Go To Definition and References
360
361Use these commands to navigate your codebase:
362
363- `editor: Go to Definition` (<kbd>f12|f12</kbd>)
364- `editor: Go to Type Definition` (<kbd>cmd-f12|ctrl-f12</kbd>)
365- `editor: Find All References` (<kbd>shift-f12|shift-f12</kbd>)
366
367### Rename Symbol
368
369To rename a symbol across your project:
370
3711. Place your cursor on the symbol
3722. Use the `editor: Rename Symbol` command (<kbd>f2|f2</kbd>)
3733. Enter the new name and press Enter
374
375These features depend on the capabilities of the language server for each language.
376
377When 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.
378
379### Hover Information
380
381Use the `editor: Show Hover` command to display information about the symbol under the cursor. This often includes type information, documentation, and links to relevant resources.
382
383### Workspace Symbol Search
384
385The `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.
386
387### Code Completion
388
389Zed 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.
390
391### Diagnostics
392
393Language servers provide real-time diagnostics (errors, warnings, hints) as you code. View all diagnostics for your project using the `diagnostics: Toggle` command.