Zensical Overview

Zensical turns a folder of Markdown files and one configuration file into a static website: navigation, a built-in client-side search, light and dark colour schemes, code highlighting, admonitions, diagrams and a responsive layout. It is installed as a Python package (it requires Python 3.11 or later), reads either its own zensical.toml or an existing mkdocs.yml, and builds with the command zensical build.

The team states two motivations in its announcement. First, Material for MkDocs had reached limits that were rooted in the architecture of MkDocs, its host program, so they could not be fixed from inside a theme. Second, MkDocs has not had a stable release since August 2024, which the team calls a supply chain risk for projects that depend on it. Rather than fork or port MkDocs, the team rebuilt static site generation from scratch, around a differential build engine named ZRX (a standalone open source project) that handles incremental builds, caching and data flow. The announcement does not say which language ZRX is written in, so this page does not either.

The generated HTML intentionally stays close to what Material for MkDocs produced, and Zensical keeps using Python Markdown and its extensions. That is why most existing Markdown, template overrides and custom CSS or JavaScript should carry over unchanged. Plugins are the exception: a planned module system will replace the MkDocs plugin model, and today only a subset of plugins is supported (see Blog, Tags and Plugins).

The three projects form one lineage, shown in the timeline.

Figure: first releases and status changes of MkDocs, Material for MkDocs and Zensical. Dates come from the PyPI release history and the official announcements.

Source: Material for MkDocs blog: Zensical announcement

The dates in the table were read from the PyPI release metadata of each package (mkdocs, mkdocs-material, zensical) on 2026-10-26.

Material for MkDocs is in maintenance mode. The team announced on 2025-11-05 that feature development had ended, and that critical bug fixes and security fixes would continue for twelve months. At the launch of the 0.1.0 line, scheduled for 2026-11-05 the team extended that period by six months, so critical maintenance now runs until 2027-05-05. After that date existing installations and already published sites keep working, but nothing is promised for new problems. The announcement does not name a Material for MkDocs version that marks the start of maintenance mode. The 9.7.0 release appeared on PyPI six days after the announcement, so it is a convenient reference point, but the official sources only give the dates.

MkDocs itself is described by the Zensical team as unmaintained since August 2024. Its last stable release is 1.6.1 from 2024-08-30. Whatever you think of that judgement, it is relevant for planning: a documentation site built on Material for MkDocs still depends on MkDocs for the build, and both are on a path of critical fixes only.

In practice this gives three choices for an existing Material for MkDocs site: stay on 9.x until 2027-05-05 and plan the move, migrate gradually to Zensical while keeping mkdocs.yml (see Migrating from Material for MkDocs), or move to another tool such as Antora, Docusaurus or DocFX described elsewhere in this section.

Every Zensical release so far is a 0.0.x release, and the package is classified as alpha on PyPI. The upcoming changes page of the project announces that on 2026-11-05 version 0.1.0 starts what the team calls a dependable release line. The project stays on 0.x while the module system and the ecosystem around it take shape; 1.0 is planned for when the public APIs are stable. An older wording on the upgrade page still speaks of a beta release approaching, so the upcoming changes page is the more recent statement.

For a team this means the following:

When 0.1.0 is published, the details above change from "planned" to "released"; check PyPI and the project’s upcoming changes page for the current state before relying on this page.

Zensical and its open source projects, including ZRX, are published under the MIT licence and are free to use for any purpose, commercial use included. The announcement adds that the search engine Disco will also be released as a standalone MIT project. Closed-source products exist around the core, described next; none of them is needed to build a site.

Two commercial offerings fund the work. Neither is required for anything described in this subsection, which uses only the open source package.

Prices change, so none are quoted here; see the roadmap and the Spark page. Studio and Spark were not tried for this documentation, because they are separate products.

Pocket Units, the running example of this section, has a Python package. A minimal Zensical project for its documentation is one configuration file, one Markdown page with an API directive and the package folder next to them.

Source: Zensical docs: Basics

Building it in a project with zensical 0.0.72 and mkdocstrings-python installed printed:

The output folder site contained index.html, 404.html, sitemap.xml, search.json, objects.inv, assets and the rendered api/index.html. The next pages explain each part: installation and the command line, configuration, and API documentation from docstrings.