Document differences from Commonmark

[Crissov]

The syntax documentation mentions wherever it diverges from Gruber’s description for his markdown.pl, called “Standard Markdown” here (sometimes with lowercase s). I think it would be more helpful nowadays to (also) document differences from Commonmark which is much more internally coherent than Markdown.

By the way, the homepage claims GFM as an alternative input format. GitHub changed its markdown parser to an extended fork of cmark in 2017, i.e. (almost) conforms to CM, so Kramdown should do so there as well.

PS: #197 asked for closer CM compatibility over three years ago.

[gettalong]

The GFM parser is based on the orginal GFM syntax, created at a time when there were no official references or a parser; it was mainly included for the Jekyll people so that they get more coherent rendering between Github and Github pages.

I don't have anything against commonmark trying to be more compatible to kramdown 😄. But I don't think that we will get that in the near future.

As for the documentation: I don't think that it is useful to document differences from another Markdown version. If I went down the route, I would probably need to document differences from other popular parsers/converters like PHP Markdown (Extra).

[Crissov]

In my experience, Commonmark is (rightly) perceived as the new gold standard for Markdown compatibility. It is not just yet another flavor. Your users would benefit from knowing what if anything Kramdown does differently. Also, if you really wanted Commonmark to become more like Kramdown, it would help to know where they are not the same yet.

[gettalong]

Commonmark may become a standard but currently it is not. The situation is still like XKCD foretold. Also note that the new GFM is not commonmark, i.e. yet another Markdown implementation.

And I think you misunderstand the purpose of kramdown. It is not here to serve people who want to use commonmark, they can use commonmark for this task. And since Github uses commonmark there are Ruby bindings to the reference C implementation or a pure Ruby implementation. No need for me or anybody else to add yet another Ruby commonmark implementation.

The reason people are still using kramdown is that there are still some things it does that commonmark doesn't do, IALs for example. That's also the main reason I wrote kramdown in the first place once Maruku wasn't maintained anymore.

[Crissov]

GitHub’s cmark-gfm supports Commonmark with extensions. This is exactly the point of CM. Kramdown does not need to become yet another implementation of vanilla CM. It’s fine as it is. It is just really helpful for users if the same basic markdown syntax (without using extensions) yields the same output. After all, “markdown” can be entered in a lot of cases where the user cannot control the parser used nor would they know.

[gettalong]

GitHub’s cmark-gfm supports Commonmark with extensions.

So some text written for cmark-gfm is parsed and rendered differently when used with just cmark. Two parser, two ways to render one input file, two standards, not one.

As I said: If you want to use commonmark, just go ahead and use it. It just doesn't make sense for me in this case to invest time into re-implementing commonmark as another parser option in kramdown.

And it currently also doesn't make sense to change the way kramdown parses "basic" things as it would break tons of existing documents. Those that were made with kramdown and not commonmark syntax in mind.

As for use of markdown on websites: There are so many different flavours in use - why should kramdown implement commonmark's flavour and not the other way around?