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.
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.
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.
> 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.
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?
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.
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.
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.
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.
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.
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)
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.
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
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.
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!
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.
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.
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
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.
> 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.
As a multi-year sponsor for your work, our open-source community really appreciates the work.
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?
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.
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.
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
> Most users favor the new look over the old one.
How do you know?
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.
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!
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/
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.
We set up a Discord for the community, and have a dedicated space for professionals! https://zensical.org/docs/community/get-involved/
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)
We'll ship fuzzy search in the coming weeks. It's just awaiting a release.
Nice!
https://github.com/zensical/zensical
Bold to move away from both of the things that contributed to their success initially (mkdocs, material design) at once.
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.
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
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.
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!
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.