Maruku is a Markdown interpreter written in Ruby.
Maruku allows you to write in an easy-to-read-and-write syntax, like this:
Then it can be translated to HTML:
or Latex, which is then converted to PDF:
Maruku implements the original Markdown syntax (HTML or PDF, translated by Maruku).
Markdown implements also all the improvements in PHP Markdown Extra.
Moreover, it implements ideas from MultiMarkdown.
Maruku has been developed so far by Andrea Censi. Contributors are most welcome!
Table of contents:
The development site is http://rubyforge.org/projects/maruku/.
Download current gem at http://rubyforge.org/frs/?group_id=2795 or try to install with:
$ gem install maruku
Anonymous access to the repository is possible with:
$ svn checkout svn://rubyforge.org/var/svn/maruku
If you want commit-access, just create an account on Rubyforge and drop me a mail.
This is the basic usage:
require 'maruku' doc = Maruku.new(markdown_string) puts doc.to_html
or, if you install through RubyGems,
require 'rubygems' require 'maruku'
This 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
There are two command-line programs installed: maruku and marutex
maruku converts Markdown in HTML:
$ maruku file.md # creates file.html
marutex converts Markdown in TeX, then calls pdflatex to transform to PDF:
$ marutex file.md # creates file.tex and file.pdf
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 1
* footnotes [^foot] [^foot]: I really was missing those.
Markdown inside HTML elememnts
<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
## Header ## {#id}For example, a link to the download header.
definition lists
Definition list : something very hard to parse
abbreviations or ABB for short.
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 (altough, for, now)
Other improvements over Bluecloth:
the HTML output is provided also as a REXML document tree.
PHP Markdown Syntax support.
Maruku implements a syntax that allows to attach "meta" information to objects.
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.
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
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
Also, if the value is not present, it defaults to true:
@ test This paragraph has the attribute 'test' set.
(document) Sets the title of the document (HTML: used in the TITLE element).
(document, HTML) Url of stylesheet.
(document, HTML) Use the syntax library to add source highlighting.
(document, LaTex) Use fancy listing package for better displaying code blocks.
(any block object, HTML) Standard CSS attributes are copied.
(code blocks) Name of programming language (ruby) for syntax highlighting (does not work yet)
Default for this is code_lang in document.
Shows tabs and newlines (default is read in the document object).
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}.
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>
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.
Things I'm thinking about:
a syntax for commenting parts of the document:
This is a paragraph % This is a comment
choose a syntax for adding math:
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)
I really was missing those.↩