I'll note first for visibility: I would be more than happy to make a pull request for all this myself... but I have a strong feeling that would be annoying to review, so I won't do so without explicit permission 😅
There are a number of instances where HTML tags are used within Markdown documents. For consistency and readability, these should be replaced with their respective Markdown syntax. See markdownlint's MD033, and one of the stated design goals of Markdown:
The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
There are still some cases where HTML is needed. <sup> has no Markdown equivalent (though we could use a simple extension for that), so we'd want to add it to the allowed_elements list for MD033. And obviously there's no way to recreate the install form in Markdown. For that, we should wrap it in an explicit configuration comment: <!-- markdownlint-{disable,enable} no-inline-html -->
There's also the alert.html includes, where Markdown is not parsed within the content parameter. I would personally advocate for using {% capture %} syntax to solve this. This would also allow usage of Liquid tags within the alert text itself.
We would be replacing:
{% include alert.html type='note' content='Kernel-level anti-cheat solutions are generally unsupported on desktop Linux.<br>You may want to search <a href="https://areweanticheatyet.com">Are We Anti-Cheat Yet</a> if a game doesn't work.' %}with:
{% capture anticheat_note %}
Kernel-level anti-cheat solutions are generally unsupported on desktop Linux. \\
You may want to search [Are We Anti-Cheat Yet](https://areweanticheatyet.com) if a game doesn't work.
{% endcapture %}
{% include alert.html type='note' content=anticheat_note %}
I'll note first for visibility: I would be more than happy to make a pull request for all this myself... but I have a strong feeling that would be annoying to review, so I won't do so without explicit permission 😅
There are a number of instances where HTML tags are used within Markdown documents. For consistency and readability, these should be replaced with their respective Markdown syntax. See markdownlint's
MD033, and one of the stated design goals of Markdown:<hr>should be replaced with the---horizontal rule syntax<img>should be replaced with theimage syntax<a>should be replaced with the[text](url)inline link syntax (there's a couple instances inINSTALL.mdandIMAGES.md)There are still some cases where HTML is needed.
<sup>has no Markdown equivalent (though we could use a simple extension for that), so we'd want to add it to theallowed_elementslist forMD033. And obviously there's no way to recreate the install form in Markdown. For that, we should wrap it in an explicit configuration comment:<!-- markdownlint-{disable,enable} no-inline-html -->There's also the
alert.htmlincludes, where Markdown is not parsed within thecontentparameter. I would personally advocate for using{% capture %}syntax to solve this. This would also allow usage of Liquid tags within the alert text itself.We would be replacing:
{% include alert.html type='note' content='Kernel-level anti-cheat solutions are generally unsupported on desktop Linux.<br>You may want to search <a href="https://areweanticheatyet.com">Are We Anti-Cheat Yet</a> if a game doesn't work.' %}with:
{% capture anticheat_note %} Kernel-level anti-cheat solutions are generally unsupported on desktop Linux. \\ You may want to search [Are We Anti-Cheat Yet](https://areweanticheatyet.com) if a game doesn't work. {% endcapture %} {% include alert.html type='note' content=anticheat_note %}