1 | # ![mdast](https://cdn.rawgit.com/wooorm/mdast/master/logo.svg)
|
2 |
|
3 | [![Build Status](https://img.shields.io/travis/wooorm/mdast.svg?style=flat)](https://travis-ci.org/wooorm/mdast) [![Coverage Status](https://img.shields.io/coveralls/wooorm/mdast.svg?style=flat)](https://coveralls.io/r/wooorm/mdast?branch=master)
|
4 |
|
5 | **mdast** is a markdown processor powered by plugins. Lots of tests. Node,
|
6 | io.js, and the browser. 100% coverage.
|
7 |
|
8 | **mdast** is not just another markdown to HTML compiler. It can generate,
|
9 | and reformat, markdown too. It’s powered by [plugins](doc/plugins.md) to do
|
10 | all kinds of things: [validate your markdown](https://github.com/wooorm/mdast-lint),
|
11 | [add links for GitHub references](https://github.com/wooorm/mdast-github), or
|
12 | [add a table of contents](https://github.com/wooorm/mdast-toc).
|
13 |
|
14 | The project contains both an extensive [JavaScript API](doc/mdast.3.md) for
|
15 | parsing, modifying, and stringifying markdown, and a friendly [Command Line
|
16 | Interface](doc/mdast.1.md) making it easy to validate, prepare, and compile
|
17 | markdown in a build step.
|
18 |
|
19 | ## Table of Contents
|
20 |
|
21 | * [Installation](#installation)
|
22 |
|
23 | * [Usage](#usage)
|
24 |
|
25 | * [API](#api)
|
26 |
|
27 | * [mdast.process(value, options?, done?)](#mdastprocessvalue-options-done)
|
28 | * [mdast.use(plugin, options?)](#mdastuseplugin-options)
|
29 |
|
30 | * [CLI](#cli)
|
31 |
|
32 | * [Benchmark](#benchmark)
|
33 |
|
34 | * [License](#license)
|
35 |
|
36 | ## Installation
|
37 |
|
38 | [npm](https://docs.npmjs.com/cli/install):
|
39 |
|
40 | ```bash
|
41 | npm install mdast
|
42 | ```
|
43 |
|
44 | [Component.js](https://github.com/componentjs/component):
|
45 |
|
46 | ```bash
|
47 | component install wooorm/mdast
|
48 | ```
|
49 |
|
50 | [Bower](http://bower.io/#install-packages):
|
51 |
|
52 | ```bash
|
53 | bower install mdast
|
54 | ```
|
55 |
|
56 | [Duo](http://duojs.org/#getting-started):
|
57 |
|
58 | ```javascript
|
59 | var mdast = require('wooorm/mdast');
|
60 | ```
|
61 |
|
62 | UMD (globals/AMD/CommonJS) ([uncompressed](mdast.js) and
|
63 | [compressed](mdast.min.js)):
|
64 |
|
65 | ```html
|
66 | <script src="path/to/mdast.js" charset="utf-8"></script>
|
67 | <script>
|
68 | mdast.process('*hello* __world__'); // _hello_ **world**
|
69 | </script>
|
70 | ```
|
71 |
|
72 | ## Usage
|
73 |
|
74 | ```javascript
|
75 | var mdast = require('mdast');
|
76 | var yamlConfig = require('mdast-yaml-config');
|
77 | ```
|
78 |
|
79 | Use a plugin. mdast-yaml-config allows settings in YAML frontmatter.
|
80 |
|
81 | ```javascript
|
82 | var processor = mdast().use(yamlConfig);
|
83 | ```
|
84 |
|
85 | Parse, modify, and stringify the document:
|
86 |
|
87 | ```javascript
|
88 | var doc = processor.process(
|
89 | '---\n' +
|
90 | 'mdast:\n' +
|
91 | ' commonmark: true\n' +
|
92 | '---\n' +
|
93 | '\n' +
|
94 | '2) Some *emphasis*, **strongness**, and `code`.\n'
|
95 | );
|
96 | ```
|
97 |
|
98 | Yields:
|
99 |
|
100 | ```markdown
|
101 | ---
|
102 | mdast:
|
103 | commonmark: true
|
104 | ---
|
105 |
|
106 | 2. Some _emphasis_, **strongness**, and `code`.
|
107 | ```
|
108 |
|
109 | ## API
|
110 |
|
111 | This section only covers the interface you’ll use most often. See
|
112 | [mdast(3) documentation](doc/mdast.3.md) for a more complete description:
|
113 |
|
114 | * [mdast.parse(file, options?)](doc/mdast.3.md#mdastparsefile-options)
|
115 | — Parses markdown into an abstract syntax tree;
|
116 |
|
117 | * [mdast.run(ast, file, done?)](doc/mdast.3.md#mdastrunast-file-done)
|
118 | — Applies plugins to the syntax tree;
|
119 |
|
120 | * [mdast.stringify(ast, options?)](doc/mdast.3.md#mdaststringifyast-options)
|
121 | — Compiles the syntax tree into a string;
|
122 |
|
123 | * [mdast.process(file, options?, done?)](doc/mdast.3.md#mdastprocessfile-options-done)
|
124 | — More detailed than [below](#mdastprocessvalue-options-done);
|
125 |
|
126 | * [mdast.use(plugin, options?)](doc/mdast.3.md#mdastuseplugin-options)
|
127 | — More detailed than [below](#mdastuseplugin-options);
|
128 |
|
129 | * [function done(err?, doc?, file?)](doc/mdast.3.md#function-doneerr-doc-file)
|
130 | — Callback passed to `run()` and `process()`.
|
131 |
|
132 | * [File()](doc/mdast.3.md#file)
|
133 | — Wrapper around (virtual) files.
|
134 |
|
135 | ### [mdast](#api).process(value, [options](doc/options.md)?, done?)
|
136 |
|
137 | Parse a markdown document, apply plugins to it, and compile it into
|
138 | something else.
|
139 |
|
140 | **Signatures**
|
141 |
|
142 | * `doc = mdast.process(value, options?, done?)`.
|
143 |
|
144 | **Parameters**
|
145 |
|
146 | * `value` (`string`) — Markdown document;
|
147 |
|
148 | * `options` (`Object`) — Settings:
|
149 |
|
150 | * `gfm` (`boolean`, default: `true`) — See [Github Flavoured Markdown](doc/options.md#github-flavoured-markdown);
|
151 | * `yaml` (`boolean`, default: `true`) — See [YAML](doc/options.md#yaml);
|
152 | * `commonmark` (`boolean`, default: `false`) — See [CommonMark](doc/options.md#commonmark);
|
153 | * `footnotes` (`boolean`, default: `false`) — See [Footnotes](doc/options.md#footnotes);
|
154 | * `pedantic` (`boolean`, default: `false`) — See [Pedantic](doc/options.md#pedantic);
|
155 | * `breaks` (`boolean`, default: `false`) — See [Breaks](doc/options.md#breaks);
|
156 | * `entities` (`boolean`, default: `false`) — See [Encoding Entities](doc/options.md#encoding-entities);
|
157 | * `setext` (`boolean`, default: `false`) — See [Setext Headings](doc/options.md#setext-headings);
|
158 | * `closeAtx` (`boolean`, default: `false`) — See [Closed ATX Headings](doc/options.md#closed-atx-headings);
|
159 | * `looseTable` (`boolean`, default: `false`) — See [Loose Tables](doc/options.md#loose-tables);
|
160 | * `spacedTable` (`boolean`, default: `true`) — See [Spaced Tables](doc/options.md#spaced-tables);
|
161 | * `fence` (`"~"` or ``"`"``, default: ``"`"``) — See [Fence](doc/options.md#fence);
|
162 | * `fences` (`boolean`, default: `false`) — See [Fences](doc/options.md#fences);
|
163 | * `bullet` (`"-"`, `"*"`, or `"+"`, default: `"-"`) — See [List Item Bullets](doc/options.md#list-item-bullets);
|
164 | * `listItemIndent` (`"tab"`, `"mixed"` or `"1"`, default: `"tab"`) — See [List Item Indent](doc/options.md#list-item-indent);
|
165 | * `incrementListMarker` (`boolean`, default: `true`) — See [List Marker Increase](doc/options.md#list-marker-increasement);
|
166 | * `rule` (`"-"`, `"*"`, or `"_"`, default: `"*"`) — See [Horizontal Rules](doc/options.md#horizontal-rules);
|
167 | * `ruleRepetition` (`number`, default: `3`) — See [Horizontal Rules](doc/options.md#horizontal-rules);
|
168 | * `ruleSpaces` (`boolean`, default `true`) — See [Horizontal Rules](doc/options.md#horizontal-rules);
|
169 | * `strong` (`"_"`, or `"*"`, default `"*"`) — See [Emphasis Markers](doc/options.md#emphasis-markers);
|
170 | * `emphasis` (`"_"`, or `"*"`, default `"_"`) — See [Emphasis Markers](doc/options.md#emphasis-markers).
|
171 | * `position` (`boolean`, default: `true`) — See [Position](doc/options.md#position);
|
172 |
|
173 | * `done` (`function(Error?, string?)`) — Callback invoked when the output
|
174 | is generated with either an error, or a result. Only strictly needed when
|
175 | async plugins are used.
|
176 |
|
177 | All options (including the options object itself) can be `null` or `undefined`
|
178 | to default to their default values.
|
179 |
|
180 | **Returns**
|
181 |
|
182 | `string` or `null`: A document. Formatted in markdown by default, or in
|
183 | whatever a plugin generates.
|
184 | The result is `null` if a plugin is asynchronous, in which case the callback
|
185 | `done` should’ve been passed (don’t worry: plugin creators make sure you know
|
186 | its async).
|
187 |
|
188 | ### [mdast](#api).use([plugin](doc/plugins.md#plugin), options?)
|
189 |
|
190 | Change the way [`mdast`](#api) works by using a [`plugin`](doc/plugins.md).
|
191 |
|
192 | **Signatures**
|
193 |
|
194 | * `processor = mdast.use(plugin, options?)`;
|
195 | * `processor = mdast.use(plugins)`.
|
196 |
|
197 | **Parameters**
|
198 |
|
199 | * `plugin` (`Function`) — A [**Plugin**](doc/plugins.md);
|
200 |
|
201 | * `plugins` (`Array.<Function>`) — A list of [**Plugin**](doc/plugins.md)s;
|
202 |
|
203 | * `options` (`Object?`) — Passed to the plugin. Specified by its
|
204 | documentation.
|
205 |
|
206 | **Returns**
|
207 |
|
208 | `Object`: an instance of MDAST: The returned object functions just like
|
209 | **mdast** (it has the same methods), but caches the `use`d plugins. This
|
210 | provides the ability to chain `use` calls to use multiple plugins, but
|
211 | ensures the functioning of the **mdast** module does not change for other
|
212 | dependents.
|
213 |
|
214 | ## CLI
|
215 |
|
216 | Install:
|
217 |
|
218 | ```bash
|
219 | npm install --global mdast
|
220 | ```
|
221 |
|
222 | Use:
|
223 |
|
224 | ```text
|
225 | Usage: mdast [options] file|dir ...
|
226 |
|
227 | Markdown processor powered by plugins
|
228 |
|
229 | Options:
|
230 |
|
231 | -h, --help output usage information
|
232 | -V, --version output the version number
|
233 | -o, --output [path] specify output location
|
234 | -c, --config-path <path> specify configuration location
|
235 | -i, --ignore-path <path> specify ignore location
|
236 | -s, --setting <settings> specify settings
|
237 | -u, --use <plugins> use transform plugin(s)
|
238 | -e, --ext <extensions> specify extensions
|
239 | -a, --ast output AST information
|
240 | -q, --quiet output only warnings and errors
|
241 | -S, --silent output only errors
|
242 | --file-path <path> specify file path to process as
|
243 | --no-color disable color in output
|
244 | --no-rc disable configuration from .mdastrc
|
245 | --no-ignore disable ignore from .mdastignore
|
246 |
|
247 | Usage:
|
248 |
|
249 | # Pass `readme.md` through mdast
|
250 | $ mdast readme.md -o readme-new.md
|
251 |
|
252 | # Pass stdin through mdast, with settings, to stdout
|
253 | $ cat readme.md | mdast -s "setext: true, bullet: "*"" > readme-new.md
|
254 |
|
255 | # Use a plugin (with options)
|
256 | $ npm install mdast-toc
|
257 | $ mdast --use toc=heading:"contents" readme.md -o
|
258 |
|
259 | # Rewrite markdown in a directory
|
260 | $ mdast . -o
|
261 |
|
262 | See also:
|
263 |
|
264 | man 1 mdast, man 3 mdast, man 5 mdastrc, man 5 mdastignore, man 7 mdastconfig
|
265 | ```
|
266 |
|
267 | ## Benchmark
|
268 |
|
269 | On a MacBook Air, it parses ± 322Kb of markdown (in 214 documents) per second.
|
270 |
|
271 | ```text
|
272 | 214 fixtures (total: 80.62Kb)
|
273 | 4 op/s » mdast.parse w/ `gfm: true`, and `yaml: true`
|
274 | 69 op/s » mdast.stringify w/ `gfm: true`, and `yaml: true`
|
275 | 4 op/s » mdast.parse w/ `gfm: false`, and `yaml: false`
|
276 | 70 op/s » mdast.stringify w/ `gfm: false`, and `yaml: false`
|
277 | 4 op/s » mdast.parse w/ `gfm: true`, `yaml: true`, and `commonmark: true`
|
278 | 72 op/s » mdast.stringify w/ `gfm: true`, `yaml: true`, and `commonmark: true`
|
279 | ```
|
280 |
|
281 | ## License
|
282 |
|
283 | [MIT](LICENSE) © [Titus Wormer](http://wooorm.com)
|
284 |
|
285 | > This project was initially a fork of [marked](https://github.com/chjj/marked).
|
286 |
|
287 | Copyright (c) 2011-2014, Christopher Jeffrey. (MIT License)
|