.config/coc/extensions/node_modules/coc-prettier/node_modules/remark-stringify/readme.md

   1 # remark-stringify [![Build Status][build-badge]][build-status] [![Coverage Status][coverage-badge]][coverage-status] [![Chat][chat-badge]][chat]
   2
   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
   6 markdown is compiled.
   7
   8 ## Installation
   9
  10 [npm][]:
  11
  12 ```sh
  13 npm install remark-stringify
  14 ```
  15
  16 ## Usage
  17
  18 ```js
  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');
  24
  25 var processor = unified()
  26   .use(parse)
  27   .use(toc)
  28   .use(stringify, {
  29     bullet: '*',
  30     fence: '~',
  31     fences: true,
  32     incrementListMarker: false
  33   });
  34
  35 process.stdin
  36   .pipe(createStream(processor))
  37   .pipe(process.stdout);
  38 ```
  39
  40 ## Table of Contents
  41
  42 *   [API](#api)
  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)
  48 *   [License](#license)
  49
  50 ## API
  51
  52 ### `processor.use(stringify[, options])`
  53
  54 Configure the `processor` to stringify [**MDAST**][mdast] syntax trees
  55 to markdown.
  56
  57 ##### `options`
  58
  59 Options are passed directly, or passed later through [`processor.data()`][data].
  60
  61 ###### `options.gfm`
  62
  63 Stringify with the required escapes for GFM compatible markdown (`boolean`,
  64 default: `true`).
  65
  66 *   Escape pipes (`|`, for tables)
  67 *   Escape colons (`:`, for literal URLs)
  68 *   Escape tildes (`~`, for strike-through)
  69
  70 ###### `options.commonmark`
  71
  72 Stringify for CommonMark compatible markdown (`boolean`, default: `false`).
  73
  74 *   Compile adjacent blockquotes separately
  75 *   Escape more characters using slashes, instead of as entities
  76
  77 ###### `options.pedantic`
  78
  79 Stringify for pedantic compatible markdown (`boolean`, default: `false`).
  80
  81 *   Escape underscores in words
  82
  83 ###### `options.entities`
  84
  85 How to stringify entities (`string` or `boolean`, default: `false`):
  86
  87 *   `true` — Entities are generated for special HTML characters
  88     (`&` > `&amp;`) and non-ASCII characters (`©` > `&copy;`).
  89     If named entities are not (widely) supported, numbered character
  90     references are used (`’` > `&#x2019;`)
  91 *   `'numbers'` — Numbered entities are generated (`&` > `&#x26;`)
  92     for special HTML characters and non-ASCII characters
  93 *   `'escape'` — Special HTML characters are encoded (`&` >
  94     `&amp;`, `’` > `&#x2019;`), non-ASCII characters not (ö persists)
  95
  96 ###### `options.setext`
  97
  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`).
 101
 102 ###### `options.closeAtx`
 103
 104 Compile ATX headings with the same amount of closing hashes as opening hashes
 105 (`boolean`, default: `false`).
 106
 107 ###### `options.looseTable`
 108
 109 Create tables without fences: initial and final pipes (`boolean`, default:
 110 `false`).
 111
 112 ###### `options.spacedTable`
 113
 114 Create tables without spacing between pipes and content (`boolean`, default:
 115 `true`).
 116
 117 ###### `options.paddedTable`
 118
 119 Create tables with padding in each cell so that they are the same size
 120 (`boolean`, default: `true`).
 121
 122 ###### `options.stringLength`
 123
 124 Function passed to [`markdown-table`][markdown-table] to detect the length of a
 125 table cell (`Function`, default: [`s => s.length`][string-length]).
 126
 127 ###### `options.fence`
 128
 129 Fence marker to use for code blocks (`'~'` or ``'`'``, default: ``'`'``).
 130
 131 ###### `options.fences`
 132
 133 Stringify code blocks without language with fences (`boolean`, default:
 134 `false`).
 135
 136 ###### `options.bullet`
 137
 138 Bullet marker to use for unordered list items (`'-'`, `'*'`, or `'+'`,
 139 default: `'-'`).
 140
 141 ###### `options.listItemIndent`
 142
 143 How to indent the content from list items (`'tab'`, `'mixed'` or `'1'`,
 144 default: `'tab'`).
 145
 146 *   `'tab'`: use tab stops (4 spaces)
 147 *   `'1'`: use one space
 148 *   `'mixed'`: use `1` for tight and `tab` for loose list items
 149
 150 ###### `options.incrementListMarker`
 151
 152 Whether to increment ordered list item bullets (`boolean`, default: `true`).
 153
 154 ###### `options.rule`
 155
 156 Marker to use for thematic breaks / horizontal rules (`'-'`, `'*'`, or `'_'`,
 157 default: `'*'`).
 158
 159 ###### `options.ruleRepetition`
 160
 161 Number of markers to use for thematic breaks / horizontal rules (`number`,
 162 default: `3`).  Should be `3` or more.
 163
 164 ###### `options.ruleSpaces`
 165
 166 Whether to pad thematic break (horizontal rule) markers with spaces (`boolean`,
 167 default `true`).
 168
 169 ###### `options.strong`
 170
 171 Marker to use for importance (`'_'` or `'*'`, default `'*'`).
 172
 173 ###### `options.emphasis`
 174
 175 Marker to use for emphasis (`'_'` or `'*'`, default `'_'`).
 176
 177 ### `stringify.Compiler`
 178
 179 Access to the raw [compiler][], if you need it.
 180
 181 ## Extending the Compiler
 182
 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.
 186
 187 The below plug-in modifies a [visitor][] to add an extra blank line
 188 before level two headings.
 189
 190 ```js
 191 module.exports = gap;
 192
 193 function gap() {
 194   var Compiler = this.Compiler;
 195   var visitors = Compiler.prototype.visitors;
 196   var heading = visitors.heading;
 197
 198   visitors.heading = heading;
 199
 200   function heading(node) {
 201     return (node.depth === 2 ? '\n' : '') + heading.apply(this, arguments);
 202   }
 203 }
 204 ```
 205
 206 ### `Compiler#visitors`
 207
 208 An object mapping [node][] types to [`visitor`][visitor]s.
 209
 210 ### `function visitor(node[, parent])`
 211
 212 Stringify `node`.
 213
 214 ###### Parameters
 215
 216 *   `node` ([`Node`][node]) — Node to compile
 217 *   `parent` ([`Node`][node], optional) — Parent of `node`
 218
 219 ###### Returns
 220
 221 `string`, the compiled given `node`.
 222
 223 ## License
 224
 225 [MIT][license] © [Titus Wormer][author]
 226
 227 <!-- Definitions -->
 228
 229 [build-badge]: https://img.shields.io/travis/wooorm/remark.svg
 230
 231 [build-status]: https://travis-ci.org/wooorm/remark
 232
 233 [coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/remark.svg
 234
 235 [coverage-status]: https://codecov.io/github/wooorm/remark
 236
 237 [chat-badge]: https://img.shields.io/gitter/room/wooorm/remark.svg
 238
 239 [chat]: https://gitter.im/wooorm/remark
 240
 241 [license]: https://github.com/wooorm/remark/blob/master/LICENSE
 242
 243 [author]: http://wooorm.com
 244
 245 [npm]: https://docs.npmjs.com/cli/install
 246
 247 [unified]: https://github.com/wooorm/unified
 248
 249 [processor]: https://github.com/wooorm/remark
 250
 251 [data]: https://github.com/unifiedjs/unified#processordatakey-value
 252
 253 [compiler]: https://github.com/wooorm/unified#processorcompiler
 254
 255 [mdast]: https://github.com/wooorm/mdast
 256
 257 [node]: https://github.com/wooorm/unist#node
 258
 259 [extend]: #extending-the-compiler
 260
 261 [visitor]: #function-visitornode-parent
 262
 263 [markdown-table]: https://github.com/wooorm/markdown-table
 264
 265 [string-length]: https://github.com/wooorm/markdown-table#stringlengthcell