[HN Gopher] Zensical - A modern static site generator built by t...
___________________________________________________________________
Zensical - A modern static site generator built by the Material for
MkDocs team
Author : japhyr
Score : 107 points
Date : 2025-11-09 12:50 UTC (10 hours ago)
(HTM) web link (squidfunk.github.io)
(TXT) w3m dump (squidfunk.github.io)
| fishgoesblub wrote:
| I was excited up until they showed what the new theme looks like.
| mkdocs-Material was nice in that it didn't have overly rounded
| corners and over travesties, a shame that custom CSS will be
| needed to undo the "modernisation". Overall this seems very
| interesting, especially the performance improvements, just a
| letdown visually.
| squidfunk wrote:
| 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
| wpm wrote:
| > Most users favor the new look over the old one.
|
| How do you know?
| squidfunk wrote:
| 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.
| whycome wrote:
| Early adopters are a very distinct set of users. Probably
| not great to extrapolate from it.
| quietbritishjim wrote:
| 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.
| esafak wrote:
| https://github.com/zensical/zensical
| irskep wrote:
| I'm really excited by this development! Material for MkDocs has
| raised the quality level of so many projects' docs, my own
| included, by making good navigation the default. It's by far my
| favorite system to browse as a reader, and use as a project
| maintainer.
|
| 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!
| portaouflop wrote:
| I use docusaurus and am happy - any reason I should switch to
| this or does it make more sense if you have a greenfield use
| case?
|
| 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
| Thev00d00 wrote:
| Bold to move away from both of the things that contributed to
| their success initially (mkdocs, material design) at once.
| maxloh wrote:
| 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.
| bryanhogan wrote:
| 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/
| maxloh wrote:
| 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.
|
| 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.
| squidfunk wrote:
| > 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.
| RyJones wrote:
| As a multi-year sponsor for your work, our open-source
| community really appreciates the work.
| eviks wrote:
| 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 wrote:
| We'll ship fuzzy search in the coming weeks. It's just awaiting
| a release.
| eviks wrote:
| Nice!
| mberning wrote:
| 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 wrote:
| 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 wrote:
| 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.
| thisisharsh7 wrote:
| 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 wrote:
| We set up a Discord for the community, and have a dedicated
| space for professionals!
| https://zensical.org/docs/community/get-involved/
| laserbeam wrote:
| 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 wrote:
| 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.
| xixixao wrote:
| 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 wrote:
| 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
| kapilvt wrote:
| Sphinx does have markdown support fwiw
| WhyNotHugo wrote:
| 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.
| tamimio wrote:
| It looks interesting, might give it a try. I currently use Zola
| and it's been great so far.
| aerzen wrote:
| Why are some files obfuscated in the ui repo? It looks like
| compiled typescript has been included without the original
| source.
|
| A gated feature? Malicious intent?
| squidfunk wrote:
| 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.
| evilmonkey19 wrote:
| 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 wrote:
| 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.
| samwillis wrote:
| I'm really intrigued by the use of differential dataflow in a
| static site toolkit, but there isn't much in the way written
| about it. If anyone from the team are here I would love it if you
| could explain how it's being used? Does this enable fast
| incremental builds, only changing the parts that change in the
| input? If so how do you model that? Are you using multisets as a
| message format inside the engine?
|
| For context, I work on TanStack DB which is a differential
| dataflow / DBSP inspired reactive client datastore. Super
| interested in your use case.
| squidfunk wrote:
| 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
| runningmike wrote:
| 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.
___________________________________________________________________
(page generated 2025-11-09 23:00 UTC)