Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.
docs: Document language auto-indentation rules (#63009)
Smit Barmase10b2925e7c44
diff --git a/docs/src/extensions/languages.md b/docs/src/extensions/languages.mdindex 59f20d16de8..cc3be060496 100644--- a/docs/src/extensions/languages.md+++ b/docs/src/extensions/languages.md@@ -44,7 +44,6 @@ TBD: Document `language_name/config.toml` keys- opt_into_language_servers- code_fence_block_name- scope_opt_in_language_servers-- increase_indent_pattern, decrease_indent_pattern- collapsed_placeholder- auto_indent_on_paste, auto_indent_using_last_non_empty_line- overrides: `[overrides.element]`, `[overrides.string]`@@ -212,19 +211,96 @@ This query captures object keys for the outline structure.The `indents.scm` file defines indentation rules.-Here's an example from an `indents.scm` file for JSON:+#### Indenting and outdenting based on syntax++| Capture | Description |+| -------- | ---------------------------------------------------------------------- |+| @indent | Defines an indentation range using the captured node |+| @start | Moves the start of an `@indent` range to the end of the captured node |+| @end | Moves the end of an `@indent` range to the start of the captured node |+| @outdent | Ends the innermost indentation range at the start of the captured node |++For example, to indent all of an `if_statement` node's contents:```scheme-(array "]" @end) @indent-(object "}" @end) @indent+(if_statement) @indent```-This query marks the end of arrays and objects for indentation purposes.+The indentation range runs from the start of the node to its end.++An HTML element includes its opening and closing tags. To indent only the+content between them:++```scheme+(element+ (start_tag) @start ; Begin indentation after the opening tag+ (end_tag)? @end) @indent ; End indentation before the closing tag+```++A subsequent case label must outdent from the preceding case body so that+sibling labels stay aligned:++```scheme+(compound_statement+ (case_statement+ ":" @start) ; Begin indenting the case body+ "}" @end) @indent++(compound_statement+ (case_statement)+ (case_statement) @outdent) ; Align subsequent case labels+```++#### Indenting and outdenting based on line patterns++Use these `config.toml` options for indentation rules that match line contents+instead of syntax nodes:++| Option | Description |+| -------------------------- | ------------------------------------------------------------------------ |+| `increase_indent_pattern` | A matching line indents the following line by one level |+| `decrease_indent_pattern` | A matching line outdents by one level without considering syntax context |+| `decrease_indent_patterns` | A matching line aligns with an allowed earlier syntax construct |++For example, to indent after a line ending in `:`:++```toml+increase_indent_pattern = ":\\s*$"+```++For example, to outdent lines beginning with `end`:++```toml+decrease_indent_pattern = "^\\s*end\\b"+```++#### Aligning clauses with related blocks++Use `decrease_indent_patterns` when a line should align with a related block+instead of always moving left by one level. In `indents.scm`, mark the block+start with a named `@start.<name>` capture:++```scheme+(if_statement) @start.if+```++In `config.toml`, list the capture suffix in `valid_after`:++```toml+decrease_indent_patterns = [+ { pattern = "^\\s*else\\b", valid_after = ["if"] },+]+```++A line beginning with `else` aligns with the most recent `@start.if` at the same+or a lower indentation level. If Zed finds no matching block, it leaves the+indentation unchanged.++Named captures such as `@start.if` mark blocks for these rules. Unlike+`@start`, they do not change an `@indent` range.-| Capture | Description |-| ------- | -------------------------------------------------- |-| @end | Captures closing brackets and braces |-| @indent | Captures entire arrays and objects for indentation |+Zed checks rules in order and stops after the first matching `pattern`. Put+more specific patterns before overlapping general patterns.### Code injections