Rewrite product prose and local path/command examples across the docs
to match the shipped application (gwen CLI, Gwen config paths, Gwen.app,
com.yrkaierx.Gwen). Upstream distribution channels, service URLs and
package identifiers stay factually intact.
Instead of a dropdown, it is now just a one-click icon.
Self-Review Checklist:
- [X] I've reviewed my own diff for quality, security, and reliability
- [X] Unsafe blocks (if any) have justifying comments
- [X] The content is consistent with the [UI/UX
checklist](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md#uiux-checklist)
- [X] Tests cover the new/changed behavior
- [X] Performance impact has been considered and is acceptable
Release Notes:
- Improved theme toggle for the documentation website
---------
Co-authored-by: Gaauwe Rombouts <mail@grombouts.nl>
Context
This PR makes the Zed docs easier for AI tools, search crawlers, and
users to consume without changing the visible docs content. The current
production docs are primarily optimized for browser navigation. They do
not expose first-class Markdown URLs, an `llms.txt` index, page-level
copy affordances, or machine-readable freshness metadata that let users
and agents grab clean, current page content.
Changes
- Generate Markdown copies for docs pages during the mdBook postprocess
step, including `/docs/index.md` as an alias for Getting Started.
- Generate `/docs/llms.txt` from the mdBook chapter list, grouped by
`SUMMARY.md` sections and annotated with page frontmatter descriptions.
- Generate `/docs/sitemap.xml` with `<lastmod>` values for every docs
page.
- Emit machine-readable freshness metadata in HTML via `last-modified`
and `article:modified_time` meta tags.
- Generate Cloudflare Pages `_redirects` for `.html`, extensionless, and
`.md` redirect variants, with channel-aware docs destinations.
- Add discovery hints for agents and crawlers: `rel="llms.txt"`,
`rel="alternate" type="text/markdown"`, and a short generated `llms.txt`
directive in copied Markdown pages.
- Update the docs proxy so `Accept: text/markdown`, `/docs.md`, and
direct `.md` requests can resolve to the generated Markdown artifacts.
- Move primary docs content earlier in the HTML source while preserving
the visible layout, so crawlers and agent scorers encounter the article
before sidebar chrome.
- Move the existing copy-as-Markdown control from the top navigation
into the page-title row, using the generated Markdown alternate link as
the source of truth.
- Split AI-discovery artifact generation out of
`docs_preprocessor/src/main.rs` into a focused module.
Best Practices Adopted
- Use `llms.txt` as a concise navigation index, not a dump of full page
content.
- Link to absolute, canonical Markdown URLs from `llms.txt`.
- Preserve the docs hierarchy in `llms.txt` instead of emitting a flat
sitemap-like list.
- Include short per-link descriptions from existing metadata rather than
inventing summaries.
- Keep `llms.txt`, Markdown copies, sitemap data, redirects, and
freshness metadata generated from the same mdBook source to avoid drift.
- Advertise Markdown alternates with standard HTML metadata and
same-origin URLs.
- Support both explicit Markdown URLs and content negotiation for
clients that prefer Markdown.
- Keep browser copy behavior pointed at generated Markdown alternate
links instead of duplicating route inference in JavaScript.
- Keep the copy-as-Markdown affordance in the page title row without
duplicating header chrome controls.
Validation
- `cargo check -p docs_preprocessor`
- `cargo test -p docs_preprocessor`
- `./script/clippy -p docs_preprocessor`
- `mdbook build ./docs --dest-dir=../target/deploy/docs/`
- `node --check docs/theme/plugins.js`
- `pnpm dlx prettier@3.5.0 docs/theme/plugins.js --check`
- `git diff --check`
- Local artifact checks confirmed generated Markdown pages, `llms.txt`,
`sitemap.xml` lastmod values, HTML freshness metadata, Markdown
alternate links, redirect targets, and preprocessed action/keybinding
tags resolve as expected.
- Worker URL rewrite mock covered `/docs/`, `/docs.md`,
`/docs/index.md`, extensionless docs routes, `.html` routes,
`/docs/llms.txt`, and `/docs/sitemap.xml`.
- High-effort adversarial subagent review found blockers around
channel-aware redirects, shallow-checkout date fallback, file size,
duplicated Markdown path inference, and process spawning. Those were
addressed.
Remaining Notes
- Local `python -m http.server` does not emulate Cloudflare Pages pretty
URLs, `_redirects`, or the docs-proxy Worker, so full local `afdocs`
still cannot prove content negotiation end to end.
- Existing production remains unchanged until this PR is deployed
through the docs workflow.
- Production baseline `npx afdocs check https://zed.dev/docs/ --fixes
--verbose` still reports the original failures before this PR is
deployed: 12 passed, 8 failed, 3 skipped.
Release Notes:
- Improved docs AI-readiness by adding machine-readable discovery,
Markdown access, and freshness metadata.
---------
Co-authored-by: Katie Geer <katie@zed.dev>
Co-authored-by: Ben Kunkle <ben@zed.dev>
Closes #ISSUE
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 *or* Added/Fixed/Improved ...
Update the heading typeface to use IBM Plex Serif, the code typeface to
use Lilex (IBM Plex Mono), and pull them from the zed.dev CDN. Also
added some stray design adjustments here and there.
Release Notes:
- N/A
Fixes a typo in the consent banner check on docs pages, which makes the
opt-out logic work correctly.
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
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
We were previously always highlighting the last header in the table of
contents as active even if you were at the top of the page. This is now
fixed, where upon loading the page, no header is highlighted, and as you
scroll, we highlight the top-most heading one by one.
Release Notes:
- N/A
Follow up to https://github.com/zed-industries/zed/pull/43758.
This PR uses view transition animations to reduce the page flickering
when navigating between one and the other. Pretty cool CSS-only
solution.
Release Notes:
- N/A
This is still not perfect, but it reduces the shift that happens when
navigating between pages that have and don't have the table of contents.
It also tries to reduce the theme flicker that happens by moving its
loading to an earlier moment.
Release Notes:
- N/A
This PR adds the ability to collapse section in the docs sidebar (which
are persistent until you close the tab), and some design facelift to the
docs, which makes its design close to the site as well as polishing up
many elements and interactions (like moving the search to a modal and
making the table of content visible in smaller breakpoints).
<img width="600" height="2270" alt="Screenshot 2025-11-28 at 5 26@2x"
src="https://github.com/user-attachments/assets/3a8606c6-f74f-4bd2-84c8-d7a67ff97564"
/>
Release Notes:
- N/A
## Summary
Adds a "Copy as Markdown" button to the documentation toolbar that
allows users to easily copy the raw markdown content of any
documentation page.
This feature is inspired by similar implementations on sites like
[Better Auth docs](https://www.better-auth.com/docs/installation) and
[Cloudflare Workers docs](https://developers.cloudflare.com/workers/)
which provide easy ways for users to copy documentation content.
## Features
- **Button placement**: Positioned between theme toggle and search icon
for optimal UX
- **Content fetching**: Retrieves raw markdown from GitHub's API for the
current page
- **Consistent styling**: Matches existing toolbar button patterns
## Test plan
- [x] Copy functionality works on all documentation pages
- [x] Toast notifications appear and disappear correctly
- [x] Button icon animations work properly (spinner → checkmark → copy)
- [x] Styling matches other toolbar buttons
- [x] Works in both light and dark themes
## Screenshots
The button appears as a copy icon between the theme and search buttons
in the left toolbar.
<img width="798" height="295" alt="image"
src="https://github.com/user-attachments/assets/37d41258-d71b-40f8-b8fe-16eaa46b8d7f"
/>
<img width="1628" height="358" alt="image"
src="https://github.com/user-attachments/assets/fc45bc04-a290-4a07-8d1a-a010a92be033"
/>
---------
Co-authored-by: Danilo Leal <daniloleal09@gmail.com>
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>
While visually unintrusive, these navigation links enable proper
navigation in readers and extensions like Vimium that rely on
rel=next/prev
Release Notes:
- N/A
I was finding hard to navigate the "Configuring Zed" page with just
white space creating a boundary between the different chunks of content.
I think a slight border below the h2 heading helps a lot with that!
Release Notes:
- N/A
This PR pins Prettier to a specific version when we run the docs
formatting check.
This should prevent drift when new Prettier versions are released that
may impact the formatting.
Release Notes:
- N/A
Closes https://github.com/zed-industries/zed/issues/17911
This PR enables dark mode on the documentation. This is done without any
special plugins, just pure JavaScript and CSS variables. I may open
fast-follow PRs to fine-tune design and code details that haven't been
super polished yet. For example, when switching to dark mode, the
`class` attribute on the `html` tag would change immediately, whereas
other attributes such as `data-theme` and `data-color-scheme` would
require a full refresh. This seems to be resolved, but not 100%
confident yet.
---
Release Notes:
- Enabled dark mode on the documentation
Follow up to https://github.com/zed-industries/zed/pull/17505. This one
contains a bit more copywriting adjustments. Figured we were using the
"You can do x..." sentence shape quite frequently, so tried to kickstart
reducing that slightly. There are also more images not loading in
complement to the one I removed, but I'm not fully sure why that's the
case.
---
Release Notes:
- N/A
This PR adds several design tweaks to elements of the documentation,
most notably swapping the heading title font from `PPAgrandir` to
`Lora`, which makes the docs consistent with the new website. Aside from
this, there's also some tiny, low-hanging content adjustments to a few
pages.
---
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
This PR formats the CSS in the docs with Prettier.
The indentation of these CSS files kept changing based on who last
touched them, so I added settings to the Zed repo to try and keep the
formatting intact until we can enforce it in CI.
Release Notes:
- N/A
yenru0
