Zensical – a Modern Static Site Generator Built by the Material for Mkdocs Team
Key topics
The Material for MkDocs team has released Zensical, a new static site generator, sparking discussion about its features, design choices, and potential use cases, with some users excited about its potential and others raising concerns about compatibility and customization.
Snapshot generated from the HN discussion
Discussion Activity
Very active discussionFirst comment
3h
Peak period
21
6-12h
Avg / period
7.8
Based on 62 loaded comments
Key moments
- 01Story posted
Nov 9, 2025 at 7:50 AM EST
about 2 months ago
Step 01 - 02First comment
Nov 9, 2025 at 11:06 AM EST
3h after posting
Step 02 - 03Peak activity
21 comments in 6-12h
Hottest window of the conversation
Step 03 - 04Latest activity
Nov 12, 2025 at 10:03 PM EST
about 2 months ago
Step 04
Generating AI Summary...
Analyzing up to 500 comments to identify key contributors and discussion patterns
Want the full context?
Jump to the original sources
Read the primary article or dive into the live Hacker News thread when you're ready.
[1]: https://zensical.org/docs/setup/basics/#theme-variant
How do you know?
I am also very curious about what the MKDocs future would be like. Material has been the most popular theme for MkDocs. People are not using it because they have chosen MkDocs, but using MkDocs because they have chosen Material. With Zensical promising (some kind of) MkDocs compatibility, there will be fewer reasons to stay on MkDocs instead of migrating to the new project.
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.
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.
if not I'd be happy to help get something started for folks who want to learn and contribute.
Should I expect a “good enough” pdf export experience in zensical at some point or now?
[1]: mkdocstrings.github.io
A gated feature? Malicious intent?
Zensical itself is entirely free OSS software.
For context, I work on TanStack DB which is a differential dataflow / DBSP inspired reactive client datastore. Super interested in your use case.
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
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.
It doesn't support loading content from a database that I'm aware of, it uses markdown files on disk as input.
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.
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.
That said, if pressed, I’d recommend AsciiDoc[0] over any Markup flavor for a greenfield project _today_. We had to either add or bake plugins or extensions to get features that are already included in AsciiDoc, making our Markup implementation both more complex and wholly unique. That wasn’t a huge problem, because we didn’t have a large pool of contributors to educate and support, but it would have been much easier just to point to a standard.
But, hey! The roadmap includes modules, to make way for other source formats! This is the way. :-)
[0] https://asciidoc.org/
EDIT: s/That's the way/This is the way. :-)/
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 hasn't reached its v0.1.0 milestone yet, but soon.
First, your landing page doesn't describe how TapirMD fits into the Markdown universe. I just see a list of features. Why should I read the list? Ah, the spec page[0] has some info, but it should really be on the landing page.
Second, and more importantly, TapirMD is not a superset of CommonMark[1]. GitHub had its own flavor of MD, but it's been some years now since they migrated to a CommonMark base plus extensions[2].
I recommend looking more closely at the CommonMark universe and innovating there.
[0] https://tmd.tapirgames.com/specification.html [1] https://commonmark.org/ [2] https://github.github.com/gfm/
TapirMD is not a superset of Markdown or CommonMark. It simply inherits some of its DNA from Markdown. While Markdown is very simple, it is also highly underspecified and syntactic inconsistent. CommonMark improves on it slightly, but not fundamentally. Moreover, basic Markdown lacks many essential features that web content writers need.
Yes, none of these factors prevent it from being adopted widely. But for me, the limited feature set is the real blocker. I don’t want to rely on a patchwork of extensions and third-party tools.
TapirMD (where MD stands for `markup doc`) aims to address these shortcomings. It is a new language, deliberately not compatible with Markdown, and never intended to fit within the Markdown ecosystem. Its official toolchain is designed to empower web content writers to create rich, feature-complete articles without relying on any third-party tools.
The spec is too long to serve as a landing page. Maybe a concise demo showcasing sample code on the leading page would be great. Thank you again for the constructive criticism.
TapirMD was primarily developed for my own needs as a technical writer, to produce content for my websites (see the .tmd soruce of my articles: https://tmd.tapirgames.com/use-cases.html). Markdown simply felt too limiting. I've been using TapirMD for over a year now and am quite satisfied with it. I'd be delighted if it proves helpful to other writers as well.
Is there anything planned like 11ty's data files[1]? For example, I can pass it a JSON file, or a TOML file, and have it generate one HTML page per document in that file using their pagination system in a hacky way, and add those pages to collections for grouping in navigation and such using their templating language. This makes it a lot easier to autogenerate documentation from a combination of sources (since anything we want can emit some appropriate JSON/TOML) without having a real "source document". It's hard to tell at a glance if this is something that would be possible with the upcoming module system.
[1]: https://www.11ty.dev/docs/data-global/
[1]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-py...
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/
I'm currently using Material for MkDocs but was thinking of switching off it, in part due to the lack of options around having custom highlighting in code blocks (my docs website is for a programming language I am working on). What are Zensical's plans here? Tree sitter highlighting would be perfect in my case.
Since adopting it, I’ve also grown fond of Mike, the plugin which lets users see the various different versions of a doc (without needing to resort to git).
But I’ve also experienced plenty of pain points when pushing the customisation envelop. Weird bugs appeared in many places which were clearly due to MKDocs’s poor architecture and performance was also never stellar.
Congratulations on launching Zeniscal and I’m quite excited to see the future of it, but I do very much hope that in 12 months time, one way or the other, I’m able to still have similar functionality to what the plugins provide.
I hope the new theme allows for more customization than the old Material theme. It was really hard to create a unique brand identity within the constraints of Material; it just wasn't built with customization in mind beyond a color. The "modern" theme looks minimal in a way that gives me some hope for this.
Looking forward to kicking the tires on Zensical!
[1]: https://starlight.astro.build/getting-started/
I don’t really care how long it takes to build as long as it’s not minutes. Also don’t care about “modern” look whatever that means really. And I have lots of custom components that (I assume?) would be hard to migrate
Launched last week and build upon MyST engine. Makes Shphinx obsolete. Like to see a real comparison with Zensical.