remark

Core

remark is an ecosystem of plugins for processing markdown built on unified. The project parses and compiles markdown, and lets programs process markdown without ever compiling to HTML (it can though). Powered by plugins to do all kinds of things: check markdown code style, transform safely to React, add a table of contents, or compile to man pages.

It aims to do for Markdown what Esprima did for JavaScript and PostCSS for CSS: bring Markdown into the tooling age.

remark has lots of tests (800+), great coverage (100%), and a free license.

View the project on GitHub or inspect the syntax tree on AST Explorer.

CLI

The Command Line Interface is powerful, it supports all settings the API provides and has built-in support for regenerating markdown files in a project according to a given style-guide, and emits warnings triggered by plugins in a beautiful fashion.

Say example.md looks as follows:

example.md
* Hello

[World][]

Now, by running remark in a terminal we’ll see the following:

sh
remark example.md --use remark-preset-lint-recommended
example.md
       1:3  warning  Incorrect list-item indent: add 2 spaces  list-item-indent
  3:1-3:10  warning  Found reference to undefined definition   no-undefined-references

 2 warnings

Read more about the CLI in its readme.

API

The Application Programming Interface is the gist of remark and the CLI. It’s provided by unified so head to its API documentation for more info.

Say we have the following index.js file using remark, remark-preset-lint-markdown-style-guide, remark-html, and vfile-reporter:

index.js
var remark = require('remark');
var guide = require('remark-preset-lint-markdown-style-guide');
var html = require('remark-html');
var report = require('vfile-reporter');

remark()
  .use(guide)
  .use(html)
  .process('*emphasis* and _importance_', function (err, file) {
    console.log(String(file));
    console.error(report(err || file));
  });

Now, after installing dependencies and running index.js with Node, you’ll see the following:

sh
npm install remark vfile-reporter remark-html remark-preset-lint-markdown-style-guide
/Users/tilde/example
├── remark@7.0.1
├── remark-html@6.0.0
├── remark-preset-lint-markdown-style-guide@1.0.0
└── vfile-reporter@3.0.0

node index.js
<p><em>emphasis</em> and <em>importance</em></p>
example.md
  1:16-1:28  warning  Emphasis should use `*` as a marker  emphasis-marker

 1 warning

unified

unified is an interface for processing text with syntax trees and transforming between them. Three syntaxes are connected to unified, each coming with a syntax tree definition, and a parser and stringifier: mdast with remark for markdown, nlcst with retext for prose, and hast with rehype for HTML.

unified also bridges between syntaxes, such as between markdown and HTML, as can be seen below:

index.js
var unified = require('unified');
var stream = require('unified-stream');
var markdown = require('remark-parse');
var toc = require('remark-toc');
var remark2rehype = require('remark-rehype');
var doc = require('rehype-document');
var format = require('rehype-format');
var html = require('rehype-stringify');

var processor = unified()
  .use(markdown)
  .use(toc)
  .use(remark2rehype)
  .use(doc, {title: 'Contents'})
  .use(format)
  .use(html);

process.stdin
  .pipe(stream(processor))
  .pipe(process.stdout);

View the unified project on GitHub or peruse the website.