Redcarpet Documentation

If you are migrating from RedCloth and need the old API, you can use the compatibility library. This provides a Markdown class that renders 100% standards-compliant Markdown with zero extensions enabled.

require 'redcarpet/compat'

# Uses the classical RedCloth API
Markdown.new('this is my text').to_html

You can create custom renderers by inheriting from Redcarpet::Render::HTML (to extend existing behavior) or Redcarpet::Render::Base (to build from scratch).

# Extending HTML renderer
class CustomRender < Redcarpet::Render::HTML
  def block_quote(quote)
    %(<blockquote class="my-custom-class">#{quote}</blockquote>)
  end
end

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

# Creating from scratch
class ManPage < Redcarpet::Render::Base
  # Implement methods here
end

Redcarpet is available as a Ruby gem. It builds native extensions but the parser is standalone and requires no installed libraries.

Minimum Ruby version for Redcarpet 3.0+ is 1.9.2 (or Rubinius in 1.9 mode). For Ruby 1.8.7, use version 2.3.0.

You can create a custom CLI binary by inheriting from Redcarpet::CLI. By overriding the self.options_parser method, you can use Ruby's OptionParser to add new flags. You can also override self.render_object to return a custom renderer based on the flags provided.

class Custom::CLI < Redcarpet::CLI
  def self.options_parser
    super.tap do |opts|
      opts.on("--rainbow") do
        @@options[:rainbow] = true
      end
    end
  end

  def self.render_object
    @@options[:rainbow] ? RainbowRender : super
  end
end

Redcarpet includes a high-performance SmartyPants implementation. You can use it as a mixin in your renderer class or call it standalone.

# As a Mixin (overrides postprocess to perform replacements)
class HTMLWithPants < Redcarpet::Render::HTML
  include Redcarpet::Render::SmartyPants
end

# Standalone usage
Redcarpet::Render::SmartyPants.render("<p>Oh SmartyPants, you're so crazy...</p>")

When building a custom renderer, you can override several callback methods.

Important: If a method returns nil, the block is skipped. For block-level methods, ensure you return an HTML element at the correct level to avoid unexpected output.

Redcarpet provides high-performance C-implemented renderers:

1. Redcarpet::Render::HTML: Outputs HTML.
2. Redcarpet::Render::XHTML: Outputs XHTML.
3. Redcarpet::Render::HTML_TOC: Outputs HTML with a Table of Contents based on headers. Supports nesting_level (integer or range) to limit header depth.
4. Redcarpet::Render::StripDown: Strips all formatting to plaintext.

# HTML Renderer with options
renderer = Redcarpet::Render::HTML.new(no_links: true, hard_wrap: true)

# Plaintext (StripDown) Renderer
require 'redcarpet'
require 'redcarpet/render_strip'
markdown = Redcarpet::Markdown.new(Redcarpet::Render::StripDown)
markdown.render("**This** _is_ an [example](http://example.org/).")
# => "This is an example (http://example.org/)."

The core of the library is the Redcarpet::Markdown class. You should instantiate it once with a renderer and desired extensions, then reuse it to render multiple documents using #render.

# Initialize with a renderer and optional extensions hash
markdown = Redcarpet::Markdown.new(renderer, extensions = {})

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