Using Markdown
with the
kramdown Library and Tools

by Thomas Leitner

a.k.a. gettalong

What is Markdown?

Markdown is a lightweight markup language
originally designed for conversion to HTML.

Why Markdown?

  • HTML is very verbose
  • Textile is unpleasant to read
  • reStructuredText/AsciiDoc is complex


  • Simplicity
  • Easy to read/write
  • HTML for everything more complex

Markdown Syntax

## Header like this

This is *emphasized* and this **strong**! And [this is an
inline link]( This whole
thing is a paragraph.

> Blockquotes are nice.
And can be lazy.

    Code blocks are just indented chunks of text.

* Unordered list
+ Can use different markers
- Like we do here

1. Looks like an
2. ordered list,
3. at least to me!


<h2>Header like this</h2>

<p>This is <em>emphasized</em> and this <strong>strong</strong>! And
<a href="">this is an inline link</a>. This whole
thing is a paragraph.</p>

  <p>Blockquotes are nice.
And can be lazy.</p>

<pre><code>Code blocks are just indented chunks of text.

  <li>Unordered list</li>
  <li>Can use different markers</li>
  <li>Like we do here</li>

  <li>Looks like an</li>
  <li>ordered list</li>
  <li>at least to me!</li>

Current Status

Source: xkcd 927

  • Many implementations (>70), nearly all differ
  • No single specification (CommonMark tried, failed?)
  • Only the basic syntax portable to other implementations
  • But widely used

For example: Github Stack Overflow WordPress

And What is kramdown?

kramdown is a pure-Ruby Markdown implementation

  • based on ideas from Maruku and Markdown Extra
  • fast (but not C-like fast)
  • supports extended syntax
  • easily extensible
  • multiple parsers and converters


kramdown architecture

kramdown’s Extended Syntax, Part 1

  • Header IDs

    # Some long header {#shortid}
  • Fenced codeblocks

    codeblock is here
  • Definition lists

    term 1
    term 2
    : definition, all block level elements allowed
    term 3
    : another definition

kramdown’s Extended Syntax, Part 2

  • Simple tables

    | header | cells are | in first row |
    | :---   |   :---:   |     -------: |
    | left   |   center  |        right |
    | other  |   data    |     *inline* |
  • Footnotes

    There is a footnote marker[^note] here.
        Here can be any blocklevel content.
  • EOB (end of block) marker

    * a list
    * another list

kramdown’s Extended Syntax, Part 3

  • Inline attribute lists

    A [link](some_place.html){:.classX} with class!
    {: #paraid style="text-align: center"}
    Assign IDs, classes or any key-value pair to any
    span or block level element.
    {:ref: .multiple.classes.allowed}
  • And some more… see the syntax guide!

Syntax Caveats

  • Correct indentation for lists and codeblocks
  • Blank lines needed to separate block level elements

Commandline Usage

shell> cat file
# Test

A paragraph
shell> kramdown file
<h1 id="test">Test</h1>

<p>A paragraph</p>
shell> kramdown --no-auto-ids file | kramdown -i html -o kramdown
# Test

A paragraph

Library Usage

require 'kramdown/document'

puts, auto_ids: false).to_html
kramdown Syntax Guide

The go-to ressource when one is unsure about the correct syntax.


Allows comparing various Markdown implementations

Thank you!