By default, remarkable is configured to be similar to GFM, but with HTML disabled.
This is easy to change if you prefer different settings.
There are two ways to define options.
constructor
Define options in the constructor:
// Actual default valuesvar md = new Remarkable({ html: false, // Enable HTML tags in source xhtmlOut: false, // Use '/' to close single tags (<br />) breaks: false, // Convert '\n' in paragraphs into <br> langPrefix: 'language-', // CSS language prefix for fenced blocks // Enable some language-neutral replacement + quotes beautification typographer: false, // Double + single quotes replacement pairs, when typographer enabled, // and smartquotes on. Set doubles to '«»' for Russian, '„“' for German. quotes: '“”‘’', // Highlighter function. Should return escaped HTML, // or '' if the source string is not changed highlight: function (/*str, lang*/) { return ''; }
.set
Or define options via the .set() method:
import { Remarkable } from 'remarkable';var md = new Remarkable();md.set({ html: true, breaks: true});
Note: To achieve the best possible performance, don't modify a Remarkable
instance on the fly. If you need multiple configurations, create
multiple instances and initialize each with a configuration that is ideal for
that instance.
Presets
Remarkable offers some "presets" as a convenience to quickly enable/disable
active syntax rules and options for common use cases.
commonmark
Enable strict CommonMark mode with the commonmark preset:
import { Remarkable } from 'remarkable';var md = new Remarkable('commonmark');
full
Enable all available rules (but still with default options, if not set):
import { Remarkable } from 'remarkable';var md = new Remarkable('full');// Or with options:var md = new Remarkable('full', { html: true, typographer: true});
Syntax highlighting
Apply syntax highlighting to fenced code blocks with the highlight option:
import { Remarkable } from 'remarkable';import hljs from 'highlight.js' // https://highlightjs.org/// Actual default valuesvar md = new Remarkable({ highlight: function (str, lang) { if (lang && hljs.getLanguage(lang)) { try { return hljs.highlight(lang, str).value; } catch (err) {} } try { return hljs.highlightAuto(str).value; } catch (err) {} return ''; // use external default escaping
HEADS UP!: Experimental extensions can be changed later for something like Critic Markup, but you will still be able to use old-style rules via external plugins if you prefer.
Manage rules
var md = new Remarkable();md.inline.ruler.enable([ 'ins', 'mark' ]);md.block.ruler.disable([ 'table', 'footnote' ]);// Enable everythingmd = new Remarkable('full', { html: true, typographer: true,});//// Manually enable rules, disabled by default://var md = new Remarkable();md.core.ruler.enable([ 'abbr']);md.block.ruler.enable([
Typographer
Although full-weight typographical replacements are language specific, remarkable
provides coverage for the most common and universal use cases:
Big thanks to John MacFarlane for his work on the
CommonMark spec and reference implementations. His work saved us a lot of time
during this project's development.
Parser consists of several responsibility chains filled with
rules. You can reconfigure any of them as you wish. Renderer also
can be modified and extended. See source code to understand details. Pay
attention to these properties:
Here is result of CommonMark spec parse at Core i5 2.4 GHz (i5-4258U):
$ benchmark/benchmark.js specSelected samples: (1 of 27) > specSample: spec.txt (110610 bytes) > commonmark-reference x 40.42 ops/sec ±4.07% (51 runs sampled) > current x 74.99 ops/sec ±4.69% (67 runs sampled) > current-commonmark x 93.76 ops/sec ±1.23% (79 runs sampled) > marked-0.3.2 x 22.92 ops/sec ±0.79% (41 runs sampled)
As you can see, remarkable doesn't pay with speed for its flexibility. Because
it's written in monomorphic style and uses JIT inline caches effectively.