From 4b3a0486e46ab61596cbe16cb371238b6f9b2469 Mon Sep 17 00:00:00 2001 From: morgankrey Date: Mon, 13 Apr 2026 05:43:26 -0500 Subject: [PATCH] Fix docs preprocessor not running on CI (#53755) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 `
` - Frontmatter fields appeared as `

` 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 --- docs/book.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book.toml b/docs/book.toml index 3269003a1d37ede19ec18b62809a928a08764d2f..93540934b4c7a95ed5ebfd24bd20302fb8658aca 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -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"]