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 o PDF, translated by Maruku)
all the improvements in PHP Markdown Extra.
a new meta-data syntax
some ideas from MultiMarkdown
The test directory is quite messy but it shows every capability.
Maruku has been developed so far by Andrea Censi. Contributors are most welcome!
Table of contents: (auto-generated by Maruku!)
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.
Use the tracker or drop me an email.
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
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
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
## Download ## {#download}For example, a link to the download header.
Note that you can use also the new meta-data syntax for the same purpose:
@ id: 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 (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.
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.
Meta-data keys are assumed to be case-insensitive.
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
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`.
(document) Sets the title of the document (HTML: used in the TITLE element).
(document) If true, headers are numbered (just like this document). Default is false.
(document, HTML) Url of stylesheet.
(document, HTML) If set, use the Ruby syntax library to add source highlighting.
(document, LaTeX) If set, use the fancy listings package for better displaying code blocks.
If not set, use standard verbatim environment.
(any block object, HTML) Standard CSS attributes are copied.
(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.
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>
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.
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.
If you want to use HTML entities, go on! We will take care of the translation to LaTeX:
| Entity | Result |
|---|---|
| © | © |
| £ | £ |
| a b | a b |
| λ | λ |
| — | — |
Export to HTML
Add -split options to maruku that splits the document over multiple pages.
This should require the possibility of specifying a template for navigational elements. Investigate template engine.
Include RubyPants
Export to PDF
Export to Markdown (pretty-printing)
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.
Maybe something like this:
This is a paragraph. Really, a normal paragraph. The second
line of this paragraph has the last element {with meta data}@ class: important_span
and the paragraph continues...
So the idea is:
Only elements at the end of the line can have meta data.
Syntax is:
Or, we could allow metadata specified after the text. In the following, three fragments are marked as "special", and, after their containing block-level elements, their attributes are set:
Lorem ipsum dolor sit @{amet}, consectetuer adipiscing
elit. Donec sit amet sapien vitae augue @{interdum hendrerit.}
Maecenas tempor ultrices nisl. @{Praesent laoreet tortor sit
amet est.} Praesent in nisl eu libero sodales bibendum.
@{1} id: amet
@{2} style: "font-style: bold"
@{3} class: warning
We can be much liberal in the syntax. For example, instead of numeric references to the part in the text, we could write:
Lorem ipsum dolor sit @{amet}, consectetuer adipiscing
elit. Donec sit amet sapien vitae augue @{interdum hendrerit.}
Maecenas tempor ultrices nisl. @{Praesent laoreet tortor sit
amet est.} Praesent in nisl eu libero sodales bibendum.
@{amet} id: amet
@{interdum ...} style: "font-style: bold"
@{Praesent ...} class: warning
with ... acting as a wildcard, to match a long phrase ({ Praesent laoreet tortor sit amet est.}) without specifying the full text.
I feel this is very readable and not intrusive. But then again, subjective tastes vary. Let me know of any comments and suggestions. I want to wait for feedback before implementing this.
This is a paragraph % This is a comment
Or % on a line by itself comments the following block:
% The following paragraph is ignored % Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec sit amet sapien vitae augue interdum hendrerit. Maecenas tempor ultrices nisl. Praesent laoreet tortor sit amet est. Praesent in nisl eu libero sodales bibendum. This paragraph is not ignored.
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)
I really was missing those.↩