Zensical team here. Yes, there are very good reasons for that change. First and foremost, with MkDocs using YAML, and Material for MkDocs being the main entrypoint for many of our users, we got a lot of issues with users having trouble just getting the indentation of YAML right. Secondly, and this is even more problematic: Python Markdown allows the use of custom YAML tags[1], which translate to function references during parsing. This means that YAML parsing is tied to Python and thus not portable to other languages. It's also the reason why we currently need to go through Python to parse MkDocs configuration and render Markdown. TOML on the other hand doesn't have such magic, making it portable.
Thank you for your prompt response. Your explanation clarifies things much better than the brief description in the documentation. While I still prefer YAML over TOML, I understand your reasoning.
Coming from Material for MkDocs, right now, sources need to be in Markdown files. However, our new build system is extremely flexible, so with the upcoming module system, it will be possible to add further sources and integrate them into the static site generation process. What you mention is part of the feedback we got from talking to organizations, for which Markdown is actually only the target, generated from database records to render a static documentation site.
Zensical team here. It's perfectly usable – we're of course building our own docs with it and the first users have already switched – but you have to have an eye on compatibility. Whether you can switch right now largely depends on which plugins you're using from the MkDocs ecosystem. We have an entire section on compatibility.[1]
If Material for MkDocs ticks off all or most of the boxes, you can definitely start using it, and switch later once everything you need is available. Our promise to the 70k+ projects using Material for MkDocs is that we'll make switching to Zensical as simple as possible with automatic conversion tooling once we ship certain functionality. The compatibility we have now is a first step towards that goal.
Zensical team here – right now it's still Python/Pygments under the hood, as we're using the same toolchain for rendering for compatibility reasons, but we'll be rethinking language support from the ground up, and tree sitter is something we're experimenting with. Ideally, we'll be able to unify code highlighting with language support with API reference docs.
Excellent question. We're not using differential dataflow (DD), but are rolling our own differential runtime. It's basically functions stitched together with operators, heavily inspired by DD and RxJS, and is optimized for performance and ease of use. The decision to go from scratch allows us to provide something that, IMHO, is much simpler to work with than DD and Rx, as our goal is to allow an ecosystem to evolve, as MkDocs did as well. For this, the API needs to be as simple as possible, while ensuring DD semantics.
Right now, builds are not fast, since Python Markdown is our bottleneck. We decided to go this route to offer the best compatibility possible with the Material for MkDocs ecosystem, so users can switch easily. In the next 12 months, we'll be working on moving the rest of the code base gradually to Rust and entirely detaching from Python, which will make builds significantly faster. Rebuilds are already fast, due to the (still preliminary) caching we employ.
The differential runtime is called ZRX[1], which forms the foundation of Zensical.
Zensical Spark is our offering for professional users. In the past 12 months, we've had numerous conversations with organizations and enterprises to understand how they adapted Material for MkDocs to their processes and workflows. Our goal with Zensical is to build a far more flexible solution than (Material for) MkDocs, developed closely alongside the professional users who rely on it daily. This is a paid product and represents the way we ensure the long-term sustainability of the project.
It's definitely not malicious intent. It's an inlined version of our new search engine that we'll release in early 2026, but already wanted to ship with Zensical. However, you're right that this might raise some eyebrows – we'll fix it with the next release.
We'll do our best! The author of mkdocstrings[1] (the leading API reference docs solution in the MkDocs space) is part of our team, so we're aiming to bring much more powerful API reference docs support to Zensical.
Yes, we're basically agnostic to the input and output formats. Right now it's Markdown -> HTML, but with the upcoming module system, it'll be possible to convert anything to anything. Our focus will stay Markdown/HTML first, and once we reach feature parity, we'll explore to support formats like PDF etc. natively.
We've heard this many times when talking to our enterprise users, which is one of the reasons that motivated the fresh start. WYSIWYG is on our roadmap as a stretch goal, allowing non-tech users to contribute. It'll take some time, but we'll reach it eventually!
[1]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-py...