Zensical – A modern static site generator built by the Material for MkDocs team

f2hex 11/10/2025|

I would be interested to know why the radical change to move the configuration file from YAML to TOML. Is there any good reason for that change?

squidfunk 11/10/2025|

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

f2hex 11/10/2025||

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.

Thev00d00 11/9/2025||

Bold to move away from both of the things that contributed to their success initially (mkdocs, material design) at once.

maxloh 11/9/2025|

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.

tamimio 11/9/2025||

It looks interesting, might give it a try. I currently use Zola and it’s been great so far.

xixixao 11/9/2025|

Documentation tooling for Python (especially reference docs) is… abysmal. Sphinx is the king, with no markdown support. Pdoc would be nice, it the authors didn’t reject reasonable additions, leading to forks. And mkdocs is not simple to setup. If you’re building a company for this, please fix this.

squidfunk 11/9/2025||

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

WhyNotHugo 11/9/2025|||

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.

kapilvt 11/9/2025||

Sphinx does have markdown support fwiw