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- Keep frontmatter values as simple single-line `key: value` entries (no
84 multiline values, no quotes) for compatibility with the docs postprocessor
85
86#### Frontmatter SEO Guidelines
87
88- Choose one primary keyword/intent phrase for each page
89- Write unique `title` values that clearly state the page topic and target user
90 intent; aim for ~50-60 characters
91- Write `description` values that summarize what the reader can do on the page;
92 aim for ~140-160 characters
93- Use the primary keyword naturally in the `title` and page body at least once
94 (usually in the opening paragraph); avoid keyword stuffing
95
96### Section Ordering
97
981. **Title** (`# Feature Name`) — Clear, scannable
992. **Opening paragraph** — What this is and why you'd use it (1-2 sentences)
1003. **Getting Started / Usage** — How to access or enable it
1014. **Core functionality** — Main features and workflows
1025. **Configuration** — Settings, with JSON examples
1036. **Keybindings / Actions** — Reference tables
1047. **See Also** — Links to related docs
105
106### Section Depth
107
108- Use `##` for main sections
109- Use `###` for subsections
110- Avoid `####` unless absolutely necessary — if you need it, consider restructuring
111
112### Anchor IDs
113
114Add explicit anchor IDs to sections users might link to directly:
115
116```markdown
117## Getting Started {#getting-started}
118
119### Configuring Models {#configuring-models}
120```
121
122Use anchor IDs when:
123
124- The section is a common reference target
125- You need a stable link that won't break if the heading text changes
126- The heading contains special characters that would create ugly auto-generated anchors
127
128---
129
130## Formatting Conventions
131
132### Code Formatting
133
134Use inline `code` for:
135
136- Setting names: `vim_mode`, `buffer_font_size`
137- Keybindings: `cmd-shift-p`, `ctrl-w h`
138- Commands: `:w`, `:q`
139- File paths: `~/.config/zed/settings.json`
140- Action names: `git::Commit`
141- Values: `true`, `false`, `"eager"`
142
143### Action and Keybinding References
144
145Use Zed's special syntax for dynamic rendering:
146
147- `{#action git::Commit}` — Renders the action name
148- `{#kb git::Commit}` — Renders the keybinding for that action
149
150This ensures keybindings stay accurate if defaults change.
151
152### JSON Examples
153
154Always use the `[settings]` or `[keymap]` annotation:
155
156```json [settings]
157{
158 "vim_mode": true
159}
160```
161
162```json [keymap]
163{
164 "context": "Editor",
165 "bindings": {
166 "ctrl-s": "workspace::Save"
167 }
168}
169```
170
171### Tables
172
173Use tables for:
174
175- Action/keybinding reference lists
176- Setting options with descriptions
177- Feature comparisons
178
179Keep tables scannable — avoid long prose in table cells.
180
181### Paragraphs
182
183- Keep paragraphs short (2-3 sentences max)
184- One idea per paragraph
185- Use bullet lists for multiple related items
186
187### Pronouns
188
189Minimize vague pronouns like "it", "this", and "that". Repeat the noun so readers know exactly what you're referring to.
190
191**Bad:**
192
193> The API creates a token after authentication. It should be stored securely.
194
195**Good:**
196
197> The API creates a token after authentication. The token should be stored securely.
198
199This improves clarity for both human readers and AI systems parsing the documentation.
200
201### Callouts
202
203Use blockquote callouts for tips, notes, and warnings:
204
205```markdown
206> **Note:** This feature requires signing in.
207
208> **Tip:** Hold `cmd` when submitting to automatically follow the agent.
209
210> **Warning:** This action cannot be undone.
211```
212
213### Version-Specific Notes
214
215When behavior differs by version, be explicit:
216
217```markdown
218> **Note:** In Zed v0.224.0 and above, tool approval is controlled by `agent.tool_permissions.default`.
219```
220
221Include the version number and what changed. This helps users on older versions understand why their behavior differs.
222
223---
224
225## Cross-Linking
226
227### Internal Links
228
229Link to other docs using relative paths:
230
231- `[Vim mode](./vim.md)`
232- `[AI configuration](./ai/configuration.md)`
233
234### External Links
235
236- Link to `zed.dev` pages when appropriate
237- Link to upstream documentation (e.g., Tree-sitter, language servers) when explaining integrations
238
239### "See Also" Sections
240
241End pages with related links when helpful:
242
243```markdown
244## See also
245
246- [Agent Panel](./agent-panel.md): Agentic editing with file read/write
247- [Inline Assistant](./inline-assistant.md): Prompt-driven code transformations
248```
249
250### SEO Linking Guidelines
251
252- Ensure each page is reachable from at least one other docs page (no orphan
253 pages)
254- For non-reference pages, include at least 3 internal links to related docs
255 when possible
256- Reference pages (for example, `docs/src/reference/*`) can use fewer links when
257 extra links would add noise
258- Add links to closely related docs where they help users complete the next task
259- Use descriptive link text that tells users what they will get on the linked
260 page
261- For main feature pages with a matching marketing page, include a relevant
262 `zed.dev` marketing link in addition to docs links
263
264---
265
266## Language-Specific Documentation
267
268Language docs in `src/languages/` follow a consistent structure:
269
2701. Language name and brief description
2712. Installation/setup (if needed)
2723. Language server configuration
2734. Formatting configuration
2745. Language-specific settings
2756. Known limitations (if any)
276
277Keep language docs focused on Zed-specific configuration, not general language tutorials.
278
279---
280
281## Settings Documentation
282
283When documenting settings:
284
2851. **Show the Settings Editor (UI) approach first** — Most settings have UI support
2862. **Then show JSON** as "or add to your settings file:"
2873. **State the setting key** in code formatting
2884. **Describe what it does** in one sentence
2895. **Show the type and default** if not obvious
2906. **Provide a complete JSON example**
291
292Example:
293
294> Configure inline blame in Settings ({#kb zed::OpenSettings}) by searching for "inline blame", or add to your settings file:
295>
296> ```json [settings]
297> {
298> "git": {
299> "inline_blame": {
300> "enabled": false
301> }
302> }
303> }
304> ```
305
306For JSON-only settings (complex types without UI support), note this and link to instructions:
307
308> Add the following to your settings file ([how to edit](./configuring-zed.md#settings-files)):
309
310### Settings File Locations
311
312- **macOS/Linux:** `~/.config/zed/settings.json`
313- **Windows:** `%AppData%\Zed\settings.json`
314
315### Keymap File Locations
316
317- **macOS/Linux:** `~/.config/zed/keymap.json`
318- **Windows:** `%AppData%\Zed\keymap.json`
319
320---
321
322## Terminology
323
324Use consistent terminology throughout:
325
326| Use | Instead of |
327| --------------- | -------------------------------------- |
328| folder | directory |
329| project | workspace |
330| Settings Editor | settings UI |
331| command palette | command bar |
332| panel | sidebar (be specific: "Project Panel") |
333
334---
335
336## Formatting Requirements
337
338All documentation must pass **Prettier** formatting (80 character line width):
339
340```sh
341cd docs && npx prettier --check src/
342```
343
344Before any documentation change is considered complete:
345
3461. Run Prettier to format: `cd docs && npx prettier --write src/`
3472. Verify it passes: `cd docs && npx prettier --check src/`
348
349---
350
351## Quality Checklist
352
353Before finalizing documentation:
354
355- [ ] Frontmatter includes `title` and `description`
356- [ ] Page has a clear primary keyword/intent phrase
357- [ ] Primary keyword appears naturally in the page body (no keyword stuffing)
358- [ ] Opening paragraph explains what and why
359- [ ] Settings show UI first, then JSON examples
360- [ ] Actions use `{#action ...}` and `{#kb ...}` syntax
361- [ ] All actions are documented (completeness matters)
362- [ ] Anchor IDs on sections likely to be linked
363- [ ] Version callouts where behavior differs by release
364- [ ] No orphan pages (linked from somewhere)
365- [ ] Non-reference pages include at least 3 useful internal docs links
366- [ ] Main feature pages include a relevant `zed.dev` marketing link
367- [ ] Passes Prettier formatting check
368- [ ] Passes brand voice rubric (see `brand-voice/rubric.md`)
369
370---
371
372## Gold Standard Examples
373
374See `../.doc-examples/` for curated examples of well-documented features. Use these as templates when writing new documentation.
375
376---
377
378## Reference
379
380For automation-specific rules (safety constraints, change classification, output formats), see `docs/AGENTS.md`.