motion-markdown-it

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 8.4.1

Javascript Live demo

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.

Benefit

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

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

Table of content

• Install
• Usage examples
• Plugins
• Upgrading
• References / Thanks
• License

Install

Ruby

Add it to your project's Gemfile

gem 'motion-markdown-it'

and run bundle install

RubyMotion

Add it to your project's Gemfile

gem 'motion-markdown-it'

Edit your Rakefile and add

require 'motion-markdown-it'

and run bundle install

Usage examples

Simple

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')

Init with presets and options

(*) 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
  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

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:

• Abbreviations
• Checkbox/Tasklists
• Containers
• Definition Lists
• Insert
• Mark
• Subscript
• Superscript

Upgrading

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.

charCodeAt

Make sure you have

include MarkdownIt::Common::Utils

at 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

slice_to_end has been removed. Change references like this

state.src.slice_to_end(pos)

to

state.src[pos..-1]

References / Thanks

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.

License

MIT