Posted by japhyr 14 hours ago
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. :-)
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...
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.
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 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!
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.
How do you know?
Zensical itself is entirely free OSS software.
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.
Launched last week and build upon MyST engine. Makes Shphinx obsolete. Like to see a real comparison with Zensical.