## Summary
- Restructures docs nav: new **Account & Billing**, **Zed Business**,
and **Privacy & Security** sections, positioned above Platform Support
- Moves Plans & Pricing and Billing out of AI > Subscription into
Account & Billing
- Moves Models and Providers to direct children of AI (removes
Subscription wrapper)
- Adds 4 new Zed Business pages: Overview, Organizations, Admin
Controls, Business Support
- Existing `roles.md` wired in as Roles & Permissions
- Privacy & Security, Privacy for Business, and SOC2 remain as draft
entries pending BIZOPS-983
- Adds redirect: `/ai/subscription.html` →
`/docs/ai/plans-and-usage.html`
## Status
Draft — active work in progress. Remaining issues on this branch:
- BIZOPS-982 (due 3/21): Account & Billing content updates
- BIZOPS-983 (due 3/23): Privacy & Security content
- BIZOPS-984 (due 3/25): Final review and QA
## Notes for reviewers
- Implementation-specific UI flows in the Business pages are stubbed
with `<!-- TODO -->` comments — these need to be filled in closer to
launch once the dashboard is finalized
Release Notes:
- N/A
---------
Co-authored-by: Zed Zippy <234243425+zed-zippy[bot]@users.noreply.github.com>
Co-authored-by: Katie Geer <katie@zed.dev>
Co-authored-by: Marshall Bowers <git@maxdeviant.com>
## Summary
The docs preprocessor was configured with `renderer = ["html"]`, but the
actual output renderer is `zed-html`. This mismatch caused mdbook to
skip the preprocessing step, leaving YAML frontmatter unprocessed in the
rendered HTML.
**Symptoms:**
- YAML frontmatter (`---\ntitle: ...\n---`) leaked into rendered HTML
- `---` rendered as `<hr />`
- Frontmatter fields appeared as `<h2>` headings (setext heading
interpretation)
- Meta description tags showed default values instead of page-specific
descriptions
## Root Cause
The `renderer = ["html"]` config was introduced in August 2024 (#16883)
when the preprocessor was first added. At that time, the output was the
standard `html` renderer.
In July 2025 (#35112), the `[output.zed-html]` custom renderer was added
for frontmatter/postprocessing support, but the preprocessor's
`renderer` filter wasn't updated to match.
**Why it broke now (April 12, 2026):**
The mismatch was latent - it worked inconsistently depending on CI
environment conditions. Comparing two deploys from the same day:
| Deploy | Network Errors | Preprocessing |
|--------|---------------|---------------|
| 19:00 UTC | 0 | ✓ Runs correctly |
| 21:54 UTC | Many (`static.crates.io` connection failures) | ✗ Skipped
|
The 21:54 deploy had network errors during `cargo run -p
docs_preprocessor`. mdbook appears to have silently skipped the
preprocessor and proceeded directly to the renderer. The postprocessor
still ran (via the renderer's separate cargo command), but without
preprocessing, frontmatter wasn't converted to metadata.
**The fix:** Change `renderer = ["html"]` to `renderer = ["html",
"zed-html"]` to support both the custom renderer and any fallback to the
standard html renderer (e.g., during local development or if mdbook
commands internally use html).
## Test plan
- [x] Local build produces correct HTML without frontmatter leaking
- [x] Meta descriptions correctly populated from frontmatter
- [x] CI `check_docs` shows all 3 preprocessor steps running:
- `docs_preprocessor supports zed-html`
- `docs_preprocessor` (preprocessing)
- `docs_preprocessor postprocess`
Release Notes:
- N/A
Adds a consent banner, similar to the one on zed.dev
Before you mark this PR as ready for review, make sure that you have:
- [x] Added a solid test coverage and/or screenshots from doing manual
testing
- [x] Done a self-review taking into account security and performance
aspects
- [x] Aligned any UI changes with the [UI
checklist](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md#uiux-checklist)
Release Notes:
- N/A
Closes #ISSUE
Adds basic frontmatter support to `.md` files in docs. The only
supported keys currently are `description` which becomes a `<meta
name="description" contents="...">` tag, and `title` which becomes a
normal `title` tag, with the title contents prefixed with the subject of
the file.
An example of the syntax can be found in `git.md`, as well as below
```md
---
title: Some more detailed title for this page
description: A page-specific description
---
# Editor
```
The above will be transformed into (with non-relevant tags removed)
```html
<head>
<title>Editor | Some more detailed title for this page</title>
<meta name="description" contents="A page-specific description">
</head>
<body>
<h1>Editor</h1>
</body>
```
If no front-matter is provided, or If one or both keys aren't provided,
the title and description will be set based on the `default-title` and
`default-description` keys in `book.toml` respectively.
## Implementation details
Unfortunately, `mdbook` does not support post-processing like it does
pre-processing, and only supports defining one description to put in the
meta tag per book rather than per file. So in order to apply
post-processing (necessary to modify the html head tags) the global book
description is set to a marker value `#description#` and the html
renderer is replaced with a sub-command of `docs_preprocessor` that
wraps the builtin `html` renderer and applies post-processing to the
`html` files, replacing the marker value and the `<title>(.*)</title>`
with the contents of the front-matter if there is one.
## Known limitations
The front-matter parsing is extremely simple, which avoids needing to
take on an additional dependency, or implement full yaml parsing.
* Double quotes and multi-line values are not supported, i.e. Keys and
values must be entirely on the same line, with no double quotes around
the value.
The following will not work:
```md
---
title: Some
Multi-line
Title
---
```
* The front-matter must be at the top of the file, with only white-space
preceding it
* The contents of the title and description will not be html-escaped.
They should be simple ascii text with no unicode or emoji characters
Release Notes:
- N/A *or* Added/Fixed/Improved ...
---------
Co-authored-by: Katie Greer <katie@zed.dev>
Adding a number of settings that weren't documented, restructuring
things a bit to separate what is model-related settings from agent panel
usage-related settings, adding the recently introduced `disable_ai` key,
and more.
Release Notes:
- Improved docs around configuring and using AI in Zed
While creating a new MCP extension this weekend, I visited these pages
and it felt like they could be improved a little bit. I'm renaming the
MCP-related page under the /extension directory to use the "MCP"
acronym, instead of "context servers".
Release Notes:
- N/A
This PR adds a redirect from `zed.dev/docs/ai` to
`zed.dev/docs/ai/overview`.
Not 100% sure this will work, but want to give it a try.
Release Notes:
- N/A
To support the Agentic Editing launch. To dos before merging:
- [ ] Anything marked as `todo!` within `docs/src` (Anyone)
- [x] Check all internal links (Joe)
- Joe: I checked all links and fixed all aside from a few that I
annotated with `todo!` comments
- [ ] Update images (Danilo)
- [ ] Go over / show images of tool cards in agent panel overview
(Danilo)
- [ ] Point billing FAQ to new billing docs (Joe)
- [x] Redirects external links
- [ ] Needs testing
- [x] Delete old docs
- [ ] Ensure all mentioned bindings use the `{#kb ...}` format and that
they are rendering correctly
- [ ] All agent-related actions are now `agent::` and not `assistant::`
- [x] Mention support of `.rules` files in `rules.md`
Release Notes:
- N/A
---------
Co-authored-by: Joseph T. Lyons <josephtlyons@gmail.com>
Co-authored-by: morgankrey <morgankrey@gmail.com>
Co-authored-by: Smit Barmase <37347831+smitbarmase@users.noreply.github.com>
Co-authored-by: Ben Kunkle <Ben.kunkle@gmail.com>
Co-authored-by: Peter Tripp <peter@zed.dev>
Co-authored-by: Ben Kunkle <ben@zed.dev>
Co-authored-by: Mikayla Maki <mikayla.c.maki@gmail.com>
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
Temporarily revert #16700 to deal with this error:
`error: manifest path `../crates/docs_preprocessor/Cargo.toml` does not
exist` as it was causing the docs-preprocessor not to run, meaning
unexpanded templates were showing up in the public docs.
Reverts zed-industries/zed#16700
Release Notes:
- N/A
This PR adds a mdbook preprocessor for supporting Zed's docs.
This initial version adds the following custom commands:
**Keybinding**
`{#kb prefix::action_name}` (e.g. `{#kb zed::OpenSettings}`)
Outputs a keybinding template like `<kbd
class="keybinding">{macos_keybinding}|{linux_keybinding}</kbd>`. This
template is processed on the client side through `mdbook` to show the
correct keybinding for the user's platform.
**Action**
`{#action prefix::action_name}` (e.g. `{#action zed::OpenSettings}`)
For now, simply outputs the action name in a readable manner. (e.g.
zed::OpenSettings -> zed: open settings)
In the future we'll add additional modes for this template, like create
a standard way to render `{action} ({keybinding})`.
## Example Usage
```
To open the assistant panel, toggle the right dock by using the {#action workspace::ToggleRightDock} action in the command palette or by using the
{#kb workspace::ToggleRightDock} shortcut.
```
Release Notes:
- N/A
This PR significantly expands the assistant documentation, breaking it
out into sections, adding examples and further documenting features.
This PR introduces a convention in docs for swapping keybindings for mac
vs linux:
`<kbd>cmd-enter|ctrl-enter</kbd>`
In the above example, the first will be shown for mac, the second for
linux or windows.
TODO:
- [ ] Fix table style (for `/assistant/configuration`)
- [x] Add script to swap keybindings based on platform
- It should take in this format: [`cmd-n` (mac)|`ctrl-n`(linux)] and
return just the correct binding for the viewer's platform.
- [ ] Add image/video assets (non-blocking)
Release Notes:
- Updated assistant documentation
To ease navigating on pages that are long and having a birds-eye view of
all the available content.
This is done client-side and done via the files initially generated by
the `mdbook-pagetoc` plugin ([crates.io link
here](https://crates.io/crates/mdbook-pagetoc)).
<img width="600" alt="Screenshot 2024-07-25 at 13 34 08"
src="https://github.com/user-attachments/assets/a78c69e5-8cc4-4414-9d9c-27a4ceb27620">
---
Release Notes:
- N/A
---------
Co-authored-by: Marshall Bowers <elliott.codes@gmail.com>
This PR sets up deployments for the docs using mdBook.
Right now the new docs are hosted at
[zed.dev/docs2](https://zed.dev/docs2/).
The docs are deployed to Cloudflare Pages on merges to `main`, and we
have a Cloudflare Worker that routes traffic from `zed.dev/docs2` to the
docs deployment.
We can iterate on the docs for a bit, and then promote them to
`zed.dev/docs` when we're all ready for the switchover.
Release Notes:
- N/A
---------
Co-authored-by: Conrad Irwin <conrad.irwin@gmail.com>
