Top
Best
New

Posted by japhyr 11/9/2025

Zensical – A modern static site generator built by the Material for MkDocs team(squidfunk.github.io)
168 points | 62 commentspage 2
evilmonkey19 11/9/2025|
I really like this new approach and I will give it a go on some open-source projects I have. Btw, I have looked into Zensical Spark but I did not fully understand what is it? It is just for connecting with the team so you help other teams to set it up and help them with feature requests and training?
squidfunk 11/9/2025|
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.

bryanhogan 11/9/2025||
Interested to look into this more, but Astro Starlight[1] has been by far the best in recent times. Only Vitepress comes close.

[1]: https://starlight.astro.build/getting-started/

adastra22 11/10/2025||
How mature is this right now? I am just now starting a new greenfield project and might have gone with MkDocs. Should I do Zensical instead? Or would it be better to use Material for MkDocs while the bugs are being worked out, and trust in the upgrade path?
squidfunk 11/10/2025|
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/

esafak 11/9/2025||
https://github.com/zensical/zensical
laserbeam 11/9/2025||
Unfortunately, I require PDF outputs for some of my documentation. Right now this is possible via some plugins (I cannot remember which fork of a pdf export plugin worked, but at least one does) in Material for MkDocs. It’s not perfect, but it is good enough.

Should I expect a “good enough” pdf export experience in zensical at some point or now?

squidfunk 11/9/2025|
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.
runningmike 11/9/2025||
The new modern static site generator and best for now seems to be Jupyter Book 2 - https://jupyterbook.org/stable/

Launched last week and build upon MyST engine. Makes Shphinx obsolete. Like to see a real comparison with Zensical.

eviks 11/9/2025||
the featured search engine is not typo-resistant, so unfortunately loses to google again, a bane of many sites. Wish search baseline finally caught up to the fact that humans can't type perfectly... (hopefully that's just because it's new and fresh, though)
squidfunk 11/9/2025|
We'll ship fuzzy search in the coming weeks. It's just awaiting a release.
eviks 11/9/2025||
Nice!
sureglymop 11/9/2025||
Can I also use it to write blog posts and generate an RSS feed for them?

A lot of documentation sites want this but it was always hard with things like sphinx where the input must be files on disk so one couldn't e.g. load blog posts from a db.

perpil 11/10/2025||
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.

sureglymop 11/10/2025||
Thanks for the information. If files on disk are a requirement that would be a shame. Such tools keep abstracting such that one can generate a plethora of output formats but don't abstract the input in such a way that one could programmatically add content. Even though that wouldn't stand in the way of using the filesystem as the source regardless.
kurayashi 11/10/2025||
It’s a requirement for now. But once the module system is in its possible to add other data sources.
jarofgreen 11/10/2025||
> 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.

sureglymop 11/10/2025||
Sure! I am coming from sphinx, another python based documentation tool that is used for example for the Linux Kernel docs, Python's docs, etc.

While it is great for documentation, we used it for the whole website of a project, mainly because people in the team already understood it. But we ran into many issues when it came to adding a blog...

Sphinx has a hard requirement for input files to be on disk. It means that, for example, it would be hard to add a page that lists all blog posts posted in a certain category (as the "meta" page would have to inspect other pages and then be generated on the fly). The only option is to pre-generate such pages into the source folder before a build.

I think that the inputs should be abstracted in a way such that there isn't a hard requirement on the filesystem. For example, extensions should be able to add input files using code, without having to write them to the filesystem first. This would make many things much easier and open a new world of possibilities without actually resulting in more maintenance work for the ssg.

The thing is that the output is abstracted in that way, one can create a new plugin to write to a different output format. If one could also "generate" input/source files dynamically, one would get support for all of these output formats "for free".

As for me personally, I don't really have enough blog posts to have to store them in a db, that was just an example. But if abstracted transparently in the way I am thinking about it actually doesn't matter for the ssg, it only knows about inputs and outputs and not how it got these inputs.

thisisharsh7 11/9/2025||
Hi, congrats on Zensical release. Want to ask is there any community space where people discuss ideas or what's being built?

if not I'd be happy to help get something started for folks who want to learn and contribute.

squidfunk 11/9/2025|
We set up a Discord for the community, and have a dedicated space for professionals! https://zensical.org/docs/community/get-involved/
mberning 11/9/2025|
The biggest issue I had with material for mkdocs was training BA type people to contribute. They had to muddle their way through python, pip, git, github, etc. just to make a one line change.
squidfunk 11/9/2025||
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!
synergy20 11/9/2025||
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.

More comments...