docs: add Modelines documentation

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>

Author: elmarco

docs/src/SUMMARY.md

@@ -13,6 +13,7 @@
 # Configuration
 
 - [Configuring Zed](./configuring-zed.md)
+  - [Modelines](./modelines.md)
 - [Configuring Languages](./configuring-languages.md)
   - [Toolchains](./toolchains.md)
 - [Key bindings](./key-bindings.md)

docs/src/configuring-zed.md

@@ -43,6 +43,10 @@ For example you can set `tab_size`, `formatter` etc. but not `theme`, `vim_mode`
 
 The syntax for configuration files is a super-set of JSON that allows `//` comments.
 
+## Per-file Settings
+
+Zed has some compatibility support for Emacs and Vim [modelines](./modelines.md), so you can set some settings per-file.
+
 ## Per-release Channel Overrides
 
 Zed reads the same `settings.json` across all release channels (Stable, Preview or Nightly).
@@ -2710,6 +2714,16 @@ Positive `integer` values or `null` for unlimited tabs
 
 `boolean` values
 
+## Modeline Lines
+
+- Description: Number of lines to search for modelines at the beginning and end of files. Modelines contain editor directives (e.g., vim/emacs settings) that configure the editor behavior for specific files. See [Modelines](./modelines.md) for more details on supported modeline variables.
+- Setting: `modeline_lines`
+- Default: `5`
+
+**Options**
+
+Positive `integer` values. Set to `0` to disable modeline parsing.
+
 ## Multi Cursor Modifier
 
 - Description: Determines the modifier to be used to add multiple cursors with the mouse. The open hover link mouse gestures will adapt such that it do not conflict with the multicursor modifier.

docs/src/extensions/languages.md

@@ -27,6 +27,7 @@ line_comments = ["# "]
 - `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.
+- `modeline_aliases` is an array of additional Emacs modes or Vim filetypes to map modeline settings to Zed language.
 - `debuggers` is an array of strings that are used to identify debuggers in the language. When launching a debugger's `New Process Modal`, Zed will order available debuggers by the order of entries in this array.
 
 <!--

docs/src/modelines.md

@@ -0,0 +1,67 @@
+# Modelines
+
+Modelines are special comments at the beginning or end of a file that configure editor settings for that specific file. Zed supports both Vim and Emacs modeline formats, allowing you to specify settings like tab size, indentation style, and file type directly within your files.
+
+## Configuration
+
+Use the [`modeline_lines`](./configuring-zed.md#modeline-lines) setting to control how many lines Zed searches for modelines:
+
+```json [settings]
+{
+  "modeline_lines": 5
+}
+```
+
+Set to `0` to disable modeline parsing entirely.
+
+## Emacs
+
+Zed has some compatibility support for [Emacs file variables](https://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-Variables.html).
+
+Example:
+
+```python
+# -*- mode: python; tab-width: 4; indent-tabs-mode: nil; -*-
+```
+
+### Supported Emacs Variables
+
+| Variable                   | Description                    | Zed Setting                                                           |
+| -------------------------- | ------------------------------ | --------------------------------------------------------------------- |
+| `mode`                     | Major mode/language            | Language detection                                                    |
+| `tab-width`                | Tab display width              | [`tab_size`](./configuring-zed.md#tab-size)                           |
+| `fill-column`              | Line wrap column               | [`preferred_line_length`](./configuring-zed.md#preferred-line-length) |
+| `indent-tabs-mode`         | `nil` for spaces, `t` for tabs | [`hard_tabs`](./configuring-zed.md#hard-tabs)                         |
+| `electric-indent-mode`     | Auto-indentation               | [`auto_indent`](./configuring-zed.md#auto-indent)                     |
+| `require-final-newline`    | Ensure final newline           | [`ensure_final_newline`](./configuring-zed.md#ensure-final-newline)   |
+| `show-trailing-whitespace` | Show trailing whitespace       | [`show_whitespaces`](./configuring-zed.md#show-whitespaces)           |
+
+## Vim
+
+Zed has some compatibility support for [Vim modeline](https://vimhelp.org/options.txt.html#modeline).
+
+Example:
+
+```python
+# vim: set ft=python ts=4 sw=4 et:
+```
+
+### Supported Vim Options
+
+| Option         | Aliases | Description                       | Zed Setting                                                           |
+| -------------- | ------- | --------------------------------- | --------------------------------------------------------------------- |
+| `filetype`     | `ft`    | File type/language                | Language detection                                                    |
+| `tabstop`      | `ts`    | Number of spaces a tab counts for | [`tab_size`](./configuring-zed.md#tab-size)                           |
+| `textwidth`    | `tw`    | Maximum line width                | [`preferred_line_length`](./configuring-zed.md#preferred-line-length) |
+| `expandtab`    | `et`    | Use spaces instead of tabs        | [`hard_tabs`](./configuring-zed.md#hard-tabs)                         |
+| `noexpandtab`  | `noet`  | Use tabs instead of spaces        | [`hard_tabs`](./configuring-zed.md#hard-tabs)                         |
+| `autoindent`   | `ai`    | Enable auto-indentation           | [`auto_indent`](./configuring-zed.md#auto-indent)                     |
+| `noautoindent` | `noai`  | Disable auto-indentation          | [`auto_indent`](./configuring-zed.md#auto-indent)                     |
+| `endofline`    | `eol`   | Ensure final newline              | [`ensure_final_newline`](./configuring-zed.md#ensure-final-newline)   |
+| `noendofline`  | `noeol` | Disable final newline             | [`ensure_final_newline`](./configuring-zed.md#ensure-final-newline)   |
+
+## Notes
+
+- The first kilobyte of a file is searched for modelines.
+- Emacs modelines take precedence over Vim modelines when both are present.
+- Modelines in the first few lines take precedence over those at the end of the file.