Why Markdown?

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

Goals

• 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](http://kramdown.gettalong.org). 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!

Result

<h2>Header like this</h2>

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

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

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

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

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

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:

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

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.
  
  [^note]:
      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"}
  
  {:ref}
  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 Kramdown::Document.new(ARGF.read, auto_ids: false).to_html

Links

kramdown Syntax Guide

http://kramdown.gettalong.org/syntax.html

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

Babelmark

http://johnmacfarlane.net/babelmark2

Allows comparing various Markdown implementations