Introduction

mdast parses and compiles markdown. It lets programs process markdown without ever compiling to HTML (it can though) by creating a syntax tree. This enables code analysis (e.g., mdast-lint), code transformation (e.g., mdast-toc), and code generation (built in).

It aims to do for markdown what esprima did for javascript and PostCSS for css: bring markdown into the tooling age.

mdast has lots of tests (800+), great coverage (100%), a free license, sensible code style (eslint, jscs), internal documentation, and man pages.

GitHub »

Demo »

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 plug-ins in a beautiful fashion.

Settings and plug-ins can be provided through cascading configuration files (.mdastrc or an "mdast" property in package.json files).

CLI docs »

API

Require dependencies:

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

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

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

Parse, modify, and stringify the document:

const doc = processor.process(`---
mdast:
  commonmark: true
---

2) Some *emphasis*, **strongness**, and `code`.
`);

Yields:

---
mdast:
  commonmark: true
---

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

---

The Application Programming Interface is the gist of mdast and the CLI. The API allows advanced markdown processing through several parsing and stringification settings.

mdast understand multiple flavours of markdown (GitHub Flavoured, CommonMark, and more) and generates documents based on provided style settings (list bullets, syntax markers, indentation, and more).

API docs »

Plug-ins

Plug-ins are the core of mdast. As noted earlier, they analyse, transform, configure, and generate documents based on given settings.

To use plugins on the CLI, use the --use or -u key:

npm install --global mdast mdast-lint
mdast --use mdast-lint example.md

In the API, use the use() function:

const mdast = require('mdast');
const lint = require('mdast-lint');
const processor = mdast().use(lint);

It’s also easy to create plug-ins yourself. Read how to do that in the docs.

Plug-in docs »