6 ms·

Kramdown – A Ruby library for parsing and converting a superset of Markdown

46 points by type0 10y ago

bitexploder 10y ago
This is very similar to Pandoc, which also processes things into its own AST/Internal representation. It then knows how to translate its representation into a many different outputs. Pandoc is really nice and you can script it with a variety of languages, though if you really want to dig in you have to use Haskell. Kramdown using Ruby makes it more accessible and has some cool options like table of contents generation that is more flexible than Pandoc. You can see some discussion of supporting Kramdown in pandoc. https://github.com/jgm/pandoc/issues/2711 https://github.com/jgm/pandoc/issues/2711 Generally I think pandoc is the more mature tool, but I can see places where it might be a better call (especially if your app needs it as a library and you aren't willing to call a command (Pandoc).
- cel1ne 10y ago
  I use pandoc to convert the electron API-doc from markdown to XML. Then I use XSLT to create kotlin bindings: https://github.com/fab1an/kotlin-electron-api https://github.com/fab1an/kotlin-electron-api XSLT still rules for content-transformation.
- nerdponx 10y ago
  In my opinion, Pandoc is by far the best Markdown parser nowadays because it can be configured to support just about any Markdown flavor you can think of. Kramdown meanwhile seems to lack that configurability, and moreover has somewhat nonstandard support for in-line math. I switched to Pandoc on my Jekyll site and never looked back.
  - geraldbauer 10y ago
    > Kramdown meanwhile seems to lack that configurability FYI: To configure kramdown such as using GitHub-flavored markdown (GFM) or using govspeak or slackdown etc. you use a new/different parser class. For example to use GFM in GitHub Pages / Jekyll in _config.yml add: kramdown: input: GFM Cheers.
busterarm 10y ago
Kramdown is the default for Jekyll now and it's pretty awesome. I switched the content team over to writing all of the pages for our sites in Kramdown and they're enjoying it much more than HTML. Easier for both them and us to maintain.
ddebernardy 10y ago
> It is probably the fastest pure-Ruby Markdown converter available (September 2014), being about 3x faster than Maruku and about 4.5x faster than BlueFeather. Last I was regularly programming in Ruby, the yardstick seemed to be RedCarpet. Has this changed? https://github.com/vmg/redcarpet https://github.com/vmg/redcarpet
- ferbivore 10y ago
  RedCarpet is partly written in C.
myst 10y ago
"Fast" and "pure-Ruby" in one phrase puzzles me.
- blunte 10y ago
  It's all relative. For processing one or a few documents at a time, on modern hardware it probably doesn't matter what language is used. Repeat the process on a million documents (do a million markdown docs exist in one place?), and Kramdown might not be considered "fast" compared to other options...
  - busterarm 10y ago
    We're processing several thousand documents every time our site builds and performing multiple full-document regexp replacements, writing YML front matter and parsing HTML to Kramdown. Only takes a few seconds total.
    - blunte 10y ago
      Exactly. As long as it fits your situation, it's fast enough. My last company used Ruby a lot (and it's what got me hired there), but we hit so many cases where the data was so large that we were forced to use something else. My colleague would fall back to Java, but I used those times as excuses to learn Go. Where Ruby fits, it's wonderful. Where it just doesn't fit, all of its niceness is overshadowed by its scaling issues.
      - busterarm 10y ago
        I've done massive (billions of rows) ETL jobs in pure ruby (since 2.2.0) without Ruby being the bottleneck. A lot of performance problems I've seen went away when they fixed the garbage collection (especially of symbols). There's a small handful of others I saw resolved by using JRuby. I mean, if you need good threads, you probably shouldn't be on Ruby, but as far as I can tell its single-core performance is pretty okay compared to other scripting languages. It's still the absolute best (most features I need in the standard library, or easy to use libraries, and easiest to use) thing I've ever used for working with manipulating large quantities of text (save for maybe Perl, but ew). I've started using Elixir when I need concurrency, but Ruby is still the language I'm most likely to use for most classes of problem.
