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

Deprecate Maruku in favor of a new default markdown interpreter #1752

Closed
benbalter opened this Issue Nov 24, 2013 · 30 comments

Comments

Projects
None yet
@benbalter
Copy link
Contributor

benbalter commented Nov 24, 2013

Maruku is dead. Long live Maruku.

Breaking out a discussion started in #1747 (comment) to its own thread: moving to a new default Markdown parser for Jekyll 2.0.0... Discuss.

marukuuuuu

The two big contenders in my mind would be Kramdown and Redcarpet.

Assuming performance and other developer concerns are a wash, I'd push for Kramdown, especially considering many users are going to be forced to move from Maruku. Kramdown supports Markdown Extra, like Maruku did/does, and I'd assume a non-small percentage rely on it. Syntax-wise, Kramdown is going to be most similar to Redcarpet, making the transition even easier.

Let the holy wars begin.

@polymetis

This comment has been minimized.

Copy link

polymetis commented Nov 24, 2013

Personally I have been using Kramdown for about 2 years and I quite like it.

@gregkare

This comment has been minimized.

Copy link
Contributor

gregkare commented Nov 24, 2013

Nice, I was just looking for the old "update maruku to 0.7" issue, because maruku 0.6.1 depends on syntax, which currently has issues installing on Rubinius >= 2.2.0 (#1733, distler/syntax#1).

@JesseHerrick

This comment has been minimized.

Copy link

JesseHerrick commented Nov 24, 2013

I think given the extra features, Kramdown would be a better switch so as not to force people out of using their favorite Markdown syntax (like Markdown Extra).

@anselmh

This comment has been minimized.

Copy link

anselmh commented Nov 24, 2013

Currently using redcarpet or rdiscount. The latter is working somehow the best with markdown and mixed (md+html) files. All others (incl. redcarpet) sometimes failed and misrendered Markdown syntax occasionally.

@jashank

This comment has been minimized.

Copy link
Contributor

jashank commented Nov 24, 2013

Hello... Is it speed you're looking for?

I spent some time benchmarking Jekyll with various Markdown processors. I'll let the resultant spreadsheet speak for itself: https://docs.google.com/spreadsheet/ccc?key=0Aq0ht9Vb59MXdDRVenVERlJ2M2dqZHJ3Zk95ZHp2UFE

From my write up at the time, the best performers were:

  1. BlueCloth, average 60.7 posts/s (stddev 17.860954)
  2. RedCarpet, average 56.1 posts/s (stddev 16.510995)
  3. RDiscount, average 54.9 posts/s (stddev 16.571145)
  4. RPEG-Markdown, average 52.6 posts/s (stddev 11.800097)
  5. Kramdown, average 40.1 posts/s (stddev 8.438867)
  6. Maruku, average 34.1 post/s (stddev 6.584619)
  7. Pandoc-Ruby, average 17.1 post/s (stddev 1.948292)

The most obvious, and in my opinion most interesting, observation is that the best case to run Jekyll is against 150-200 Markdown posts; the performance clearly peaks about here, then falls off quite sharply, up to nearly 50% fewer posts per second in most engines at the maximum number of posts.

Strangely, BlueCloth and RDiscount (which both use the same C library, Discount, to do their processing) perform detectably differently. RedCarpet (which has its own C extension based on Sundown), does fairly well, too, as does the Ruby wrapper around John MacFarlane's PEG-Markdown, another C library.

Of the pure-Ruby parsers, Kramdown performs the best, but it's noticeably behind the pace. Maruku is even further back, and Pandoc-Ruby, which calls out through the system to John MacFarlane's Pandoc (which is written in Haskell and can do everything), is about half as slow again.

The three groupings — native-accelerated, pure Ruby and shelling out — are all very obvious.

Personally, I prefer Kramdown for the balance of speed and features. I also quite like the internal architecture; it lends itself far more readily to extensibility.

@doktorbro

This comment has been minimized.

Copy link
Member

doktorbro commented Nov 27, 2013

I like Kramdown because:

  • the main developer is a European and would understand multilingual needs
  • it’s well documented

I like Redcarpet because:

  • @mattr- maintains Jekyll too
  • I’ve seen how easy the maintainers accept new features like ==mark== and "quote"

Documentation is a killer feature, so I would choose Kramdown as default parser.

@parkr

This comment has been minimized.

Copy link
Member

parkr commented Dec 8, 2013

Next release will be 2.0.0. Thoughts? I like Redcarpet myself, but I'm happy to use whatever, really.

@mattr-

This comment has been minimized.

Copy link
Member

mattr- commented Dec 9, 2013

Pros for Redcarpet:

  • Fast
  • HTML 5 compliant

Cons:

  • Releases are slow.

I haven't used the other Markdown tools enough to know.

@parkr

This comment has been minimized.

Copy link
Member

parkr commented Dec 14, 2013

Which markdown library supports Windows? Redcarpet can sometimes be difficult to build on Windows.

@polymetis

This comment has been minimized.

Copy link

polymetis commented Dec 14, 2013

Kramdown is pure ruby so it would support Windows as much as jekyll does.

@benbalter

This comment has been minimized.

Copy link
Contributor Author

benbalter commented Jan 5, 2014

I'm partial to RedCarpet but it makes upgrading annoying if you're using any of the other three, especially Maruku.

We're only talking about the default use case here (power users will use whatever they want), and any move we make is going to get us a speed bump from where we are now.

I think the upgrade path for non-technical "default" users is going to be the biggest factor here. Kramdown is 99% syntactically similar to MaruKu (excepting attributes), and anyone using attributes would be sophisticated enough to switch engines.

@doktorbro

This comment has been minimized.

Copy link
Member

doktorbro commented Jan 6, 2014

Pros for Redcarpet: HTML 5 compliant

This is not true. Issues:

@parkr

This comment has been minimized.

Copy link
Member

parkr commented Jan 16, 2014

GitHub Pages recommends Kramdown, as it has the greatest feature parity with Maruku: https://help.github.com/articles/migrating-your-pages-site-from-maruku

I'm 👍 on moving to either Kramdown or a GFM solution.

@mhulse

This comment has been minimized.

Copy link

mhulse commented Jan 16, 2014

Sorry, but what does GHFMD use? I thought that was RedCarpet? I'd personally like to stick with whatever GH uses for issues and such.

@JesseHerrick

This comment has been minimized.

Copy link

JesseHerrick commented Jan 16, 2014

It seems as if they're based on Kramdown given the Markdown Extra features.

On Thu, Jan 16, 2014 at 4:57 PM, Micky Hulse notifications@github.comwrote:

Sorry, but what does GHFMD use? I thought that was RedCarpet? I'd
personally like to stick with whatever GH uses for issues and such.


Reply to this email directly or view it on GitHubhttps://github.com//issues/1752#issuecomment-32551389
.

@mattr-

This comment has been minimized.

Copy link
Member

mattr- commented Jan 16, 2014

GFM isn't based on anything that's public. The closest that comes to it is RedCarpet, which was used for GFM for awhile but isn't anymore.

@benbalter

This comment has been minimized.

Copy link
Contributor Author

benbalter commented Jan 16, 2014

AFAIK, GitHub uses https://github.com/jch/html-pipeline, but that includes other non-Markdown things like Emoji.

@mhulse

This comment has been minimized.

Copy link

mhulse commented Jan 16, 2014

Ahh, interesting. Learn something new everyday. Thanks folks! :octocat:

@afeld

This comment has been minimized.

Copy link
Contributor

afeld commented Jan 16, 2014

GitHub uses https://github.com/jch/html-pipeline

True. I think @gjtorikian is experimenting w/ creating a plugin to support it here: https://github.com/gjtorikian/jekyll-html-pipeline/.

@parkr

This comment has been minimized.

Copy link
Member

parkr commented Jan 25, 2014

After giving this more thought, I think the final decision should be about compatibility and the best user experience. Kramdown has syntax most similar to Maruku (for non-standard features, that is), and it has stellar docs, which makes getting started with it and migrating to it from Maruku wonderfully easy.

I've made a PR for this: #1988

@tyoc213

This comment has been minimized.

Copy link

tyoc213 commented Jan 27, 2014

Latelly I have seen a lot of pages on github (pages) where

some

or

console.log("test");

Is printed "normal" without any formatting, is this "normal"? or it is not related to this?

@parkr

This comment has been minimized.

Copy link
Member

parkr commented Jan 27, 2014

@tyoc213 We haven't switched over the default markdown converter yet – where are you seeing this?

@tyoc213

This comment has been minimized.

Copy link

tyoc213 commented Jan 27, 2014

One of them was an output from a octopress... this one for example: http://javaongsan.github.io/blog/2014/01/19/how-to-control-mdi-form-menu-dynamically-for-different-login-user/ so that is a false.

But I guess this one: is applicable? https://github.com/tinkerpop/gremlin/wiki/Gremlin-Groovy-Path-Optimizations or perhaps they just missed something? also see that here it is ok: https://github.com/tinkerpop/gremlin/wiki same place. Haven't clone it, but doing a compare, it looks like they have used at less

 some

isn't that right? https://github.com/tinkerpop/gremlin/wiki/Gremlin-Groovy-Path-Optimizations/_compare/fbe85e8f13136dd6da7fc61a1d0911c6bae28e08...1b5865393b794baf3a4874bee7e4a570ce03d5f2

Don't know if Im right or wrong... it is just something that I see.

@pathawks

This comment has been minimized.

Copy link
Member

pathawks commented Jan 27, 2014

One of them was an output from a octopress... this one for example: http://javaongsan.github.io/blog/2014/01/19/how-to-control-mdi-form-menu-dynamically-for-different-login-user/ so that is a false.

I don't think this has anything to do with Marku or Kramdown.

javaongsan.github.io is using rdiscount for Markdown.

@parkr parkr closed this in #1988 Feb 8, 2014

@nasht00

This comment has been minimized.

Copy link
Contributor

nasht00 commented Nov 4, 2015

I know this is old. I'm just starting with Jekyll and liked that redcarpet supports

'''languageName

But I am wondering about drawbacks.

Is there a list that compares features, pros and cons?
I'm not worried about migrating from Maruku since it's a new project.

@JesseHerrick

This comment has been minimized.

Copy link

JesseHerrick commented Nov 4, 2015

I actually wrote an article comparing markdown processors: http://www.sitepoint.com/markdown-processing-ruby/

On Wed, Nov 4, 2015 at 7:30 AM, Nathan Hazout notifications@github.com
wrote:

I know this is old. I'm just starting with Jekyll and liked that redcarpet supports

'''languageName

But I am wondering about drawbacks.
Is there a list that compares features, pros and cons?

I'm not worried about migrating from Maruku since it's a new project.

Reply to this email directly or view it on GitHub:
#1752 (comment)

@nasht00

This comment has been minimized.

Copy link
Contributor

nasht00 commented Nov 4, 2015

Thanks! You wrote that they all support fences, like the example I showed above.
However when I used kramdown it did not display correctly. With redcarpet yes.

I guess from your blog post, I'm safe choosing redcarpet as my default...

@JesseHerrick

This comment has been minimized.

Copy link

JesseHerrick commented Nov 4, 2015

@nasht00 I've found both Kramdown and Redcarpet wonderfully full-featured, but Redcarpet is significantly faster. Back to your problem, however, fences are denoted using backticks, not single quotes.

Correct:

```ruby
```

Incorrect:

'''ruby
'''
@envygeeks

This comment has been minimized.

Copy link
Contributor

envygeeks commented Nov 4, 2015

It's both ``` and ~~~. The latter belonging to Kramdown which does not follow the Github definition of what the fencing delimiter is.

@nasht00

This comment has been minimized.

Copy link
Contributor

nasht00 commented Nov 5, 2015

@JesseHerrick in my example I used single quotes because I could not figure out how to escape backtiks :)

@envygeeks Thanks that seems to be it. Although it did not seem to trigger syntax highlighting.
More reasons to use Redcarpet I guess.

@jekyll jekyll locked and limited conversation to collaborators Feb 27, 2017

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.