docs: bump mdbook version#6556
Conversation
🤖 Kimi Code ReviewThis PR updates the documentation toolchain to mdBook 0.5.2 and removes deprecated preprocessors. Overall, the changes are correct and well-structured. Security & Stability
Correctness
Documentation Formatting
Configuration
Minor
Acknowledgment Automated review by Kimi (Moonshot AI) · kimi-k2.5 · custom prompt |
Greptile SummaryThis PR bumps mdbook from 0.4.51 to 0.5.2, removes the now-redundant
Confidence Score: 3/5Not safe to merge as-is — the roadmap symlink is broken and the page it claims to fix will still 404. One P1 finding: the symlink docs/roadmap.md — broken symlink target
|
| Filename | Overview |
|---|---|
| docs/roadmap.md | New symlink to ROADMAP.md — but target is ROADMAP.md (resolves to docs/ROADMAP.md), not ../ROADMAP.md; symlink is broken |
| Makefile | Removes mdbook-alerts dep; bumps mdbook-katex to alpha pre-release (0.10.0-alpha), mdbook-linkcheck2 to 0.12.0, mdbook-mermaid to 0.17.0 |
| .github/workflows/pr-main_mdbook.yml | Bumps mdbook version from 0.4.51 to 0.5.2 in CI workflow |
| book.toml | Removes mdbook-alerts preprocessor config; adds ROADMAP redirect |
| docs/SUMMARY.md | Updates Roadmap link from ../ROADMAP.md to ./roadmap.md (new symlink) |
| docs/developers/l1/dashboards.md | Escapes square brackets to suppress mdbook 0.5 incomplete-link warnings |
| docs/l2/stages.md | Escapes dollar signs to prevent mdbook-katex from parsing $1.9B as math |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A["docs/SUMMARY.md<br/>./roadmap.md"] --> B["docs/roadmap.md<br/>(symlink)"]
B -->|"target: ROADMAP.md (relative)"| C["❌ docs/ROADMAP.md<br/>(does not exist)"]
B -.->|"intended: ../ROADMAP.md"| D["✅ ROADMAP.md<br/>(repo root)"]
E["book.toml redirect<br/>/ROADMAP.html → /roadmap.html"] --> F["Built roadmap page"]
D --> F
Prompt To Fix All With AI
Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
docs/roadmap.md:1
**Broken symlink — roadmap page will still 404**
The symlink `docs/roadmap.md` has a relative target of `ROADMAP.md`. Since symlinks are resolved relative to the directory containing the symlink, the OS looks for `docs/ROADMAP.md`, which doesn't exist — only `ROADMAP.md` at the repository root does. The correct target should be `../ROADMAP.md` to traverse up one directory from `docs/`.
### Issue 2 of 2
Makefile:208
**Alpha pre-release dependency in CI**
`mdbook-katex` is pinned to `0.10.0-alpha`, a pre-release version, while the other dependencies use stable releases. Alpha versions can have undocumented breaking changes or be yanked from crates.io. Consider using the latest stable release of `mdbook-katex` instead.
Reviews (1): Last reviewed commit: "docs: fix roadmap 404 error" | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| @@ -0,0 +1 @@ | |||
| ROADMAP.md No newline at end of file | |||
There was a problem hiding this comment.
The symlink docs/roadmap.md has a relative target of ROADMAP.md. Since symlinks are resolved relative to the directory containing the symlink, the OS looks for docs/ROADMAP.md, which doesn't exist — only ROADMAP.md at the repository root does. The correct target should be ../ROADMAP.md to traverse up one directory from docs/.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/roadmap.md
Line: 1
Comment:
**Broken symlink — roadmap page will still 404**
The symlink `docs/roadmap.md` has a relative target of `ROADMAP.md`. Since symlinks are resolved relative to the directory containing the symlink, the OS looks for `docs/ROADMAP.md`, which doesn't exist — only `ROADMAP.md` at the repository root does. The correct target should be `../ROADMAP.md` to traverse up one directory from `docs/`.
How can I resolve this? If you propose a fix, please make it concise.| cargo install --version 0.9.1 mdbook-linkcheck2 | ||
| cargo install --version 0.8.0 mdbook-alerts | ||
| cargo install --version 0.15.0 mdbook-mermaid | ||
| cargo install --version 0.10.0-alpha mdbook-katex |
There was a problem hiding this comment.
mdbook-katex is pinned to 0.10.0-alpha, a pre-release version, while the other dependencies use stable releases. Alpha versions can have undocumented breaking changes or be yanked from crates.io. Consider using the latest stable release of mdbook-katex instead.
Prompt To Fix With AI
This is a comment left during a code review.
Path: Makefile
Line: 208
Comment:
**Alpha pre-release dependency in CI**
`mdbook-katex` is pinned to `0.10.0-alpha`, a pre-release version, while the other dependencies use stable releases. Alpha versions can have undocumented breaking changes or be yanked from crates.io. Consider using the latest stable release of `mdbook-katex` instead.
How can I resolve this? If you propose a fix, please make it concise.
🤖 Claude Code ReviewNow I have everything I need. Here is the full review: PR Review:
|
There was a problem hiding this comment.
Pull request overview
Updates the documentation toolchain to mdBook 0.5.2, removes the now-unneeded alerts plugin, and adjusts docs content/links to eliminate build warnings and fix the roadmap page link/redirects.
Changes:
- Bump CI mdBook version to 0.5.2 and update installed mdBook plugins (dropping
mdbook-alerts). - Fix mdBook warnings by escaping
$(KaTeX) and[](incomplete link/reference parsing) in docs pages. - Fix the roadmap navigation link and add an HTML redirect for legacy roadmap URLs.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
docs/l2/stages.md |
Escapes $ amounts to avoid KaTeX/math parsing warnings. |
docs/developers/l1/dashboards.md |
Escapes [] text to avoid link/reference warnings. |
docs/SUMMARY.md |
Points “Roadmap” to the in-book docs/roadmap.md page. |
book.toml |
Removes alerts preprocessor config and adds redirect for legacy /ROADMAP.html. |
Makefile |
Updates docs plugin versions and removes mdbook-alerts from docs-deps. |
.github/workflows/pr-main_mdbook.yml |
Bumps CI mdBook version to 0.5.2. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| cargo install --version 0.9.1 mdbook-linkcheck2 | ||
| cargo install --version 0.8.0 mdbook-alerts | ||
| cargo install --version 0.15.0 mdbook-mermaid | ||
| cargo install --version 0.10.0-alpha mdbook-katex |
| cargo install --version 0.10.0-alpha mdbook-katex | ||
| cargo install --version 0.12.0 mdbook-linkcheck2 | ||
| cargo install --version 0.17.0 mdbook-mermaid |
🤖 Codex Code Review
Assumption: I’m assuming No Ethereum execution, consensus, trie, RLP, or gas-accounting code is touched here; the review concerns are limited to docs build correctness and CI coverage. Automated review by OpenAI Codex · gpt-5.4 · custom prompt |
Motivation
mdbook recently released a new major version 0.5
Description
This PR bumps the mdbook version to the latest (0.5.2), fixes some warnings when running
make docs, and also fixes a 404 error when loading the roadmap page.One of the major changes from 0.5 is adding support for admonitions, so the mdbook-alerts plugin is no longer needed and was removed.