mdast

mdast is speedy Markdown parser (and stringifier) for multipurpose analysis (a syntax tree) in JavaScript. Node.JS and the browser. Lots of tests. 100% coverage.

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 minified):

<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": 19
            }
          }
        },
        {
          "type": "strong",
          "children": [
            {
              "type": "text",
              "value": "strongness",
              "position": {
                "start": {
                  "line": 1,
                  "column": 21
                },
                "end": {
                  "line": 1,
                  "column": 31
                }
              }
            }
          ],
          "position": {
            "start": {
              "line": 1,
              "column": 19
            },
            "end": {
              "line": 1,
              "column": 33
            }
          }
        },
        {
          "type": "text",
          "value": ", and ",
          "position": {
            "start": {
              "line": 1,
              "column": 33
            },
            "end": {
              "line": 1,
              "column": 39
            }
          }
        },
        {
          "type": "inlineCode",
          "value": "code",
          "position": {
            "start": {
              "line": 1,
              "column": 39
            },
            "end": {
              "line": 1,
              "column": 45
            }
          }
        },
        {
          "type": "text",
          "value": ".",
          "position": {
            "start": {
              "line": 1,
              "column": 45
            },
            "end": {
              "line": 1,
              "column": 46
            }
          }
        }
      ],
      "position": {
        "start": {
          "line": 1,
          "column": 1
        },
        "end": {
          "line": 1,
          "column": 46
        }
      }
    }
  ],
  "position": {
    "start": {
      "line": 1,
      "column": 1
    },
    "end": {
      "line": 1,
      "column": 46
    }
  }
}

And passing that document into mdast.stringify:

var doc = mdast.stringify(ast);

Yields:

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

API

mdast.parse(value, options?)

Parameters:

• value (string) — Markdown document;
• options (Object, null, undefined) — Optional options:
  • gfm (boolean, default: true). See Github Flavoured Markdown;
  • tables (boolean, default: true). See Tables;
  • yaml (boolean, default: true). See YAML;
  • 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: An Object. See Nodes for the AST specification.

mdast.stringify(ast, options?)

Parameters:

• ast (Object) — An AST as returned by mdast.parse();
• options (Object) — Optional options:
  • 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: string ("~" 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: A string.

mdast.use(plugin)

Creates a version of mdast which uses the given plugin to modify the AST after mdast.parse() is invoked.

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 mdast 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, or change the mdast instance.

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 parser more than 3 megabytes of markdown per second, depending on how much markup v.s. plain text the document contains, and which language the document is in, that’s more than the entire works of Shakespeare, in under two seconds.

         benchmarks * 76 fixtures (total: 50Kb markdown)
 63 op/s » mdast.parse
145 op/s » mdast.stringify

License

MIT © Titus Wormer

This project was initially a fork of marked.

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