remarkable
Markdown parser, done right. Commonmark support, extensions, syntax plugins, high speed - all in one. Gulp and metalsmith plugins available. Used by Facebook, Docusaurus and many others! Use https://github.com/breakdance/breakdance for HTML-to-markdown conversion. Use https://github.com/jonschlinkert/markdown-toc to generate a table of contents.
Top Related Projects
A markdown parser and compiler. Built for speed.
Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed
A bidirectional Markdown to HTML to Markdown converter written in Javascript
CommonMark parser and renderer in JavaScript
A Markdown parser for javascript
Quick Overview
Remarkable is a powerful and flexible Markdown parser for JavaScript. It offers high speed, extensibility through plugins, and supports both CommonJS and browser environments. Remarkable aims to be feature-rich while maintaining a small footprint and excellent performance.
Pros
- High performance and speed compared to other Markdown parsers
- Extensible through plugins and custom rules
- Supports both CommonJS and browser environments
- Highly configurable with many options for customization
Cons
- Less actively maintained compared to some other Markdown parsers
- Documentation could be more comprehensive
- Some advanced features may require additional configuration or plugins
Code Examples
- Basic usage:
const { Remarkable } = require('remarkable');
const md = new Remarkable();
console.log(md.render('# Hello, world!'));
// Output: <h1>Hello, world!</h1>
- Customizing options:
const md = new Remarkable({
html: true,
breaks: true,
typographer: true
});
console.log(md.render('This is *italic* and **bold** text.'));
// Output: <p>This is <em>italic</em> and <strong>bold</strong> text.</p>
- Using plugins:
const { Remarkable } = require('remarkable');
const highlightjs = require('remarkable-highlightjs');
const md = new Remarkable()
.use(highlightjs, { hljs: require('highlight.js') });
console.log(md.render('```js\nconsole.log("Hello");\n```'));
// Output: <pre><code class="hljs language-js"><span class="hljs-built_in">console</span>.log(<span class="hljs-string">"Hello"</span>);</code></pre>
Getting Started
To use Remarkable in your project, follow these steps:
-
Install the package:
npm install remarkable
-
Import and use in your JavaScript code:
const { Remarkable } = require('remarkable'); const md = new Remarkable(); const markdownText = '# Hello\nThis is **Markdown**'; const htmlOutput = md.render(markdownText); console.log(htmlOutput);
This will render the Markdown text to HTML. You can further customize the parser by passing options to the constructor or using plugins to extend its functionality.
Competitor Comparisons
A markdown parser and compiler. Built for speed.
Pros of Marked
- Faster parsing and rendering speed
- More active development and community support
- Better documentation and examples
Cons of Marked
- Less extensible and customizable
- Fewer built-in features and options
- Stricter adherence to CommonMark specification, which may limit flexibility
Code Comparison
Marked:
import { marked } from 'marked';
const html = marked.parse('# Heading\n\nParagraph');
console.log(html);
Remarkable:
import { Remarkable } from 'remarkable';
const md = new Remarkable();
const html = md.render('# Heading\n\nParagraph');
console.log(html);
Key Differences
- Marked focuses on speed and simplicity, while Remarkable offers more customization options
- Remarkable provides a plugin system for extending functionality, whereas Marked has limited extension capabilities
- Marked strictly follows CommonMark, while Remarkable allows for more flexibility in parsing and rendering
Use Cases
- Choose Marked for projects requiring fast parsing and rendering of standard Markdown
- Opt for Remarkable when extensive customization or additional features are needed
Community and Maintenance
- Marked has a larger user base and more frequent updates
- Remarkable has a smaller but dedicated community and less frequent updates
Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed
Pros of markdown-it
- More extensive plugin ecosystem and customization options
- Better performance, especially for large documents
- Active development and frequent updates
Cons of markdown-it
- Slightly larger bundle size
- Steeper learning curve for advanced customization
Code Comparison
markdown-it
const md = require('markdown-it')();
const result = md.render('# Hello, world!');
remarkable
const Remarkable = require('remarkable');
const md = new Remarkable();
const result = md.render('# Hello, world!');
Both libraries offer similar basic usage, but markdown-it provides more advanced features and configuration options out of the box. For example, markdown-it allows for easier plugin integration:
const md = require('markdown-it')()
.use(plugin1)
.use(plugin2, options);
While remarkable requires more setup for similar functionality:
const md = new Remarkable();
md.inline.ruler.enable(['plugin1', 'plugin2']);
Overall, markdown-it offers more flexibility and power, but remarkable may be simpler for basic use cases. The choice between the two depends on project requirements and developer preferences.
A bidirectional Markdown to HTML to Markdown converter written in Javascript
Pros of Showdown
- Wider browser compatibility, including older versions
- More extensive documentation and examples
- Active community with frequent updates and contributions
Cons of Showdown
- Slightly slower performance for large documents
- Less strict adherence to CommonMark specification
- Larger file size, which may impact load times in browser environments
Code Comparison
Showdown
var converter = new showdown.Converter();
var html = converter.makeHtml('# Hello, Markdown!');
Remarkable
var md = new remarkable.Remarkable();
var html = md.render('# Hello, Markdown!');
Both libraries offer similar ease of use, with Showdown using a Converter
object and Remarkable using a Remarkable
object. The main difference lies in the method names: makeHtml
for Showdown and render
for Remarkable.
Showdown provides more flexibility in configuration and extension, while Remarkable focuses on performance and strict adherence to CommonMark. Choose Showdown for broader compatibility and extensive documentation, or Remarkable for speed and spec compliance in modern environments.
CommonMark parser and renderer in JavaScript
Pros of commonmark.js
- Strictly adheres to the CommonMark specification, ensuring consistent parsing across implementations
- Extensive test suite with over 600 tests, providing robust coverage and reliability
- Offers a clear and well-documented API for easy integration
Cons of commonmark.js
- Less flexible for customization compared to Remarkable
- May have slower performance for certain use cases due to strict spec adherence
- Fewer built-in extensions and plugins available out-of-the-box
Code Comparison
Remarkable:
var md = new Remarkable();
var result = md.render('# Hello, world!');
commonmark.js:
var reader = new commonmark.Parser();
var writer = new commonmark.HtmlRenderer();
var parsed = reader.parse("# Hello, world!");
var result = writer.render(parsed);
The code comparison shows that Remarkable offers a more straightforward API for basic usage, while commonmark.js separates parsing and rendering steps, providing more granular control but requiring slightly more code.
Both libraries are well-maintained and widely used in the Markdown parsing ecosystem. The choice between them depends on specific project requirements, such as the need for strict CommonMark compliance or flexibility for customization.
A Markdown parser for javascript
Pros of markdown-js
- Longer history and established user base
- Supports both client-side and server-side usage
- Offers a wider range of output formats (HTML, JSON, XML)
Cons of markdown-js
- Less actively maintained (last commit over 5 years ago)
- Slower parsing speed compared to Remarkable
- Limited extension capabilities
Code Comparison
markdown-js:
var markdown = require( "markdown" ).markdown;
console.log(markdown.toHTML("Hello *World*!"));
Remarkable:
var Remarkable = require('remarkable');
var md = new Remarkable();
console.log(md.render('Hello *World*!'));
Performance
Remarkable generally outperforms markdown-js in terms of parsing speed, especially for larger documents.
Extensibility
Remarkable offers a more robust plugin system, allowing for easier customization and extension of its functionality.
Community and Maintenance
While markdown-js has a longer history, Remarkable has more recent updates and active maintenance, which can be crucial for bug fixes and feature additions.
Compatibility
Both libraries aim to be CommonMark compliant, but Remarkable tends to have better adherence to the specification.
Use Cases
markdown-js might be preferred for simpler projects or those requiring multiple output formats, while Remarkable is better suited for performance-critical applications or those needing extensive customization.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
remarkable
Markdown parser done right. Fast and easy to extend.
- Supports the CommonMark spec + syntax extensions + sugar (URL autolinking, typographer).
- Configurable syntax! You can add new rules and even replace existing ones.
- High speed!
- Community plugins on npm.
Install
node.js:
npm install remarkable --save
browser (CDN):
Usage
import { Remarkable } from 'remarkable';
var md = new Remarkable();
console.log(md.render('# Remarkable rulezz!'));
// => <h1>Remarkable rulezz!</h1>
or with commonjs
const { Remarkable } = require('remarkable');
var md = new Remarkable();
console.log(md.render('# Remarkable rulezz!'));
// => <h1>Remarkable rulezz!</h1>
If installed globally with npm
:
cat myfile.md | remarkable
remarkable --file myfile.md
# get options
remarkable -h
Documentation
See the docs directory for documentation on the following topics:
Options
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 values
var 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 ''; }
});
console.log(md.render('# Remarkable rulezz!'));
// => <h1>Remarkable rulezz!</h1>
.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 values
var 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
}
});
Syntax extensions
Enabled by default:
Disabled by default:
- <sup> -
19^th^
- <sub> -
H~2~O
- abbreviations
- <ins> -
++inserted text++
(experimental) - <mark> -
==marked text==
(experimental)
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 everything
md = 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([
'footnote',
'deflist'
]);
md.inline.ruler.enable([
'footnote_inline',
'ins',
'mark',
'sub',
'sup'
]);
Typographer
Although full-weight typographical replacements are language specific, remarkable
provides coverage for the most common and universal use cases:
import { Remarkable } from 'remarkable';
var md = new Remarkable({
typographer: true,
quotes: 'ââââ'
});
// Disable rules at all:
md.core.ruler.disable([ 'replacements', 'smartquotes' ]);
// Actual default replacements:
//
// '' â ââ
// "" â ââ. Set '«»' for Russian, 'ââ' for German, empty to disable
// (c) (C) â ©
// (tm) (TM) â â¢
// (r) (R) â ®
// +- â ±
// (p) (P) -> §
// ... â ⦠(also ?.... â ?.., !.... â !..)
// ???????? â ???, !!!!! â !!!, `,,` â `,`
// -- â –, --- â —
//
Of course, you can also add your own rules or replace the defaults with something more advanced or specific to your language.
Plugins
Easily load plugins with the .use()
method:
var md = new Remarkable();
md.use(plugin1)
.use(plugin2, opts)
.use(plugin3);
Please refer to the plugin documentation to create your own plugins.
linkify plugin
Autoconvert URL-like text to links
import { Remarkable } from 'remarkable';
import { linkify } from 'remarkable/linkify';
var md = new Remarkable().use(linkify);
UMD
UMD bundle provides linkify out of the box
const { Remarkable, linkify, utils } = window.remarkable;
References / Thanks
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.
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.
Development / Modification
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:
Remarkable.core
Remarkable.core.ruler
Remarkable.block
Remarkable.block.ruler
Remarkable.inline
Remarkable.inline.ruler
Remarkable.renderer
Remarkable.renderer.rules
Benchmark
Here is result of CommonMark spec parse at Core i5 2.4 GHz (i5-4258U):
$ benchmark/benchmark.js spec
Selected samples: (1 of 27)
> spec
Sample: 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.
Authors
- Jon Schlinkert github/jonschlinkert
- Alex Kocharin github/rlidwka
- Vitaly Puzrin github/puzrin
License
Top Related Projects
A markdown parser and compiler. Built for speed.
Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed
A bidirectional Markdown to HTML to Markdown converter written in Javascript
CommonMark parser and renderer in JavaScript
A Markdown parser for javascript
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot