Roadmap¶

We are building Zensical as a vertically integrated set of systems, which allows us to rethink all aspects of the authoring (AX), developer (DX) and user experience (UX), as we aim to deliver a comprehensive and coherent and expanding set of well-integrated solutions.

Our roadmap serves to make the overall trajectory of the project transparent to our users, and to help us prioritize high-value items to work on. Rather than promising concrete dates, we prefer to make our work transparent so you can track progress.

The items on this roadmap do not have a strict ordering or implied dates of completion.

Foundation¶

This section explores the core principles that form the foundation of Zensical. These aspects are crucial to understanding its characteristics and underlying philosophy. Temporary limitations are being actively addressed through our close collaboration with Zensical Spark members, who are integral partners in our development process.

Zensical is stable and ready for use, though it has not yet achieved complete feature parity with Material for MkDocs. We invite you to review our compatibility table for a detailed breakdown.

Rust runtime¶

The most important but least visible feature of Zensical is our next-generation architecture and runtime ZRX, that fundamentally redefines how static sites are built.

Rather than going the easy route of just porting MkDocs to Rust, we've invested thousands of hours, building a robust and efficient system from the ground up to address core limitations that have severely limited the progress we could make with Material for MkDocs' in the past years.

Key aspects

• Differential builds - Unlike traditional incremental builds that rebuild entire dependency chains when any file changes, our differential runtime tracks actual content changes and rebuilds only the specific artifacts that are truly affected. This unlocks near-instantaneous rebuilds even for massive documentation sites.

• Dynamic task orchestration - Our scheduler uses a workflow-based approach, breaking down the entire build process into discrete tasks with explicit dependencies. It replaces the implicit dependencies of MkDocs' plugin system – where plugins can mysteriously interfere with each other – with a transparent network of tasks that can be understood, debugged, and optimized.

• Automatic parallelization - Build processes are optimally distributed across available CPU cores without manual configuration, with both I/O and CPU-bound tasks running concurrently. Everything that can be parallelized is automatically parallelized, determined by the scheduler by analyzing the topology of the network of tasks, significantly reducing build times.

• Written in Rust – Built entirely in Rust, our new runtime represents a significant infrastructure investment that strives to balance performance, modularity and reliability. This positions Zensical to deliver capabilities that are impossible to achieve with conventional static site generators (SSGs) at scale, laying the foundation for all other features in the pipeline.¹

Modern design¶

A new, modern design is available alongside the classic Material for MkDocs look, breaking free from the Material aesthetic to create a more brandable foundation – you're looking at it right now. This makes it significantly easier for organizations to customize the looks, while giving a more contemporary feel without breaking existing projects or user expectations.

You can keep the original look of Material or MkDocs, or opt into the new, modern design.

Key aspects

• Identical layout – We continue to use the battle-tested layout of Material for MkDocs, so there are no big surprises when switching to Zensical. Additionally, we are working on a component system to add support for alternative and even completely custom layouts.

• Identical HTML output – The HTML output generated by Zensical is identical to that of Material for MkDocs, ensuring that existing content and customizations continue to work seamlessly. This means you can continue to use your existing JavaScript and CSS overrides.

• New mobile navigation – In the modern design, mobile navigation has been redesigned to be closer to the desktop version, improving usability and consistency.

• New icon set – Shipping all icons that Material for MkDocs provides, we are also introducing the Lucide icon set that is designed to be more modern and visually appealing.

Compatibility¶

Zensical is compatible with Material for MkDocs – when you run zensical build in your Material for MkDocs project, it will build your project as if it were an MkDocs project, as Zensical natively understands the mkdocs.yml configuration format.

All our work is guided by this principle: compatibility is key to a smooth transition.

Key aspects

• Identical Markdown dialect – Zensical uses Python Markdown, the same dialect that MkDocs depends on, ensuring compatibility of your existing content. While this requires Python interop for Markdown rendering (rather than native Rust), it enables seamless migration from Material for MkDocs without any content changes.

  We view this as a pragmatic bridge solution that prioritizes immediate usability, and currently explore switching to CommonMark in the near future. Of course, switching will be seamless for users, as we will provide automatic translation between both dialects.