edem 10y ago
I'm not sure whether the author intended "pure-Ruby" to be an advantage or a disadvantage. For me Ruby is a huge no-go and I always try to avoid it if possible for the simpe reason that no Ruby program works for the first time and whenever I install a gem it is possible that it breaks another. For someone who comes from the distributable binaries world this is simply unbearable.
- roryisok 10y ago
  Learning ruby at the moment and this is setting off alarm bells. What? gems break each other?
  - byroot 10y ago
    That is mostly FUD. It's trendy to hate on Ruby these days. But yes, in Ruby there is a global namespace and open classes, so you can do pretty much whatever you want. But in any language you'll find bad libraries. I mean I can write a go / rust / Java / whatever library that immediately segfault, panic or exit(1) when you invoke it. Does it mean any of those languages are bad?
    - edem 10y ago
      The big difference is that if you download a jar it won't brake your other jars because they work in isolation
  - yebyen 10y ago
    If you are learning, then you should learn about rvm, bundler, gemsets, and vendoring gems. There are ways in Ruby to avoid stepping on your own feet with gems, simultaneously whilst avoiding stepping on others feet within in your own team(s) and on the same servers in a traditional Unix-type multi-tenant environment. The central question solved by Bundler is "what version of the gem am I using?" and the core issue addressed by RVM is "what version of Ruby." If you are coming from a tradition of packages for your programming language interpreter that are managed by the OS, and similarly language module packages that come from the OS, and you expect that pattern to just work with Ruby, then yeah, you are quite likely going to have a bad time. Ruby handles these issues internally out of necessity. It does so because for most of us taking this stuff very seriously, we need to be able to run the latest version of the gem (or, any given arbitrary version that our own production release engineering process has settled on) with our chosen OS Distro with the Long-Term Support release. Long term support releases (or, for example, Debian stable releases) use packages that are frozen to a version at a point in time and are likely to be at least a year old. If your gem solves a problem for you but it legitimately hasn't been updated in more than a year, chances are good it's because there's someone else who has made another gem, solving the problem in a better way, and people have already moved on. There is simply no way to address this concern on arbitrarily many OS Distros simultaneously without solving it generally in a way that eschews the OS package manager altogether. When you're committed to solving the problem without the OS package manager's help, bringing it back into the loop is more likely to get in the way than to solve any actual problem. So you find a lot of outdated packages for ruby libraries in OS package managers, when they are even provided at all. I'm not sure if GP had problems with Ruby because of reliance on OS package managers, but if I was a betting man... This is concern #2 from 12 factor methodology of development, Dependency Isolation: https://12factor.net https://12factor.net
