Ruby/RubyMotion version of Markdown-it (CommonMark compliant and extendable)
This gem is a port of the markdown-it Javascript package by Vitaly Puzrin and Alex Kocharin.
Currently synced with markdown-it 13.0.1
Follows the CommonMark spec + adds syntax extensions & sugar (URL autolinking, typographer).
- Configurable syntax. You can add new rules and even replace existing ones.
- Safe by default.
- Community-written plugins
- Ruby/RubyMotion
- original javascript plugins and other packages on npm.
The benefit of this project, for me at least, is to have a standardized CommonMark compliant, fast, and extendable, Markdown parser which can be used from Javascript, Ruby, and/or RubyMotion, as the development situation warrants.
Performance is slower than, say, kramdown, but for most uses, is pretty fast. Here are some non-scientific benchmarks. Note that kramdown and redcarpet are not CommonMark compliant.
Running tests on 2018-04-04 under ruby 2.3.1p112 (2016-04-26 revision 54768) [x86_64-darwin16]
==> Test using file mdsyntax.text and 500 runs
Rehearsal -------------------------------------------------------------
motion-markdown-it 8.4.1 17.940000 0.710000 18.650000 ( 18.721629)
kramdown 1.16.2 14.720000 0.180000 14.900000 ( 15.015840)
commonmarker 0.17.9 0.220000 0.000000 0.220000 ( 0.222098)
redcarpet 3.4.0 0.140000 0.010000 0.150000 ( 0.145821)
--------------------------------------------------- total: 33.920000sec
user system total real
motion-markdown-it 8.4.1 18.290000 0.720000 19.010000 ( 19.113943)
kramdown 1.16.2 13.320000 0.110000 13.430000 ( 13.459096)
commonmarker 0.17.9 0.190000 0.000000 0.190000 ( 0.187104)
redcarpet 3.4.0 0.120000 0.000000 0.120000 ( 0.123931)
Real time as a factor of motion-markdown-it
motion-markdown-it 8.4.1 1.0
kramdown 1.16.2 0.7042
commonmarker 0.17.9 0.0098
redcarpet 3.4.0 0.0065
Add it to your project's Gemfile
gem 'motion-markdown-it'
and run bundle install
Add it to your project's Gemfile
gem 'motion-markdown-it'
Edit your Rakefile and add
require 'motion-markdown-it'
and run bundle install
parser = MarkdownIt::Parser.new(:commonmark, { html: false })
parser.render('# markdown-it in **Ruby**')Single line rendering, without paragraph wrap:
result = MarkdownIt::Parser.new.renderInline('__markdown-it__ in Ruby')(*) presets define combinations of active rules and options. Can be
:commonmark, :zero or :default (if skipped).
#--- commonmark mode
parser = MarkdownIt::Parser.new(:commonmark)
#--- default mode
parser = MarkdownIt::Parser.new
#--- enable everything
parser = MarkdownIt::Parser.new({ html: true, linkify: true, typographer: true })
#--- full options list (defaults)
parser = MarkdownIt::Parser.new({
html: false, # Enable HTML tags in source
xhtmlOut: false, # Use '/' to close single tags (<br />).
# This is only for full CommonMark compatibility.
breaks: false, # Convert '\n' in paragraphs into <br>
langPrefix: 'language-', # CSS language prefix for fenced blocks. Can be
# useful for external highlighters.
linkify: false, # Autoconvert URL-like text to links
# Enable some language-neutral replacement + quotes beautification
# For the full list of replacements, see https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/replacements.js
typographer: false,
# Double + single quotes replacement pairs, when typographer enabled,
# and smartquotes on. Could be either a String or an Array.
#
# For example, you can use '«»„“' for Russian, '„“‚‘' for German,
# and ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] for French (including nbsp).
quotes: '“”‘’',
# Highlighter function. Should return escaped HTML,
# or nil if the source string is not changed and should be escaped externally.
highlight: lambda {|str, lang| return nil}
})Plugins can be used to extend the syntax and functionality. A sample set of plugins has been created based on those already created for the javascript version. Included are:
Upgrading to 8.4.1.2 could cause some small breakage if you are using any custom plugins. The motion-markdown-it-plugins plugins have already been upgraded.
Make sure you have
include MarkdownIt::Common::Utilsat the top of your plugin file. Then change any references to charCodeAt. For example,
state.src.charCodeAt(pos)would become
charCodeAt(state.src, pos)slice_to_end has been removed. Change references like this
state.src.slice_to_end(pos)to
state.src[pos..-1]Thanks to the authors of the original implementation in Javascript, markdown-it:
- Alex Kocharin github/rlidwka
- Vitaly Puzrin github/puzrin
and to John MacFarlane for his work on the CommonMark spec and reference implementations.
Related Links:
- https://github.com/jgm/CommonMark - reference CommonMark implementations in C & JS, also contains latest spec & online demo.
- http://talk.commonmark.org - CommonMark forum, good place to collaborate developers' efforts.