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:

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 - version 0.3.0 (January 3rd, 2007)

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.3.0:

Immediate TODO-list:

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.

4. Examples of PHP Markdown Extra syntax

<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

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:

6. New meta-data syntax

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

6.1. 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.2. Meta-data for elements

Maruku introduces a new syntax for attaching metadata to paragraphs, tables, and so on.

For example, consider the creation of two paragraphs:

Paragraph 1 is a warning.

Paragraph 2

Now you really want to attach a 'class' attribute to the paragraphs (for example for CSS styling). Maruku allows you to use:

@ class: warning
Paragraph 1 is a warning

Paragraph 2

You can add more by separating with a ;:

@ class: warning; id: warning1
Paragraph 1 is a warning

A meta-data declaration is composed of

  1. newline
  2. an at-symbol @
  3. a series of name-value pairs. Each name-value is separated by a colon :, pairs are separated by semi-colons ;

Many declaration can be used, and they refer to the following object:

@ class: warning
@ id: warning1
Paragraph 1 is a warning

These can also be separated by newlines:

@ class: warning

@ id: warning1

Paragraph 1 is a warning

6.3. Shortcuts

This:

@ .xyz
Paragraph

is equivalent to:

@ class: xyz
Paragraph

This:

@ #xyz
Paragraph

is equivalent to:

@ id: xyz
Paragraph

Also, if the value is not present, it defaults to true:

@ test

This paragraph has the attribute `test` set to `true`.

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

6.5. Examples

An example of this is the following:

@¬code_show_spaces;¬code_background_color:¬green

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

That will produce:

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

Example with css-style color:

@ code_background_color: #455678

	A strange color

produces:

A strange color

Or highlighting (does not work well yet):

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

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.

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

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:

EntityResult
&copy; ©
&pound; £
a&nbsp;b a b
&lambda; λ
&mdash; —

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)

  1. I really was missing those.↩

Created by Maruku at 00:33 on Wednesday, January 03rd, 2007.