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! <http://ajh.us/bbmk-title-in-div> vs <http://ajh.us/bbmk-title-in-header> 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. <http://ajh.us/bbmk-title-in-header-extra> 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. <http://ajh.us/bbmk-title-in-header> 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
Le 17-sept.-2014 ? 17:46, Alan Hogan <contact at alanhogan.com> a ?crit :> 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. > > <http://ajh.us/bbmk-title-in-header-extra>I'll just point out that the markdown="1" trick should be credited to John Gruber. It was his plan to incorporate this into Markdown at some point (and if I recall well, one of the 1.0.2 betas had the feature enabled, but it was removed in later betas because it had issues). I do agree that it is overly verbose. Perhaps we should have an alternative simpler syntax. I though of this the other day (notice the `*`): <header*> Header! ------ Subtitle </header>> 5. Look for Common Mark, a.k.a. ?stdmd 0.1?, in Babelmark. > > <http://ajh.us/bbmk-title-in-header> > > 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.Here is the conflict. CommonMark interprets it "right" according to your intent, but the Markdown spec by John Gruber is very explicit about block-level HTML elements:> Note that Markdown formatting syntax is not processed within > block-level HTML tags. E.g., you can?t use Markdown-style *emphasis* > inside an HTML block. > > -- <https://daringfireball.net/projects/markdown/syntax#html>Of course, Markdown.pl doesn't treat `<header>` as a block-level HTML element as this element didn't exist at the time. HTML5 brought us a couple of those block-level elements, and some Markdown parsers have been catching up while others ignored this completely. I think the spec makes it clear that the content of `<header>` should not be parsed with the Markdown syntax. As for whether the spec is right or wrong in that choice, that is another debate entirely. As a new flavor, CommonMark is free to deviate from the Markdown spec. But for my part I don't intend to implement a change that'd break who knows how many of a ten year legacy of documents with HTML snippets in them. -- Michel Fortin michel.fortin at michelf.ca http://michelf.ca
On 9/17/14, 5:46 PM, Alan Hogan wrote:> 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. )I?m not sure that everyone shares your expectations. I expect HTML to be left alone unless I specifically say otherwise. As for Markdown per se, the decision is Gruber?s. As for everything else, that?s the beauty of open source ? if you don?t like what exists, create your own. The necessary downside to this is the Tower of Babel effect where different ?Markdown variants? are not equal to each other.> 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! > > <http://ajh.us/bbmk-title-in-div> > vs > <http://ajh.us/bbmk-title-in-header>This is where robust test suites are helpful. In my mind, the most valuable part of the Common Mark effort thus far is a robust test suite. The problem is that the test suite doesn?t differentiate between *fixing* Markdown (e.g. the known bugs and inconsistencies) and *changing* Markdown (e.g. rewriting the rules and expectations into something different). This means that authors of other tools (e.g. me) have to dig through 100?s of ?failed? tests to see which ones are true failures and which ones are differences of opinion.> 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. > > <http://ajh.us/bbmk-title-in-header-extra> > > 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.The more you use tools that deviate from Markdown, by definition the more this will happen. MultiMarkdown and PHP Markdown Extra both support this feature, so three of the four tools you mention should support this feature ? though it may be limited to the iA Writer Pro version only according to their website? http://support.iawriter.com/help/kb/general-questions/how-can-i-preview-markdown If GitHub Flavored Markdown doesn?t support this feature, it would seem to be a reasonable feature request, and then this would work everywhere for you.> 5. Look for Common Mark, a.k.a. ?stdmd 0.1?, in Babelmark. > > <http://ajh.us/bbmk-title-in-header> > > 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.Again ?right? is a subjective term here. It?s only right if you?re using the CommonMark syntax. If you?re using Markdown, then some of what you call ?right? is actually ?wrong.? But if you prefer the CommonMark approach, then by all means continue to use it. That?s the beauty of choice.> 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 > _______________________________________________ > Markdown-Discuss mailing list > Markdown-Discuss at six.pairlist.net > https://pairlist6.pair.net/mailman/listinfo/markdown-discuss >-- Fletcher T. Penney fletcher at fletcherpenney.net