## Summary Closes #66715 It's a follow-up of #45939 ## Testing This PR includes two commits. The first commit only removes CLAUDE.md and GEMINI.md, and the second involves changes to [dangerfile.ts](https://github.com/zed-industries/zed/blob/main/script/danger/dangerfile.ts). Reset the second if not favored. ## Self-review - [x] I've reviewed my diff for quality, security, reliability, and performance. - [x] UI changes follow the [checklist](https://zed.dev/docs/development/ui-checklist). - [x] Tests cover the new or changed behavior. Release Notes: - N/A --------- Co-authored-by: Smit Barmase <heysmitbarmase@gmail.com>
17 KiB
Zed Documentation Guidelines
Voice and Tone
Core Principles
- Practical over promotional: Focus on what users can do, not on selling Zed. Avoid marketing language like "powerful," "revolutionary," or "best-in-class."
- Honest about limitations: When Zed lacks a feature or doesn't match another tool's depth, say so directly. Pair limitations with workarounds or alternative workflows.
- Direct and concise: Use short sentences. Get to the point. Developers are scanning, not reading novels.
- Second person: Address the reader as "you." Avoid "the user" or "one."
- Present tense: "Zed opens the file" not "Zed will open the file."
What to Avoid
- Superlatives without substance ("incredibly fast," "seamlessly integrated")
- Hedging language ("simply," "just," "easily")—if something is simple, the instructions will show it
- Apologetic tone for missing features—state the limitation and move on
- Comparisons that disparage other tools—be factual, not competitive
- Meta-commentary about honesty ("the honest take is...", "to be frank...", "honestly...")—let honesty show through frank assessments, not announcements
- LLM-isms and filler words ("entirely," "certainly,", "deeply," "definitely," "actually")—these add nothing
Content Structure
Page Organization
- Start with the goal: Open with what the reader will accomplish, not background
- Front-load the action: Put the most common task first, edge cases later
- Use headers liberally: Readers scan; headers help them find what they need
- End with "what's next": Link to related docs or logical next steps
Section Patterns
For how-to content:
- Brief context (1-2 sentences max)
- Steps or instructions
- Example (code block or screenshot reference)
- Tips or gotchas (if any)
For reference content:
- What it is (definition)
- How to access/configure it
- Options/parameters table
- Examples
Formatting Conventions
Keybindings
- Use backticks for key combinations:
Cmd+Shift+P - Show both macOS and Linux/Windows when they differ:
Cmd+,(macOS) orCtrl+,(Linux/Windows) - Use
+to join simultaneous keys, space for sequences:Cmd+K Cmd+C
Code and Settings
- Inline code for setting names, file paths, commands:
format_on_save,.zed/settings.json,zed . - Code blocks for JSON config, multi-line commands, or file contents
- Always show complete, working examples—not fragments
Terminal Commands
Use sh code blocks for terminal commands, not plain backticks:
brew install --cask zed
Not:
brew install --cask zed
For single inline commands in prose, backticks are fine: zed .
Tables
Use tables for:
- Keybinding comparisons between editors
- Settings mappings (e.g., VS Code → Zed)
- Feature comparisons with clear columns
Format:
| Action | Shortcut | Notes |
| --- | --- | --- |
| Open File | `Cmd+O` | Works from any context |
Tips and Notes
Use blockquote format with bold label:
> **Tip:** Practical advice that helps bridge gaps or saves time.
Reserve tips for genuinely useful information, not padding.
Writing Guidelines
Settings Documentation
- Settings Editor first: Show how to find and change settings in the UI before showing JSON
- JSON as secondary: Present JSON examples as "Or add this to your settings.json" for users who prefer direct editing
- Complete examples: Include the full JSON structure, not just the value
Migration Guides
- Jobs to be done: Frame around tasks ("How do I search files?") not features ("File Search Feature")
- Acknowledge the source: Respect that users have muscle memory and preferences from their previous editor
- Keybindings tables: Essential for migration docs—show what maps, what's different, what's missing
- Trade-offs section: Be explicit about what the user gains and loses in the switch
Feature Documentation
- Start with the default: Document the out-of-box experience first
- Configuration options: Group related settings together
- Cross-link generously: Link to related features, settings reference, and relevant guides
Terminology
| Use | Instead of |
|---|---|
| folder | directory (in user-facing text) |
| project | workspace (Zed doesn't have workspaces) |
| Settings Editor | settings UI, preferences |
| command palette | command bar, action search |
| language server | LSP (spell out first use, then LSP is fine) |
| panel | tool window, sidebar (be specific: "Project Panel," "Terminal Panel") |
Examples
Good: Direct and actionable
To format on save, open the Settings Editor (`Cmd+,`) and search for `format_on_save`. Set it to `on`.
Or add this to your settings.json:
{
"format_on_save": "on"
}
Bad: Wordy and promotional
Zed provides a powerful and seamless formatting experience. Simply navigate to the settings and you'll find the format_on_save option which enables Zed's incredible auto-formatting capabilities.
Good: Honest about limitations
Zed doesn't index your project like IntelliJ does. You open a folder and start working immediately—no waiting. The trade-off: cross-project analysis relies on language servers, which may not go as deep.
**How to adapt:**
- Use `Cmd+Shift+F` for project-wide text search
- Use `Cmd+O` for symbol search (powered by your language server)
Bad: Defensive or dismissive
While some users might miss indexing, Zed's approach is actually better because it's faster.
Pull request hygiene
- Include a
Release Notes:section as the final section in the PR body. - For docs-only PRs, use exactly:
Release Notes:
- N/A
Documentation Automation Agent Guidelines
This file governs automated documentation updates triggered by code changes. All automation phases must comply with these rules.
Documentation System
This documentation uses mdBook (https://rust-lang.github.io/mdBook/).
Key Files
docs/src/SUMMARY.md: Table of contents following mdBook format (https://rust-lang.github.io/mdBook/format/summary.html)docs/book.toml: mdBook configurationdocs/.prettierrc: Prettier config (80 char line width)
SUMMARY.md Format
The SUMMARY.md file defines the book structure. Format rules:
- Chapter titles are links:
[Title](./path/to/file.md) - Nesting via indentation (2 spaces per level)
- Separators:
---for horizontal rules between sections - Draft chapters:
[Title]()(empty parens, not yet written)
Example:
# Section Title
- [Chapter](./chapter.md)
- [Nested Chapter](./nested.md)
---
# Another Section
Custom Preprocessor
The docs use a custom preprocessor (docs_preprocessor) that expands special commands:
| Syntax | Purpose | Example |
|---|---|---|
| {#kb action::ActionName} | Keybinding for action | {#kb agent::ToggleFocus} |
| {#action agent::ActionName} | Action reference (renders as command) | {#action agent::OpenSettings} |
Rules:
- Always use preprocessor syntax for keybindings instead of hardcoding
- Action names use
snake_casein the namespace,PascalCasefor the action - Common namespaces:
agent::,editor::,assistant::,vim::
Formatting Requirements
All documentation must pass Prettier formatting:
cd docs && npx prettier --check src/
Before any documentation change is considered complete:
- Run Prettier to format:
cd docs && npx prettier --write src/ - Verify it passes:
cd docs && npx prettier --check src/
Prettier config: 80 character line width (docs/.prettierrc)
Section Anchors
Use {#anchor-id} syntax for linkable section headers:
## Getting Started {#getting-started}
### Custom Models {#anthropic-custom-models}
Anchor IDs should be:
- Lowercase with hyphens
- Unique within the page
- Descriptive (can include parent context like
anthropic-custom-models)
Code Block Annotations
Use annotations after the language identifier to indicate file context:
\`\`\`json [settings]
{
"agent": { ... }
}
\`\`\`
\`\`\`json [keymap]
[
{ "bindings": { ... } }
]
\`\`\`
Valid annotations: [settings] (for settings.json), [keymap] (for keymap.json)
Blockquote Formatting
Use bold labels for callouts:
> **Note:** Important information the user should know.
> **Tip:** Helpful advice that saves time or improves workflow.
> **Warn:** Caution about potential issues or gotchas.
Image References
Images are hosted externally. Reference format:

Cross-Linking
- Relative links for same-directory:
[Agent Panel](./agent-panel.md) - With anchors:
[Custom Models](./llm-providers.md#anthropic-custom-models) - Parent directory:
[Telemetry](../telemetry.md)
Voice and Tone
Core Principles
- Practical over promotional: Focus on what users can do, not on selling Zed. Avoid marketing language like "powerful," "revolutionary," or "best-in-class."
- Honest about limitations: When Zed lacks a feature or doesn't match another tool's depth, say so directly. Pair limitations with workarounds or alternative workflows.
- Direct and concise: Use short sentences. Get to the point. Developers are scanning, not reading novels.
- Second person: Address the reader as "you." Avoid "the user" or "one."
- Present tense: "Zed opens the file" not "Zed will open the file."
What to Avoid
- Superlatives without substance ("incredibly fast," "seamlessly integrated")
- Hedging language ("simply," "just," "easily")—if something is simple, the instructions will show it
- Apologetic tone for missing features—state the limitation and move on
- Comparisons that disparage other tools—be factual, not competitive
- Lots of use of em or en dashes.
Examples of Good Copy
Good: Direct and actionable
To format on save, open the Settings Editor (`Cmd+,`) and search for `format_on_save`. Set it to `on`.
Or add this to your settings.json:
{
"format_on_save": "on"
}
Bad: Wordy and promotional
Zed provides a powerful and seamless formatting experience. Simply navigate to the settings and you'll find the format_on_save option which enables Zed's incredible auto-formatting capabilities.
Good: Honest about limitations
Zed doesn't index your project like IntelliJ does. You open a folder and start working immediately—no waiting. The trade-off: cross-project analysis relies on language servers, which may not go as deep.
**How to adapt:**
- Use `Cmd+Shift+F` for project-wide text search
- Use `Cmd+O` for symbol search (powered by your language server)
Bad: Defensive or dismissive
While some users might miss indexing, Zed's approach is actually better because it's faster.
Scope
In-Scope Documentation
- All Markdown files in
docs/src/ docs/src/SUMMARY.md(mdBook table of contents)- Language-specific docs in
docs/src/languages/ - Feature docs (AI, extensions, configuration, etc.)
Out-of-Scope (Do Not Modify)
CHANGELOG.md,CONTRIBUTING.md,README.mdat repo root- Inline code comments and rustdoc
CLAUDE.md,GEMINI.md, or other AI instruction files- Build configuration (
book.toml, theme files,docs_preprocessor) - Any file outside
docs/src/
Page Structure Patterns
Standard Page Layout
Most documentation pages follow this structure:
- Title (H1) - Single sentence or phrase
- Overview/Introduction - 1-3 paragraphs explaining what this is
- Getting Started
{#getting-started}- Prerequisites and first steps - Main Content - Feature details, organized by topic
- Advanced/Configuration - Power user options
- See Also (optional) - Related documentation links
Settings Documentation Pattern
When documenting settings:
- Show the Settings Editor (UI) approach first
- Then show JSON as "Or add this to your settings.json:"
- Always show complete, valid JSON with surrounding structure:
{
"agent": {
"default_model": {
"provider": "anthropic",
"model": "claude-sonnet-4"
}
}
}
Provider/Feature Documentation Pattern
For each provider or distinct feature:
- H3 heading with anchor:
### Provider Name {#provider-name} - Brief description (1-2 sentences)
- Setup steps (numbered list)
- Configuration example (JSON code block)
- Custom models section if applicable:
#### Custom Models {#provider-custom-models}
Style Rules
Follow these key conventions:
Voice
- Second person ("you"), present tense
- Direct and concise—no hedging ("simply", "just", "easily")
- Honest about limitations; no promotional language
Formatting
- Keybindings: backticks with
+for simultaneous keys (Cmd+Shift+P) - Show both macOS and Linux/Windows variants when they differ
- Use
shcode blocks for terminal commands - Settings: show Settings Editor UI first, JSON as secondary
Terminology
| Use | Instead of |
|---|---|
| folder | directory |
| project | workspace |
| Settings Editor | settings UI |
| command palette | command bar |
| panel | tool window, sidebar (be specific: "Project Panel," "Terminal Panel") |
| language server | LSP (spell out first use, then LSP is fine) |
Zed-Specific Conventions
Recognized Rules Files
When documenting rules/instructions for AI, note that Zed recognizes these files (in priority order):
.rules.cursorrules.windsurfrules.clinerules.github/copilot-instructions.mdAGENT.mdAGENTS.mdCLAUDE.mdGEMINI.md
Settings File Locations
- macOS:
~/.config/zed/settings.json - Linux:
~/.config/zed/settings.json - Windows:
%AppData%\Zed\settings.json
Keymap File Locations
- macOS:
~/.config/zed/keymap.json - Linux:
~/.config/zed/keymap.json - Windows:
%AppData%\Zed\keymap.json
Safety Constraints
Must Not
- Delete existing documentation files
- Remove sections documenting existing functionality
- Change URLs or anchor links without verifying references
- Modify
SUMMARY.mdstructure without corresponding content - Add speculative documentation for unreleased features
- Include internal implementation details not relevant to users
Must
- Preserve existing structure when updating content
- Maintain backward compatibility of documented settings/commands
- Flag uncertainty explicitly rather than guessing
- Link to related documentation when adding new sections
Change Classification
Requires Documentation Update
- New user-facing features or commands
- Changed keybindings or default behaviors
- Modified settings schema or options
- Deprecated or removed functionality
- API changes affecting extensions
Does Not Require Documentation Update
- Internal refactoring without behavioral changes
- Performance optimizations (unless user-visible)
- Bug fixes that restore documented behavior
- Test changes
- CI/CD changes
Output Format
Phase 4 Documentation Plan
When generating a documentation plan, use this structure:
## Documentation Impact Assessment
### Summary
Brief description of code changes analyzed.
### Documentation Updates Required: [Yes/No]
### Planned Changes
#### 1. [File Path]
- **Section**: [Section name or "New section"]
- **Change Type**: [Update/Add/Deprecate]
- **Reason**: Why this change is needed
- **Description**: What will be added/modified
#### 2. [File Path]
...
### Uncertainty Flags
- [ ] [Description of any assumptions or areas needing confirmation]
### No Changes Needed
- [List files reviewed but not requiring updates, with brief reason]
Phase 6 Summary Format
## Documentation Update Summary
### Changes Made
| File | Change | Related Code |
| -------------- | ----------------- | ----------------- |
| path/to/doc.md | Brief description | link to PR/commit |
### Rationale
Brief explanation of why these updates were made.
### Review Notes
Any items reviewers should pay special attention to.
Behavioral Guidelines
Conservative by Default
- When uncertain whether to document something, flag it for human review
- Prefer smaller, focused updates over broad rewrites
- Do not "improve" documentation unrelated to the triggering code change
Traceability
- Every documentation change should trace to a specific code change
- Include references to relevant commits, PRs, or issues in summaries
Incremental Updates
- Update existing sections rather than creating parallel documentation
- Maintain consistency with surrounding content
- Follow the established patterns in each documentation area