> That said, if pressed, I’d recommend AsciiDoc over any Markup flavor for a greenfield project _today_.

Likewise for me as well, and I am a massive Material for MkDocs fan. Markdown is certainly simple to use and gets the job done, but AsciiDoc just provides so much out of the box without hurting my eyes like reStructuredText (used by Sphinx) does. It also helps that's there's effectively one type of AsciiDoc I'm aware of, whereas there's a number of Markdown flavors atop CommonMark to be cognizant of. I will concede, however, it's learning curve is not as simple as MarkDown's...

A powerful framework for working with AsciiDoc for documentation purposes is Antora[0]. The Red Hat ecosystem (Fedora and CentOS projects) uses it for their public facing docs. That being said, it is a beast to understand if starting from scratch rather than contributing to project's existing docs. It designed to be able to consolidate large projects with multiple component repositories and versions per component into a single docs site. Typical balance of more capabilities, more up-front cost of adoption.

The AsciiDoc WG also maintains an Awesome AsciiDoc[1] page of projects within the ecosystem.

[0] https://antora.org/

[1] https://gitlab.eclipse.org/eclipse-wg/asciidoc-wg/asciidoc.o...

> It is a very reasonable choice: your plug-in project has grown to a scale you have never anticipated. Therefore, you built your own system from the ground up, one which you have total control over, instead of keeping to rely on someone else's system as you did before. This would make new features and bug fixes more easy to be implemented.

Exactly this. We ran against walls trying to realize our ideas with MkDocs' APIs, so a rewrite was due. With MkDocs being unmaintained for over a year, we took the initiative. Since we have excellent product-market fit, investing into a new stack was just logical.

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.

[1]: https://github.com/zensical/zrx

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.

[1]: https://zensical.org/compatibility/

Creator of Zensical here! As always, it's a matter of taste. We felt the original look was a little date. You can use the classic Material for MkDocs look with Zensical by adding a single line of configuration[1]. This works because the HTML is exactly the same right now. Most users favor the new look over the old one.

[1]: https://zensical.org/docs/setup/basics/#theme-variant

Someone builds a complete documentation system from scratch and you call it a "travesty" because it has rounded corners? Visual design is important but this is very misplaced priorities.

undefined

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.

Zensical itself is entirely free OSS software.

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. 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.

[1]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-py...

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.

> load blog posts from a db

Can you explain a bit more about your requirement and how many blog posts you are talking about?

I'm curious to hear more for my future work as I have an extendable static site builder it would be easy to add this too. I don't want to be going all marketing on someone else's post (and it's early days so you'd probably find other features lacking) so I'll just say my email is in my profile if you want.

Its predecessor (mkdocs material) supported blogs via a plugin and rss feeds via a mkdocs plugin (https://guts.github.io/mkdocs-rss-plugin/). I don't believe it supports blogs yet according to this: https://zensical.org/compatibility/#phased-transition-strate... but will in the next phase when it supports plugins.

It doesn't support loading content from a database that I'm aware of, it uses markdown files on disk as input.

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'll ship fuzzy search in the coming weeks. It's just awaiting a release.

We set up a Discord for the community, and have a dedicated space for professionals! https://zensical.org/docs/community/get-involved/

Material Design have been overhauled twice since the theme has been released. That was not the reason why they succeeded, just a solid foundation which they happened to built from.

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.

[1]: mkdocstrings.github.io

AFAIK, Sphinx does support markdown… the issue with markdown is that it doesn’t support macros like RST, so there’s a huge amount of functionality that can’t translate well to it.

Sphinx does have markdown support fwiw

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!

now adding rust on top of that.

i actually tried zensical yesterday and fell back to mkdocs, not sure what I'm missing while trying. Material for mkdocs served me well so I will stay with it for now.

zensical installation is longer than mkdocs, probably due to the rust side.