Opinion on asciiDoc for docs-as-code approach

[fjp]

Hi, I recently discovered asciiDoc and looking at https://squidfunk.github.io/mkdocs-material/alternatives/ if it is compared too.

I know asciiDoc is not based on markdown files but it seems to provide some useful and commonly used features out of the box, such as richer table formatting, admonitions, inclusion of external content and it is following a standard (no variants needed compared to markdown). A comparison between asciiDoc and markdown can be found here: https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/. It seems to also shine in generating different output formats such as pdf. With mkdocs-material, PyMdown Extensions and some other MkDocs plugins most of these ootb features are covered but I would still be interested in your opinion.

So in case you have some experience with asciiDoc and/or antora (to combine docs from mutliple repos) could you please share your thoughts on using asciiDoc for the docs-as-code approach instead of MkDocs?

[squidfunk]

I'm not a user of AsciiDoc, so I can't answer that part, but I want to lose a few words on the "it's standardized" argument. In simple words, a standard is essentially just something many people agree on in the form of a document, so that implementers have a reference on expected behavior. Markdown also comes with several standards, e.g. GFM or CommonMark.

We currently don't have a standard for the flavor of Markdown we are supporting, but I already talked to several people if it would be worth writing something up. In the end, the flavor of Markdown we're using and which is largely powered and influenced by @facelessuser's Python Markdown Extension has proven to work, given so many people and companies are using it happily and successfully. Furthermore, not having to spec everything out from the beginning helped us iterate, providing or even inventing features that wouldn't otherwise have seen the light of day. If we trust GitHub's metrics, Material for MkDocs alone seems to have more than twice as many users as AsciiDoc, not considering MkDocs as a whole or all Markdown solutions combined. People seem to favor Markdown for its simplicity and extensibility. However, I agree that printing and publishing in other formats is something were other tools are more powerful than MkDocs. There's definitely some work to be done on that front, but it's all solvable.

IMHO, a proper solution to print Material for MkDocs flavored Markdown or convert it to a portable format, might be a great sponsorware project to start, if you're up to it! Also, if somebody wants to help push out a standard, I'm happy to support them in any way I can. I just don't have the time to craft a standard myself, and it should be a working group anyway.

Other than that, my opinion is: choose whatever works for you. There are hundreds of discussions on Twitter, Reddit, etc. with users switching back and forth between SSG, which often sounds like "grass is always greener on the other side" syndrom. There's no perfect solution, it always depends on your use case.