Hello, module system!

Yesterday we shipped the first version of the module system – the most significant architectural change we've been building toward since the beginning. The module system is the foundation that allows us to port your favorite MkDocs plugins to Zensical, adding support for the functionality you rely on. But first, let's talk about topic-based authoring, an area we've been exploring due to significant interest, and will be working on alongside feature parity. Read on to learn more.

Topic-based authoring

Zensical grew out of Material for MkDocs, a tool used by thousands of organizations that follow docs-as-code practices. Now, as we've talked to more professional documentation teams, a pattern has emerged: topic-based authoring is still the way they write and organize their work, as it brings important benefits, including single sourcing, flexible content reuse and multi-channel publishing.

The tooling, however, has not kept up. The dominant tools in this space – Adobe FrameMaker, MadCap Flare, Paligo – were built in an era when print was the primary medium and the web was an afterthought. FrameMaker dates to 1986; Flare, widely considered its modern successor, arrived in 2006; Paligo launched in 2015. All three were shaped by a world of compiled Help files, PDF manuals, and page-based layouts. The web has moved on enormously since then, and teams feel it. Many told us they've started gravitating toward modern static site generators simply because they render modern, fast, and searchable documentation sites – something these legacy tools continue to struggle with. The gap between what they offer and what the web now demands has, if anything, widened with every passing year.

We're going to close that gap.

The foundation we're building with Zensical puts us in the unique position to bring topic-based authoring into the modern era, without asking teams to abandon the structure and scalability they depend on. Docs-as-code and topic-based authoring have long existed in separate worlds – we think they belong together.

Join the topic-based authoring focus group

We're forming a focus group within Zensical Spark for organizations that use topic-based authoring today – in FrameMaker, Flare, Paligo, or similar tools – and are already moving away from proprietary tooling, or actively planning to. We published ZAP 006, which outlines the landscape and the requirements we've identified. Onboarding has started, and kickoff is planned for the beginning of May.

Reach out to [email protected] if your team is interested in joining the focus group, or just reply to this email. We're here to answer all remaining questions.

Highlights

Versioning support

If your team uses mike to publish versioned MkDocs projects to GitHub Pages, migrating to Zensical just got easier. We've created a fork of mike that works with Zensical exactly as it does with MkDocs – every CLI command stays the same, so there's nothing new to learn and no workflow changes required.

This is intentionally a stopgap. Native versioning support is on our roadmap, and it will go considerably further than what mike provides: flexible version management that works with any branching strategy, deployment target, or organizational structure. Differential rebuilds ensure that only changes are processed – whether it's releasing the latest version or fixing a typo in an older one. Once we ship native versioning, our fork of mike will be deprecated. We'll provide tooling and guidance to make the transition straightforward, so it's safe to adopt our fork now and migrate later.

We've updated our documentation to get you up and running in 5 minutes.

Module system

After three months of intensive work, we're happy to announce that we've just shipped the module system as part of the latest ZRX release. This completes phase 2 of our phased transition strategy. We redesigned the scheduler and streaming API from the ground up to support modularity, which makes modules pluggable without restarts. This will allow us to provide a snappy developer experience in our upcoming Python module API – a code change to your module is immediately picked up by the runtime, allowing for fast iteration and live debugging. For design considerations, see ZAP 007.

As we're entering phase 3, our focus shifts to porting functionality from all Tier 1 and Tier 2 plugins. We expect to move quickly, since the module system handles large parts of the orchestration for us. This phase also gives us the opportunity to exercise the new architecture thoroughly before opening it up to third-party developers.

A small excerpt of the results of our MkDocs plugin ecosystem analysis, shared and discussed with our Zensical Spark members in our most recent open call

We're not releasing a public module API just yet, and that's intentional. Once we've validated the design in practice, we'll release a preview within Zensical Spark for early feedback. At that point, we'll also be inviting key ecosystem maintainers of MkDocs plugins, several of which have already reached out to us. Then, they can start building and provide feedback before we release the module API for general availability.

In other news

What's next

With the module system shipped, April and May are all about working towards feature parity with the most essential MkDocs plugins, so the majority of Material for MkDocs projects can make the switch to Zensical without leaving functionality behind.

Your voice matters

Our community is growing daily, and we're overwhelmed by the positive feedback we receive about Zensical. Here's one of our favorite quotes from last month:

Do you have questions, suggestions, or anything else on your mind? Is there anything you would like to see in future issues of Zensical Monthly? Hit reply and let us know!

Keep on creating with Zensical!