geraldbauer 10y ago
FYI: I've put together an Awesome Kramdown page - https://github.com/viennahtml/awesome-kramdown https://github.com/viennahtml/awesome-kramdown - (in the GitHub tradition) incl. q&a w/ founder/dev, tips & tricks, kramdown extensions, live services & more. New links/additions welcome.
lmm 10y ago
I don't think Kramdown can be a superset of Markdown, because it doesn't handle nested bulleted lists that indicate the level with simple indentation (unlike every Markdown implementation I've seen). I was very frustrated when GitHub Pages switched to Kramdown and broke many of my posts.
- tomatsu 10y ago
  > [Kramdown] doesn't handle nested bulleted lists that indicate the level with simple indentation Works for me. * foo * bar * bat * asdf Results in: <ul> <li>foo <ul> <li>bar</li> <li>bat</li> </ul> </li> <li>asdf</li> </ul>
  - busterarm 10y ago
    Definition lists are better HTML for this anyway and I switched to those a long time ago. Kramdown implemented this in a similar way to PHP Markdown Extra. https://kramdown.gettalong.org/syntax.html#definition-lists https://kramdown.gettalong.org/syntax.html#definition-lists That said, it's not very clean Markdown.
- geraldbauer 10y ago
  > it doesn't handle nested bulleted lists that indicate the level with simple indentation (unlike every Markdown implementation I've seen) Again kramdown can - of course - handle nested lists (bulleted or numbered or even with nested code blocks and more). kramdown is just a little bit stricter about the whitespace indentation (your indentation has to line-up - that's all - no big deal really. Try it live here -> http://trykramdown.herokuapp.com http://trykramdown.herokuapp.com
accordionclown 10y ago
is there a javascript version of kramdown? by the way, i don't know how they compare with each other, but the speed of commonmark.js is blazing fast these days.
- geraldbauer 10y ago
  FYI: kramdown is popular because it has "out-of-the-box" lots of extras built-in e.g. attribute lists, table of content generation, html blocks with inline markdown, and so on - commonmark.js is "just" plain old vanilla markdown. Cheers.

46 points by type0 10y ago

This is very similar to Pandoc, which also processes things into its own AST/Internal representation. It then knows how to translate its representation into a many different outputs. Pandoc is really nice and you can script it with a variety of languages, though if you really want to dig in you have to use Haskell. Kramdown using Ruby makes it more accessible and has some cool options like table of contents generation that is more flexible than Pandoc. You can see some discussion of supporting Kramdown in pandoc. https://github.com/jgm/pandoc/issues/2711 https://github.com/jgm/pandoc/issues/2711 Generally I think pandoc is the more mature tool, but I can see places where it might be a better call (especially if your app needs it as a library and you aren't willing to call a command (Pandoc).

cel1ne 10y ago
I use pandoc to convert the electron API-doc from markdown to XML. Then I use XSLT to create kotlin bindings: https://github.com/fab1an/kotlin-electron-api https://github.com/fab1an/kotlin-electron-api XSLT still rules for content-transformation.
nerdponx 10y ago
In my opinion, Pandoc is by far the best Markdown parser nowadays because it can be configured to support just about any Markdown flavor you can think of. Kramdown meanwhile seems to lack that configurability, and moreover has somewhat nonstandard support for in-line math. I switched to Pandoc on my Jekyll site and never looked back.
- geraldbauer 10y ago
  > Kramdown meanwhile seems to lack that configurability FYI: To configure kramdown such as using GitHub-flavored markdown (GFM) or using govspeak or slackdown etc. you use a new/different parser class. For example to use GFM in GitHub Pages / Jekyll in _config.yml add: kramdown: input: GFM Cheers.

busterarm 10y ago

Kramdown is the default for Jekyll now and it's pretty awesome. I switched the content team over to writing all of the pages for our sites in Kramdown and they're enjoying it much more than HTML. Easier for both them and us to maintain.

ddebernardy 10y ago

> It is probably the fastest pure-Ruby Markdown converter available (September 2014), being about 3x faster than Maruku and about 4.5x faster than BlueFeather. Last I was regularly programming in Ruby, the yardstick seemed to be RedCarpet. Has this changed? https://github.com/vmg/redcarpet https://github.com/vmg/redcarpet

ferbivore 10y ago
RedCarpet is partly written in C.

myst 10y ago

"Fast" and "pure-Ruby" in one phrase puzzles me.

blunte 10y ago
It's all relative. For processing one or a few documents at a time, on modern hardware it probably doesn't matter what language is used. Repeat the process on a million documents (do a million markdown docs exist in one place?), and Kramdown might not be considered "fast" compared to other options...
- busterarm 10y ago
  We're processing several thousand documents every time our site builds and performing multiple full-document regexp replacements, writing YML front matter and parsing HTML to Kramdown. Only takes a few seconds total.
  - blunte 10y ago
    Exactly. As long as it fits your situation, it's fast enough. My last company used Ruby a lot (and it's what got me hired there), but we hit so many cases where the data was so large that we were forced to use something else. My colleague would fall back to Java, but I used those times as excuses to learn Go. Where Ruby fits, it's wonderful. Where it just doesn't fit, all of its niceness is overshadowed by its scaling issues.
    - busterarm 10y ago
      I've done massive (billions of rows) ETL jobs in pure ruby (since 2.2.0) without Ruby being the bottleneck. A lot of performance problems I've seen went away when they fixed the garbage collection (especially of symbols). There's a small handful of others I saw resolved by using JRuby. I mean, if you need good threads, you probably shouldn't be on Ruby, but as far as I can tell its single-core performance is pretty okay compared to other scripting languages. It's still the absolute best (most features I need in the standard library, or easy to use libraries, and easiest to use) thing I've ever used for working with manipulating large quantities of text (save for maybe Perl, but ew). I've started using Elixir when I need concurrency, but Ruby is still the language I'm most likely to use for most classes of problem.

edem 10y ago

I'm not sure whether the author intended "pure-Ruby" to be an advantage or a disadvantage. For me Ruby is a huge no-go and I always try to avoid it if possible for the simpe reason that no Ruby program works for the first time and whenever I install a gem it is possible that it breaks another. For someone who comes from the distributable binaries world this is simply unbearable.

