1# Zed Documentation Conventions
2
3This document covers structural conventions for Zed documentation: what to document, how to organize it, and when to create new pages.
4
5For voice, tone, and writing style, see the [brand-voice/](./brand-voice/) directory, which contains:
6
7- `SKILL.md` — Core voice principles and workflow
8- `rubric.md` — 8-point scoring criteria for quality
9- `taboo-phrases.md` — Patterns and phrases to avoid
10- `voice-examples.md` — Before/after transformation examples
11
12---
13
14## What Needs Documentation
15
16### Document
17
18- **New user-facing features** — Anything users interact with directly
19- **New settings or configuration options** — Include the setting key, type, default value, and example
20- **New keybindings or commands** — Use `{#action ...}` and `{#kb ...}` syntax
21- **All actions** — Completeness matters; document every action, not just non-obvious ones
22- **New AI capabilities** — Agent tools, providers, workflows
23- **New providers or integrations** — LLM providers, MCP servers, external agents
24- **New tools** — Agent tools, MCP tools, built-in tools
25- **New UI panels or views** — Any new panel, sidebar, or view users interact with
26- **Public extension APIs** — For extension developers
27- **Breaking changes** — Even if the fix is simple, document what changed
28- **Version-specific behavior changes** — Include version callouts (e.g., "In Zed v0.224.0 and above...")
29
30### Skip
31
32- **Internal refactors** — No user-visible change, no docs
33- **Bug fixes** — Unless the fix reveals that existing docs were wrong
34- **Performance improvements** — Unless user-visible (e.g., startup time)
35- **Test changes** — Never document tests
36- **CI/tooling changes** — Internal infrastructure
37
38---
39
40## Page vs. Section Decisions
41
42### Create a new page when:
43
44- Introducing a **major feature** with multiple sub-features (e.g., Git integration, Vim mode)
45- The topic requires **extensive configuration examples**
46- Users would search for it **by name** (e.g., "Zed terminal", "Zed snippets")
47- It's a **new category** (e.g., a new AI provider type)
48
49### Add to an existing page when:
50
51- Adding a **setting** to a feature that already has a page
52- Adding a **keybinding** to an existing feature
53- The change is a **minor enhancement** to existing functionality
54- It's a **configuration option** for an existing feature
55
56### Examples
57
58| Change | Action |
59| ------------------------------------ | -------------------------------------- |
60| New "Stash" feature for Git | Add section to `git.md` |
61| New "Remote Development" capability | Create `remote-development.md` |
62| New setting `git.inline_blame.delay` | Add to existing Git config section |
63| New AI provider (e.g., "Ollama") | Add section to `llm-providers.md` |
64| New agent tool category | Potentially new page, depends on scope |
65
66---
67
68## Document Structure
69
70### Frontmatter
71
72Every doc page needs YAML frontmatter:
73
74```yaml
75---
76title: Feature Name - Zed
77description: One sentence describing what this page covers. Used in search results.
78---
79```
80
81- `title`: Feature name, optionally with "- Zed" suffix for SEO
82- `description`: Concise summary for search engines and link previews
83
84### Section Ordering
85
861. **Title** (`# Feature Name`) — Clear, scannable
872. **Opening paragraph** — What this is and why you'd use it (1-2 sentences)
883. **Getting Started / Usage** — How to access or enable it
894. **Core functionality** — Main features and workflows
905. **Configuration** — Settings, with JSON examples
916. **Keybindings / Actions** — Reference tables
927. **See Also** — Links to related docs
93
94### Section Depth
95
96- Use `##` for main sections
97- Use `###` for subsections
98- Avoid `####` unless absolutely necessary — if you need it, consider restructuring
99
100### Anchor IDs
101
102Add explicit anchor IDs to sections users might link to directly:
103
104```markdown
105## Getting Started {#getting-started}
106
107### Configuring Models {#configuring-models}
108```
109
110Use anchor IDs when:
111
112- The section is a common reference target
113- You need a stable link that won't break if the heading text changes
114- The heading contains special characters that would create ugly auto-generated anchors
115
116---
117
118## Formatting Conventions
119
120### Code Formatting
121
122Use inline `code` for:
123
124- Setting names: `vim_mode`, `buffer_font_size`
125- Keybindings: `cmd-shift-p`, `ctrl-w h`
126- Commands: `:w`, `:q`
127- File paths: `~/.config/zed/settings.json`
128- Action names: `git::Commit`
129- Values: `true`, `false`, `"eager"`
130
131### Action and Keybinding References
132
133Use Zed's special syntax for dynamic rendering:
134
135- `{#action git::Commit}` — Renders the action name
136- `{#kb git::Commit}` — Renders the keybinding for that action
137
138This ensures keybindings stay accurate if defaults change.
139
140### JSON Examples
141
142Always use the `[settings]` or `[keymap]` annotation:
143
144```json [settings]
145{
146 "vim_mode": true
147}
148```
149
150```json [keymap]
151{
152 "context": "Editor",
153 "bindings": {
154 "ctrl-s": "workspace::Save"
155 }
156}
157```
158
159### Tables
160
161Use tables for:
162
163- Action/keybinding reference lists
164- Setting options with descriptions
165- Feature comparisons
166
167Keep tables scannable — avoid long prose in table cells.
168
169### Paragraphs
170
171- Keep paragraphs short (2-3 sentences max)
172- One idea per paragraph
173- Use bullet lists for multiple related items
174
175### Pronouns
176
177Minimize vague pronouns like "it", "this", and "that". Repeat the noun so readers know exactly what you're referring to.
178
179**Bad:**
180
181> The API creates a token after authentication. It should be stored securely.
182
183**Good:**
184
185> The API creates a token after authentication. The token should be stored securely.
186
187This improves clarity for both human readers and AI systems parsing the documentation.
188
189### Callouts
190
191Use blockquote callouts for tips, notes, and warnings:
192
193```markdown
194> **Note:** This feature requires signing in.
195
196> **Tip:** Hold `cmd` when submitting to automatically follow the agent.
197
198> **Warning:** This action cannot be undone.
199```
200
201### Version-Specific Notes
202
203When behavior differs by version, be explicit:
204
205```markdown
206> **Note:** In Zed v0.224.0 and above, tool approval is controlled by `agent.tool_permissions.default`.
207```
208
209Include the version number and what changed. This helps users on older versions understand why their behavior differs.
210
211---
212
213## Cross-Linking
214
215### Internal Links
216
217Link to other docs using relative paths:
218
219- `[Vim mode](./vim.md)`
220- `[AI configuration](./ai/configuration.md)`
221
222### External Links
223
224- Link to `zed.dev` pages when appropriate
225- Link to upstream documentation (e.g., Tree-sitter, language servers) when explaining integrations
226
227### "See Also" Sections
228
229End pages with related links when helpful:
230
231```markdown
232## See also
233
234- [Agent Panel](./agent-panel.md): Agentic editing with file read/write
235- [Inline Assistant](./inline-assistant.md): Prompt-driven code transformations
236```
237
238---
239
240## Language-Specific Documentation
241
242Language docs in `src/languages/` follow a consistent structure:
243
2441. Language name and brief description
2452. Installation/setup (if needed)
2463. Language server configuration
2474. Formatting configuration
2485. Language-specific settings
2496. Known limitations (if any)
250
251Keep language docs focused on Zed-specific configuration, not general language tutorials.
252
253---
254
255## Settings Documentation
256
257When documenting settings:
258
2591. **Show the Settings Editor (UI) approach first** — Most settings have UI support
2602. **Then show JSON** as "or add to your settings file:"
2613. **State the setting key** in code formatting
2624. **Describe what it does** in one sentence
2635. **Show the type and default** if not obvious
2646. **Provide a complete JSON example**
265
266Example:
267
268> Configure inline blame in Settings ({#kb zed::OpenSettings}) by searching for "inline blame", or add to your settings file:
269>
270> ```json [settings]
271> {
272> "git": {
273> "inline_blame": {
274> "enabled": false
275> }
276> }
277> }
278> ```
279
280For JSON-only settings (complex types without UI support), note this and link to instructions:
281
282> Add the following to your settings file ([how to edit](./configuring-zed.md#settings-files)):
283
284### Settings File Locations
285
286- **macOS/Linux:** `~/.config/zed/settings.json`
287- **Windows:** `%AppData%\Zed\settings.json`
288
289### Keymap File Locations
290
291- **macOS/Linux:** `~/.config/zed/keymap.json`
292- **Windows:** `%AppData%\Zed\keymap.json`
293
294---
295
296## Terminology
297
298Use consistent terminology throughout:
299
300| Use | Instead of |
301| --------------- | -------------------------------------- |
302| folder | directory |
303| project | workspace |
304| Settings Editor | settings UI |
305| command palette | command bar |
306| panel | sidebar (be specific: "Project Panel") |
307
308---
309
310## Formatting Requirements
311
312All documentation must pass **Prettier** formatting (80 character line width):
313
314```sh
315cd docs && npx prettier --check src/
316```
317
318Before any documentation change is considered complete:
319
3201. Run Prettier to format: `cd docs && npx prettier --write src/`
3212. Verify it passes: `cd docs && npx prettier --check src/`
322
323---
324
325## Quality Checklist
326
327Before finalizing documentation:
328
329- [ ] Frontmatter includes `title` and `description`
330- [ ] Opening paragraph explains what and why
331- [ ] Settings show UI first, then JSON examples
332- [ ] Actions use `{#action ...}` and `{#kb ...}` syntax
333- [ ] All actions are documented (completeness matters)
334- [ ] Anchor IDs on sections likely to be linked
335- [ ] Version callouts where behavior differs by release
336- [ ] No orphan pages (linked from somewhere)
337- [ ] Passes Prettier formatting check
338- [ ] Passes brand voice rubric (see `brand-voice/rubric.md`)
339
340---
341
342## Gold Standard Examples
343
344See `../.doc-examples/` for curated examples of well-documented features. Use these as templates when writing new documentation.
345
346---
347
348## Reference
349
350For automation-specific rules (safety constraints, change classification, output formats), see `docs/AGENTS.md`.