mdBook parity A–E: pipeline, SUMMARY, CLI, output, themes

[AlexMikhalev]

See Gitea PR. Increments A–E of mdBook parity. Refs issues 1–5.

[github-actions]

🚀 Deployment Preview

Your changes have been deployed to Cloudflare Pages!

🔗 Preview URL: https://preview-27.md-book.pages.dev

The deployment will be updated automatically when you push new changes to this PR.

[github-actions]

🚀 Deployment Preview

Your changes have been deployed to Cloudflare Pages!

🔗 Preview URL: https://preview-27.md-book.pages.dev

The deployment will be updated automatically when you push new changes to this PR.

[github-actions]

🚀 Deployment Preview

Your changes have been deployed to Cloudflare Pages!

🔗 Preview URL: https://preview-27.md-book.pages.dev

The deployment will be updated automatically when you push new changes to this PR.

[github-actions]

🚀 Deployment Preview

Your changes have been deployed to Cloudflare Pages!

🔗 Preview URL: https://preview-27.md-book.pages.dev

The deployment will be updated automatically when you push new changes to this PR.

[github-actions]

🚀 Deployment Preview

Your changes have been deployed to Cloudflare Pages!

🔗 Preview URL: https://preview-27.md-book.pages.dev

The deployment will be updated automatically when you push new changes to this PR.

[github-actions]

🚀 Deployment Preview

Your changes have been deployed to Cloudflare Pages!

🔗 Preview URL: https://preview-27.md-book.pages.dev

The deployment will be updated automatically when you push new changes to this PR.

[github-actions]

🚀 Deployment Preview

Your changes have been deployed to Cloudflare Pages!

🔗 Preview URL: https://preview-27.md-book.pages.dev

The deployment will be updated automatically when you push new changes to this PR.

[github-actions]

🚀 Deployment Preview

Your changes have been deployed to Cloudflare Pages!

🔗 Preview URL: https://preview-27.md-book.pages.dev

The deployment will be updated automatically when you push new changes to this PR.

[AlexMikhalev]

Summary

Brings md-book to contract parity with mdBook across increments A–E, plus E7 (conditional mermaid) and a large body of defect fixes found by reviewing and then actually running the output in a browser.

Key changes:

• src/book/ — a real Book/BookItem/Chapter model parsed from SUMMARY.md, replacing structure inferred from a path-sorted walkdir. Prefix/suffix chapters, part titles, nesting, drafts, separators, section numbering and summary-driven exclusion all derive from one source. Directory-walk fallback retained, selected by the presence of SUMMARY.md, so no existing book breaks.
• src/pipeline/ — the former 250-line build_sync_impl_sync split into collect → preprocess → render → index, with preprocess.rs left as an identity seam for the deferred P2 directive work.
• src/paths.rs + src/main.rs — build|serve|watch|init|clean [dir] subcommands honouring book.src / build.build-dir, with -i/-o retained as overrides.
• Output correctness — path_to_root on every URL, server-side heading IDs, 404 page, vendored Shoelace (356KB subset, not the 14MB distribution), and default css/js/img/components embedded via include_dir so an installed binary emits a complete book.
• src/watch.rs — SelfWriteFilter, so create-missing stubs no longer trigger their own rebuild.

Done well: the book model is the right abstraction and everything else reads from it; the NavEntry open/close deltas are a neat answer to Tera's lack of recursion; path containment in book_from_summary covers symlinked ancestors, which is more than the specification asked for; and the test suite grew from substring assertions to structural fixtures plus browser-verified behaviour (134 tests across seven targets).

Issues from prior rounds that are now resolved:

• B round 1 (3/5): symlink escape in summary path resolution — fixed and covered by test_create_missing_rejects_symlink_escape.
• C/D/E round 1 (2/5): redirect from path traversal and unescaped to — both fixed; the writer now rejects absolute/parent paths, canonicalises the parent against the build root, and escapes with encode_double_quoted_attribute.
• Session review (8 findings): red e2e test, silent empty-book builds, half-applied path_to_root, unstyled books from an installed binary, missing config defaults, unreachable error variant, duplicate config loader, missing regression guards — all fixed, each with a test.

