Language Extensions in Zed: Metadata, Grammars, and Queries

# Language Extensions Language support in Zed has several components: - Language metadata and configuration - Grammar - Queries - Language servers ## Language Metadata Each language supported by Zed must be defined in a subdirectory inside the `languages` directory of your extension. This subdirectory must contain a file called `config.toml` file with the following structure: ```toml name = "My Language" grammar = "my-language" path_suffixes = ["myl"] line_comments = ["# "] ``` - `name` (required) is the human readable name that will show up in the Select Language dropdown. - `grammar` (required) is the name of a grammar. Grammars are registered separately, described below. - `path_suffixes` is an array of file suffixes that should be associated with this language. Unlike `file_types` in settings, this does not support glob patterns. - `line_comments` is an array of strings that are used to identify line comments in the language. This is used for the `editor::ToggleComments` keybind: {#kb editor::ToggleComments} for toggling lines of code. - `tab_size` defines the indentation/tab size used for this language (default is `4`). - `hard_tabs` whether to indent with tabs (`true`) or spaces (`false`, the default). - `first_line_pattern` is a regular expression, that in addition to `path_suffixes` (above) or `file_types` in settings can be used to match files which should use this language. For example Zed uses this to identify Shell Scripts by matching the [shebangs lines](https://github.com/zed-industries/zed/blob/main/crates/languages/src/bash/config.toml) in the first line of a script.  ## Grammar Zed uses the [Tree-sitter](https://tree-sitter.github.io) parsing library to provide built-in language-specific features. There are grammars available for many languages, and you can also [develop your own grammar](https://tree-sitter.github.io/tree-sitter/creating-parsers#writing-the-grammar). A growing list of Zed features are built using pattern matching over syntax trees with Tree-sitter queries. As mentioned above, every language that is defined in an extension must specify the name of a Tree-sitter grammar that is used for parsing. These grammars are then registered separately in extensions' `extension.toml` file, like this: ```toml [grammars.gleam] repository = "https://github.com/gleam-lang/tree-sitter-gleam" rev = "58b7cac8fc14c92b0677c542610d8738c373fa81" ``` The `repository` field must specify a repository where the Tree-sitter grammar should be loaded from, and the `rev` field must contain a Git revision to use, such as the SHA of a Git commit. If you're developing an extension locally and want to load a grammar from the local filesystem, you can use a `file://` URL for `repository`. An extension can provide multiple grammars by referencing multiple tree-sitter repositories. ## Tree-sitter Queries Zed uses the syntax tree produced by the [Tree-sitter](https://tree-sitter.github.io) query language to implement several features: - Syntax highlighting - Bracket matching - Code outline/structure - Auto-indentation - Code injections - Syntax overrides - Text redactions - Runnable code detection - Selecting classes, functions, etc. The following sections elaborate on how [Tree-sitter queries](https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax) enable these features in Zed, using [JSON syntax](https://www.json.org/json-en.html) as a guiding example. ### Syntax highlighting In Tree-sitter, the `highlights.scm` file defines syntax highlighting rules for a particular syntax.

This section describes how language support is implemented in Zed through language extensions. It covers language metadata configuration (config.toml), which specifies the language name, grammar, file suffixes, and line comments. It also explains how Zed uses Tree-sitter grammars for parsing and how they are registered in the extension.toml file. Finally, it elaborates on how Tree-sitter queries enable several features like syntax highlighting.