Redcarpet is written with sugar, spice and everything nice

Redcarpet is Ruby library for Markdown processing that smells like butterflies and popcorn.

This library is written by people

Redcarpet was written by Vicent Martí. It is maintained by Robin Dupret and Matt Rogers.

Redcarpet would not be possible without the Sundown library and its authors (Natacha Porté, Vicent Martí, and its many awesome contributors).

You can totally install it as a Gem

Redcarpet is readily available as a Ruby gem. It will build some native extensions, but the parser is standalone and requires no installed libraries. Starting with Redcarpet 3.0, the minimum required Ruby version is 1.9.2 (or Rubinius in 1.9 mode).

$ [sudo] gem install redcarpet

If you need to use it with Ruby 1.8.7, you will need to stick with 2.3.0:

$ [sudo] gem install redcarpet -v 2.3.0

The Redcarpet source is available at GitHub:

$ git clone git://github.com/vmg/redcarpet.git

And it's like really simple to use

The core of the Redcarpet library is the Redcarpet::Markdown class. Each instance of the class is attached to a Renderer object; the Markdown class performs parsing of a document and uses the attached renderer to generate output.

The Redcarpet::Markdown object is encouraged to be instantiated once with the required settings, and reused between parses.

# Initializes a Markdown parser
Redcarpet::Markdown.new(renderer, extensions = {})

Here, the renderer variable refers to a renderer object, inheriting from Redcarpet::Render::Base. If the given object has not been instantiated, the library will do it with default arguments.

You can also specify a hash containing the Markdown extensions which the parser will identify. The following extensions are accepted:

:no_intra_emphasis: do not parse emphasis inside of words. Strings such as foo_bar_baz will not generate <em> tags.
:tables: parse tables, PHP-Markdown style.
:fenced_code_blocks: parse fenced code blocks, PHP-Markdown style. Blocks delimited with 3 or more ~ or backticks will be considered as code, without the need to be indented. An optional language name may be added at the end of the opening fence for the code block.
:autolink: parse links even when they are not enclosed in <> characters. Autolinks for the http, https and ftp protocols will be automatically detected. Email addresses are also handled, and http links without protocol, but starting with www.
:disable_indented_code_blocks: do not parse usual markdown code blocks. Markdown converts text with four spaces at the front of each line to code blocks. This options prevents it from doing so. Recommended to use with fenced_code_blocks: true.
:strikethrough: parse strikethrough, PHP-Markdown style. Two ~ characters mark the start of a strikethrough, e.g. this is ~~good~~ bad.
:lax_spacing: HTML blocks do not require to be surrounded by an empty line as in the Markdown standard.
:space_after_headers: A space is always required between the hash at the beginning of a header and its name, e.g. #this is my header would not be a valid header.
:superscript: parse superscripts after the ^ character; contiguous superscripts are nested together, and complex values can be enclosed in parenthesis, e.g. this is the 2^(nd) time.
:underline: parse underscored emphasis as underlines. This is _underlined_ but this is still *italic*.
:highlight: parse highlights. This is ==highlighted==. It looks like this: <mark>highlighted</mark>
:quote: parse quotes. This is a "quote". It looks like this: <q>quote</q>
:footnotes: parse footnotes, PHP-Markdown style. A footnote works very much like a reference-style link: it consists of a marker next to the text (e.g. This is a sentence.[^1]) and a footnote definition on its own line anywhere within the document (e.g. [^1]: This is a footnote.).

Example:

markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML, :autolink => true, :space_after_headers => true)

Rendering with the Markdown object is done through Markdown#render. Unlike in the RedCloth API, the text to render is passed as an argument and not stored inside the Markdown instance, to encourage reusability. Example:

markdown.render("This is *bongos*, indeed.")
# => "<p>This is <em>bongos</em>, indeed</p>"

Darling, I packed you a couple renderers for lunch

Redcarpet comes with two built-in renderers, Redcarpet::Render::HTML and Redcarpet::Render::XHTML, which output HTML and XHTML, respectively. These renderers are actually implemented in C and hence offer brilliant performance — several degrees of magnitude faster than other Ruby Markdown solutions.

All the rendering flags that previously applied only to HTML output have now been moved to the Redcarpet::Render::HTML class, and may be enabled when instantiating the renderer:

Redcarpet::Render::HTML.new(render_options = {})

Initializes an HTML renderer. The following flags are available:

:filter_html: do not allow any user-inputted HTML in the output.
:no_images: do not generate any <img> tags.
:no_links: do not generate any <a> tags.
:no_styles: do not generate any <style> tags.
:safe_links_only: only generate links for protocols which are considered safe.
:with_toc_data: add HTML anchors to each header in the output HTML, to allow linking to each section.
:hard_wrap: insert HTML <br> tags inside on paragraphs where the origin Markdown document had newlines (by default, Markdown ignores these newlines).
:xhtml: output XHTML-conformant tags. This option is always enabled in the Render::XHTML renderer.
:prettify: add prettyprint classes to <code> tags for google-code-prettify.
:link_attributes: hash of extra attributes to add to links.

Example:

renderer = Redcarpet::Render::HTML.new(:no_links => true, :hard_wrap => true)

The HTML renderer has an alternate version, Redcarpet::Render::HTML_TOC, which will output a table of contents in HTML based on the headers of the Markdown document.

When instantiating this render object, you can optionally pass a nesting_level option which takes an integer and allows you to make it render only headers until a specific level.

Furthermore, the abstract base class Redcarpet::Render::Base can be used to write a custom renderer purely in Ruby, or extending an existing renderer. See the following section for more information.

And you can even cook your own

Custom renderers are created by inheriting from an existing renderer. The built-in renderers, HTML and XHTML may be extended as such:

# create a custom renderer that allows highlighting of code blocks
class HTMLwithPygments < Redcarpet::Render::HTML
  def block_code(code, language)
    Pygments.highlight(code, :lexer => language)
  end
end

markdown = Redcarpet::Markdown.new(HTMLwithPygments, :fenced_code_blocks => true)

But new renderers can also be created from scratch (see lib/redcarpet/render_man.rb for an example implementation of a Manpage renderer)