Markdown versus HTML

Use either HTML or Markdown. 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 might 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 might be difficult or impossible in Markdown. For example, you might have to switch to using the HTML code element for special characters in code such as nonbreaking spaces.

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.