• Identical template structure – We haven't changed the template structure, so your existing template overrides should work without modification.² Additionally, we switched the template engine from Jinja2 to minijinja, a Jinja implementation in pure Rust, which allows for templates to be rendered in parallel within our new Rust runtime.

  As mentioned above, we built an experimental prototype of a component system, which will provide much more flexibility than common template and partial-based systems.

• Integrated web server – Zensical includes a high-performance web server built in Rust that replaces MkDocs' rather basic HTTP server for previews. The server features an extensible easy-to-use middleware architecture, making it seamlessly compatible with our upcoming module system, enabling authors to add middlewares and routes with minimal effort.

Temporary limitations

• Navigation - Your site's navigation currently has to be explicitly defined in mkdocs.yml - this limitation will be resolved with our upcoming navigation redesign. The proposal is currently in draft stage, with design and implementation proceeding in collaboration with Zensical Spark members to ensure the solution works seamlessly across diverse documentation patterns.

• Plugins – Third-party plugins are not yet supported, but extensibility is fundamental to our architecture. We're developing a comprehensive module system that will replace traditional plugins with a more powerful and flexible approach.

  While the plugins setting is temporarily ignored in mkdocs.yml, we're actively implementing native Zensical modules that correspond to existing MkDocs plugins, including many of the most popular third-party plugins. Your migration will be complete once we've covered the specific plugins your project depends on.

  Check out the compatibility table for more information.

Feature parity¶

The next immediate goal of Zensical is to establish feature parity with Material for MkDocs, the documentation framework that we created, and are now moving away from, due to the technical limitations of MkDocs we've hit in the past years.

Zensical will support all features that Material for MkDocs supports, plus a whole lot more, including support for blogging, tagging, downloading of external assets for GDPR compliance, generation of social cards, search, and everything else.

Next up¶

This section outlines the upcoming features that are on our roadmap – it's where our vision starts coming to life. Now, we're developing the transformative features that were the initial motivation for Zensical, redefining the future of how documentation is created.

These features will be developed in close collaboration with all Zensical Spark members. Note that the following features are not just in ideation stage – we've already invested significant resources into architecture, design, and prototyping, but they're not yet ready for release.

Module system¶

It's modules all the way down - Zensical is built entirely from composable modules that implement functionality against a simple API, making every part of the build pipeline customizable, extensible, and even replaceable. Modules define the structure of the task graph through a stream-like API, stitching together a coherent build pipeline.

Key aspects

• Unlimited extensibility – Traditional plugin systems constrain developers to a handful of predefined extension points with semi-manual ordering that leads to fragile configurations and unexpected interactions. With Zensical, modules can inject, extend, or completely redefine functionality at any point in the processing pipeline.

  Topological ordering ensures dependencies are always satisfied. Modules can even be remixed, changing and adapting parts of their behavior to perfectly fit your requirements.

• Standard library – We're building a comprehensive standard library that eliminates boilerplate for module authors. Common operations like file I/O and HTTP requests are hoisted into a clean provider architecture, allowing developers to focus on their unique transformation logic rather than reimplementing basic functionality.

• Module interdependencies – Modules define explicit contracts specified through the types of artifacts they consume and produce, which ensures that interdependencies are always explicit. Tied modules can be automatically detected and resolved, reducing bugs related to ordering. Module priorities can be dynamically adjusted to resolve those conflicts.

• Intelligent build caching – Build artifact caching becomes completely transparent to module authors through automatic dependency tracking in the task graph. The Rust runtime intelligently caches intermediate results and reuses them when inputs remain unchanged, enabling instant previews even for massive documentation sites with tens of thousands of pages and complex processing pipelines.

