Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document differences from Commonmark #500

Closed
Crissov opened this Issue Mar 6, 2018 · 5 comments

Comments

Projects
None yet
2 participants
@Crissov
Copy link

Crissov commented Mar 6, 2018

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 gettalong self-assigned this Mar 6, 2018

@gettalong

This comment has been minimized.

Copy link
Owner

gettalong commented Mar 6, 2018

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).

@gettalong gettalong closed this Mar 6, 2018

@Crissov

This comment has been minimized.

Copy link
Author

Crissov commented Mar 6, 2018

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

This comment has been minimized.

Copy link
Owner

gettalong commented Mar 6, 2018

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

This comment has been minimized.

Copy link
Author

Crissov commented Mar 6, 2018

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

This comment has been minimized.

Copy link
Owner

gettalong commented Mar 6, 2018

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.