Please prefer standard Markdown syntax wherever possible and only use HTML if you can't accomplish the goal with the Markdown syntax! Raw HTML reduces the readability and portability, but can improve the design, layout and overview of rendered documents. Anyway, consider to use raw HTML sparingly and only if necessary!
Use a HTML paragraph <p>
tag with the align
attribute. Although if the HTML 5 specification states that the align
attribute is obsolete it is the only possible solution because the style
tag is disallowed raw HTML within Markdown so the CSS text-align
property can not be used.
Aligning content can improve the design and layout e.g. images and project logos by either using center
, left
or right
as value for the align
attribute.
⇣ Incorrect code for this rule:
<p style="text-align:center">The winter is winter is sparkling and frozen!</p>
⇡ Correct code for this rule:
<p align="center">The winter is winter is sparkling and frozen!</p>
Use a HTML <img>
to add inline content like images or icons for better visualization. This allows to use e.g. a favicon of a website and define its size with the width
and height
attributes using either a pixel or percentage (withdouble quotes for the %
character) value.
Although MDN states that the width
and height
attributes are deprecated and advises to replace them with the corresponding CSS attributes, but it is the only possible solution because the style
tag is disallowed raw HTML within Markdown so the CSS width
and height
property can not be used.
⇣ Incorrect code for this rule:
Sparkling <img src="https://raw.githubusercontent.com/nordtheme/assets/main/static/images/artworks/arctic/nature/dark/snowfall.svg?sanitize=true" style="text-align:center;width:16;height:16" /> snowflakes falling down in the winter!
No way to define the size:
Sparkling ![falling snowflakes](https://raw.githubusercontent.com/nordtheme/assets/main/static/images/artworks/arctic/nature/dark/snowfall.svg?sanitize=true) snowflakes falling down in the winter!
⇡ Correct code for this rule:
Sparkling <img src="https://raw.githubusercontent.com/nordtheme/assets/main/static/images/artworks/arctic/nature/dark/snowfall.svg?sanitize=true" width=16 height=16 align="center" /> snowflakes falling down in the winter!
Use the HTML <details>
tag to add collapsible content. It creates a disclosure widget in which information is visible only when the widget is toggled into an open state. A summary or label can be provided using the <summary>
element.
This can be useful to e.g. hide large table of contents or code blocks that might disturb the focus or force the reader to scroll long sites.
⇡ Correct code for this rule:
<details>
<summary>Winter</summary>
<p>Sparkling and frozen!</p>
</details>