morgankrey created
## 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/Adocs/book.toml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
@@ -102,4 +102,4 @@ enable = false
# Comment the below section out if you need to bypass the preprocessor for some reason.
[preprocessor.zed_docs_preprocessor]
command = "cargo run -p docs_preprocessor --"
-renderer = ["html"]
+renderer = ["html", "zed-html"]