squidfunk
Joined 11 years ago
Karma
124
Submissions
63
Member since
Aug 10
Recent submissions
Comment · 7 months ago
Creator of Zensical here! Would you mind sharing a bit more detail on why you feel the comparison is on point? One of our core goals with Zensical is to simplify things – not add complexity. We’re also working toward making it an almost 100% drop-in replacement for Material and the broader MkDocs ecosystem, so I’d be especially interested in understanding what feels more complicated from your perspective. I’d appreciate any specifics on where we can improve.
That said, I do think the linked comparison may be a bit misleading. As far as I can tell, MaterialX is still largely based on the Material for MkDocs codebase with mostly some UI changes, several of which the author has taken from Zensical.
Comment · 11 months ago
Zensical 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-py...
Comment · 1 year ago
Coming 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.
Comment · 1 year ago
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.
Comment · 1 year ago
Zensical 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.
Comment · 1 year ago
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.
Comment · 1 year ago
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.
Comment · 1 year ago
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.
Comment · 1 year ago
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
Comment · 1 year ago
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.
Comment · 1 year ago
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!
Comment · 1 year ago
We set up a Discord for the community, and have a dedicated space for professionals!
https://zensical.org/docs/community/get-involved/
Comment · 1 year ago
We'll ship fuzzy search in the coming weeks. It's just awaiting a release.
Comment · 1 year 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.
Based in Cologne, Germany.