wooorm
remark recently changed its name from mdast. Read more about what changed and how to migrate »
remark is a markdown processor powered by plugins. Lots of tests. Node, io.js, and the browser. 100% coverage.
remark is not just another markdown to HTML compiler. It can generate, and reformat, markdown too. Powered by plugins to do all kinds of things: validate your markdown, add links for GitHub references, or add a table of contents.
The project has both an extensive JavaScript API for parsing, modifying, and compiling markdown, and a friendly Command Line Interface making it easy to validate, prepare, and compile markdown in a build step.
Table of Contents
Installation
npm:
npm install remarkRead more about alternative ways to install and use »
Usage
Load dependencies:
var remark = require('remark');
var html = require('remark-html');
var yamlConfig = require('remark-yaml-config');Use plugins:
var processor = remark().use(yamlConfig).use(html);Process the document:
var doc = processor.process([
'---',
'remark:',
' commonmark: true',
'---',
'',
'2) Some *emphasis*, **strongness**, and `code`.'
].join('\n'));Yields:
<ol start="2">
<li>Some <em>emphasis</em>, <strong>strongness</strong>, and <code>code</code>.</li>
</ol>API
remark.process(value[, options][, done])
Parse a markdown document, apply plugins to it, and compile it into something else.
Signatures:
doc = remark.process(value, options?, done?).
Parameters:
value(string) — Markdown document;options(Object) — Settings:gfm(boolean, default:true) — See GitHub Flavoured Markdown;yaml(boolean, default:true) — See YAML;commonmark(boolean, default:false) — See CommonMark;footnotes(boolean, default:false) — See Footnotes;pedantic(boolean, default:false) — See Pedantic;breaks(boolean, default:false) — See Breaks;entities(boolean, default:false) — See Encoding Entities;setext(boolean, default:false) — See Setext Headings;closeAtx(boolean, default:false) — See Closed ATX Headings;looseTable(boolean, default:false) — See Loose Tables;spacedTable(boolean, default:true) — See Spaced Tables;fence("~"or"`", default:"`") — See Fence;fences(boolean, default:false) — See Fences;bullet("-","*", or"+", default:"-") — See List Item Bullets;listItemIndent("tab","mixed"or"1", default:"tab") — See List Item Indent;incrementListMarker(boolean, default:true) — See List Marker Increase;rule("-","*", or"_", default:"*") — See Horizontal Rules;ruleRepetition(number, default:3) — See Horizontal Rules;ruleSpaces(boolean, defaulttrue) — See Horizontal Rules;strong("_", or"*", default"*") — See Emphasis Markers;emphasis("_", or"*", default"_") — See Emphasis Markers.position(boolean, default:true) — See Position;
done(function(Error?, string?)) — Callback invoked when the output is generated with either an error, or a result. Only strictly needed when asynchronous plugins are used.
All options (including the options object itself) can be null or undefined
to default to their default values.
Returns:
string or null: A document. Formatted in markdown by default, or in
whatever a plugin generates.
The result is null if a plugin is asynchronous, in which case the callback
done should’ve been passed (do not worry: plugin creators make sure you know
its asynchronous).
remark.use(plugin[, options])
Change the way remark works by using a plugin.
Signatures:
processor = remark.use(plugin, options?);processor = remark.use(plugins).
Parameters:
plugin(Function) — A Plugin;plugins(Array.<Function>) — A list of Plugins;options(Object?) — Passed to plugin. Specified by its documentation.
Returns:
Object: an instance of Remark: The returned object functions just like
remark (it has the same methods), but caches the used plugins. This
provides the ability to chain use calls to use more than one plugin, but
ensures the functioning of the remark module does not change for other
dependents.
CLI
Install:
npm install --global remarkUse:
Usage: remark [options] <pathspec...>
Markdown processor powered by plugins
Options:
-h, --help output usage information
-V, --version output the version number
-o, --output [path] specify output location
-c, --config-path <path> specify configuration location
-i, --ignore-path <path> specify ignore location
-s, --setting <settings> specify settings
-u, --use <plugins> use transform plugin(s)
-e, --ext <extensions> specify extensions
-w, --watch watch for changes and reprocess
-q, --quiet output only warnings and errors
-S, --silent output only errors
-f, --frail exit with 1 on warnings
-t, --tree input and output syntax tree
--file-path <path> specify file path to process as
--tree-out output syntax tree
--tree-in input syntax tree
--no-stdout disable writing to stdout
--no-color disable color in output
--no-rc disable configuration from .remarkrc
--no-ignore disable ignore from .remarkignore
See also: man 1 remark, man 3 remark,
man 3 remarkplugin, man 5 remarkrc,
man 5 remarkignore, man 7 remarksetting,
man 7 remarkconfig, man 7 remarkplugin.
Examples:
# Process `readme.md`
$ remark readme.md -o readme-new.md
# Pass stdin(4) through remark, with settings, to stdout(4)
$ remark --setting "setext: true, bullet: \"*\"" < readme.md > readme-new.md
# Use a plugin (with options)
$ npm install remark-toc
$ remark readme.md --use "toc=heading:\"contents\"" -o
# Rewrite markdown in a directory
$ remark . -o