HTML in a Markdown Document

Markdown is for content, not for formatting

For “those” of you who are familiar with Markdown and its variants¹, the headers of this page will seem misleading. You see, when I say that “markdown is for content, not for formatting” I do not mean that we should never include html in our documents, but rather that we should only include html in a markdown document when it pertains to the visual organization of the document, not to its semantic organization. The reason for this distinction becomes apparent if you try to use markdown in any serious way on the web.

It should come as no surprise to you that when you generate html from a markdown document that there are no div tags. This is because, as the W3C puts it: the div element has no special meaning at all. It would be meaningless to include div tags in markdown output because markdown creates semantically meaningful html.

Most would take this as a hint to disallow div tags within a markdown document; personally, I take the opposite stance. Because the div tag has no semantic meaning, we should include div tags whenever we know the content will be deployed via the web within some visual system. Adding div tags to a markdown document may make the file seem less like ‘true’ markdown, but it will not alter the way the markdown processor creates files².

This means that I can add div tags to my web content (which I write in markdown) whenever I feel that the content needs additional visual organization, beyond the semantic. Using div tags I can alter the way a site looks without altering what it means.

The only caveat is Markdown doesn’t like to parse within block elements. Luckily for us many have built a work-around:

<div class="someclass" id="someid" markdown="1">
    Insert markdown here
</div>

This is supported both by Markdown Extra, and Python Markdown Extra

Let’s omit the HTML5 please

With HTML 5 becoming very popular, markdown users have found that the new block level tags such as article or section do not play nice with markdown. People have made much of this when they shouldn’t have. Most of the changes to HTML5 are an attempt to restore semantic meaning within a web-page. What this means fundamentally is that markdown and the new changes to HTML5 are diametrically opposed. You shouldn’t include HTML5 elements in your markdown precisely because the new tags mean something to the structure of the content. The article tag and the section tag try to tell the browser what kind the content is, much like paragraph tags, or header tags. There is no real cogent reason to include HTML5 markdown in a document, unless, of course, one wishes to deploy the content only through html, in which case I might reasonably question why you chose markdown.