Markdown within block-level elements

Alan Hogan contact at
Wed Sep 17 17:46:13 EDT 2014

I just wanted to share a few short observations regarding Markdown within block-level elements, which I (and the Common Mark project) wish to be enabled by default.

1. I believe this to be a very desirable feature for writing Web content. (See item #6 for specific motivation. Generally and intuitively, I expect everything in my markdown document to be subject to Markdownification, with the exception of indented, fenced, or back tick-delimited code and content within (not between!) HTML tags. )

2. If your parser/converter does allow this, *please* make sure it is HTML5-aware. There should not be this much difference between a <div> and a <header>.  Just look at how many implementations consider <header> to be plain text, wrapping it in paragraph tags!


3. Michel Fortin came up with a clever solution to allow this at authors’ discretion way back when, but it is not popular, and most other flavors ignore the markdown=“1” flag altogether. It is usually echoed into rendered HTML by other flavors. It is One More Thing for an author to memorize, so I don’t love the writing experience with it, either. I would like to see Markdown within block-level elements to be the default.


4. This won’t be a surprise to anyone, but the differences between flavors here is causing me real problems as an author. I am currently writing in iA Writer, previewing with Marked, managing changes with GitHub, and publishing with PHP Markdown Extra. Naturally, these all give different results, decreasing (a) my confidence as an author and (b) the utility of Markdown, since I am forced to write more raw HTML to get consistent and desirable output.

5. Look for Common Mark, a.k.a. “stdmd 0.1”, in Babelmark.


  Note that it gets the output right: It interprets the <header> tags as block-level tags inside of which I wrote more content. The only other packages to do so were Haskell markdown package 0.1, cheapskate 0.1, and pandoc 1.13.

6. For those curious, the reason I want to wrap an <h1> and a <p> inside of a <header> is that, with the removal of <hgroup>, it arguably remains the best way to semantically represent some instances of the “subtitle” concept HTML never really provided for. It’s a pattern recommended in the HTML5 standard.

Thanks for your consideration.
Alan Hogan

More information about the Markdown-Discuss mailing list