Maruku: a Markdown-superset interpreter

Maruku is a Markdown interpreter written in Ruby.

Last release is version 0.5.3 – 2007-02-05.

Use this command to update:

$ gem update maruku

Maruku allows you to write in an easy-to-read-and-write syntax, like this:

This document in Markdown

Then it can be translated to HTML:

This document in HTML

or LaTeX, which is then converted to PDF:

This document in PDF

Maruku implements:

• the original Markdown syntax (HTML or PDF), translated by Maruku).

• all the improvements in PHP Markdown Extra.

• a new meta-data syntax

Authors: Maruku has been developed so far by Andrea Censi. Contributors are most welcome!

The name of the game: Maruku is the romaji transliteration of the katakana transliteration of “Mark”, the first word in Markdown. I chose this name because Ruby is Japanese, and also the sillable “ru” appears in Maruku.

Table of contents: (auto-generated by Maruku!)

1. Release notes

Note: Maruku seems to be very robust, nevertheless it is still beta-level software. So if you want to use it in production environments, please check back in a month or so, while we squash the remaining bugs.

In the meantime, feel free to toy around, and please signal problems, request features, by contacting me or using the tracker. For issues about the Markdown syntax itself and improvements to it, please write to the Markdown-discuss mailing list.

Have fun!

See the changelog.

2. Download

The development site is http://rubyforge.org/projects/maruku/.

Install with:

$ gem install maruku

Released files can also be seen at http://rubyforge.org/frs/?group_id=2795.

Anonymous access to the repository is possible with:

$ svn checkout svn://rubyforge.org/var/svn/maruku/trunk

If you want commit access to the repository, just create an account on Rubyforge and drop me a mail.

2.1. Bugs report

Use the tracker or drop me an email.

3. Usage

3.1. Embedded Maruku

This is the basic usage:

require 'rubygems'
require 'maruku'

doc = Maruku.new(markdown_string)
puts doc.to_html

The method to_html outputs only an HTML fragment, while the method to_html_document outputs a complete XHTML 1.0 document:

puts doc.to_html_document

You can have the REXML document tree with:

tree = doc.to_html_document_tree

3.2. From the command line

There is one command-line program installed: maruku.

Without arguments, it converts Markdown to HTML:

$ maruku file.md  # creates file.html

With the --pdf arguments, it converts Markdown to LaTeX, then calls pdflatex to transform to PDF:

$ maruku --pdf file.md  # creates file.tex and file.pdf

4. Maruku and Bluecloth

The other Ruby implementation of Markdown is Bluecloth.

Maruku is much different in philosophy from Bluecloth: the biggest difference is that parsing is separated from rendering. In Maruku, an in-memory representation of the Markdown document is created. Instead, Bluecloth mantains the document in memory as a String at all times, and does a series of gsub to transform to HTML.

Maruku is usually faster than Bluecloth. Bluecloth is faster for very small documents. Bluecloth sometimes chokes on very big documents (it is reported that the blame should be on Ruby’s regexp implementation).

This is the canonical benchmark (the Markdown specification), executed with Ruby 1.8.5 on a Powerbook 1.5GhZ:

BlueCloth (to_html): parsing 0.01 sec + rendering 1.87 sec = 1.88 sec   (1.00x)
   Maruku (to_html): parsing 0.66 sec + rendering 0.43 sec = 1.09 sec   (1.73x)
  Maruku (to_latex): parsing 0.67 sec + rendering 0.23 sec = 0.90 sec   (2.10x)

Please note that Maruku has a lot more features and therefore is looking for much more patterns in the file.

5. Maruku summary of features

• Supported syntax

  • Basic Markdown
  • Markdown Extra
  • Meta-data syntax

• Output

  • XHTML

    • Syntax highlighting via the syntax library.

  • LaTeX

    • Translation of HTML entities to LaTeX
    • Syntax highlighting via the listings package.

• Misc

  • Documentation for supported attributes

  • Automatic generation of the TOC

Experimental features (not released yet)

• LaTeX Math syntax (not enabled by default)
• An extension system for adding new syntax is available, but the API is bound to change in the future, so please don’t use it.
• LaTeX to MathML using either one of ritex, itex2mml, blahtex.
• LaTeX to PNG using blahtex.

5.1. New meta-data syntax

Maruku implements a syntax that allows to attach “meta” information to objects.

See this proposal for how to attach metadata to the elements.

See the documentation for supported attributes.

Meta-data for the document itself is specified through the use of email headers:

Title: A simple document containing meta-headers
CSS: style.css

Content of the document

When creating the document through

Maruku.new(s).to_html_document

the title and stylesheet are added as expected.

Meta-data keys are assumed to be case-insensitive.

5.2. Automatic generation of the table of contents

If you create a list, and then set the toc attribute, when rendering Maruku will create an auto-generated table of contents.

* This will become a table of contents (this text will be scraped).
{:toc}

You can see an example of this at the beginning of this document.

5.3. Use HTML entities

If you want to use HTML entities, go on! We will take care of the translation to LaTeX:

See the list of supported entities (pdf).

5.4. This header contains emphasis strong text and code

Note that this header contains formatting and it still works, also in the table of contents.

And This is a link with all sort of weird stuff in the text.

6. Examples of PHP Markdown Extra syntax

• tables

  Col1 | Very very long head | Very very long head|
  -----|:-------------------:|-------------------:|
  cell | center-align        | right-align        |

  Col1	Very very long head	Very very long head
  cell	center-align	right-align

• footnotes ¹

  * footnotes [^foot]
  
  [^foot]: I really was missing those.

• Markdown inside HTML elements

  <div markdown="1" style="border: solid 1px black">
     This is a div with Markdown **strong text**
  </div>

  This is a div with Markdown strong text

• header ids

  ## Download ##     {#download}

  For example, a link to the download header.

• definition lists

  Definition list
  : something very hard to parse

  Definition list

  something very hard to parse

• abbreviations or ABB for short.