squidfunk

Creator of Zensical here! Would you mind sharing a bit more detail on why you feel the comparison is on point? One of our core goals with Zensical is to simplify things – not add complexity. We’re also working toward making it an almost 100% drop-in replacement for Material and the broader MkDocs ecosystem, so I’d be especially interested in understanding what feels more complicated from your perspective. I’d appreciate any specifics on where we can improve.

That said, I do think the linked comparison may be a bit misleading. As far as I can tell, MaterialX is still largely based on the Material for MkDocs codebase with mostly some UI changes, several of which the author has taken from Zensical.

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

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.

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

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

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.

[1]: mkdocstrings.github.io

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!

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

We'll ship fuzzy search in the coming weeks. It's just awaiting a release.

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.

From the feedback we got after launching. More accurately: most users that we conversed with since launch are very happy about the new look. Regardless, for compatibility reasons, the old look is available as well.

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

Hey there, maintainer of Material for MkDocs here! MkDocs has quite a history, which is why we theme, plugin and extension authors are working very hard to put MkDocs on a solid foundation, and to build an inclusive and welcoming team that takes the project to a whole new level

https://github.com/mkdocs/mkdocs/discussions/3622

Author here. What specifically don't you like about the blog plugin? We'd love to improve it with user feedback and make it even more powerful!

Author of Material for MkDocs here. We're currently working on re-architecting the entire search engine and rewriting it from scratch. We're currently based on lunr.js, which is unmaintained as of 2020 and has more or less run its course. We've learned a lot what matters in respect to efficient and user friendly documentation search, and can't wait to give the first version into the hands of our users. I'm convinced that the next iteration of search we'll be releasing will solve many of the shortcomings that our current implementation has. Of course, it will work on the client side as it does now, no server needed, but there will be other options as well, e.g. for when your search index is in the megabytes and too big to ship to clients.

Author of Material for MkDocs here. I totally understand that some people don't like Material Design, as it's just everywhere nowadays and can be considered a bit overused. However, with little effort, you can adjust the style of Material for MkDocs with a few lines of additional CSS [0] and fit it to your taste. For example, several days ago I did this [1] in 20min. Nevertheless, Furo is an awesome theme if you like to use Sphinx over MkDocs!

[0] https://squidfunk.github.io/mkdocs-material/customization/#a...

[1] https://twitter.com/squidfunk/status/1598341366869856257/pho...

Maintainer of Material for MkDocs here. Correct! The Sponsorware strategy is an alternative to dual-licensing which works fairly well for our project. If you have a successful Open Source project that is a pain killer and product-market fit, this strategy might also work for your project.

I recommend checking the list of OpenSource projects that use Material for MkDocs [1], for example FastAPI [2]. Alternatively, you can clone the Material for MkDocs repository, as the docs are built with itself.

[1] https://github.com/squidfunk/mkdocs-material#trusted-by-

[2] https://github.com/tiangolo/fastapi

Jup, MathJax is supported with minimal setup: https://squidfunk.github.io/mkdocs-material/reference/mathja...

Author of Material for MkDocs here. MkDocstrings [1] implements automatic generation of reference documentation from sources. It's language-agnostic, actively maintained and currently supports Python [2] and Crystal [3]. It also integrates nicely with Material for MkDocs.

[1] https://mkdocstrings.github.io/

[2] https://github.com/mkdocstrings/python

[3] https://github.com/mkdocstrings/crystal

Thanks for your continued support!

The README has some links to installations used by open source projects and companies, see my other comment [1].

[1] https://news.ycombinator.com/item?id=27301712

Sphinx is Python-specific, and yes, in that instance much more powerful than MkDocs. MkDocs is a general documentation solution, which is language-agnostic. Also, Sphinx is normally written in rST with a steeper learning curve than Markdown, which to my knowledge is preferred by many users (especially non-technical people). As always, YMMV.

The Furo theme is rather new and borrows some things from Material for MkDocs, for example Admonitions. There's also Material for Sphinx [1], which is a port of Material for MkDocs to Sphinx. Note that it doesn't include all features Material for MkDocs offers.

[1] https://bashtage.github.io/sphinx-material/

Sure! The README links [1] to several installations used by large Open Source projects and companies. Some prominent examples:

- https://fastapi.tiangolo.com/

- https://crystal-lang.org/reference/

- https://docs.pi-hole.net/

- https://docs.openfaas.com/

- https://mozillafoundation.github.io/engineering-handbook/

- https://microsoft.github.io/code-with-engineering-playbook/

[1] https://github.com/squidfunk/mkdocs-material#trusted-by-

Jup, that's sadly a still unfixed bug in Safari [1]. Super annoying, but if we would use px for media queries, we would have to swap out all rem units with px, thus not respecting your default font size.

[1] https://adamwathan.me/dont-use-em-for-media-queries/

Did you maybe use a slow connection? When the search index is ready (it's built client-side in a web worker) it switches from "Initializing search" to "Type to start searching". This can be observed when setting network conditions in web inspector to "Slow 3G".

EDIT: You're right, on mobile it only switches to "Type to start searching" after clicking in the search field. Thanks! I'll file a bug report so we can fix it.