• Non-destructive editing – Zensical will enable non-destructive editing of content, allowing authors to make changes without losing the original context or formatting. For instance, this allows to render proper HTML within navigation elements, something that MkDocs does not support, as it strips HTML too early.

• Python API – Language bindings to Python using PyO3, and possibly other languages, allow for creating extensions in those languages while leveraging the entirety of Zensical's module system. You won't need to learn Rust to extend Zensical in other languages, but you can always move parts of extensions to Rust at any time, if it becomes necessary.

• Native modules – Zensical will include a growing library of native modules that are maintained by the Zensical team, including search, API documentation, modular navigation, versioning, internationalization, subprojects and much more.

Search and discovery¶

Disco, our new modular and blazing fast search engine, is purpose-built for Zensical, and works in browsers, on servers, or at the edge, with robust offline capabilities, allowing for easy hosting in air-gapped environments. Of course, it's fully Open Source, so it can be integrated into a wide range of applications far beyond Zensical itself.

Key aspects

• Modular engine system - Disco's core architecture supports multiple specialized search engines operating simultaneously: inverted indexes for traditional text search, hierarchical filters for structured navigation, and vector search for semantic matching. Each engine can be configured independently while contributing to unified search results.

  The following functionality will be provided by built-in engines:

  • Inverted index for traditional text search
  • Hierarchical filtering (engine)
  • Vector search for semantic matching
  • Router to federate multiple search indexes
  • Integration of local and remote indexes

• Plugin-first design – Engines provide the core search infrastructure, but plugins deliver the advanced functionality through well-defined extension points, enabling dynamic capabilities like intelligent filtering, pagination, wildcard and fuzzy matching, custom ranking, and result transformation. Plugins are also dead-simple to write.

  The following functionality will be provided by built-in plugins:

  • Wildcard expansion
  • Highlighting of search terms
  • Ranking with tie-breaking and BM-25
  • Stemming and segmentation
  • Pagination of search results
  • Aggregations and faceting
  • Hierarchical filtering (plugin)
  • Fuzzy-search and auto-correct
  • Search suggestions and completions
  • Caching of search results

• Flexible ranking methods – Disco employs a completely customizable tie-breaking strategy that delivers consistent and flexible results for documentation search. It also includes classic BM25 as a built-in ranking method, which additionally supports proximity-based ranking for multi-word queries. However, for type-ahead search, tie-breaking proved to be unbeatable.

• Federated search – Search can be unified across multiple documentation projects by aggregating results from disparate indexes, which breaks down information silos to create a single, coherent body of knowledge for organizations with multiple products or services.

Component system¶

Moving from a templating system to a component architecture allows for much greater flexibility and reusability in documentation authoring. Zensical aims to replace Python Markdown and Jinja with a unified component system, which is then used to render templates, as well as to implement custom components that can be used in Markdown files.

We already have a working prototype for the component system, and plan to roll it out gradually, by first moving all templates into components, and then replacing the components inherited from Material for MkDocs one after another.

Key aspects

• Markdown and HTML AST – Zensical provides both, a Markdown and HTML AST, which allows for much simpler creation of extensions, as well as custom components.

  The Markdown AST allows content to be cleanly rendered into any format – including HTML, EPUB, PDF, and man pages – from a single source. This method is far superior to the regular-expression-based parsing used by many existing parsers, which is often brittle and limited.

• Self-contained components – Components are at the heart of Zensical's presentational system. Each component is a self-contained artifact that can be used in Markdown and templates, and can touch the following layers:

  • Retrieval – Components can instruct how to fetch or load data, which can be used to render the component. Component attributes and children can be used to define the presentation of the data. They can define workflows for data processing, or use data from prior actions to render the component.

  • Rendering – Components specify how data is rendered. They are only re-rendered when their inputs change. Components may have arbitrary children, which are all tracked as individual components. This allows to dedupe rendering common elements like headers or footers that are mostly identical across pages.

  • Styling – Components can define their own styles, which can be scoped to the component itself, and reuse and tap into variables from the theme to provide a consistent look and feel across the application. Business logic can be decoupled from styling, so components can be reused across different themes much more easily.

  • Interactivity – Components can be interactive, implemented through a so called island architecture. They are rendered via SSR by design, and can be rehydrated on the client if JavaScript is available. Interactivity allows us to provide different implementations with different trade-offs, e.g., for accessible navigation.

