Zed Documentation Conventions

This document covers structural conventions for Zed documentation: what to document, how to organize it, and when to create new pages.

For voice, tone, and writing style, see the brand-voice/ directory, which contains:

• SKILL.md — Core voice principles and workflow
• rubric.md — 8-point scoring criteria for quality
• taboo-phrases.md — Patterns and phrases to avoid
• voice-examples.md — Before/after transformation examples

What Needs Documentation

Document

• New user-facing features — Anything users interact with directly
• New settings or configuration options — Include the setting key, type, default value, and example
• New keybindings or commands — Use {#action ...} and {#kb ...} syntax
• All actions — Completeness matters; document every action, not just non-obvious ones
• New AI capabilities — Agent tools, providers, workflows
• New providers or integrations — LLM providers, MCP servers, external agents
• New tools — Agent tools, MCP tools, built-in tools
• New UI panels or views — Any new panel, sidebar, or view users interact with
• Public extension APIs — For extension developers
• Breaking changes — Even if the fix is simple, document what changed
• Version-specific behavior changes — Include version callouts (e.g., "In Zed v0.224.0 and above...")

Skip

• Internal refactors — No user-visible change, no docs
• Bug fixes — Unless the fix reveals that existing docs were wrong
• Performance improvements — Unless user-visible (e.g., startup time)
• Test changes — Never document tests
• CI/tooling changes — Internal infrastructure

Page vs. Section Decisions

Create a new page when:

• Introducing a major feature with multiple sub-features (e.g., Git integration, Vim mode)
• The topic requires extensive configuration examples
• Users would search for it by name (e.g., "Zed terminal", "Zed snippets")
• It's a new category (e.g., a new AI provider type)

Add to an existing page when:

• Adding a setting to a feature that already has a page
• Adding a keybinding to an existing feature
• The change is a minor enhancement to existing functionality
• It's a configuration option for an existing feature

Examples

Document Structure

Frontmatter

Every doc page needs YAML frontmatter:

---
title: Feature Name - Zed
description: One sentence describing what this page covers. Used in search results.
---

• title: Feature name, optionally with "- Zed" suffix for SEO
• description: Concise summary for search engines and link previews
• Keep frontmatter values as simple single-line key: value entries (no multiline values, no quotes) for compatibility with the docs postprocessor

Frontmatter SEO Guidelines

• Choose one primary keyword/intent phrase for each page
• Write unique title values that clearly state the page topic and target user intent; aim for ~50-60 characters
• Write description values that summarize what the reader can do on the page; aim for ~140-160 characters
• Use the primary keyword naturally in the title and page body at least once (usually in the opening paragraph); avoid keyword stuffing

Section Ordering

1. Title (# Feature Name) — Clear, scannable
2. Opening paragraph — What this is and why you'd use it (1-2 sentences)
3. Getting Started / Usage — How to access or enable it
4. Core functionality — Main features and workflows
5. Configuration — Settings, with JSON examples
6. Keybindings / Actions — Reference tables
7. See Also — Links to related docs

Section Depth

• Use ## for main sections
• Use ### for subsections
• Avoid #### unless absolutely necessary — if you need it, consider restructuring

Anchor IDs

Add explicit anchor IDs to sections users might link to directly:

## Getting Started {#getting-started}

### Configuring Models {#configuring-models}

Use anchor IDs when:

• The section is a common reference target
• You need a stable link that won't break if the heading text changes
• The heading contains special characters that would create ugly auto-generated anchors

Formatting Conventions

Code Formatting

Use inline code for:

• Setting names: vim_mode, buffer_font_size
• Keybindings: cmd-shift-p, ctrl-w h
• Commands: :w, :q
• File paths: ~/.config/zed/settings.json
• Action names: git::Commit
• Values: true, false, "eager"

Action and Keybinding References

Use Zed's special syntax for dynamic rendering:

• {#action git::Commit} — Renders the action name
• {#kb git::Commit} — Renders the keybinding for that action

This ensures keybindings stay accurate if defaults change.

JSON Examples

Always use the [settings] or [keymap] annotation:

{
  "vim_mode": true
}

{
  "context": "Editor",
  "bindings": {
    "ctrl-s": "workspace::Save"
  }
}

Tables

Use tables for:

• Action/keybinding reference lists
• Setting options with descriptions
• Feature comparisons

Keep tables scannable — avoid long prose in table cells.

Paragraphs

• Keep paragraphs short (2-3 sentences max)
• One idea per paragraph
• Use bullet lists for multiple related items

Pronouns

Minimize vague pronouns like "it", "this", and "that". Repeat the noun so readers know exactly what you're referring to.

Bad:

The API creates a token after authentication. It should be stored securely.

Good:

The API creates a token after authentication. The token should be stored securely.

This improves clarity for both human readers and AI systems parsing the documentation.

Callouts

Use blockquote callouts for tips, notes, and warnings:

> **Note:** This feature requires signing in.

> **Tip:** Hold `cmd` when submitting to automatically follow the agent.

> **Warning:** This action cannot be undone.

Version-Specific Notes

When behavior differs by version, be explicit:

> **Note:** In Zed v0.224.0 and above, tool approval is controlled by `agent.tool_permissions.default`.

Include the version number and what changed. This helps users on older versions understand why their behavior differs.

Cross-Linking

Internal Links

Link to other docs using relative paths:

• [Vim mode](./vim.md)
• [AI configuration](./ai/configuration.md)

External Links

• Link to zed.dev pages when appropriate
• Link to upstream documentation (e.g., Tree-sitter, language servers) when explaining integrations

"See Also" Sections

End pages with related links when helpful:

## See also

- [Agent Panel](./agent-panel.md): Agentic editing with file read/write
- [Inline Assistant](./inline-assistant.md): Prompt-driven code transformations

SEO Linking Guidelines

• Ensure each page is reachable from at least one other docs page (no orphan pages)
• For non-reference pages, include at least 3 internal links to related docs when possible
• Reference pages (for example, docs/src/reference/*) can use fewer links when extra links would add noise
• Add links to closely related docs where they help users complete the next task
• Use descriptive link text that tells users what they will get on the linked page
• For main feature pages with a matching marketing page, include a relevant zed.dev marketing link in addition to docs links

Language-Specific Documentation

Language docs in src/languages/ follow a consistent structure:

1. Language name and brief description
2. Installation/setup (if needed)
3. Language server configuration
4. Formatting configuration
5. Language-specific settings
6. Known limitations (if any)

Keep language docs focused on Zed-specific configuration, not general language tutorials.

Settings Documentation

When documenting settings:

1. Show the Settings Editor (UI) approach first — Most settings have UI support
2. Then show JSON as "or add to your settings file:"
3. State the setting key in code formatting
4. Describe what it does in one sentence
5. Show the type and default if not obvious
6. Provide a complete JSON example

Example:

Configure inline blame in Settings ({#kb zed::OpenSettings}) by searching for "inline blame", or add to your settings file:

jsonCopy

{
  "git": {
    "inline_blame": {
      "enabled": false
    }
  }
}

For JSON-only settings (complex types without UI support), note this and link to instructions:

Add the following to your settings file (how to edit):

Settings File Locations

• macOS/Linux: ~/.config/zed/settings.json
• Windows: %AppData%\Zed\settings.json

Keymap File Locations

• macOS/Linux: ~/.config/zed/keymap.json
• Windows: %AppData%\Zed\keymap.json

Terminology

Use consistent terminology throughout:

Formatting Requirements

All documentation must pass Prettier formatting (80 character line width):

cd docs && npx prettier --check src/

Before any documentation change is considered complete:

1. Run Prettier to format: cd docs && npx prettier --write src/
2. Verify it passes: cd docs && npx prettier --check src/

Quality Checklist

Before finalizing documentation:

• Frontmatter includes title and description
• Page has a clear primary keyword/intent phrase
• Primary keyword appears naturally in the page body (no keyword stuffing)
• Opening paragraph explains what and why
• Settings show UI first, then JSON examples
• Actions use {#action ...} and {#kb ...} syntax
• All actions are documented (completeness matters)
• Anchor IDs on sections likely to be linked
• Version callouts where behavior differs by release
• No orphan pages (linked from somewhere)
• Non-reference pages include at least 3 useful internal docs links
• Main feature pages include a relevant zed.dev marketing link
• Passes Prettier formatting check
• Passes brand voice rubric (see brand-voice/rubric.md)

Gold Standard Examples

See ../.doc-examples/ for curated examples of well-documented features. Use these as templates when writing new documentation.

Reference

For automation-specific rules (safety constraints, change classification, output formats), see docs/AGENTS.md.