3 ms·

Is there a canonical Markdown specification now? A machine readable grammar? Last I looked, Markdown was a bunch of almost-compatible interpretations based on l

Is there a canonical Markdown specification now? A machine readable grammar? Last I looked, Markdown was a bunch of almost-compatible interpretations based on lore and opinion.

hprotagonist 4y ago
there's still at least four marksdown that i can think of offhand, and likely far more.
Decabytes 4y ago
> This has been somewhat ameliorated by the rise of CommonMark, which aims to provide a more formal specification for Markdown, and the adoption of CommonMark (albeit often with some extensions) on some popular social platforms They mention CommonMark as a popular specification
the_af 4y ago
What's puzzling is that the creator of Markdown wants it like this, and actively resisted endorsing an official standard. He got into a fight with Jeff Atwood from Coding Horror / StackOverflow because of this.
- eduction 4y ago
  He didn’t like when CommonMark was named “Standard Markdown” or when it was renamed “Common Markdown:” https://blog.codinghorror.com/standard-markdown-is-now-common-markdown/ https://blog.codinghorror.com/standard-markdown-is-now-commo... It also sounds like he ignored an invitation to join the effort to create what became CommonMark. Since that was as close as anyone came to standardizing, ya it seems reasonable to conclude he’s fine with the ambiguities.
  - the_af 4y ago
    Yes, that's the conversation I meant. Gruber got irritated by even attempting to get his opinion on this effort. Very, very weird.
  - avgcorrection 4y ago
    Should have called it Common AppleFan.
laurent123456 4y ago
I'm getting a sense that it's standardising around CommonMark.
xiaq 4y ago
Much of the community has coalesced around CommonMark. You'll still find Markdown implementations with a "don't care" attitude, but if an implementation targets any specification at all it's going to be CommonMark, a superset of it, or (more rarely) a subset of it.
zdw 4y ago
This is the reason that most projects I've been a part of end up on Sphinx/ReStructuredText as the docs generator of choice - has a huge installed base of users and developers spread across many projects. Markdown is great for a simple readme, but once you start needing larger more structured docs, or want output formats other than HTML, it just falls down.
- partdavid 4y ago
  On the whole, rST for sure has the right stuff. Having a document model and a nice standard extensible mechanism for syntax really helps. It's been my favorite. But even when writing my last paper I used Markdown (+pandoc) because I had a coauthor and Github et al. have made it more familiar to so many more people. Maybe in niches like the Python community but it's a distinctly minority option, at least where I've worked.
- grumpyprole 4y ago
  Is there a formal spec for ReStructuredText? Not every project would want a dependency on the Python ecosystem.
- thangalin 4y ago
  > it just falls down. Oh? These are written in Markdown and typeset using ConTeXt: * https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_Design https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_... (see 9.9.1) * https://www.docdroid.net/eGHQ6O7/autonoma-pdf https://www.docdroid.net/eGHQ6O7/autonoma-pdf (see emojis and speech bubbles in chapter 2) * https://impacts.to/downloads/lowres/impacts.pdf https://impacts.to/downloads/lowres/impacts.pdf (99% pure Markdown) * https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdown-part-8/jekyll-hyde.pdf https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... (technically XHTML, but can be converted)
shp0ngle 4y ago
There is CommonMark, but even that is very opiniated. One of the issues is that original Markdown used tabs everywhere, but people started using spaces, but some implementations choke down on them. The biggest issue in Markdown is that whitespace is significant and important; and there are tons of weird edgecases of all the various rules clashing with each other. Even CommonMark has some weird unspecified edgecases. I was briefly involved with a Markdown parser implementation… it’s really really hard to parse MarkDown. Not sure if harder than to parse HTML, as I did not do that. But it’s still really really hard.

Is there a canonical Markdown specification now? A machine readable grammar? Last I looked, Markdown was a bunch of almost-compatible interpretations based on lore and opinion.

hprotagonist 4y ago

there's still at least four marksdown that i can think of offhand, and likely far more.

Decabytes 4y ago

> This has been somewhat ameliorated by the rise of CommonMark, which aims to provide a more formal specification for Markdown, and the adoption of CommonMark (albeit often with some extensions) on some popular social platforms They mention CommonMark as a popular specification

the_af 4y ago

What's puzzling is that the creator of Markdown wants it like this, and actively resisted endorsing an official standard. He got into a fight with Jeff Atwood from Coding Horror / StackOverflow because of this.

eduction 4y ago
He didn’t like when CommonMark was named “Standard Markdown” or when it was renamed “Common Markdown:” https://blog.codinghorror.com/standard-markdown-is-now-common-markdown/ https://blog.codinghorror.com/standard-markdown-is-now-commo... It also sounds like he ignored an invitation to join the effort to create what became CommonMark. Since that was as close as anyone came to standardizing, ya it seems reasonable to conclude he’s fine with the ambiguities.
- the_af 4y ago
  Yes, that's the conversation I meant. Gruber got irritated by even attempting to get his opinion on this effort. Very, very weird.
- avgcorrection 4y ago
  Should have called it Common AppleFan.

laurent123456 4y ago

I'm getting a sense that it's standardising around CommonMark.

xiaq 4y ago

Much of the community has coalesced around CommonMark. You'll still find Markdown implementations with a "don't care" attitude, but if an implementation targets any specification at all it's going to be CommonMark, a superset of it, or (more rarely) a subset of it.

zdw 4y ago

This is the reason that most projects I've been a part of end up on Sphinx/ReStructuredText as the docs generator of choice - has a huge installed base of users and developers spread across many projects. Markdown is great for a simple readme, but once you start needing larger more structured docs, or want output formats other than HTML, it just falls down.

partdavid 4y ago
On the whole, rST for sure has the right stuff. Having a document model and a nice standard extensible mechanism for syntax really helps. It's been my favorite. But even when writing my last paper I used Markdown (+pandoc) because I had a coauthor and Github et al. have made it more familiar to so many more people. Maybe in niches like the Python community but it's a distinctly minority option, at least where I've worked.
grumpyprole 4y ago
Is there a formal spec for ReStructuredText? Not every project would want a dependency on the Python ecosystem.
thangalin 4y ago
> it just falls down. Oh? These are written in Markdown and typeset using ConTeXt: * https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_Design https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_... (see 9.9.1) * https://www.docdroid.net/eGHQ6O7/autonoma-pdf https://www.docdroid.net/eGHQ6O7/autonoma-pdf (see emojis and speech bubbles in chapter 2) * https://impacts.to/downloads/lowres/impacts.pdf https://impacts.to/downloads/lowres/impacts.pdf (99% pure Markdown) * https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdown-part-8/jekyll-hyde.pdf https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... (technically XHTML, but can be converted)

shp0ngle 4y ago

There is CommonMark, but even that is very opiniated. One of the issues is that original Markdown used tabs everywhere, but people started using spaces, but some implementations choke down on them. The biggest issue in Markdown is that whitespace is significant and important; and there are tons of weird edgecases of all the various rules clashing with each other. Even CommonMark has some weird unspecified edgecases. I was briefly involved with a Markdown parser implementation… it’s really really hard to parse MarkDown. Not sure if harder than to parse HTML, as I did not do that. But it’s still really really hard.