2025 Documentation best practices

[dbuenzli]

@davesnx

If we render html in the markdown mode, this output can’t be used for github renderer, static site generators or problems with LLMs.

These all look like pretty bad arguments to degrade the user experience. I’m not sure why you’d want to please the github renderer. If your static site generator is not able to render raw HTML in commonmark then maybe switch to another one. And for LLMs… ah yes, people never learn.