Roadmap¶

We publish this roadmap to make the direction of Zensical transparent. It connects current work with the larger capabilities we're building toward.

Our roadmap is directional and does not promise delivery dates or a fixed implementation order. Priorities evolve through short development cycles and feedback from people using Zensical.

Status¶

The table summarizes recent releases, work in development, and what comes next. It does not cover every change; smaller improvements are released continuously.

Items marked Spark early access are available to Zensical Spark members before public release; Spark first items enter early access later. This lets us test larger changes in real projects and refine them through feedback before broad release.

Build and extensibility¶

MkDocs compatibility¶

Zensical supports existing MkDocs projects and can build many of them with few or no changes. This includes mkdocs.yml, the standard project structure, Python Markdown, Material for MkDocs settings, and common customizations. We are currently working on replacements for the most popular plugins.

• Configuration and structure: Use existing mkdocs.yml configurations.
• Python Markdown: Render existing content and common extensions.
• Material for MkDocs: Use Material settings and the classic theme.
• Customizations: Keep additional CSS, JavaScript, and most template overrides.
• Plugin compatibility: Use Zensical replacements for widely used MkDocs plugins.

Markdown toolchain¶

We're experimenting with an extensible Rust parser compatible with Python Markdown. Our latest parser benchmarks show it running more than 50x faster than Python Markdown. We're testing it through Zensical Studio as we prepare an MIT-licensed release, integration into Zensical, and command-line and CI access to its formatter and linter.

• Python Markdown compatibility: Use common Python Markdown extensions.
• Zensical Markdown: Reimplement Python Markdown for faster builds and easier extensions.
• Markdown formatter: Format Markdown files locally and check formatting in CI.
• Markdown linter: Report Markdown problems locally and in CI.
• Markdown extension API: Create custom Markdown extensions.
• CommonMark compatibility: Use CommonMark content alongside Python Markdown.

Module system¶

Documentation projects often need publishing steps tailored to their content and workflows. The Module API defines how those steps connect to Zensical, while language APIs let extension authors implement them in familiar languages.

• Module API: Define custom steps in the publishing pipeline.
• Module API for Python: Extend Zensical by writing modules in Python.
• Module packages: Install and share modules across projects.

Configuration¶

Small projects benefit from useful defaults, while larger projects need settings that vary by folder, environment, or build. Authors should be able to add that complexity gradually and reuse it across projects.

• Zero-configuration mode: Start a site from content with sensible defaults.
• Folder-level settings: Layer settings across folders with predictable overrides.
• Environment variables: Set environment-specific values outside project files.
• Programmatic configuration: Define conditional settings in code.
• Reusable presets: Package and share common settings.
• Preset overrides: Customize a preset within a project.

API documentation¶

Zensical already supports API documentation through mkdocstrings. The capabilities below describe a native API documentation system designed from first principles, with references that can stand alone, sit inside guides, and connect related concepts across languages and frameworks.

• OpenAPI references: Generate API documentation from OpenAPI files.
• Source-code references: Generate API references from source code.
• Standalone references: Publish API references in their own section.
• Embedded references: Place API references inside guides.
• Cross-language API links: Connect corresponding APIs across programming languages.
• API components: Customize API references with reusable components.

Authoring workflows¶

Content reuse¶

Directives is a Markdown extension for assembling documentation variants from shared sources. A catalog defines the variants and their values; directives select blocks, substitute values, and include source files during the build. The extension is currently available to Zensical Spark members in early access.

Larger documentation sets also need reusable topics that remain portable across publications and folder structures. Structured topics can sit alongside ordinary Markdown for gradual adoption.

• Content catalogs: Define variables and named variants.
• Conditional content: Select Markdown blocks for a named variant.
• Variable substitutions: Insert values from the selected variant.
• Source inclusions: Include complete source files with @use.
• Variant preview: Preview the selected variant in Zensical Studio.
• Parameterized inclusions: Pass values to included source files.
• Reusable topics: Reuse self-contained topics across publications.
• Stable topic references: Refer to topics by identifier instead of file path.
• Gradual adoption: Mix structured topics with ordinary Markdown.

