On Wed, Aug 24, 2022 at 9:08 AM Fabian Arrotin arrfab@centos.org wrote:
For that reason, some SIGs (including Infra SIG), moved already their doc to markdown format, easy to write/review through PR and automatically rendered.
I'd just like to throw out a vote for using a more powerful markup language such as asciidoc with better support for templating, linking, and overall a more robust experience when it comes to writing documentation.
For example we write our upstream documentation for STF in asciidoc ( https://github.com/infrawatch/documentation) and upon merge to the main branch, is auto-rendered ( https://github.com/infrawatch/documentation/blob/master/.github/workflows/ma...) and published into a static site ( https://infrawatch.github.io/documentation/).
I understand the desire for markdown since most people are generally able to guess the syntax, but for a little bit of extra effort asciidoc has been a really enjoyable experience from the extra power and rendering capabilities it provides (while maintaining the ability to review and preview content out of git both remote and locally).
Thanks Leif.