knghtbrd
commented
8 years ago I've committed a few changes toward this for the obvious things I knew about. Since at this time we aren't trying to re-render those .md files to HTML, and since I thinkI got the major issues, I'm going to close this as resolved. If I missed something major, feel free to reopen and tell me what I missed.
See rasppleii/a2cloud#13 for the A2CLOUD bug for this same issue.
TL;DR: Redcarpet/GFM sucks for writing HTML manuals. Kramdown doesn't, but has bugs in GFM mode. Kramdown syntax differs from GFM for a few things. I blame John Gruber. README.md files need to be written in GFM for GitHub.
Longer explanation in commit log for rasppleii/a2cloud@60d54a6:
Fix the remaining fixme's Note: I've been using kramdown to generate HTML, and kramdown generates id tags for headings automatically. Redcarpet does not, and in fact Redcarpet (the official GFM implementation) does not support any alternative means of specifying id, class, or other HTMLish things. In other words, redcarpet is extremely limited compared to kramdown.
So just use kramdown right? Well it's not that easy. Kramdown can parse GFM, but it has some bugs when doing so. For example, when fixing these last fixmes, I had some level three headings,
### stuff, which were rendered as<p>### stuff</p>rather than<h3>stuff</h3>. Sigh.When rendering the HTML using kramdown's own syntax variant, it did this right. But kramdown's variant has some subtle differences in things like fenced code blocks. GitHub will not render kramdown's fenced code bocks properly, and kramdown will not render GitHub's fenced code blocks properly unless set to parse GFM.
In terms of source code, that only matters for README.md, since GitHub only renders README.md for you. You can't get it to render other .md files even if you want it to. That said, using two different Markdown variants causes problems with confusion regarding what is and isn't valid Markdown syntax. As it is, vim doesn't fully recognize either syntax using any syntax plugin I've tried. And the precise syntax used on the GitHub website is obviously going to be GitHub's.
All of this to basically more eloquently say, DAMMIT JOHN GRUBER! He readily acknowledges the limitations of the reference implementation of Markdown, suggests anyone who wants to improve the syntax go and do so, yet stubbornly refuses any effort to standardize these extensions. He's encouraging a thousand niche forks, but actively trying to sabotage any standardization. This is a widely acknowledged irritation with the Markdown family of markup languages.
My notion going forward is that we should assume README.md is in GFM, and all other .md files are Kramdown format. If I can come up with a clever way to indicate this syntactic difference, I will.