Skip to content
Notes

mdbook extentions

Mdbook Extensions in Practice (Setup Cheatsheet)

Section titled “Mdbook Extensions in Practice (Setup Cheatsheet)”

Enable Common Preprocessors in Book.toml

Section titled “Enable Common Preprocessors in Book.toml”
[preprocessor.mermaid]
command = "mdbook-mermaid"


[preprocessor.admonish]
command = "mdbook-admonish"


[preprocessor.katex]
command = "mdbook-katex"


[preprocessor.pagetoc]
command = "mdbook-pagetoc"

Order matters: run after built-in links so includes are expanded first.

[preprocessor.katex]
after = ["links"]

Only run some preprocessors for HTML.

[preprocessor.mermaid]
renderers = ["html"]

HTML Renderer Settings

Section titled “HTML Renderer Settings”
[output.html]
default-theme = "rust"
mathjax-support = false  # Use true if you prefer MathJax over KaTeX.
additional-js = ["mermaid.min.js", "mermaid-init.js"]  # `mdbook-mermaid install` writes these.
Section titled “Popular Plugins: Quick Notes”
  • mdbook-katex: pre-renders math to HTML for fast loads, no client JS. mdbook-katex
  • mdbook-mermaid: adds Mermaid diagrams; mdbook-mermaid install wires assets + config. mdbook-mermaid
  • mdbook-admonish: Material-style callouts via admonish info .... mdbook-admonish
    Tip for mdbook test: set [preprocessor.admonish.renderer.test].render_mode = "strip".
  • mdbook-plantuml / mdbook-graphviz: render UML or DOT to SVG/PNG. mdbook-plantuml mdbook-graphviz
  • mdbook-pagetoc: page-local ToC; writes pagetoc.css/js on first build. mdbook-pagetoc
  • mdbook-linkcheck: run as a backend in CI to fail builds on broken links. mdbook-linkcheck

Extra Outputs (Renderers)

Section titled “Extra Outputs (Renderers)”

Choose one or more; configure under [output.*]

[output.epub]  # mdbook-epub
[output.pdf]   # mdbook-pdf; requires headless Chrome available in PATH.
[output.pandoc]  # mdbook-pandoc; bridge to LaTeX and many formats.

Writing Your Own Preprocessor (Outline)

Section titled “Writing Your Own Preprocessor (Outline)”
  • Binary name: mdbook-<name>. Discovery via [preprocessor.<name>].
  • Handshake: mdbook-<name> supports <renderer> exit code 0/1.
  • Data flow: mdBook → stdin: [context, book] JSON; plugin → stdout: book JSON.
  • Order control: before/after; scope: renderers = ["html", "epub", ...].
  • Not just Rust: any language that can read/write JSON over stdio.
  • Scaffold: mdbook-preprocessor-boilerplate. mdbook-preprocessor-boilerplate

[Copy into AI Mdbook Extension](copy into ai mdbook extention.md)
[PDF Mdbook Extension](pdf mdbook extention.md)
[Drawio Mdbook Extension](drawio mdbook extention.md)
[Autosummary Mdbook Extension](autosummary mdbook extention.md)
[Callouts Mdbook Extension](callouts mdbook extention.md)