1 # remark-stringify [![Build Status][build-badge]][build-status] [![Coverage Status][coverage-badge]][coverage-status] [![Chat][chat-badge]][chat]
3 [Compiler][] for [**unified**][unified]. Stringifies an
4 [**MDAST**][mdast] syntax tree to markdown. Used in the [**remark**
5 processor][processor]. Can be [extended][extend] to change how
13 npm install remark-stringify
19 var unified = require('unified');
20 var createStream = require('unified-stream');
21 var parse = require('remark-parse');
22 var toc = require('remark-toc');
23 var stringify = require('remark-stringify');
25 var processor = unified()
32 incrementListMarker: false
36 .pipe(createStream(processor))
37 .pipe(process.stdout);
43 * [processor.use(stringify\[, options\])](#processorusestringify-options)
44 * [stringify.Compiler](#stringifycompiler)
45 * [Extending the Compiler](#extending-the-compiler)
46 * [Compiler#visitors](#compilervisitors)
47 * [function visitor(node\[, parent\])](#function-visitornode-parent)
52 ### `processor.use(stringify[, options])`
54 Configure the `processor` to stringify [**MDAST**][mdast] syntax trees
59 Options are passed directly, or passed later through [`processor.data()`][data].
63 Stringify with the required escapes for GFM compatible markdown (`boolean`,
66 * Escape pipes (`|`, for tables)
67 * Escape colons (`:`, for literal URLs)
68 * Escape tildes (`~`, for strike-through)
70 ###### `options.commonmark`
72 Stringify for CommonMark compatible markdown (`boolean`, default: `false`).
74 * Compile adjacent blockquotes separately
75 * Escape more characters using slashes, instead of as entities
77 ###### `options.pedantic`
79 Stringify for pedantic compatible markdown (`boolean`, default: `false`).
81 * Escape underscores in words
83 ###### `options.entities`
85 How to stringify entities (`string` or `boolean`, default: `false`):
87 * `true` — Entities are generated for special HTML characters
88 (`&` > `&`) and non-ASCII characters (`©` > `©`).
89 If named entities are not (widely) supported, numbered character
90 references are used (`’` > `’`)
91 * `'numbers'` — Numbered entities are generated (`&` > `&`)
92 for special HTML characters and non-ASCII characters
93 * `'escape'` — Special HTML characters are encoded (`&` >
94 `&`, `’` > `’`), non-ASCII characters not (ö persists)
96 ###### `options.setext`
98 Compile headings, when possible, in Setext-style (`boolean`, default: `false`).
99 Uses `=` for level one headings and `-` for level two headings. Other heading
100 levels are compiled as ATX (respecting `closeAtx`).
102 ###### `options.closeAtx`
104 Compile ATX headings with the same amount of closing hashes as opening hashes
105 (`boolean`, default: `false`).
107 ###### `options.looseTable`
109 Create tables without fences: initial and final pipes (`boolean`, default:
112 ###### `options.spacedTable`
114 Create tables without spacing between pipes and content (`boolean`, default:
117 ###### `options.paddedTable`
119 Create tables with padding in each cell so that they are the same size
120 (`boolean`, default: `true`).
122 ###### `options.stringLength`
124 Function passed to [`markdown-table`][markdown-table] to detect the length of a
125 table cell (`Function`, default: [`s => s.length`][string-length]).
127 ###### `options.fence`
129 Fence marker to use for code blocks (`'~'` or ``'`'``, default: ``'`'``).
131 ###### `options.fences`
133 Stringify code blocks without language with fences (`boolean`, default:
136 ###### `options.bullet`
138 Bullet marker to use for unordered list items (`'-'`, `'*'`, or `'+'`,
141 ###### `options.listItemIndent`
143 How to indent the content from list items (`'tab'`, `'mixed'` or `'1'`,
146 * `'tab'`: use tab stops (4 spaces)
147 * `'1'`: use one space
148 * `'mixed'`: use `1` for tight and `tab` for loose list items
150 ###### `options.incrementListMarker`
152 Whether to increment ordered list item bullets (`boolean`, default: `true`).
154 ###### `options.rule`
156 Marker to use for thematic breaks / horizontal rules (`'-'`, `'*'`, or `'_'`,
159 ###### `options.ruleRepetition`
161 Number of markers to use for thematic breaks / horizontal rules (`number`,
162 default: `3`). Should be `3` or more.
164 ###### `options.ruleSpaces`
166 Whether to pad thematic break (horizontal rule) markers with spaces (`boolean`,
169 ###### `options.strong`
171 Marker to use for importance (`'_'` or `'*'`, default `'*'`).
173 ###### `options.emphasis`
175 Marker to use for emphasis (`'_'` or `'*'`, default `'_'`).
177 ### `stringify.Compiler`
179 Access to the raw [compiler][], if you need it.
181 ## Extending the Compiler
183 If this plug-in is used, it adds a [`Compiler`][compiler] constructor
184 to the `processor`. Other plug-ins can change and add visitors on
185 the compiler’s prototype to change how markdown is stringified.
187 The below plug-in modifies a [visitor][] to add an extra blank line
188 before level two headings.
191 module.exports = gap;
194 var Compiler = this.Compiler;
195 var visitors = Compiler.prototype.visitors;
196 var heading = visitors.heading;
198 visitors.heading = heading;
200 function heading(node) {
201 return (node.depth === 2 ? '\n' : '') + heading.apply(this, arguments);
206 ### `Compiler#visitors`
208 An object mapping [node][] types to [`visitor`][visitor]s.
210 ### `function visitor(node[, parent])`
216 * `node` ([`Node`][node]) — Node to compile
217 * `parent` ([`Node`][node], optional) — Parent of `node`
221 `string`, the compiled given `node`.
225 [MIT][license] © [Titus Wormer][author]
229 [build-badge]: https://img.shields.io/travis/wooorm/remark.svg
231 [build-status]: https://travis-ci.org/wooorm/remark
233 [coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/remark.svg
235 [coverage-status]: https://codecov.io/github/wooorm/remark
237 [chat-badge]: https://img.shields.io/gitter/room/wooorm/remark.svg
239 [chat]: https://gitter.im/wooorm/remark
241 [license]: https://github.com/wooorm/remark/blob/master/LICENSE
243 [author]: http://wooorm.com
245 [npm]: https://docs.npmjs.com/cli/install
247 [unified]: https://github.com/wooorm/unified
249 [processor]: https://github.com/wooorm/remark
251 [data]: https://github.com/unifiedjs/unified#processordatakey-value
253 [compiler]: https://github.com/wooorm/unified#processorcompiler
255 [mdast]: https://github.com/wooorm/mdast
257 [node]: https://github.com/wooorm/unist#node
259 [extend]: #extending-the-compiler
261 [visitor]: #function-visitornode-parent
263 [markdown-table]: https://github.com/wooorm/markdown-table
265 [string-length]: https://github.com/wooorm/markdown-table#stringlengthcell