docs: migrate from mdBook to Material for MkDocs#159
Open
YuanYuYuan wants to merge 14 commits intomainfrom
Open
docs: migrate from mdBook to Material for MkDocs#159YuanYuYuan wants to merge 14 commits intomainfrom
YuanYuYuan wants to merge 14 commits intomainfrom
Conversation
Replace book/ (mdBook) with docs/ (Material for MkDocs):
- Reorganize content into getting-started/, core-concepts/, user-guide/,
tools/, bindings/, experimental/, reference/ sections
- Inline all {{#include}} directives from example source files
- Convert mdbook-admonish blocks to MkDocs admonition syntax (!!! / ???)
- Fix all cross-section relative links and broken fence fragments
- Add mkdocs.yml with Material theme, Mermaid via superfences, nav tree
- Replace mdbook-preview.yml with mkdocs-preview.yml
- Update docs.yml CI to build/deploy with mkdocs build --strict
- Update flake.nix docTools: mdbook -> mkdocs-material + pymdown-extensions
- Update crate README links to new URL structure
- Add site/ to .gitignore
mkdocs build --strict passes. All pre-commit hooks pass.
- networking.md: change rust,ignore to rust to fix #running-the-zenoh-router anchor - quick-start.md: rewrite with clean fenced blocks (fix Option 2 anchor + broken mdBook includes) - protobuf.md: fix Troubleshooting section (broken ??? question blocks from mdBook includes) - python.md: fix broken pub/sub, service, action code blocks from mdBook include fragmentation - Add markdownlint-disable MD046 where MkDocs admonition indentation conflicts with CommonMark
- Replace plain index.md with a custom Material for MkDocs home page:
hero section with Zenoh dragon logo, 9 feature cards (all clickable),
architecture iframe, "Choose Your Path" routing cards, CTA section
- Fix 115 rust,ignore fences across 18 files — pymdownx.superfences
does not support the ,ignore suffix, rendering all affected blocks
as raw text; replacing with rust fixes syntax highlighting and
resolves secondary heading corruption in shm.md
- Add mermaid diagram support via ES module loader with Material
document$ hook and dark/light theme awareness
- Add architecture.html (copied from book/src) for homepage iframe
- Add Python Quick Start page (mirrors existing Go Quick Start)
- Restructure nav for better user journey:
- Running Examples moved to Getting Started
- Parameters reordered before Lifecycle Nodes in Core Concepts
- Configuration grouped as sub-section (Options + Advanced)
- Messages & Serialization sub-section (Message Cache, Generation,
Custom Messages, Protobuf)
- Language Bindings split into Python/Go sub-groups
- rmw_zenoh_rs and Key Expression Formats moved to Reference
- Experimental renamed to Advanced Topics (SHM only)
- Nix Development moved to Reference
- Set dark mode (slate) as default palette
- Switch primary/accent color to indigo (Material default)
- Add custom home.css with hero, feature cards, path cards, CTA,
architecture frame, floating dragon animation, responsive layout
|
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
- Replace all ROS-Z occurrences with ros-z across docs - Replace the first standalone Zenoh mention in each of the 25 doc pages with Eclipse Zenoh per the branding agreement - Fix article: 'a Eclipse Zenoh' → 'an Eclipse Zenoh' where applicable
- Add vale to docTools in flake.nix for prose linting - Fix 6 truncated ??? question headings in troubleshooting.md - Fix protobuf.md: broken protobufsyntax fence and malformed MessageTypeInfo impl block - Expand config-advanced.md: annotated JSON5 session config example, common customisations (remote router, TLS, multi-router, timeout), config validation workflow - Expand nix.md: prerequisites, step-by-step usage, troubleshooting section with three common issues
Adds .vale.ini and custom vocabulary so Vale v3 can lint all docs/ without false-positive spelling errors on project-specific terms (Zenoh, protobuf, ROS 2 package names, Rust types, etc.). Vale.Terms is disabled to avoid case-enforcement noise in technical docs. Run with: vale docs/
Adds local write-good Vale style (Weasel, Passive, TooWordy rules) and fixes all 14 weasel word warnings across 8 files — removing filler words like 'rather', 'simply', 'very', 'just', 'actually', 'Various'. 74 passive voice warnings remain; passive is acceptable in technical docs.
Rewrites ~55 passive constructions to active voice throughout the docs. 8 remaining warnings are in Markdown table cells where passive is appropriate and cannot be cleanly rewritten.
Each core concept chapter now opens with a detailed explanation of the underlying ROS 2 concept — what it is, when to use it, how it works, and how it compares to alternatives. Readers no longer need to consult official ROS 2 docs. - pubsub.md: pub/sub model, bus analogy, type safety, QoS presets table - services.md: RPC model, .srv format, service vs topic vs action table - actions.md: goal/feedback/result model, .action format, lifecycle, cancellation - parameters.md: node-scoped config, declaration/enforcement, callback stages - networking.md: ROS 2 discovery phases, why Zenoh replaces DDS multicast
…t pages Adds a custom CSS/JS flashcard component (3D flip-on-click) and inserts concept flashcard decks into the four core concept chapters: - pubsub.md: 6 flashcards + message flow sequence diagram - services.md: 6 flashcards (QoS, pull model, server constraint, etc.) - actions.md: 6 flashcards + execution timeline sequence diagram - parameters.md: 6 flashcards (scope, types, callbacks, atomicity, etc.) Uses only allowed HTML elements (div, strong, p, a) to satisfy markdownlint
Rewrites all four "What is X?" concept intro sections to lead with mermaid diagrams and short bullets instead of multi-sentence paragraphs: - pubsub.md: LR topic graph, message flow sequence, type safety block, QoS table - services.md: request/response sequence, decision flowchart, .srv format, no-server timeout diagram - actions.md: 4-channel flow graph, goal state diagram, cancellation contract, type-state diagram - parameters.md: node ownership graph, 9-types graph, 3-stage validation pipeline sequence
Replace multi-sentence prose walls in all four core concept pages with
leading diagrams, short bullet summaries, comparison tables, and
step-by-step visual flows.
pubsub.md: topic graph, message flow sequence, type safety block, QoS table
services.md: request/response sequence, decision flowchart, .srv + Rust trait,
no-server timeout diagram
actions.md: 4-channel flow graph, .action format, goal state diagram,
cancellation contract, type-state pipeline
parameters.md: node ownership graph, 9-types graph, 3-stage validation
pipeline sequence, auto-created services table
Also fixes Vale vocabulary to resolve all spelling false positives in
newly added HTML/mermaid content.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Migrate documentation from mdBook to Material for MkDocs, redesign the home page with a custom hero/feature layout, fix all rendering issues from the migration, and restructure the navigation for a better user journey.
Key Changes
mkdocs.yml, removebook/tree, update all CI workflows (docs.ymlpublishes to GitHub Pages on merge,mkdocs-preview.ymldeploys PR previews)docs/overrides/home.html+docs/stylesheets/home.css): hero with Zenoh dragon logo and floating animation, 9 clickable feature cards, interactive architecture iframe, "Choose Your Path" routing cards, CTA section; dark mode (indigo) set as defaultrust,ignorefences across 18 files — pymdownx.superfences does not support the,ignoresuffix, which rendered all affected blocks as raw text and caused heading corruption inshm.mddocs/javascripts/mermaid.js) with Materialdocument$hook and dark/light theme switchingquick-start.md,protobuf.md,python.md— mdBook{{#include anchor}}directives produced interleaved orphan fences that were not valid MkDocs markdownrmw_zenoh_rsand Key Expression Formats moved to Reference; Experimental renamed to Advanced Topics; Nix Development moved to Referencedocs/bindings/python-quick-start.md) mirroring the existing Go Quick Startdocs/architecture.html(interactive 3D architecture diagram) embedded in home page via full-width iframeBreaking Changes
None — documentation-only change, no API or code changes.