• Native runtime – Components won't require the installation of an additional runtime – the component runtime will be natively implemented as part of Zensical's module system, and will leverage it to provide differential updates, and blazing fast rendering. This allows Zensical to provide a stable and performant component system.

• Asset compilation – We will incorporate an asset compiler into Zensical that will compile the assets and minify the result at the time your project is built, giving you a much improved experience as a designer. Any changes will be immediately visible in the browser.³

Configuration¶

We're completely rethinking configuration management. Zensical scales to fit your needs, from zero configuration with intelligent defaults to advanced control for multi-environment setups, feature flags, and complex project variants.

Effortlessly build for offline use, manage a portfolio of subprojects, or compile projects individually. Use presets to reduce boilerplate. Only configure what you need, as you can rely on sane defaults.

Key aspects

• Zero configuration mode – Zensical automatically infers your site structure, navigation, and build settings from your content organization. Simply point it at a folder of Markdown files and get a fully functional documentation site with sensible defaults for theming, navigation generation, with no configuration at all.

• Complex folder structures – Native support for sophisticated project layouts including monorepos, multi-language documentation, versioned content trees, and nested subprojects. Zensical allows to handle complex hierarchies that would require extensive manual configuration in traditional static site generators.

• Programmatic configuration – Define your build pipeline through code rather than static files. Use functions, conditionals, and dynamic logic to configure different builds for development, staging, and production environments. This enables advanced scenarios like feature flags, environment-specific content, and complex build variants.

• Use and create presets – Leverage community presets for common documentation patterns – API documentation, user guides, blogs and much more – or create your own reusable presets. Presets encapsulate best practices and complex setups into simple, shareable packages that eliminate repetitive configuration across projects.

API documentation¶

Most API documentation systems are limited to the language they're written in, including Rustdoc, TypeDoc, and GoDoc. Zensical eliminates this barrier by providing a unified and extensible system that supports multiple modes of operation and seamlessly integrates across any technology stack.

Key aspects

• Multi-modal documentation support: API documentation can either be standalone, and live in its own dedicated space as part of your documentation project, or be injected into existing content, mixing it with prose to create tutorials and step-by-step guides.

• Cross-language and cross-technology integration: Modern applications rarely exist in isolation. A typical web application might involve Python backend services, TypeScript frontend code, OpenAPI specifications, and configuration files for tools like nginx. Zensical understands these relationships and provides automatic linking between components.

• Extensibility for domain-specific tools: Different ecosystems have their own conventions and tools, e.g., FastAPI routes have specific metadata, Pydantic models have validation logic, and GraphQL schemas have their own structure. The system can be extended to handle these domain-specific requirements through customizable output generation.

• Component system integration: Built on Zensical's shared component system, the API documentation tools let you create modular, reusable elements. Customize the provided standard components or override them to create your own.

Modular navigation¶

Navigation is an integral part of any documentation site, and Zensical aims to provide a flexible and powerful navigation system. With Zensical, we want to significantly improve the degrees of freedom that authors have in designing an information architecture and navigation structure that best suits their project.

Key aspects

• Flexible architecture – We're moving away from MkDocs' monolithic navigation architecture, where there's only a single source of truth for site-wide navigation. Zensical aims to allow templates and themes to define arbitrary navigation elements, which authors can then configure, customize and extend.

  Of course, Zensical also provides a set of default navigation elements that template authors can use as a starting point for creating more complex navigation structures.

• Scalability – Rendering of navigation partials is one of the main factors of slow build times, since MkDocs' monolithic navigation implies quadratic runtime, with every page potentially linking to every other page. Zensical aims to improve the situation with intelligent caching and deduplication of the computation necessary, allowing to scale from 1 to 100k pages.

