Markdown versus HTML

Some of this style guide assumes that you're using HTML. If you're using Markdown, details like what HTML elements to use in various contexts may be irrelevant to you.

Markdown is easier to write than HTML, and it's easier for most humans to read Markdown source than HTML source. However, HTML is more expressive (particularly regarding semantic tagging) and can achieve some specific effects that may be difficult or impossible in Markdown.

In the end, which one to use is primarily a matter of personal preference; however, if your team or your document template already uses one or the other, it may be best to use whatever they use.