docs: Apply documentation standards across all docs#49177
Merged
morgankrey merged 21 commits intomainfrom Feb 18, 2026
Merged
Conversation
Comprehensive remediation of 146 documentation files to align with
Zed's documentation conventions and brand voice guidelines.
## Changes
### YAML Frontmatter
- Added `title` and `description` frontmatter to all docs missing it
### Settings UI Pattern
- Updated 48+ files to show Settings Editor before JSON examples
- Pattern: 'Configure X in Settings ({#kb zed::OpenSettings}), or add to your settings file:'
- Added '([how to edit](./configuring-zed.md#settings-files))' links for JSON-only settings
### Brand Voice Fixes
- Removed exclamation points (command-palette, key-bindings, repl, privacy-and-security, etc.)
- Simplified em dash chains to parentheticals (environment, troubleshooting, agent-panel, etc.)
- Fixed marketing language (yarn.md intro, development/linux.md)
### Terminology Alignment
- 'settings UI' -> 'Settings Editor'
- 'sidebar' -> specific panel names (Project Panel, Collab Panel)
- 'directory' -> 'folder' in non-technical contexts
- 'workspace' -> 'project' in non-LSP contexts
- 'Command Palette' -> 'command palette' (lowercase)
### Callout Standardization
- Converted various callout formats to standard `> **Note:**` pattern
Release Notes:
- N/A
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
4 tasks
- Fix task_picker::Toggle -> task::Spawn in running-testing.md - Fix truncated action in visual-customization.md frontmatter Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Adds two new scripts for the docs automation project: - script/docs-suggest: Analyzes code changes and suggests documentation updates using AI. Supports --pr, --commit, --diff, and --staged modes. Includes --dry-run to preview assembled context without calling LLM. - script/test-docs-suggest-batch: Runs docs-suggest on multiple PRs to validate the system and generate summary reports. Tested on 50 recent merged PRs: - 86% had source file changes (potential doc impact) - 14% were docs/tests/CI only (correctly skipped) - Sample suggestions for features (Mermaid diagrams, Git Graph keyboard nav) were accurate and actionable - Bug fixes correctly identified as not needing docs Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Updates docs-suggest with release channel awareness: - Auto-detects PR target branch (main vs release branch) - PRs to main: batch mode with Preview callouts - Cherry-picks: immediate mode without callouts Adds two new scripts: - docs-suggest-publish: Creates PR from batched suggestions - docs-strip-preview-callouts: Removes Preview callouts for stable release Workflow: 1. PRs to main → suggestions batched to docs/.suggestions/pending.md 2. At preview branch cut → run docs-suggest-publish to create docs PR 3. At stable release → run docs-strip-preview-callouts Preview callout format: > **Preview:** This feature is available in Zed Preview. It will be > included in the next Stable release. Tested on PRs #49064 (Mermaid) and #49051 (Git Graph keyboard nav). Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Workflow triggers on PRs that modify crates/**/*.rs files and: - Runs script/docs-suggest to analyze changes - Posts suggestions as PR comment (updates existing comment to avoid spam) - Includes manual workflow_dispatch for testing The workflow respects the release channel flow: - PRs to main get Preview callout instructions - Cherry-picks to release branches get immediate suggestions Requires FACTORY_API_KEY secret for droid CLI. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Updates the docs_suggestions workflow to use branch-based batching:
- PRs merged to main: suggestions committed to docs/suggestions-pending branch
- Each PR gets its own file (suggestions/PR-XXXXX.md)
- Manifest tracks all pending suggestions
- Retry logic handles concurrent pushes
Updates docs-suggest-publish to read from the branch:
- Fetches and parses the suggestions branch
- Creates a combined PR with all pending suggestions
- Resets the queue branch after PR creation
Cherry-picks to release branches still get immediate output in step summary.
Branch structure:
docs/suggestions-pending/
README.md
manifest.json
suggestions/
PR-12345.md
PR-12346.md
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Cherry-picks to release branches now get suggestions posted directly as PR comments, making them immediately visible to the cherry-picker. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Stable releases require removing Preview callouts - this shouldn't be optional. Simplified the script to always create a PR. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
morgankrey
added a commit
that referenced
this pull request
Feb 14, 2026
… standards (#49176) ## Summary This PR establishes the foundation for documentation quality and automation. ## Documentation Conventions (`docs/.conventions/`) **CONVENTIONS.md** - Structural guidelines covering: - What needs documentation vs what to skip - Page vs section decisions (with examples) - Document structure and section ordering - Formatting conventions (code, JSON, tables, callouts) - Anchor ID patterns for stable deep-linking - Settings documentation pattern (UI first, then JSON) - Terminology standards (aligned with docs/AGENTS.md) - Prettier formatting requirements **brand-voice/** - Zed's writing style: - `SKILL.md` - Core voice principles - `rubric.md` - 8-point scoring criteria (must score 4+ on all) - `taboo-phrases.md` - Patterns to avoid (exclamation points, hype words) - `voice-examples.md` - Before/after transformations ## Gold Standard Examples (`docs/.doc-examples/`) Four templates demonstrating best practices: - `simple-feature.md` - Overview/navigation docs - `complex-feature.md` - Comprehensive feature docs - `configuration.md` - Settings documentation - `reference.md` - API/tool reference ## Related Follow-up PR #49177 applies these conventions to existing documentation. Release Notes: - N/A
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Reinstate settings best-practice prompts so generated suggestions prefer Settings Editor-first wording and include JSON-only edit guidance links. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
rtfeldman
pushed a commit
that referenced
this pull request
Feb 17, 2026
… standards (#49176) ## Summary This PR establishes the foundation for documentation quality and automation. ## Documentation Conventions (`docs/.conventions/`) **CONVENTIONS.md** - Structural guidelines covering: - What needs documentation vs what to skip - Page vs section decisions (with examples) - Document structure and section ordering - Formatting conventions (code, JSON, tables, callouts) - Anchor ID patterns for stable deep-linking - Settings documentation pattern (UI first, then JSON) - Terminology standards (aligned with docs/AGENTS.md) - Prettier formatting requirements **brand-voice/** - Zed's writing style: - `SKILL.md` - Core voice principles - `rubric.md` - 8-point scoring criteria (must score 4+ on all) - `taboo-phrases.md` - Patterns to avoid (exclamation points, hype words) - `voice-examples.md` - Before/after transformations ## Gold Standard Examples (`docs/.doc-examples/`) Four templates demonstrating best practices: - `simple-feature.md` - Overview/navigation docs - `complex-feature.md` - Comprehensive feature docs - `configuration.md` - Settings documentation - `reference.md` - API/tool reference ## Related Follow-up PR #49177 applies these conventions to existing documentation. Release Notes: - N/A
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
github-actions Bot
pushed a commit
that referenced
this pull request
Feb 18, 2026
� The changes are unstaged. Now I'll generate the documentation update summary: --- ## Documentation Update Summary ### Changes Made | File | Change | Related Code | | --- | --- | --- | | docs/src/configuring-languages.md | Removed extra blank line in numbered list (Storage Location section) | Formatting cleanup | | docs/src/development.md | Removed extra blank lines between numbered list items 2 and 3 | Formatting cleanup | | docs/src/extensions/themes.md | Removed 5 extra blank lines in numbered list items (Theme Metadata, Style Properties, Syntax Highlighting, UI Elements, Editor-specific Colors) | Formatting cleanup | | docs/src/languages/r.md | Removed extra blank line after extension link | Formatting cleanup | | docs/src/reference/all-settings.md | Removed extra blank line in preview tabs description list | Formatting cleanup | | docs/src/vim.md | Removed extra blank line after "Use AnyQuotes/AnyBrackets if you:" | Formatting cleanup | ### Rationale These changes are Markdown formatting corrections that remove unnecessary blank lines between numbered/bulleted list items and their sub-content. The blank lines were inconsistent with the rest of the documentation and could cause rendering issues in some Markdown parsers (where an extra blank line might break the list continuity). These appear to be residual formatting issues from the comprehensive documentation standards update in commit `6daa541e77` (PR #49177 "docs: Apply documentation standards across all docs"). ### Review Notes - **All changes are purely cosmetic** - no content has been modified, only whitespace formatting - The pattern is consistent: removing blank lines that appeared between a numbered item's header and its content/sub-items - These changes improve list rendering consistency across different Markdown renderers - No controversial changes or assumptions - this is straightforward formatting cleanup Triggered by: pr 48892 Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
github-actions Bot
pushed a commit
that referenced
this pull request
Feb 18, 2026
� Now I have all the information needed. Let me create the documentation update summary: --- ## Documentation Update Summary ### Changes Made | File | Change | Related Code | | --- | --- | --- | | docs/src/ai/agent-panel.md | Removed "restoring threads from history" from list of unsupported external agent features | PR #49449 (b4baea8) | | docs/src/ai/external-agents.md | Removed "resuming threads from history" from unsupported features list for Gemini CLI, Claude Agent, and Codex sections | PR #49449 (b4baea8) | | docs/src/configuring-languages.md | Formatting fix: removed blank line before storage location list | PR #49177 (6daa541) | | docs/src/development.md | Formatting fix: removed blank lines before numbered sub-steps | PR #49177 (6daa541) | | docs/src/extensions/themes.md | Formatting fix: removed blank lines between numbered items and their content | PR #49177 (6daa541) | | docs/src/languages/r.md | Formatting fix: removed blank line between list item and its sub-list | PR #49177 (6daa541) | | docs/src/reference/all-settings.md | Formatting fix: removed blank line before list in preview tabs description | PR #49177 (6daa541) | | docs/src/vim.md | Formatting fix: removed blank line before sub-list in AnyQuotes/AnyBrackets section | PR #49177 (6daa541) | ### Rationale **Feature Documentation Update:** - PR #49449 enabled history/thread restoration support for external agents (Gemini CLI, Claude Agent, Codex), requiring removal of this limitation from documentation in 3 locations across 2 files. **Formatting Standardization:** - PR #49177 established documentation standards. The formatting changes (removing blank lines in numbered lists) align existing docs with these standards. ### Review Notes - **Content change**: The external agents documentation now correctly reflects that history restoration is supported. Reviewers should verify this matches the actual feature behavior from PR #49449. - **Formatting changes**: All formatting modifications are consistent with each other and follow the pattern of removing unnecessary blank lines between list markers and their content. - **No uncertainty flags**: All changes are straightforward updates reflecting either code changes or formatting standards. --- **Condensed commit message version:** ``` docs: Update external agent feature support and apply formatting standards - Remove "restoring threads from history" from unsupported features list for external agents (Gemini CLI, Claude Agent, Codex) after PR #49449 - Apply formatting fixes across 6 docs files per standards from PR #49177 ``` Triggered by: pr 48619 Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
github-actions Bot
pushed a commit
that referenced
this pull request
Feb 18, 2026
� I can now see the relevant commits. Let me generate the documentation update summary based on the Phase 6 format: ## Documentation Update Summary ### Changes Made | File | Change | Related Code | | --- | --- | --- | | docs/src/ai/external-agents.md | Removed "resuming threads from history" from unavailable features list for Gemini CLI, Claude Agent, and Codex | PR #49449 (b4baea8) - Enable history for external agents | | docs/src/ai/tool-permissions.md | Added documentation for subcommand-specific permission patterns in terminal commands | PR #49148 (d60b291) - Make terminal permission pattern suggestions subcommand-specific | | docs/src/configuring-languages.md | Formatting fix - removed extra blank line in Storage Location list | PR #49177 (6daa541) - Apply documentation standards | | docs/src/development.md | Formatting fix - removed extra blank lines in numbered list items | PR #49177 (6daa541) - Apply documentation standards | | docs/src/extensions/themes.md | Formatting fix - removed extra blank lines between numbered list items and their content | PR #49177 (6daa541) - Apply documentation standards | | docs/src/languages/r.md | Formatting fix - removed extra blank line in extension list | PR #49177 (6daa541) - Apply documentation standards | | docs/src/reference/all-settings.md | Formatting fix - removed extra blank line in preview tabs description list | PR #49177 (6daa541) - Apply documentation standards | | docs/src/vim.md | Formatting fix - removed extra blank line in text objects section | PR #49177 (6daa541) - Apply documentation standards | ### Rationale These documentation updates were triggered by two code changes: 1. **External agent history feature** (PR #49449): External agents (Gemini CLI, Claude Agent, Codex) now support resuming threads from history, so this was removed from the "not yet available" features list in the external-agents documentation. 2. **Subcommand-specific terminal permissions** (PR #49148): Terminal tool permission patterns now include subcommands (e.g., `cargo build` instead of just `cargo`), providing more granular permission control. Documentation was updated to explain this behavior to users. 3. **Documentation formatting standards** (PR #49177): Several files had inconsistent formatting with extra blank lines in numbered/bulleted lists that were cleaned up to match Prettier/mdBook standards. ### Review Notes - The external-agents.md changes are content updates reflecting new feature availability - reviewers should verify the history feature is indeed working for all three external agent types - The tool-permissions.md change adds clarification for existing behavior - the example uses `cargo build` as a concrete illustration - The remaining files (configuring-languages.md, development.md, extensions/themes.md, languages/r.md, reference/all-settings.md, vim.md) contain only formatting fixes with no semantic changes - All changes follow the documentation conventions in `docs/AGENTS.md` Triggered by: pr 48957 Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
github-actions Bot
pushed a commit
that referenced
this pull request
Feb 18, 2026
� Now I have all the information I need to generate the documentation update summary. Let me analyze the changes: ## Documentation Update Summary ### Changes Made | File | Change | Related Code | | --- | --- | --- | | docs/src/ai/external-agents.md | Removed "resuming threads from history" from unsupported features list for Gemini CLI, Claude Agent, and Codex (3 locations) | PR #49449 (b4baea8) | | docs/src/configuring-languages.md | Minor formatting fix: removed extraneous blank line in Storage Location list | PR #49177 (6daa541) | | docs/src/development.md | Minor formatting fix: removed extraneous blank lines in workflow steps | PR #49177 (6daa541) | | docs/src/extensions/themes.md | Minor formatting fixes: removed extraneous blank lines between numbered list items and their sub-content | PR #49177 (6daa541) | | docs/src/languages/r.md | Minor formatting fix: removed extraneous blank line in extension bullet list | PR #49177 (6daa541) | | docs/src/reference/all-settings.md | Minor formatting fix: removed extraneous blank line in preview tabs description | PR #49177 (6daa541) | | docs/src/vim.md | Minor formatting fix: removed extraneous blank line in AnyQuotes/AnyBrackets usage list | PR #49177 (6daa541) | ### Rationale These documentation updates fall into two categories: 1. **Feature enablement documentation (external-agents.md)**: PR #49449 enabled session history for external agents (Gemini CLI, Claude Agent, Codex) for all users by removing a feature flag. The documentation was updated to reflect that "resuming threads from history" is now supported, removing it from the list of unsupported features. 2. **Formatting standardization (6 files)**: PR #49177 applied documentation standards across all docs, and these changes appear to be Prettier-related formatting fixes that remove extraneous blank lines between numbered list items and their sub-content to ensure consistent markdown formatting per the `docs/.prettierrc` configuration. ### Review Notes - **Primary change**: The substantive documentation update is in `external-agents.md`, accurately reflecting that session history is now available for external agents. - **Formatting changes**: The other 6 files contain only whitespace/formatting fixes (removing blank lines between list items and their contents). These align with mdBook and Prettier formatting requirements. - **No controversial changes**: All changes are straightforward and trace directly to merged PRs. - **Verification**: Reviewers may want to verify that the external agents history feature is indeed working as documented before final approval. Triggered by: pr 42076 Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
github-actions Bot
pushed a commit
that referenced
this pull request
Feb 18, 2026
� Now I have a clear picture. Let me generate the documentation update summary: ## Documentation Update Summary ### Changes Made | File | Change | Related Code | | --- | --- | --- | | `docs/src/ai/external-agents.md` | Updated thread history availability notes for Gemini CLI, Claude Agent, and Codex—clarifying that thread history is now available for Claude Agent and Codex, while Gemini CLI depends on ACP capabilities | PR #49449 (`acp: Enable history for external agents for all users`) | | `docs/src/ai/tool-permissions.md` | Added new "Subcommand-Specific Patterns" section explaining how terminal permission patterns extract subcommands (e.g., `cargo build` vs `cargo test`) | PR #49148 (`Make terminal permission pattern suggestions subcommand-specific`) | | `docs/src/configuring-languages.md` | Removed unnecessary blank line before Storage Location list | PR #49177 (`docs: Apply documentation standards`) | | `docs/src/development.md` | Removed unnecessary blank lines in workflow steps | PR #49177 (`docs: Apply documentation standards`) | | `docs/src/extensions/themes.md` | Removed unnecessary blank lines after numbered list items | PR #49177 (`docs: Apply documentation standards`) | | `docs/src/languages/r.md` | Removed unnecessary blank line in extension list | PR #49177 (`docs: Apply documentation standards`) | | `docs/src/reference/all-settings.md` | Removed unnecessary blank line before list in preview tabs description | PR #49177 (`docs: Apply documentation standards`) | | `docs/src/vim.md` | Removed unnecessary blank line before list in text objects section | PR #49177 (`docs: Apply documentation standards`) | ### Rationale These documentation updates fall into two categories: 1. **Feature documentation updates**: The external agents and tool permissions changes reflect actual code changes that modified user-facing behavior: - Thread history was enabled for external agents (Claude Agent, Codex) in PR #49449 - Terminal permission patterns now extract subcommands for more granular control in PR #49148 2. **Formatting standardization**: Several files had inconsistent blank line usage around numbered lists with sub-items. These were normalized to follow consistent markdown formatting without unnecessary blank lines. ### Review Notes - **Thread history wording**: The external-agents.md changes distinguish between agents that fully support thread history (Claude Agent, Codex) and Gemini CLI which depends on its ACP implementation. Reviewers should verify this distinction is accurate. - **Subcommand patterns table**: The new section in tool-permissions.md includes a table showing example patterns. Verify the regex patterns (`^cargo\s+build\b`, etc.) match the actual implementation in the codebase. - **Formatting changes**: The blank line removals are purely cosmetic and shouldn't affect rendered output—they simply align with the project's markdown standards. Triggered by: pr 48999 Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
github-actions Bot
pushed a commit
that referenced
this pull request
Feb 18, 2026
� Now I have a complete picture of all the documentation changes. Let me create the summary: ## Documentation Update Summary ### Changes Made | File | Change | Related Code | | --- | --- | --- | | `docs/src/ai/tool-permissions.md` | Added new "Subcommand-Specific Patterns" section explaining how terminal commands with subcommands (like `cargo build` or `npm install`) generate pattern suggestions | Likely related to AI tool permission improvements | | `docs/src/reference/all-settings.md` | Added documentation for new `close_panel_on_toggle` setting; removed extra blank line in preview tabs section | New setting addition to codebase | | `docs/src/configuring-languages.md` | Removed unnecessary blank line after "Storage Location:" header | Formatting cleanup (PR #49177) | | `docs/src/development.md` | Removed unnecessary blank lines after numbered list headers | Formatting cleanup (PR #49177) | | `docs/src/extensions/themes.md` | Removed 5 unnecessary blank lines after numbered list items in theme documentation | Formatting cleanup (PR #49177) | | `docs/src/languages/r.md` | Removed unnecessary blank line after extension link | Formatting cleanup (PR #49177) | | `docs/src/vim.md` | Removed unnecessary blank line after "Use AnyQuotes/AnyBrackets if you:" header | Formatting cleanup (PR #49177) | ### Rationale These documentation updates fall into two categories: 1. **New Feature Documentation**: The `close_panel_on_toggle` setting and subcommand-specific pattern suggestions are new functionality that needed documentation to help users understand and configure these features. 2. **Formatting Standardization**: Following PR #49177 ("Apply documentation standards across all docs"), several files had residual formatting inconsistencies with extra blank lines after headers and list items that have been cleaned up for consistency. ### Review Notes - **New content additions** in `tool-permissions.md` and `all-settings.md` should be reviewed for technical accuracy - The subcommand pattern table provides concrete examples—reviewers should verify these match actual implementation behavior - The `close_panel_on_toggle` setting documentation describes default value as `false`—confirm this matches the codebase default - Formatting changes (blank line removals) are purely cosmetic and don't affect content meaning - All changes maintain the existing document structure and markdown validity ### Summary Statistics - **7 files modified** - **25 lines added, 11 lines removed** - **2 substantive content additions** (new setting docs, new section) - **5 formatting cleanups** (blank line removals) Triggered by: commit dc41f71 Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive remediation of 146 documentation files to align with Zed's documentation conventions and brand voice guidelines.
Changes
YAML Frontmatter
titleanddescriptionfrontmatter to all docs missing itSettings UI Pattern
Configure X in Settings ({#kb zed::OpenSettings}), or add to your settings file:([how to edit](./configuring-zed.md#settings-files))links for JSON-only settingsBrand Voice Fixes
Terminology Alignment
settings UI->Settings Editorsidebar-> specific panel names (Project Panel, Collab Panel)directory->folderin non-technical contextsworkspace->projectin non-LSP contextsCommand Palette->command palette(lowercase)Callout Standardization
> **Note:**patternRelated
Depends on conventions established in #49176.
Release Notes: