Roadmap and Upgrade Policy

This content was generated with the assistance of AI and should be verified against the official documentation of each tool before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

This page was written against Zensical 0.0.72 (published to PyPI on 2026-10-23, classified Development Status :: 3 - Alpha) and checked on 2026-10-26. The project moves quickly: PyPI listed 72 releases at that date, and the last eight (0.0.65 to 0.0.72) were published between 2026-09-24 and 2026-10-23, roughly one a week. Everything about dates and plans below is what the official pages said on the check date; roadmap items are directional, not promises.

Version policy

Zensical states that it follows semantic versioning, with a twist that matters while the project is young.

  • 0.0.x (today). Alpha, development releases. Any release may change behavior, so treat an upgrade as something to test, not to apply blindly.

  • 0.1.0, planned for 2026-11-05. The upcoming-changes page says this release moves Zensical out of the 0.0.x alpha series and begins a "dependable release line", on the same day Studio launches its Free, Pro and Team editions and Spark Community opens to individuals. At the check date this had not happened yet, so verify it before relying on it.

  • Staying on 0.x. The project says it will remain on the 0.x line while the module system and the ecosystem around it are shaped with the community. Public APIs may still evolve, but changes are described as deliberate, with compatibility as a design constraint and a migration path when an interface must change.

  • 1.0, later. Once the public APIs have proven stable over time, 1.0 formalizes that maturity. The project describes it as a low-drama release and explicitly tells readers not to wait for it before using Zensical.

The older wording on the upgrade page says a beta release was approaching, after which versions would move to 0.x. The upcoming-changes page is newer and is the one to follow: the milestone is called 0.1.0, not a beta.

timeline title Zensical version line 2025-11-05 : Announcement : Material for MkDocs enters maintenance 2026-10-23 : 0.0.72 : Alpha series (0.0.x) 2026-11-05 : 0.1.0 planned : Dependable release line : Studio and Spark Community launch Later : 1.0 : Stable public APIs proven over time

Material for MkDocs is the practical reason to plan an upgrade path: its critical-fix maintenance was extended by six months and now runs until 2027-05-05, which is the date by which a migration should have a controlled plan. See Migrating from Material for MkDocs.

Upgrading Zensical

The official upgrade page tells you to read the changelog for the target version first. Releases are published on the project’s GitHub releases page, and each one lists features and bug fixes with a short summary. The 0.0.72 release, for example, adds support for the privacy plugin and fixes Markdown rendering, link handling and project layouts, and updates the bundled user interface to 0.0.38.

With pip

Activate the virtual environment that holds Zensical, then force a reinstall, as the official page prescribes:

pip install --upgrade --force-reinstall zensical
pip show zensical

Source: Zensical docs: How to upgrade

I ran this in a scratch virtual environment that started at 0.0.71. The tool replaced it and finished with the new version, and pip show zensical then reported:

Name: zensical
Version: 0.0.72

With uv

With an existing lock file, uv keeps the locked version until you ask for another one. Replace the placeholder with the version you want:

uv lock --upgrade-package zensical==<version>
uv pip show zensical

Source: Zensical docs: How to upgrade

This command was not executed here because uv was not installed in the scratch environment.

Pin, then move deliberately

Because 0.0.x releases may change behavior, pin the version in the project and raise it on purpose. A dependency declaration in pyproject.toml for the Pocket Units documentation could look like this:

[project]
name = "pocket-units-docs"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "zensical==0.0.72",
    "mkdocstrings-python",
]

Source: Zensical docs: Get started

The pin follows the pattern the install page describes (declare dependencies in pyproject.toml; Zensical needs Python 3.11 or newer). In CI, install the same pinned set and run zensical build --clean --strict, so a changed warning behavior fails the pipeline instead of the published site. After 0.1.0 a compatible-release range such as zensical>=0.1,<0.2 becomes reasonable, but the project has not published a compatibility guarantee for 0.x minors, so keep the upper bound.

Clean builds after an upgrade

The build page recommends zensical build --clean when output looks wrong after an upgrade. It clears the build cache before rebuilding, because the incremental build state can go stale across versions. The same page says clean builds should become unnecessary in the near term as those stale-state bugs are fixed, and asks for an issue if a problem survives a clean build. The generated GitHub Actions workflow already uses --clean, and CI caches are not recommended.

zensical build --clean --strict

Source: Zensical docs: Build

Run against the Pocket Units copy used for this page, it printed:

Build started
No issues found
Build finished in 0.33s

