5 ms·
Zensical – A modern static site generator built by the Material for MkDocs team
- fishgoesblub 11mo agoI 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 11mo agoCreator 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 https://zensical.org/docs/setup/basics/#theme-variant
- wpm 11mo ago> Most users favor the new look over the old one. How do you know?
- squidfunk 11mo agoFrom 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.
- jug 11mo agoI do think it's looking fine, and above all a cross between Android (Material 3 Expressive), Windows 11 'Fluent UX', and iOS which I think will make many feel right at home. This wasn't really the case with the "old" Material style.
- deleted 11mo ago[deleted]
- quietbritishjim 11mo agoSomeone 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.
- j1elo 11mo agoIn todays News, someone built a whole Hotel with freely available design plans, and a user finds a travesty in the font style of the Cold/Hot sink taps being too round.
- esafak 11mo agohttps://github.com/zensical/zensical https://github.com/zensical/zensical
- irskep 11mo agoI'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 11mo agoI 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 11mo agoBold to move away from both of the things that contributed to their success initially (mkdocs, material design) at once.
- maxloh 11mo agoMaterial 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 11mo agoInterested 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/ https://starlight.astro.build/getting-started/
- maxloh 11mo agoIt 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 11mo ago> 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 11mo agoAs a multi-year sponsor for your work, our open-source community really appreciates the work.
- eviks 11mo agothe 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)
- mberning 11mo agoThe 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 11mo agoWe'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 11mo agonow 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 11mo agoHi, 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 11mo agoWe set up a Discord for the community, and have a dedicated space for professionals! https://zensical.org/docs/community/get-involved/ https://zensical.org/docs/community/get-involved/
- laserbeam 11mo agoUnfortunately, 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 11mo agoYes, 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 11mo agoDocumentation 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 11mo agoWe'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 11mo agoSphinx does have markdown support fwiw
- WhyNotHugo 11mo agoAFAIK, 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 11mo agoIt looks interesting, might give it a try. I currently use Zola and it’s been great so far.
- aerzen 11mo agoWhy 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 11mo agoIt'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 11mo agoI 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 11mo agoZensical 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 11mo agoI'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 11mo agoExcellent 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 https://github.com/zensical/zrx
- runningmike 11mo agoThe new modern static site generator and best for now seems to be Jupyter Book 2 - https://jupyterbook.org/stable/ https://jupyterbook.org/stable/ Launched last week and build upon MyST engine. Makes Shphinx obsolete. Like to see a real comparison with Zensical.
- sureglymop 11mo agoCan 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 11mo agoIts predecessor (mkdocs material) supported blogs via a plugin and rss feeds via a mkdocs plugin (https://guts.github.io/mkdocs-rss-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-strategy 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 11mo agoThanks 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 11mo agoIt’s a requirement for now. But once the module system is in its possible to add other data sources.
- jarofgreen 11mo ago> 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.
- finallyspeaking 11mo agoI’m delighted to see this project evolving and look forward to following its development! I’ve used just about every markup technology over my (many) years as a tech writer, from troff macros, to SGML/DocBook and then XML/DITA, and finally, to Markup with the Material for MkDocs project, as a sponsor. Each has its strengths and weaknesses, but for enabling contributors outside the tech writing community, simpler source formats are the way. 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/ https://asciidoc.org/ EDIT: s/That's the way/This is the way. :-)/
- mroche 11mo ago> That said, if pressed, I’d recommend AsciiDoc over any Markup flavor for a greenfield project _today_. 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/ https://antora.org/ [1] https://gitlab.eclipse.org/eclipse-wg/asciidoc-wg/asciidoc.org/-/blob/main/awesome-asciidoc.adoc https://gitlab.eclipse.org/eclipse-wg/asciidoc-wg/asciidoc.o...
- parser_error 11mo agoThis looks very interesting, I'm using mkdocs+material for one site (and it's great) but trying to find a good solution for more complex docs. 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/ https://www.11ty.dev/docs/data-global/
- squidfunk 11mo agoComing 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.
- f2hex 11mo agoI 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 11mo agoZensical 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-python-types https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-py...
- f2hex 11mo agoThank 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.
- adastra22 11mo agoHow 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 11mo agoZensical 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/ https://zensical.org/compatibility/
- amterp 11mo agoThis looks great! 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.
- squidfunk 11mo agoZensical 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.
- aryonoco 11mo agoAbout 12 months ago I was looking for a SSG for our documentation website and after trying many different options settled on Material for MKDocs. I had a list of criteria such as Mermaid.js and PlantUML support which no other option easily supported, but Material for MkDocs had a plugin for everything. 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.