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/main.yml#L17) 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.