> 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.
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...