Agentic workflows¶

Agents need access to Studio's project model and workspace intelligence. Command-line tools make those capabilities available for understanding and changing projects. Documentation builds can also make project knowledge available to users and agents.

• Project model for your agents: Give agents CLI access to the project model.
• Rule checks for your agents: Check whether agent changes follow organization-owned rules.
• Agent-ready documentation: Build documentation for users and agents.

Migration and import¶

Authors moving between documentation systems need to understand required changes and preserve reviewable content. In Zensical Studio, assessments and interchange tools keep that work alongside the project.

• Migration readiness: Assess a project before moving it to Zensical.
• Rich-text import: Convert pasted rich text into Markdown.
• HTML import: Convert HTML into Markdown.
• Tabular data import: Convert pasted tables into Markdown tables.
• Authoring-system interchange: Import and export structured content.

Site experience¶

Search and discovery¶

Readers need to find relevant information across large and distributed documentation sites. Authors need control over metadata filters, cross-site queries, and how search results are presented.

• Custom filters: Filter results by project metadata beyond tags.
• Search across sites: Search several documentation sites together.
• Query suggestions: Suggest queries as readers type.
• Custom presentation: Configure filters, previews, and result rendering.

Navigation¶

Documentation projects often need different navigation structures for different readers and sections. Authors need to shape those structures around the content and maintain them where they are easiest to manage.

• Multiple navigation areas: Place navigation in the areas provided by a theme.
• Navigation as content: Manage section navigation alongside its content.
• Section overrides: Adapt navigation for individual content sections.
• Safe reorganization: Move sections without breaking links.

Themes and components¶

Authors need to adapt a site's appearance and behavior without copying the same work between projects. Shareable themes and components make those changes reusable, while integrated asset compilation keeps the build setup simple.

• Installable themes: Use shared themes without copying them into a project.
• Reusable components: Package content, styles, and behavior for reuse.
• Markdown components: Use components in Markdown.
• Template components: Use components in site templates.
• Integrated assets: Use theme and component assets without a separate build setup.

Publishing at scale¶

Multiple projects¶

Documentation maintained by several teams often needs separate builds and release cycles while still appearing as one connected site. Authors need to combine projects without giving up independent ownership or deployment.

• Project composition: Combine independently built projects into one documentation site.
• Cross-project links: Keep links working across project boundaries.
• Cross-project navigation: Connect navigation across project boundaries.
• Combined deployment: Deploy a composed site in one release.
• Independent deployment: Publish individual projects separately.

Versioning¶

Authors often maintain documentation for several product versions across different Git and publishing workflows. They need to choose where versions come from, publish only what they need, and avoid rebuilding unchanged content.

• Git-based versions: Organize versions with Git branches or tags.
• Folder-based versions: Organize versions in folders.
• Selective publishing: Publish selected versions.
• Focused rebuilds: Publish changes without rebuilding unaffected versions.

Internationalization¶

Multilingual projects need flexibility in how they organize, translate, and publish content.

• Language organization: Organize languages with suffix- or folder-based structures.
• Translation tracking: Track source changes and translation status.
• Translation preparation: Prepare changed content for translation.
• Content localization: Localize prose, code samples, and examples.
• Interface localization: Localize navigation and interface text.
• Language publishing: Publish languages together or independently.

Publishing formats¶

Readers use documentation in browsers, documents, ebooks, and terminals. Authors need to publish the same sources in formats that fit each setting.

• HTML websites: Publish documentation as HTML.
• PDF documents: Publish documentation as PDF.
• EPUB ebooks: Publish documentation as EPUB.
• Manual pages: Publish command-line documentation as manual pages.