roryisok 10y ago
Learning ruby at the moment and this is setting off alarm bells. What? gems break each other?
- byroot 10y ago
  That is mostly FUD. It's trendy to hate on Ruby these days. But yes, in Ruby there is a global namespace and open classes, so you can do pretty much whatever you want. But in any language you'll find bad libraries. I mean I can write a go / rust / Java / whatever library that immediately segfault, panic or exit(1) when you invoke it. Does it mean any of those languages are bad?
  - edem 10y ago
    The big difference is that if you download a jar it won't brake your other jars because they work in isolation
- yebyen 10y ago
  If you are learning, then you should learn about rvm, bundler, gemsets, and vendoring gems. There are ways in Ruby to avoid stepping on your own feet with gems, simultaneously whilst avoiding stepping on others feet within in your own team(s) and on the same servers in a traditional Unix-type multi-tenant environment. The central question solved by Bundler is "what version of the gem am I using?" and the core issue addressed by RVM is "what version of Ruby." If you are coming from a tradition of packages for your programming language interpreter that are managed by the OS, and similarly language module packages that come from the OS, and you expect that pattern to just work with Ruby, then yeah, you are quite likely going to have a bad time. Ruby handles these issues internally out of necessity. It does so because for most of us taking this stuff very seriously, we need to be able to run the latest version of the gem (or, any given arbitrary version that our own production release engineering process has settled on) with our chosen OS Distro with the Long-Term Support release. Long term support releases (or, for example, Debian stable releases) use packages that are frozen to a version at a point in time and are likely to be at least a year old. If your gem solves a problem for you but it legitimately hasn't been updated in more than a year, chances are good it's because there's someone else who has made another gem, solving the problem in a better way, and people have already moved on. There is simply no way to address this concern on arbitrarily many OS Distros simultaneously without solving it generally in a way that eschews the OS package manager altogether. When you're committed to solving the problem without the OS package manager's help, bringing it back into the loop is more likely to get in the way than to solve any actual problem. So you find a lot of outdated packages for ruby libraries in OS package managers, when they are even provided at all. I'm not sure if GP had problems with Ruby because of reliance on OS package managers, but if I was a betting man... This is concern #2 from 12 factor methodology of development, Dependency Isolation: https://12factor.net https://12factor.net

geraldbauer 10y ago

FYI: I've put together an Awesome Kramdown page - https://github.com/viennahtml/awesome-kramdown https://github.com/viennahtml/awesome-kramdown - (in the GitHub tradition) incl. q&a w/ founder/dev, tips & tricks, kramdown extensions, live services & more. New links/additions welcome.

lmm 10y ago

I don't think Kramdown can be a superset of Markdown, because it doesn't handle nested bulleted lists that indicate the level with simple indentation (unlike every Markdown implementation I've seen). I was very frustrated when GitHub Pages switched to Kramdown and broke many of my posts.

tomatsu 10y ago
> [Kramdown] doesn't handle nested bulleted lists that indicate the level with simple indentation Works for me. * foo * bar * bat * asdf Results in: <ul> <li>foo <ul> <li>bar</li> <li>bat</li> </ul> </li> <li>asdf</li> </ul>
- busterarm 10y ago
  Definition lists are better HTML for this anyway and I switched to those a long time ago. Kramdown implemented this in a similar way to PHP Markdown Extra. https://kramdown.gettalong.org/syntax.html#definition-lists https://kramdown.gettalong.org/syntax.html#definition-lists That said, it's not very clean Markdown.
geraldbauer 10y ago
> it doesn't handle nested bulleted lists that indicate the level with simple indentation (unlike every Markdown implementation I've seen) Again kramdown can - of course - handle nested lists (bulleted or numbered or even with nested code blocks and more). kramdown is just a little bit stricter about the whitespace indentation (your indentation has to line-up - that's all - no big deal really. Try it live here -> http://trykramdown.herokuapp.com http://trykramdown.herokuapp.com

accordionclown 10y ago

is there a javascript version of kramdown? by the way, i don't know how they compare with each other, but the speed of commonmark.js is blazing fast these days.

geraldbauer 10y ago
FYI: kramdown is popular because it has "out-of-the-box" lots of extras built-in e.g. attribute lists, table of content generation, html blocks with inline markdown, and so on - commonmark.js is "just" plain old vanilla markdown. Cheers.