
Kramdown – A Ruby library for parsing and converting a superset of Markdown - type0
https://kramdown.gettalong.org/
======
busterarm
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.

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

------
ddebernardy
> 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
RedCarpet is partly written in C.

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

~~~
nerdponx
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
> 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.

------
lmm
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
> _[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
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.

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

~~~
blunte
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
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
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
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.

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

------
edem
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
Learning ruby at the moment and this is setting off alarm bells. What? gems
break each other?

~~~
yebyen
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)

~~~
edem
My problem is that I am not a Ruby dev and when I need to use Ruby stuff they
break each other. I expect a language to be able to produce self-contained
binaries which run in isolation (and expect this to being the norm). With Ruby
I just follow the guides and I always end up in a hour long debug session. If
you need your users to know they need bundler or whatever then your language
design is flawed.

~~~
yebyen
Ah, then you do have a problem!

I am a Ruby dev, and one of the things I appreciate most about the language is
that once I broke down the initial barriers we're talking about now, there was
practically nothing stopping me from saying "I am a Ruby dev"

It was still years after that before I would dare to say I was a Rails dev, of
course...

IMHO it is a feature if your language guides people that are at first just
passive users to become devs and contribute to your project with issues and
pull requests.

~~~
edem
I have no time/need/want to learn/write Ruby. I have 1000 better things to do.
I only use Ruby occasionally and out of necessity.