What remains problematic clusters around internationalisation and the 404 page: heading slugs discard all non-ASCII, so every heading in a non-Latin book collapses to section-N; and the 404 page uses relative asset paths, which breaks in the only scenario where a 404 page is served. Two config keys (input-404, site-url) still parse and do nothing, and are missing from the new unsupported-key warning list.

Confidence Score: 3/5

• Safe to merge with caution — two P1 findings should be addressed before or shortly after merging.
• Zero P0. Neither P1 risks data loss or security: they are correctness gaps that make two features (fragment links in non-English books; the 404 page outside the site root) not work as intended. The four P2 findings are hygiene and observability. Cumulative risk is well below where it started this round — every P0/P1 from prior rounds is resolved and covered by tests.
• Files needing attention: src/render/slug.rs, src/templates/404.html.tera and its context in src/pipeline/mod.rs, src/config.rs (warning list).

Important Files Changed

Filename	Overview
src/book/summary.rs	SUMMARY.md parser: collects all errors in one pass, rejects duplicates, non-.md targets and paths escaping src/ (symlinks included). Clean; no findings.
src/book/mod.rs	Book model, section numbering, to_nav with open/close deltas. to_nav runs per page — O(pages × chapters); fine at corpus size, see P2-4.
src/pipeline/mod.rs	Stage sequencing, orphan warnings, asset pass-through, 404, redirects, print. Redirect hardening looks correct now. 404 context passes path_to_root: "" — see P1-2.
src/render/slug.rs	Heading slugs and ID injection. Discards non-ASCII — see P1-1. Per-call collision counter causes duplicate IDs in print.html — see P2-2.
src/render/html.rs	Tera context assembly, path_to_root, embedded-asset writing, copy_tree. Sound.
src/render/markdown.rs	mdast splice + syntect, plus has_mermaid detection at fence level (not by scanning HTML — correct choice). Extra mdast parse per page, see P2-4.
src/config.rs	Hand-written Default impls (the serde defaults never fired), fill_unset_with_defaults, unsupported-key warnings. Two keys missing from the list — see P2-1.
src/watch.rs	Self-write suppression; consumed on match so real edits still rebuild. Good.
src/main.rs	Subcommand dispatch; now delegates config loading to the library. serve -n silently falls back — see P2-3.
src/server.rs	Adds serve_book_on with a bind address. See P2-3.
src/templates/*.tera	Relative URLs throughout, theme picker, gated mermaid, guarded optional links. 404 template — see P1-2.
src/templates/vendor/shoelace/**	356KB vendored subset (transitive import closure of five components + 12 icons). Verified: all 44 modules resolve under a sub-path.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["CLI: build|serve|watch|init|clean [dir]"] --> B["paths::resolve + validate_for_build"]
    B --> C["config::load_config_from<br/>defaults fill + unsupported-key warnings"]
    C --> D{"src/SUMMARY.md exists?"}
    D -- yes --> E["book::summary::parse_summary<br/>collect all errors"]
    D -- no --> F["book::directory::book_from_directory<br/>legacy walk"]
    E --> G["book_from_summary<br/>path containment + create-missing"]
    G --> H["Book { items }"]
    F --> H
    H --> I["pipeline::preprocess<br/>(identity seam; P2 directives land here)"]
    I --> J["render::markdown<br/>mdast splice + syntect + has_mermaid"]
    J --> K["render::slug::inject_heading_ids"]
    K --> L["render::html<br/>nav tree + path_to_root + theme attrs"]
    L --> M["index / print / 404 / redirects"]
    M --> N["copy_tree + embedded assets"]
    N --> O["pagefind index (optional)"]
    G -.->|created stub paths| P["watch::SelfWriteFilter<br/>drops self-inflicted events"]

    style K fill:#f8d7da,stroke:#dc3545
    style M fill:#f8d7da,stroke:#dc3545
    style H fill:#d4edda,stroke:#28a745
    style P fill:#d4edda,stroke:#28a745

Loading

Red: components carrying this round's P1 findings. Green: the new abstractions this PR is built on.

Inline Findings

P1 src/render/slug.rs, line 10: Heading slugs discard all non-ASCII, so non-Latin books lose every anchor

slugify keeps only c.is_ascii_alphanumeric(). Any heading without ASCII letters produces an empty slug and falls back to the literal "section", then section-1, section-2, … Verified on a real build:

# Café              -> id="caf"
## Обзор            -> id="section"
## 日本語の見出し     -> id="section-1"

Consequences: cross-page fragment links ([see](page.md#обзор)) can never resolve; the on-page TOC produces meaningless anchors; Pagefind result anchors point at section-N. Every heading in a Cyrillic, Greek, Hebrew, Arabic or CJK book is affected — and book.language exists precisely to support those books. GitHub's slugger, which the doc comment claims compatibility with, preserves Unicode letters and only strips punctuation.

Relatedly, test_slugify_matches_github asserts only "Hello World", "Hello, World!" and "Foo_bar" — all ASCII — so it does not establish the compatibility the name and doc comment claim.

Suggested fix: keep alphanumerics by Unicode category rather than ASCII, lowercase via to_lowercase(), and strip only punctuation/symbols:

if c.is_alphanumeric() {
    slug.extend(c.to_lowercase());
    prev_dash = false;
} else if (c.is_whitespace() || c == '-' || c == '_') && !prev_dash && !slug.is_empty() {
    slug.push('-');
    prev_dash = true;
}

and extend the test with a non-ASCII case.

P1 src/templates/404.html.tera, line 9 (context: src/pipeline/mod.rs, ctx.insert("path_to_root", &"")): The 404 page only works at the site root, which is the one place it is not needed

404.html is written at the build root with path_to_root = "", so its assets and home link are relative: css/styles.css, index.html. A server returns that single file for any unmatched path, and the browser resolves relative URLs against the request path. A request for /docs/guide/missing.html therefore fetches /docs/guide/css/styles.css (404) and the "Back to home" link points at /docs/guide/index.html.

Net effect: the 404 page renders unstyled with a broken escape route in exactly the nested-path case where it is served. output.html.site-url exists for this — it is mdBook's documented answer to the same problem — but is currently parsed and unused (see P2-1).

Suggested fix: when site-url is set, emit absolute asset paths in the 404 template only; otherwise keep the relative form and note the limitation in the README.

P2 src/config.rs, line ~330 (UNSUPPORTED list): input-404 and site-url parse, do nothing, and do not warn

The new unsupported-key warnings cover nine keys, but output.html.input-404 and output.html.site-url are used nowhere outside config.rs and are absent from the list. They are the exact failure mode the warning system was added to eliminate: an author sets input-404 = "not-found.md", no custom 404 is produced, and nothing says so.

Either implement them (they pair naturally with P1-2) or add both to UNSUPPORTED with "not implemented yet".

P2 src/render/slug.rs, line 37 (inject_heading_ids): print.html contains duplicate heading IDs

inject_heading_ids allocates a fresh seen map per call, and the print page renders each chapter with a separate call, so identical headings across chapters produce identical IDs in one document. Verified:

$ rg -o 'id="[^"]*"' print.html | sort | uniq -c
      2 id="overview"

Duplicate IDs are invalid HTML and make in-page anchors ambiguous. Fix by threading one collision map through the print assembly (an inject_heading_ids_with(&mut seen, html) variant), leaving the per-page path unchanged.

P2 src/server.rs, line 39: serve --hostname silently falls back to localhost while claiming otherwise

hostname.parse::<IpAddr>() fails for anything that is not an IP literal, and the error is swallowed in favour of 127.0.0.1 — yet line 43 prints the string the user supplied. md-book serve -n myhost.local reports "Serving book at http://myhost.local:3000" while listening only on loopback.

0.0.0.0 and IP literals work, so the common container case is fine; the failure is confined to DNS names. Suggested fix: report the parse failure and either exit or print the address actually bound.

P2 src/book/mod.rs (to_nav) and src/render/markdown.rs (has_mermaid_fence): Per-page costs added without the benchmark the plan gated on

to_nav is called once per page and walks the whole chapter tree, so navigation rendering is O(pages × chapters); has_mermaid_fence adds a second mdast parse per page. Both are defensible (correctness and single-definition respectively) and both are documented in the code. The plan's increment A recorded a benches/pagefind_bench.rs baseline specifically so these could be compared, but no post-change measurement is recorded anywhere in the PR.

Not a blocker at corpus size (30 pages), but the gate should either be met or explicitly waived. Note also that benches/pagefind_bench.rs:324 panics on main and is not run by CI, so the benchmark harness itself needs a fix before it can answer this.

Comments Outside Diff (2)

1. benches/pagefind_bench.rs, line 324 — panics with "Unexpected error" when the MultipleConfigs case does not trigger. Pre-existing on main and not covered by CI (which runs cargo test, and the bench declares harness = false). It blocks the performance verification this PR's plan calls for.

2. .github/workflows/ci.yml — the feature matrix gained the single-feature combinations in this PR, which is what exposed three latent build breaks (search, watcher and core each relied on another feature to supply a dependency). Worth keeping in mind that the matrix still omits server-only and no-feature builds, both of which do currently compile.

_{Last reviewed commit: 20e20e4 | Reviews (4)}

[AlexMikhalev]

Summary

Re-review after 4a83c34, which addresses every finding from round 4.

All six findings are resolved, each verified on a real build rather than by reading the diff:

• P1 Unicode slugs — slugify now keeps Unicode alphanumerics and lowercases via to_lowercase(). Verified: # Café → id="café", ## Обзор → id="обзор", ## 日本語の見出し → id="日本語の見出し", where all three previously collapsed to caf / section / section-1. The misleading doc comment and the ASCII-only test_slugify_matches_github are corrected, and test_slugify_keeps_unicode_letters pins the behaviour.
• P1 404 page — now uses output.html.site-url (falling back to book.base_url) for absolute asset and home-link URLs, keeping the relative form when neither is set. Verified both ways: with site-url = "/docs/" the page emits href="/docs/css/styles.css"; without it, href="css/styles.css".
• P2 input-404 / site-url — implemented rather than added to the warning list. input-404 supplies the 404 body, and its source file is excluded from the orphan-markdown warning (it was producing a false positive).
• P2 duplicate print IDs — chapters share one collision namespace via the new inject_heading_ids_with. Verified: no repeated id="overview" in print.html.
• P2 silent hostname fallback — hostnames resolve through to_socket_addrs, an unresolvable name is a hard error, the bound address is printed alongside the requested one, and a server that cannot bind now exits non-zero rather than leaving a live process with a dead listener.
• P2 unevidenced performance gate — the bench target that was meant to answer it panicked because it asserted PagefindError::MultipleConfigs, a variant PagefindBuilder::new has never constructed. Bench fixed; measurements recorded in the plan.

The performance work deserves note because it changed a decision. Measuring showed the corpus build at 139 ms against 100 ms on main, missing the plan's 10% gate. Profiling the gap found one avoidable cost — has_mermaid re-parsed each page's mdast, which the syntax-highlighting path already walks — worth 12 ms, bringing it to 127 ms. The residual +27% is attributed rather than hidden: the branch writes 4.2 MB of assets per build that main never wrote at all, since emitting no css/, js/ or img/ was the defect increment D fixed. Scaling data at 50/200/500 pages is now in the plan; per-page cost doubles by 500 pages, but that term is inherent to embedding a full sidebar in every page, which mdBook does too.

Remaining suggestions (none blocking, none new):

• The dead PagefindError::MultipleConfigs and InvalidConfigFormat variants are still declared and never constructed. Left in place deliberately rather than removed as part of a review fix — they are public API.
• Increment G (page metadata, canonical URL, skip link, search gating) is planned and tracked as #8; the search modal still ships even when no Pagefind index exists.

Confidence Score: 5/5

• Safe to merge with minimal risk.
• All P0/P1 findings from prior rounds are resolved, each with a regression test, and the remaining items are tracked follow-ups rather than defects in this diff. The test suite is now 138 tests across seven targets, and this round's fixes were verified against built output and a headless browser rather than by inspection.
• No files require special attention.

Important Files Changed

Filename	Overview
src/render/slug.rs	Unicode-preserving slugs; inject_heading_ids_with added for shared collision namespaces. Two new tests, one covering punctuation and symbols.
src/pipeline/mod.rs	404 now receives a site_url_prefix and optional input-404 body; print chapters share an id namespace; orphan warning excludes the 404 source.
src/templates/404.html.tera	Renders the custom body when configured, absolute URLs when site-url is set.
src/render/markdown.rs	Mermaid detection folded into the existing splice walk; the standalone predicate is retained for the non-highlighting path.
src/server.rs	Hostname resolution with a real error instead of a silent loopback fallback; prints the bound address.
src/main.rs	A failed bind exits non-zero.
benches/pagefind_bench.rs	The case asserting an unimplemented error variant now measures construction; the target runs again.
docs/plans/mdbook-parity-implementation-plan.md	Performance gate recorded as not met with attribution, plus the 1/30/50/200/500-page measurements.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["render_markdown(content)"] --> B{"syntax-highlighting?"}
    B -- yes --> C["process_markdown_with_highlighting<br/>one mdast walk"]
    C --> D["code node: highlight<br/>+ set saw_mermaid"]
    B -- no --> E["process_markdown_basic"]
    E --> F["has_mermaid_fence<br/>separate parse (no walk to reuse)"]
    D --> G["RenderedMarkdown { html, has_mermaid }"]
    F --> G
    G --> H{"page kind"}
    H -- chapter --> I["inject_heading_ids<br/>fresh namespace"]
    H -- print --> J["inject_heading_ids_with<br/>shared namespace"]
    I --> K["page.html: mermaid gated on has_mermaid"]
    J --> L["print.html: unique ids across chapters"]

    style C fill:#d4edda,stroke:#28a745
    style J fill:#d4edda,stroke:#28a745

Loading

Green: this round's changes — detection folded into the existing walk (removing a parse per page), and the shared id namespace for the print page.

Inline Findings

None. All findings from round 4 are resolved and covered by tests:

Round 4 finding	Resolution	Test
P1 Unicode slugs	is_alphanumeric + to_lowercase	test_slugify_keeps_unicode_letters, test_non_latin_headings_keep_addressable_ids
P1 404 relative URLs	site_url_prefix	test_404_uses_site_url_when_configured, test_404_falls_back_to_relative_without_site_url
P2 input-404 / site-url ignored	implemented	test_404_uses_site_url_when_configured
P2 duplicate print ids	shared namespace	test_print_page_heading_ids_are_unique
P2 silent hostname fallback	resolve or error	manual: serve -n nope.invalid exits 1 with a clear message
P2 unevidenced perf gate	bench fixed, measured, recorded	docs/plans/mdbook-parity-implementation-plan.md

_{Last reviewed commit: 4a83c34 | Reviews (5)}

[github-actions]

🚀 Deployment Preview

Your changes have been deployed to Cloudflare Pages!

🔗 Preview URL: https://preview-27.md-book.pages.dev

The deployment will be updated automatically when you push new changes to this PR.

[github-actions]

🚀 Deployment Preview

Your changes have been deployed to Cloudflare Pages!

🔗 Preview URL: https://preview-27.md-book.pages.dev

The deployment will be updated automatically when you push new changes to this PR.