A long long time ago,@keats expressed interest in having Asciidoc support added to Zola, but stated that doing so would require a Rust-based parser and a contributor willing to do the work.
I’m writing to explore the idea of doing exactly that. I have been working on asciidoc-parser crate for a while now and it’s approaching a point where it’s potentially usable, at least as an experiment. I’ve been using Zola as my primary web engine for 4 years now (see How I Built 146 Parks ) and would be very happy to see these two projects come together.
My thought is that I would fork Zola (tentatively named Zoladoc) and run some code experiments to test viability of an integration. If anyone out there is a serious Rust coder and would like to contribute or has design/implementation ideas, feel free to ping me at zola@scouten.me. (Both asciidoc-parser and Zoladoc are/would be side projects for me, so don’t expect super-quick responses.)
If you’re interested in using this, sorry but at best it’s going to be a while. As @keats says, it’s a LOT of work and I’m only now beginning to scope it out.
I love Typst and use it to write papers, but its HTML export is still under active development (Typst docs, roadmap, v0.13 blog).
Markdown is everywhere and easy to write, but it can fall short for more complex technical documents. (personal opinion)
AsciiDoc (via Asciidoctor) is powerful yet relatively easy to author. We use it for our documentation, and Git’s own docs are written in AsciiDoc (Git CodingGuidelines). The Asciidoctor team also created Antora, a static site generator built around AsciiDoc (antora.org, Jamstack overview).
Many open-source projects, including the Linux kernel, use reStructuredText with Sphinx. It’s flexible enough for complex documentation, though I don’t love the syntax (Linux kernel docs: Sphinx).
Zola’s “everything in a single binary” approach is simultaneously one of its biggest strengths and one of its biggest weaknesses. Each time you add support for a new thing, the complexity rises exponentially, particularly wrt documentation. Zola makes most sense as a small fixed stack: markdown, tera, sass plus home grown image processing. Choose Zola, choose that stack.
The core functionality of a site generator is actually surprisingly trivial if you have a decent template engine and TOML processor– I knocked one up in a few days when it became apparent that I was working at cross purposes to Zola, and I’ve been using it very happily ever since. I suspect that you’ll find you can do the same with something based around Tera and asciidoc. Bear in mind that Tera 2 is on the way; I’ve left mine as Python + Jinja in anticipation of porting it to Rust once Tera 2 is stable.