Skip to content
This repository

A pure-Ruby Markdown-superset interpreter (Official Repo).

branch: master
Octocat-spinner-32 bin Remove Nokogiri dependency from the S5 slides output. September 06, 2013
Octocat-spinner-32 certs Sign the gem at build time March 10, 2013
Octocat-spinner-32 data Merge changes from Hollis February 15, 2013
Octocat-spinner-32 docs Doc tweaks January 14, 2014
Octocat-spinner-32 lib Fix angle-bracket links starting with https:// at the beginning of a … January 16, 2014
Octocat-spinner-32 spec Fix angle-bracket links starting with https:// at the beginning of a … January 16, 2014
Octocat-spinner-32 tools git-svn-id: svn:// 7e2f57f0-5a7… June 22, 2007
Octocat-spinner-32 .coveralls.yml Add Simplecov and Coveralls for test coverage reporting September 08, 2013
Octocat-spinner-32 .editorconfig Add an editorconfig file January 15, 2013
Octocat-spinner-32 .gitignore Ignore coverage dir, and include json gem in 1.8.7 September 08, 2013
Octocat-spinner-32 .simplecov Add Simplecov and Coveralls for test coverage reporting September 08, 2013
Octocat-spinner-32 .travis.yml Work around a RubyGems bug on 1.8 January 07, 2014
Octocat-spinner-32 .yardopts Merge changes from Hollis February 15, 2013
Octocat-spinner-32 AUTHORS Clean up more LOAD_PATH manipulation, add myself to authors January 21, 2013
Octocat-spinner-32 Escape CHANGELOG January 14, 2014
Octocat-spinner-32 Gemfile Merge changes from distler/nokogiri December 21, 2013
Octocat-spinner-32 Gemfile.1.8.7 Upgrade itextomml in 1.8.7 too December 21, 2013
Octocat-spinner-32 MIT-LICENSE.txt Switch to the MIT license. Remove all license headers except for the … April 12, 2013
Octocat-spinner-32 Doc tweaks January 14, 2014
Octocat-spinner-32 Rakefile Un-pending some jRuby tests that work with the REXML parser September 13, 2013
Octocat-spinner-32 markdown-test.rb Improve HTML handling to avoid losing content and match other Markdow… March 03, 2013
Octocat-spinner-32 maruku.gemspec Remove dependency on nokogiri from gemspec September 09, 2013


Maruku is a Markdown-superset interpreter.

Maruku implements:

  • The original Markdown syntax.
  • All the improvements in PHP Markdown Extra.
  • A new meta-data syntax.

Read more about Maruku's Markdown syntax. It also supports inline math. Maruku docs.

News about Maruku is posted at

Build Status Gem Version Dependency Status Code Climate Coverage Status

Note: Maruku should be considered obsolete, as it has been superceded by better libraries like Kramdown. It is still supported, so feel free to continue filing bug reports.


Make sure you have Ruby and RubyGems, then run:

gem install maruku

Basic use

To convert Markdown from your Ruby programs, first create a new document and then get its HTML representation with the method to_html:

doc =
puts doc.to_html

The #to_html method returns a string, representing an HTML fragment."## Header ##").to_html
# => "<h2 id='header'>header</h2>"

If you want to create full HTML documents, use the #to_html_document method.

Error Management

Maruku warns you if something is wrong with the input. The default behaviour is to print a warning on standard error, and then try to continue.

This behavior can be customized with the :on_error option. For example:, :on_error => :raise)

This tells Maruku to raise an exception if it encounters a parsing error.

To change the error stream, use the :error_stream option:

errors = "Errors reported by Maruku:\n", :error_stream => errors)

You can pass in any object that supports the << method.

Command-line usage

Maruku comes with two command-line programs: maruku and marutex.

maruku converts Markdown to HTML:

$ maruku  # creates file.html

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

$ marutex  # creates file.tex and file.pdf

Code organization

The public interface is the Maruku class. Everything else is in the module MaRuKu.


Maruku will not depend on any gem that is not pure-Ruby. This helps maximize compatibility across Ruby implementations and make Maruku easy to use. Beyond that, Maruku should not depend on any other gem unless absolutely necessary - this make Maruku easy to consume and avoids dependency version conflicts.


Maruku follows Semantic Versioning for release versioning, starting around version 0.6.0. One caveat is that, because even the most minor bug fixes are likely to change the output of some documents, some of the patch-level changes are not strictly backwards compatible. This usually shows up as test breakages, and one suggestion is to use a tool like nokogiri-diff to compare output to the expected structure as XML rather than simply comparing strings.

Supported Ruby Versions

This library aims to support and is tested against the following Ruby implementations:

  • Ruby 1.8.7
  • Ruby 1.9.2
  • Ruby 1.9.3
  • Ruby 2.0.0
  • Ruby 2.1.0
  • JRuby (Travis' version, 1.8 and 1.9 modes)
  • Rubinius (Travis' version)

If something doesn't work on one of these interpreters, it's a bug.


  • Find something you would like to work on.
  • Fork the project and do your work in a topic branch.
    • Make sure your changes will work on all the Rubies we test on.
  • Add tests in spec/block_docs for the behavior you want to test.
  • Run all the tests using bundle exec rake.
  • Rebase your branch against bhollis/maruku to make sure everything is up to date.
  • Commit your changes and send a pull request.


Copyright (c) 2006 Andrea Censi. MIT license, see MIT-LICENSE.txt for details.

Something went wrong with that request. Please try again.