Upgrade checklist

  • Read the release notes for every version between the current and the target one.

  • Upgrade in a branch or a scratch environment, not in the publishing pipeline.

  • Run zensical build --clean --strict and compare navigation, search and API pages with the previous output.

  • Check unsupported settings: configuration of unlisted MkDocs plugins is silently ignored, so a newly supported plugin can start to take effect after an upgrade, and the compatibility pages are the place to see which ones are covered.

  • Raise the pin and commit it together with the lock file.

Roadmap

The public roadmap says it is directional and promises neither delivery dates nor a fixed order. It groups work into a status table (now available, in development, up next) and longer-term capability areas.

Status at the check date

Item What it is Status

Directives

Markdown extension that assembles documentation variants from shared sources (content reuse)

Spark early access

MkDocs plugin replacements

Native versions of privacy, include-markdown, nav-weight, markdownextradata, audio, video, llmstxt, gh-admonitions, api-autonav, autoapi, social, exclude, blog and rss

Now available

MkDocs file visibility settings

Excluding files, previewing drafts and hiding pages from navigation

Now available

MkDocs optimize plugin replacement

Optimize media files during builds

In development

Zensical Markdown

Reimplementation of Python Markdown for faster builds and easier extensions

In development, Spark first

Project model for agents

Command-line access for agents to the project model

Up next

Migration readiness

Assess a project before moving it to Zensical

Up next

Module API for Python

Extend Zensical by writing modules in Python

Up next, Spark first

Source: Zensical roadmap

The roadmap also describes a Rust parser compatible with Python Markdown. The team reports benchmark results more than 50 times faster than Python Markdown and is testing it through Zensical Studio before an MIT-licensed release, its integration into Zensical, and command-line and CI access to a Markdown formatter and linter.

Longer-term areas

  • Build and extensibility: MkDocs compatibility (the existing mkdocs.yml, Python Markdown, Material settings, the classic theme and most template overrides), the Markdown toolchain, a module system with a Python API and installable module packages, richer configuration (zero-configuration mode, folder-level settings, environment variables, presets) and a native API documentation system (OpenAPI, source-code references, embedded and standalone references).

  • Authoring workflows: content catalogs and conditional content, reusable topics, agent-ready documentation, and migration and import tools (HTML, rich text and tables to Markdown).

  • Site experience: search filters, cross-site search and query suggestions, several navigation areas, installable themes and reusable components.

  • Publishing at scale: combining independently built projects into one site, Git-based and folder-based versioning with selective publishing, content internationalization (language organization, translation tracking and localization), and output formats beyond HTML such as PDF, EPUB and manual pages.

The last group is where today’s gaps sit. Zensical has no native versioning or content translation yet, so the roadmap items are the official direction, not features you can configure now. See Versioning and internationalization for what to do in the meantime.

Spark-only and commercial features

The business model has three parts, and only one of them gates features.

  • Open source. Zensical and every project the team releases as open source are MIT-licensed and free. The team says they charge nothing for sites, readers, builds, publishing, deployment or access to your content.

  • Zensical Studio. A closed-source authoring application with Free, Pro and Team editions, launching on 2026-11-05. It adds workspace intelligence to Zensical and MkDocs projects, such as keeping links intact when content is renamed or moved. Its editor integrations are open source.

  • Zensical Spark. A paid membership: Spark Community for individuals (opens 2026-11-05) and Spark tiers for organizations with direct support and response times. Members get early access to new functionality months before public release and a direct voice in the project. Spark and Studio can be used independently.

Features marked "Spark early access" on the roadmap are available to members first; "Spark first" items enter early access later and reach everyone after that. At the check date the early-access feature was Directives, and Zensical Markdown and the Module API for Python were labeled Spark first. This is a staged release process, not a permanent paywall for the open-source build tool, so a Spark-only feature today is expected to become publicly available later, with no date promised. Check the pricing on the official pages when you evaluate it, as the early supporter prices and edition details were due to change on 2026-11-05.

I did not run any Studio or Spark feature: they require an account and, for early access, a membership.

Pitfalls

  • Do not read the 0.1.0 plan as a stability guarantee for every setting; the project itself says public APIs will keep evolving on the 0.x line.

  • Unlisted MkDocs plugins are ignored without an error, so an upgrade that adds support can change output silently.

  • A passing build is not proof of identical output. Compare the rendered site, and run the link validation described in Validation and Publishing.

  • A roadmap line is not a release. Rely on the changelog of the installed version for what exists.

References