Structured content without the noise

Modern documentation needs structure: content reuse, variants, includes, conditions, validation, and publishing workflows that scale. The challenge is adding that structure without turning documents into programs.

Today, teams often solve this with macros or custom templates. While that works, it introduces programming constructs into documentation: the source becomes noisier, intent moves into logic, and tooling sees code where it should see content. As a result, semantic structure becomes much harder to reason about.

Syntax should express reuse and conditions as content structure, not program code.

Read on to learn about our upcoming structured content and reuse extension, why we're building it on Python Markdown, and what we shipped this month.

The Zensical Stack

More than 80,000 public repositories on GitHub now depend on Material for MkDocs, showing how integral Python Markdown has become to technical writing over the years. That adoption made bigger opportunities visible.

However, after 10 years of building Material for MkDocs, we saw the limits of an assembled stack: separate projects with different priorities, APIs, release cycles, ownership boundaries, and no way for us to shape the stack as a whole.

Many problems solved through MkDocs plugins actually belong in authoring, parsing, or validation. The Zensical stack addresses each problem at the appropriate layer.

With the release of Zensical Studio three weeks ago, Zensical now spans the entire authoring stack. The editor you use every day stays at the center, while the Zensical stack brings authoring, parsing, extensibility, validation, and publishing together into a more coherent authoring experience.

The Python Markdown philosophy

When we started Zensical, CommonMark and MDX looked like the natural paths forward: CommonMark for portability, MDX for programmability. We still think both matter, and we plan to support them as alternatives. But the deeper we looked at their tradeoffs, the more convinced we became:

Python Markdown isn't standardized. For us, that is less a flaw than an opportunity to build on something proven in the field. It has already shown that Markdown can carry more structure without losing the quality that made Markdown useful in the first place.

That balance matters:

For the workflows we care most about, the question worth answering is: how can we add expressiveness without weakening Markdown's core promise of readability?

That question is the motivation for what we're building next.

Structured content and reuse

After several design iterations in ZAPs, we're preparing the first preview of our new Markdown extension for conditional content, variables, includes, and reusable content patterns. We'll share it with our Zensical Spark members in the coming weeks.

The key idea is separation of meaning and rendering. A condition describes what a piece of content is for; it does not decide how that variant must appear. Variants can be rendered as interactive content tabs, built into one site per variant, or use a custom representation, depending on the variable or dimension.

One source can describe platform-specific content without deciding whether it becomes tabs, separate outputs, or another representation.

Because reuse and conditions are semantic, tools like Zensical Studio can treat them as part of the document structure instead of opaque logic. That opens the door to validation, navigation, refactoring, and eventually the complex reuse workflows documentation teams know from topic-based authoring and CCMS environments.

Python Markdown, rewritten in Rust

Structured content needs high-fidelity tooling: the editor must precisely understand where headings, links, snippets, references, and definitions come from in the source. Python Markdown was built to transform Markdown into HTML, not to preserve the level of information necessary for workspace intelligence.

That is why we rewrote the Python Markdown parser from scratch in Rust for Zensical Studio. Our new parser preserves the structure and source positions needed for workspace intelligence, safe refactors, and deeper editor support.

It is 10-20x faster than the original Python Markdown implementation, and over the coming months, it will become the canonical parser across the Zensical stack.

What we shipped in June

Much of June went into bringing the new stack into shape across ZRX, Zensical, Zensical Studio, and the parser/tooling work that connects them. Alongside that, we also shipped several user-facing improvements:

Search excerpts

In 0.0.46, we added search excerpts. Each search result now shows a snippet of the matching content, with the search term highlighted. No configuration is necessary – excerpts just work out of the box:

Markdown Exec

In 0.0.47, we shipped support for Markdown Exec, including Pyodide-backed Python execution directly in the browser. This makes it possible to build documentation with runnable code examples that your readers can try out on your site.

Zensical Studio

We also shipped a long list of improvements and fixes for Zensical Studio. The most notable ones bring Markdown closer to the kind of workspace intelligence we've long wanted for technical writing:

Zensical Studio is now available on Open VSX, making it possible to use in VS Code-compatible editors beyond the Visual Studio Marketplace, including VS Codium, Cursor, WindSurf, and editors that can install Open VSX or VSIX extensions.

In other news

What's next

The next milestone for us is 0.1.0, which will move Zensical from alpha to beta later this year. Until then, we'll close the remaining feature-parity gaps, polish the core experience, and make the pieces of the stack work together more smoothly.

We're incredibly happy to see that many teams are already using Zensical today. We're working hard to make Zensical the obvious choice for modern Docs-as-Code.

Your voice matters

We're looking for early feedback from teams that already deal with reuse, variants, conditional content, shared sections, or multi-channel output.

The first preview of our structured content and reuse extension will be available to Zensical Spark members. If your organization wants to test it early and influence the direction, we'd love to have you in Zensical Spark.

And as always, if you have questions, ideas, concerns, or anything else on your mind, simply reply to this email – we read everything.