mdast

mdast is a markdown processor powered by plugins. Lots of tests. Node, io.js, and the browser. 100% coverage.

mdast is not just another markdown to HTML compiler. It can generate, and reformat, markdown too. It’s 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 contains both an extensive JavaScript API for parsing, modifying, and stringifying markdown, and a friendly Command Line Interface making it easy to validate, prepare, and compile markdown in a build step.

Table of Contents

• Installation

• Usage

• API

  • mdast.process(value, options?, done?)
  • mdast.use(plugin, options?)

• CLI

• Benchmark

• License

Installation

npm:

npm install mdast

Component.js:

component install wooorm/mdast

Bower:

bower install mdast

Duo:

var mdast = require('wooorm/mdast');

UMD (globals/AMD/CommonJS) (uncompressed and compressed):

<script src="path/to/mdast.js" charset="utf-8"></script>
<script>
    mdast.process('*hello* __world__'); // _hello_ **world**
</script>

Usage

var mdast = require('mdast');
var yamlConfig = require('mdast-yaml-config');

Use a plugin. mdast-yaml-config allows settings in YAML frontmatter.

var processor = mdast().use(yamlConfig);

Parse, modify, and stringify the document:

var doc = processor.process(
    '---\n' +
    'mdast:\n' +
    '  commonmark: true\n' +
    '---\n' +
    '\n' +
    '2) Some *emphasis*, **strongness**, and `code`.\n'
);

Yields:

---
mdast:
  commonmark: true
---

2.  Some _emphasis_, **strongness**, and `code`.

API

This section only covers the interface you’ll use most often. See mdast(3) documentation for a more complete description:

• mdast.parse(file, options?) — Parses markdown into an abstract syntax tree;

• mdast.run(ast, file, done?) — Applies plugins to the syntax tree;

• mdast.stringify(ast, options?) — Compiles the syntax tree into a string;

• mdast.process(file, options?, done?) — More detailed than below;

• mdast.use(plugin, options?) — More detailed than below;

• function done(err?, doc?, file?) — Callback passed to run() and process().

• File() — Wrapper around (virtual) files.

mdast.process(value, options?, done?)

Parse a markdown document, apply plugins to it, and compile it into something else.

Signatures

• doc = mdast.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, default true) — 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 async 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 (don’t worry: plugin creators make sure you know its async).

mdast.use(plugin, options?)

Change the way mdast works by using a plugin.

Signatures

• processor = mdast.use(plugin, options?);
• processor = mdast.use(plugins).

Parameters

• plugin (Function) — A Plugin;

• plugins (Array.<Function>) — A list of Plugins;

• options (Object?) — Passed to the plugin. Specified by its documentation.

Returns

Object: an instance of MDAST: The returned object functions just like mdast (it has the same methods), but caches the used plugins. This provides the ability to chain use calls to use multiple plugins, but ensures the functioning of the mdast module does not change for other dependents.

CLI

Install:

npm install --global mdast

Use:

Usage: mdast [options] file|dir ...

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
  -a, --ast                 output AST information
  -q, --quiet               output only warnings and errors
  -S, --silent              output only errors
  --file-path <path>        specify file path to process as
  --no-color                disable color in output
  --no-rc                   disable configuration from .mdastrc
  --no-ignore               disable ignore from .mdastignore

Usage:

# Pass `readme.md` through mdast
$ mdast readme.md -o readme-new.md

# Pass stdin through mdast, with settings, to stdout
$ cat readme.md | mdast -s "setext: true, bullet: "*"" > readme-new.md

# Use a plugin (with options)
$ npm install mdast-toc
$ mdast --use toc=heading:"contents" readme.md -o

# Rewrite markdown in a directory
$ mdast . -o

See also:

man 1 mdast, man 3 mdast, man 5 mdastrc, man 5 mdastignore, man 7 mdastconfig

Benchmark

On a MacBook Air, it parses ± 322Kb of markdown (in 214 documents) per second.

          214 fixtures (total: 80.62Kb)
   4 op/s » mdast.parse w/ `gfm: true`, and `yaml: true`
  69 op/s » mdast.stringify w/ `gfm: true`, and `yaml: true`
   4 op/s » mdast.parse w/ `gfm: false`, and `yaml: false`
  70 op/s » mdast.stringify w/ `gfm: false`, and `yaml: false`
   4 op/s » mdast.parse w/ `gfm: true`, `yaml: true`, and `commonmark: true`
  72 op/s » mdast.stringify w/ `gfm: true`, `yaml: true`, and `commonmark: true`

License

MIT © Titus Wormer

This project was initially a fork of marked.

Copyright (c) 2011-2014, Christopher Jeffrey. (MIT License)