Overview of #542: Zensical — a modern static site generator (Talk Python To Me)
This episode features Martin Donnorf (aka Squidfunk), creator of Material for MkDocs, discussing Zensical — a new, open source static site generator he and his team built to replace the gaps they hit with MkDocs. Zensical has a Rust core for extreme speed, a modular architecture to avoid plugin incompatibilities, strong compatibility goals for migrating existing MkDocs/Material projects, and a focus on modern design and docs-first authoring.
Key topics covered
- What Zensical is and who it's for (documentation-first static site generator)
- Why Martin moved from Material for MkDocs to building Zensical
- Architecture: Rust runtime (ZRX), modules-first design, Python bindings via PyO3
- Differential builds and dramatic performance improvements
- Markdown handling, planned move from Python Markdown to CommonMark/MDX-like components
- Search engine "Disco" (client-side index, tie-breaking ranking)
- Themes, components, and the planned asset pipeline
- Migration and compatibility strategy for MkDocs + Material projects
- Funding and sustainability: moving from SponsorWare to “Zensical Spark”
- Developer tooling decisions and dependency philosophy
Main takeaways / features & differentiators
Performance — differential builds (Rust runtime)
- Zensical’s core runtime (ZRX) is written in Rust to manage orchestration, caching, parallelization and differential builds.
- Differential builds: only rebuild changed pages and their dependents, so edits can show up in milliseconds instead of whole-site minutes-long rebuilds.
- Target is to scale from a single page to sites with 100,000+ pages.
Modular architecture — "modules all the way down"
- Zensical implements core features as modules rather than the ad-hoc plugin hooks typical of MkDocs.
- Modules are replaceable/extendable; third-party modules are encouraged.
- You can write modules in Python (via PyO3 bindings) or Rust — no need to learn Rust to extend Zensical.
Markdown, components and richer authoring
- Currently uses Python Markdown for compatibility with Material for MkDocs, but Zensical plans to move to a CommonMark-based parser and a components system (MDX-like) so richer components and attributes/classes are easy to use.
- Intention: keep Markdown simple for writers, while offering optional richer blocks/components for advanced layout and interactivity.
- Visual/WYSIWYG editor (WYSIWYG) and knowledge management are stretch goals.
Search — Disco
- Zensical ships a search project called Disco (open source), designed for fast, relevant client-side search.
- Disco uses a tie-breaking ranking strategy (title → path → body, configurable) instead of plain BM25 bag-of-words, improving autocomplete and relevance.
- For most docs sites Disco ships a small JSON index (gzipped ≈ 200 KB), enabling very fast client-side search without a paid service.
- Martin reports Disco is ~20× faster than Material’s previous search.
Design, components & themes
- Focus on modern, brandable design and many built-in components for technical documentation (admonitions, tabs, code blocks, diagrams, icon/emoji integration).
- Code annotations are a signature feature (bubbles attached to code lines that open rich Markdown tooltips).
- Themes will be packaged as source with an integrated asset pipeline (no separate precompile step), more configurable media queries, and component-level/differential rendering in the future.
Compatibility & migration
- Zensical aims to read mkdocs.yml and be as compatible as possible to ease migration from MkDocs/Material.
- Full plugin parity is a work in progress; mapping mkdocs plugin configs to Zensical modules is planned.
- Migration tooling and stepwise compatibility are core goals — important for large orgs with many projects.
Business & sustainability — Zensical Spark
- Zensical is MIT-licensed and open source; the previous pay-for-early-features SponsorWare model used for Material is being retired.
- Zensical Spark: a commercial support/community tier where companies get a seat to influence roadmap (ZAPs — Zensical Advancement Proposals), priority support, and collaboration on enterprise needs.
- Spark is positioned as collaborative product shaping + professional services (not paywalled features).
Origin story (why start from scratch)
- Material for MkDocs became very popular, but MkDocs’ architecture (templating-first, plugin limitations, slow builds) constrained what Martin wanted to build.
- MkDocs 2.0 took a direction incompatible with many Material ecosystem plugins; forking MkDocs and moving the whole ecosystem wasn’t feasible.
- The team prototyped alternatives, concluded they needed a fresh architecture, and rebuilt in Rust with a compatibility/migration plan.
Notable quotes & insights
- “It’s a tool to build beautiful websites from a folder of text files.” — succinct purpose statement.
- “Differential builds mean that we are only rebuilding what changed… changes are visible in milliseconds and not minutes.” — core UX/value prop.
- “Modules all the way down.” — emphasis on modularity vs fragile plugin orchestration.
- “Everything is open source from the start. We are saying goodbye to pay-for-features.” — important policy change vs Material’s SponsorWare era.
Practical notes for developers & maintainers
- Zensical is targeted at documentation teams, technical writers, and devs who want docs-as-code with less friction.
- You can write modules in Python via PyO3 — Rust knowledge is optional for most extension work.
- Some Material/MkDocs features are already supported; full plugin parity is ongoing. Test migrations before switching production sites.
- Disco search is an independent open source project to watch for other static site use cases.
Action items / how to get involved
- Try Zensical on new projects or test-building an existing MkDocs/Material site (Zensical can read mkdocs.yml).
- Join the Zensical community: public Discord, newsletter for monthly updates.
- For organizations: consider Zensical Spark to influence roadmap, get migration & support help.
- Watch for Disco (search) and component/CommonMark releases if you rely on advanced search or Markdown extensions.
Where Zensical is headed
- Finish module system and CommonMark/component support (MDX-like features).
- Improve theme/component tooling and asset pipeline with component-level/differential rendering.
- Continue expanding plugin/module compatibility and migration tooling for large ecosystems.
- Grow enterprise adoption via Spark while keeping core project open source.
If you’re migrating from Material for MkDocs or evaluating static site generators for documentation, Zensical is worth trying now (especially for its performance and search), and you should subscribe to their newsletter or join the Discord to track compatibility and migration tooling as they mature.