RDiscount – Markdown for Ruby

RDiscount converts documents in Markdown syntax to HTML.

It uses the excellent Discount processor by David Loren Parsons for this purpose, and thereby inherits Discount’s numerous useful extensions to the Markdown language.

Why use Discount? (and RDiscount)

Discount is fast and supports many useful extensions to the original Markdown language:

  • Footnotes - from PHP Markdown Extra
  • Tables - from PHP Markdown Extra
  • Multi-level bulleted lists
  • Images with sizes
    • ![GitHub Favicon](https://github.com/favicon.ico =16x16)GitHub Favicon
  • Typographic substitutions with SmartyPants
    • Straight quotes (" and ') → “curly” quotes
  • Fenced code blocks
  • …and more

Some of these extensions are not enabled by default. See usage instructions below to enable additional extensions.

Installation

gem install rdiscount

Ruby 1.9.2 has a known issue with RDiscount. Please use Ruby 1.9.3 or later.

If you are creating a Heroku app that depends on RDiscount, you must specify a Ruby version in your Gemfile since Heroku currently uses Ruby 1.9.2 by default.

Usage in Ruby and Jekyll

In Ruby

RDiscount implements the basic protocol popularized by RedCloth and adopted by BlueCloth:

require 'rdiscount'
markdown = RDiscount.new("Hello World!")
puts markdown.to_html

Additional extensions can be turned on when creating the RDiscount object:

markdown = RDiscount.new("Hello World!", :smart, :filter_html)

For a list of all possible extensions, see the instance attributes in the RDiscount class documentation.

Inject RDiscount into your BlueCloth-using code by replacing your bluecloth require statements with the following:

begin
  require 'rdiscount'
  BlueCloth = RDiscount
rescue LoadError
  require 'bluecloth'
end

In Jekyll

In your site’s _config.yml file, add the line:

markdown: rdiscount

To enable extensions, add the following section with the desired list of extensions:

rdiscount:
  extensions:
    - autolink      # greedily urlify links
    - footnotes     # footnotes
    - smart         # typographic substitutions with SmartyPants

For a list of all possible extensions, see the instance attributes in the RDiscount class documentation.

Contributing

All development is coordinated on the GitHub project page.

Please report bugs and feature requests on the issue tracker.