Maruku: a Markdown-superset interpreter

Maruku is a Markdown interpreter written in Ruby.

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 translitteration of the katakana translitteration 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!

Changes in 0.4

• First implementation of the new meta-data syntax.
• General refactorization of the code and much cleaner error reporting.
• Created the RDOC documentation.
• The add_whitespace method took too much time -- it was O(n^2).
• Added unit-tests for block-level elements.

Changes in 0.3

• A real parser is used instead of a regexp-based system, also for span-level elements.

  Now Maruku is almost 2x faster than Bluecloth, while having more features.

  Here are some benchmarks:

  BlueCloth (to_html): parsing 0.00 sec + rendering 1.54 sec = 1.55 sec 
  Maruku (to_html):    parsing 0.47 sec + rendering 0.38 sec = 0.85 sec 
  Maruku (to_latex):   parsing 0.49 sec + rendering 0.25 sec = 0.73 sec

  This is the result of running lib/maruku/tests/benchmark.rb on the Markdown specification.

• Prettier HTML output by adding whitespace.

• Added a full suite of unit-tests for the span-level parser.

• Error management: Having a real parser, Maruku warns you about syntax issues.

  The default action is to warn and try to continue. If you do this:

  Maruku.new(string, {:on_error => :raise})
  

  then syntax errors will cause an exception to be raised (you can catch this and retry).

• Fixed a series of bugs in handling inline HTML code.

Immediate TODO-list:

• UTF-8 input/output works OK for HTML, however I am having pain trying to export to LaTeX. I want at least Japanese characters support, so if you know how to do this you are very welcome to give me an hand.

  For example: in the HTML version, you should see accented characters in this parenthesis:

  (àèìòù)

  and Japanese text in these other parentheses:

  (カタカナで 私の 名前は アンドレア チェンシ です).

  (日本のガルは 大好き、でも、日本語は難しですから、そうぞ 英語話すガルを おしえてください).

  In the LaTeX version, these do not appear. I know how to do LaTeX with ISO-8859-1 encoding (European characters), but I'm struggling with half-baked solutions for UTF-8 encoded documents.

• Implement the new meta-data proposal.

• Exporting to Markdown (pretty printing).

• Exporting to HTML splitting in multiple files.

• RubyPants.

• Support for images in PDF.

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

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

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.1. From the command line

There are two command-line programs installed: maruku and marutex.

• maruku converts Markdown to HTML:

  $ maruku file.md  # creates file.html

• marutex converts Markdown to LaTeX, then calls pdflatex to transform to PDF:

  $ marutex file.md  # creates file.tex and file.pdf

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

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

The in-memory representation makes it very easy to export to various formats (at the moment HTML and LaTeX/PDF; the next is pretty-printed Markdown).

Other improvements over Bluecloth:

• the HTML output is provided also as a REXML document tree.

• PHP Markdown Syntax support.

6. New meta-data syntax

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

6.1. Meta-data for block-level and span-level elements

See this proposal.

6.2. Meta-data for the document

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.

6.3. List of meta-data

title, subject

(document) Sets the title of the document (HTML: used in the TITLE element).

use_numbered_headers

(document) If true, headers are numbered (just like this document). Default is false.

css

(document, HTML) Url of stylesheet.

html_use_syntax

(document, HTML) If set, use the Ruby syntax library to add source highlighting.

latex_use_listings

(document, LaTeX) If set, use the fancy listings package for better displaying code blocks.

If not set, use standard verbatim environment.

style, id, class

(any block object, HTML) Standard CSS attributes are copied.

lang

(code blocks) Name of programming language (ruby) for syntax highlighting.

Default for this is code_lang in document.

Syntax highlighting is delegated to the syntax library for HTML output and to the listings package for LaTeX output.

code_show_spaces

Shows tabs and newlines (default is read in the document object).

code_background_color

Background color for code blocks. (default is read in the document object).

The format is either a named color (green, red) or a CSS color of the form #ff00ff.

• for HTML output, the value is put straight in the background-color CSS property of the block.

• for LaTeX output, if it is a named color, it must be a color accepted by the LaTeX color packages. If it is of the form #ff00ff, Maruku defines a color using the \color[rgb]{r,g,b} macro.

  For example, for #0000ff, the macro is called as: \color[rgb]{0,0,1}.

6.4. Examples

An example of this is the following:

	 One space
	  Two spaces
		 	Tab, space, tab
				Tab, tab, tab and all is green!
{code_show_spaces code_background_color=#ffeedd}

That will produce:

¬One¬space
¬¬Two¬spaces
»   ¬»   Tab,¬space,¬tab
»   »   »   Tab,¬tab,¬tab¬and¬all¬is¬green!

Or highlighting (support depends on languages):

	<div style="text-align:center">Div</div>
{lang=html}

produces:

<div style="text-align:center">Div</div>

7. Other Features

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

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

7.3. Use HTML entities

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

8. Future developments

I think that Pandoc and MultiMarkdown are very cool projects. However, they are written in Haskell and Perl, respectively. I would love to have an equivalent in Ruby.

8.1. A syntax for adding math

Something inspired from LaTeX should be familiar to all:

This is inline math: $\alpha$


This is an equation with label:

$ \alpha = \beta + \gamma  $        (eq:1)

This is a reference to equation: please see (eq:1)