Need help with commonmarker?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

275 Stars 56 Forks MIT License 556 Commits 6 Opened issues


Ruby wrapper for libcmark (CommonMark parser)

Services available


Need anything else?

Contributors list


Build Status Gem Version

Ruby wrapper for libcmark-gfm, GitHub's fork of the reference parser for CommonMark. It passes all of the C tests, and is therefore spec-complete. It also includes extensions to the CommonMark spec as documented in the GitHub Flavored Markdown spec, such as support for tables, strikethroughs, and autolinking.

For more information on available extensions, see the documentation below.


Add this line to your application's Gemfile:

gem 'commonmarker'

And then execute:

$ bundle

Or install it yourself as:

$ gem install commonmarker


Converting to HTML


on a string to convert it to HTML:
require 'commonmarker'
CommonMarker.render_html('Hi *there*', :DEFAULT)

Hi there


The second argument is optional--see below for more information.

Generating a document

You can also parse a string to receive a

node. You can then print that node to HTML, iterate over the children, and other fun node stuff. For example:
require 'commonmarker'

doc = CommonMarker.render_doc('Hello world', :DEFAULT) puts(doc.to_html) #

Hi there


doc.walk do |node| puts node.type # [:document, :paragraph, :text, :emph, :text] end

The second argument is optional--see below for more information.

Example: walking the AST

You can use

to iterate over nodes:
  • walk
    will iterate on a node and recursively iterate on a node's children.
  • each
    will iterate on a node and its children, but no further.
require 'commonmarker'

parse the files specified on the command line

doc = CommonMarker.render_doc("# The site\n\n GitHub")

Walk tree and print out URLs for links

doc.walk do |node| if node.type == :link printf("URL = %s\n", node.url) end end

Capitalize all regular text in headers

doc.walk do |node| if node.type == :header node.each do |subnode| if subnode.type == :text subnode.string_content = subnode.string_content.upcase end end end end

Transform links to regular text

doc.walk do |node| if node.type == :link node.insert_before(node.first_child) node.delete end end

Creating a custom renderer

You can also derive a class from CommonMarker's

class. This produces slower output, but is far more customizable. For example:
class MyHtmlRenderer < CommonMarker::HtmlRenderer
  def initialize
    @headerid = 1

def header(node) block do out("", :children, "") @headerid += 1 end end end

myrenderer = puts myrenderer.render(doc)

Print any warnings to STDERR

renderer.warnings.each do |w| STDERR.write("#{w}\n") end


CommonMarker accepts the same options that CMark does, as symbols. Note that there is a distinction in CMark for "parse" options and "render" options, which are represented in the tables below.

Parse options

| Name | Description | ----------------------------- | ----------- |

| The default parsing system. |
| Allow raw/custom HTML and unsafe links. |
| Parse footnotes. |
| Support liberal parsing of inline HTML tags. |
| Use smart punctuation (curly quotes, etc.). |
| Parse strikethroughs by double tildes (compatibility with redcarpet) |
| Replace illegal sequences with the replacement character

Render options

| Name | Description | | ------------------ | ----------- | |

| The default rendering system. | |
| Allow raw/custom HTML and unsafe links. | |
| Use GitHub-style
 for fenced code blocks.           |
| Treat
as hardbreaks (by adding

). | |
| Translate
in the source to a single whitespace. | |
| Include source position in rendered HTML. | |
| Use
insted of
for table cells. | |
| Include full info strings of code blocks in separate attribute. | |
| Render footnotes. |

Passing options

To apply a single option, pass it in as a symbol argument:

CommonMarker.render_doc("\"Hello,\" said the spider.", :SMART)

“Hello,” said the spider.


To have multiple options applied, pass in an array of symbols:

CommonMarker.render_html("\"'Shelob' is my name.\"", [:HARDBREAKS, :SOURCEPOS])

For more information on these options, see the CMark documentation.



take an optional third argument defining the extensions you want enabled as your CommonMark document is being processed. The documentation for these extensions are defined in this spec, and the rationale is provided in this blog post.

The available extensions are:

  • :table
    - This provides support for tables.
  • :tasklist
    - This provides support for task list items.
  • :strikethrough
    - This provides support for strikethroughs.
  • :autolink
    - This provides support for automatically converting URLs to anchor tags.
  • :tagfilter
    - This escapes several "unsafe" HTML tags, causing them to not have any effect.

Developing locally

After cloning the repo:

bundle exec rake compile

If there were no errors, you're done! Otherwise, make sure to follow the CMark dependency instructions.


Some rough benchmarks:

$ bundle exec rake benchmark

input size = 11063727 bytes

redcarpet 0.070000 0.020000 0.090000 ( 0.079641) github-markdown 0.070000 0.010000 0.080000 ( 0.083535) commonmarker with to_html 0.100000 0.010000 0.110000 ( 0.111947) commonmarker with ruby HtmlRenderer 1.830000 0.030000 1.860000 ( 1.866203) kramdown 4.610000 0.070000 4.680000 ( 4.678398)

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.