• Navigation as content – Whether your team manages navigation as configuration or content is up to you, as Zensical supports both modes. You can compose all navigation elements in section-specific configuration files, allowing to override navigation elements on a per-section basis, or use a central configuration file for global settings.

Subprojects¶

Build complex documentation architectures that scale from simple multi-language sites to intricate project trees spanning different technologies, teams, and deployment requirements. Each subproject maintains its own build pipeline while sharing resources and maintaining cross-project relationships.

Key aspects

• Hierarchical project trees – Structure your documentation as a tree of interconnected projects rather than forcing everything into a single monolithic build. API references, tutorials, and integration guides can each live as separate projects with their own navigation, search indexes, and deployment cycles, while still presenting as a unified documentation experience.

• Flexible deployment modes – Deploy all projects together as a unified site, or selectively deploy individual projects to different domains or paths. Support for both centralized and distributed deployment strategies means you can adapt to organizational constraints while maintaining documentation quality and discoverability.

• Cross-project integration – Link seamlessly between projects with automatic resolution of references and paths. Build consolidated search indexes that span multiple projects, merge sitemaps for SEO optimization, and create unified navigation experiences that hide the complexity of the underlying project structure from your users.

• Multi-language workflows – Turn the challenging problem of internationalization into a straightforward project tree. Each language becomes its own subproject with fallback handling for untranslated content, automatic redirection to available versions, and clear indicators of translation status, maintaining a cohesive multi-language experience.

Internationalization¶

Multi-language support has been a source of frustration for users of almost all static site generators. Zensical aims to address these challenges by providing a robust framework for managing translations, language-specific content, and fallback mechanisms.

Key aspects

• Flexible content organization – Zensical aims to support multiple ways of organizing content for different languages, including suffix-based and folder-based approaches, and to provide tools that allow you to easily switch between them.

• AI-powered translation workflows – Modern LLMs can be leveraged to provide high-quality translations and localization support, making it easier to manage the evolution of multi-language content. Zensical tracks the parts of your documentation that are removed or added, and generates drafts for translations of these changes.

• Localizing all parts – Zensical aims to provide a comprehensive solution for localizing all aspects of your documentation, including UI elements, code snippets, and examples, ensuring a consistent experience across languages. Localization workflows should be easy to configure and manage, with clear guidelines for contributors.

• Flexible deployment modes – As with subprojects, Zensical will support multiple deployment modes to accommodate different documentation needs. This includes options for building all content together, as well as selective builds for individual sections or languages.

Versioning¶

Deploy multiple versions of your documentation without being locked into specific hosting platforms or Git workflows. Zensical's versioning system aims to work with any branching strategy, deployment target, or organizational structure while optimizing builds to only process changes.

Key aspects

• Flexible version management that adapts to your workflow – Deploy multiple versions of your documentation without being locked into specific hosting platforms or Git workflows. Zensical's versioning system will work with any branching strategy, deployment target, or organizational structure while optimizing builds to only process what actually changed.

• Workflow-agnostic version management – Whether you use Git tags, branch-based workflows, or custom versioning schemes, Zensical adapts to your existing processes. Support for both Git-based versioning (leveraging Git's efficient storage) and folder-based approaches for teams with different deployment requirements or organizational constraints.

• Differential rebuilds – Only rebuild the versions that actually changed. Update the latest version and only that version gets rebuilt. Fix a typo in an older version and only that specific version processes. Smart change detection across the entire version tree minimizes build times and resource usage, making it practical to maintain dozens of active versions.

Beyond¶

We have ambitious plans for the future of Zensical, including:

• Lifecycle transitions – tools for growing your project or team
• Migration tooling – tools for migrating to Zensical
• Language server – enabling deep documentation refactoring
• WYSIWYG editing – providing a visual editing experience
• Collaboration – enhancing team workflows and communication