mdast

mdast is a markdown parser and stringifier for multipurpose analysis in JavaScript. Node and the browser. Lots of tests. 100% coverage.

It’s not just another markdown to HTML compiler. mdast can generate markdown too, which enables plug-ins (and you) to change your Readme.md, or lint the JavaScript in your markdown.

Table of Contents

• Installation
• Usage
• API
  • mdast.parse(value, options?)
  • mdast.stringify(ast, options?)
  • mdast.run(ast, options?)
  • mdast.use(plugin)
    • function plugin(ast, options, mdast)
    • function attach(mdast)
• 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"></script>
<script>
    var ast = mdast.parse('*hello* __world__');
    mdast.stringify(ast); // _hello_ **world**
</script>

Usage

See Nodes for information about returned objects.

var mdast = require('mdast');

Parse markdown with mdast.parse:

var ast = mdast.parse('Some *emphasis*, **strongness**, and `code`.');

Yields:

{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "Some ",
          "position": {
            "start": {
              "line": 1,
              "column": 1
            },
            "end": {
              "line": 1,
              "column": 6
            }
          }
        },
        {
          "type": "emphasis",
          "children": [
            {
              "type": "text",
              "value": "emphasis",
              "position": {
                "start": {
                  "line": 1,
                  "column": 7
                },
                "end": {
                  "line": 1,
                  "column": 15
                }
              }
            }
          ],
          "position": {
            "start": {
              "line": 1,
              "column": 6
            },
            "end": {
              "line": 1,
              "column": 16
            }
          }
        },
        {
          "type": "text",
          "value": ", ",
          "position": {
            "start": {
              "line": 1,
              "column": 16
            },
            "end": {
              "line": 1,
              "column": 18
            }
          }
        },
        {
          "type": "strong",
          "children": [
            {
              "type": "text",
              "value": "strongness",
              "position": {
                "start": {
                  "line": 1,
                  "column": 20
                },
                "end": {
                  "line": 1,
                  "column": 30
                }
              }
            }
          ],
          "position": {
            "start": {
              "line": 1,
              "column": 18
            },
            "end": {
              "line": 1,
              "column": 32
            }
          }
        },
        {
          "type": "text",
          "value": ", and ",
          "position": {
            "start": {
              "line": 1,
              "column": 32
            },
            "end": {
              "line": 1,
              "column": 38
            }
          }
        },
        {
          "type": "inlineCode",
          "value": "code",
          "position": {
            "start": {
              "line": 1,
              "column": 38
            },
            "end": {
              "line": 1,
              "column": 44
            }
          }
        },
        {
          "type": "text",
          "value": ".",
          "position": {
            "start": {
              "line": 1,
              "column": 44
            },
            "end": {
              "line": 1,
              "column": 45
            }
          }
        }
      ],
      "position": {
        "start": {
          "line": 1,
          "column": 1
        },
        "end": {
          "line": 1,
          "column": 45
        }
      }
    }
  ],
  "position": {
    "start": {
      "line": 1,
      "column": 1
    },
    "end": {
      "line": 1,
      "column": 45
    }
  }
}

And passing that document into mdast.stringify:

var doc = mdast.stringify(ast);

Yields:

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

API

mdast.parse(value, options?)

Parse a markdown document into an abstract syntax tree.

Signatures

• ast = mdast.parse(value);
• ast = mdast.parse(value, options).

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.

All options (including the options object itself) can be null or undefined to default to their default values.

Returns

Object: see Nodes for the AST specification.

mdast.stringify(ast, options?)

Stringify an abstract syntax tree into a markdown document.

Signatures

• value = mdast.stringify(ast);
• value = mdast.stringify(ast, options).

Parameters

• ast (Object) — An AST as returned by mdast.parse();
• options (Object) — Settings:
  • 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;
  • referenceLinks (boolean, default: false). See Reference Links;
  • fence ("~" or "`", default: "`"). See Fence;
  • fences (boolean, default: false). See Fences;
  • bullet ("-", "*", or "+", default: "-"). See List Item Bullets;
  • 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.

All options (including the options object itself) can be null or undefined to default to their default values.

Returns

string: a document formatted in markdown.

mdast.run(ast, options?)

Modify an abstract syntax tree by applying used plugins to it.

Signatures

• ast = mdast.run(ast);
• ast = mdast.run(ast, options).

Parameters

• ast (Object) — An AST as returned by mdast.parse();
• options (Object) — Settings, passed to plugins.

Returns

Object: the given AST.

mdast.use(plugin)

Change the way mdast works by using a plugin.

Signatures

• mdast = mdast.use(plugin);
• mdast = mdast.use(plugins).

Parameters

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

Returns

Object: an instance of MDAST: The returned object functions just like mdast (it also has use, parse, and stringify 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 dependants.

function plugin(ast, options, mdast)

A plugin is a simple function which is invoked each time a document is mdast.parse()d. A plugin should change the AST to add or remove nodes. attach should change the mdast instance.

Signatures

• plugin(ast, options, mdast);
• error = plugin(ast, options, mdast).

Parameters

• ast (Object) — An AST as returned by mdast.parse();
• options (Object) — Options passed to mdast.parse() or mdast.run();
• mdast (Object) — Context on which mdast.parse() or mdast.run() was invoked.

Returns

undefined or Error, which in the later case will be thrown.

function attach(mdast)

To modify the parser (for an example, see test/mentions.js), specify an attach method on plugin. attach is invoked when the plugin is first used.

Signatures

• attach(mdast).

Parameters

• mdast (Object) — Context on which the plugin was used.

CLI

Install:

$ npm install --global mdast

Use:

Usage: mdast [options] file

Speedy Markdown parser/stringifier for multipurpose analysis

Options:

  -h, --help                output usage information
  -V, --version             output the version number
  -o, --output <path>       specify output location
  -s, --setting <settings>  specify settings
  -u, --use <plugins>       use transform plugin(s)
  -a, --ast                 output AST information
  --settings                output available settings

# Note that bash does not allow reading and writing
# to the same file through pipes

Usage:

# Pass `Readme.md` through mdast
$ mdast Readme.md -o Readme.md

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

# use a plugin
$ npm install mdast-toc
$ mdast --use mdast-toc -o Readme.md

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)