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.
