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

   1 # remark-parse [![Build Status][build-badge]][build-status] [![Coverage Status][coverage-badge]][coverage-status] [![Chat][chat-badge]][chat]
   2
   3 [Parser][] for [**unified**][unified].  Parses markdown to an
   4 [**MDAST**][mdast] syntax tree.  Used in the [**remark**
   5 processor][processor].  Can be [extended][extend] to change how
   6 markdown is parsed.
   7
   8 ## Installation
   9
  10 [npm][]:
  11
  12 ```sh
  13 npm install remark-parse
  14 ```
  15
  16 ## Usage
  17
  18 ```js
  19 var unified = require('unified');
  20 var createStream = require('unified-stream');
  21 var markdown = require('remark-parse');
  22 var html = require('remark-html');
  23
  24 var processor = unified()
  25   .use(markdown, {commonmark: true})
  26   .use(html)
  27
  28 process.stdin
  29   .pipe(createStream(processor))
  30   .pipe(process.stdout);
  31 ```
  32
  33 ## Table of Contents
  34
  35 *   [API](#api)
  36     *   [processor.use(parse\[, options\])](#processoruseparse-options)
  37     *   [parse.Parser](#parseparser)
  38 *   [Extending the Parser](#extending-the-parser)
  39     *   [Parser#blockTokenizers](#parserblocktokenizers)
  40     *   [Parser#blockMethods](#parserblockmethods)
  41     *   [Parser#inlineTokenizers](#parserinlinetokenizers)
  42     *   [Parser#inlineMethods](#parserinlinemethods)
  43     *   [function tokenizer(eat, value, silent)](#function-tokenizereat-value-silent)
  44     *   [tokenizer.locator(value, fromIndex)](#tokenizerlocatorvalue-fromindex)
  45     *   [eat(subvalue)](#eatsubvalue)
  46     *   [add(node\[, parent\])](#addnode-parent)
  47     *   [add.test()](#addtest)
  48     *   [add.reset(node\[, parent\])](#addresetnode-parent)
  49     *   [Turning off a tokenizer](#turning-off-a-tokenizer)
  50 *   [License](#license)
  51
  52 ## API
  53
  54 ### `processor.use(parse[, options])`
  55
  56 Configure the `processor` to read markdown as input and process an
  57 [**MDAST**][mdast] syntax tree.
  58
  59 ##### `options`
  60
  61 Options are passed directly, or passed later through [`processor.data()`][data].
  62
  63 ##### `options.gfm`
  64
  65 ```md
  66 hello ~~hi~~ world
  67 ```
  68
  69 GFM mode (`boolean`, default: `true`) turns on:
  70
  71 *   [Fenced code blocks](https://help.github.com/articles/github-flavored-markdown/#fenced-code-blocks)
  72 *   [Autolinking of URLs](https://help.github.com/articles/github-flavored-markdown/#url-autolinking)
  73 *   [Deletions (strikethrough)](https://help.github.com/articles/github-flavored-markdown/#strikethrough)
  74 *   [Task lists](https://help.github.com/articles/writing-on-github/#task-lists)
  75 *   [Tables](https://help.github.com/articles/github-flavored-markdown/#tables)
  76
  77 ##### `options.commonmark`
  78
  79 ```md
  80 This is a paragraph
  81     and this is also part of the preceding paragraph.
  82 ```
  83
  84 CommonMark mode (`boolean`, default: `false`) allows:
  85
  86 *   Empty lines to split blockquotes
  87 *   Parentheses (`(` and `)`) around for link and image titles
  88 *   Any escaped [ASCII-punctuation][escapes] character
  89 *   Closing parenthesis (`)`) as an ordered list marker
  90 *   URL definitions (and footnotes, when enabled) in blockquotes
  91
  92 CommonMark mode disallows:
  93
  94 *   Code directly following a paragraph
  95 *   ATX-headings (`# Hash headings`) without spacing after opening hashes
  96     or and before closing hashes
  97 *   Setext headings (`Underline headings\n---`) when following a paragraph
  98 *   Newlines in link and image titles
  99 *   White space in link and image URLs in auto-links (links in brackets,
 100     `<` and `>`)
 101 *   Lazy blockquote continuation, lines not preceded by a closing angle
 102     bracket (`>`), for lists, code, and thematicBreak
 103
 104 ##### `options.footnotes`
 105
 106 ```md
 107 Something something[^or something?].
 108
 109 And something else[^1].
 110
 111 [^1]: This reference footnote contains a paragraph...
 112
 113     * ...and a list
 114 ```
 115
 116 Footnotes mode (`boolean`, default: `false`) enables reference footnotes and
 117 inline footnotes.  Both are wrapped in square brackets and preceded by a caret
 118 (`^`), and can be referenced from inside other footnotes.
 119
 120 ##### `options.blocks`
 121
 122 ```md
 123 <block>foo
 124 </block>
 125 ```
 126
 127 Blocks (`Array.<string>`, default: list of [block HTML elements][blocks])
 128 exposes let’s users define block-level HTML elements.
 129
 130 ##### `options.pedantic`
 131
 132 ```md
 133 Check out some_file_name.txt
 134 ```
 135
 136 Pedantic mode (`boolean`, default: `false`) turns on:
 137
 138 *   Emphasis (`_alpha_`) and importance (`__bravo__`) with underscores
 139     in words
 140 *   Unordered lists with different markers (`*`, `-`, `+`)
 141 *   If `commonmark` is also turned on, ordered lists with different
 142     markers (`.`, `)`)
 143 *   And pedantic mode removes less spaces in list-items (at most four,
 144     instead of the whole indent)
 145
 146 ### `parse.Parser`
 147
 148 Access to the [parser][], if you need it.
 149
 150 ## Extending the Parser
 151
 152 Most often, using transformers to manipulate a syntax tree produces
 153 the desired output.  Sometimes, mainly when introducing new syntactic
 154 entities with a certain level of precedence, interfacing with the parser
 155 is necessary.
 156
 157 If the `remark-parse` plug-in is used, it adds a [`Parser`][parser] constructor
 158 to the `processor`.  Other plug-ins can add tokenizers to the parser’s prototype
 159 to change how markdown is parsed.
 160
 161 The below plug-in adds a [tokenizer][] for at-mentions.
 162
 163 ```js
 164 module.exports = mentions;
 165
 166 function mentions() {
 167   var Parser = this.Parser;
 168   var tokenizers = Parser.prototype.inlineTokenizers;
 169   var methods = Parser.prototype.inlineMethods;
 170
 171   /* Add an inline tokenizer (defined in the following example). */
 172   tokenizers.mention = tokenizeMention;
 173
 174   /* Run it just before `text`. */
 175   methods.splice(methods.indexOf('text'), 0, 'mention');
 176 }
 177 ```
 178
 179 ### `Parser#blockTokenizers`
 180
 181 An object mapping tokenizer names to [tokenizer][]s.  These
 182 tokenizers (for example: `fencedCode`, `table`, and `paragraph`) eat
 183 from the start of a value to a line ending.
 184
 185 ### `Parser#blockMethods`
 186
 187 Array of `blockTokenizers` names (`string`) specifying the order in
 188 which they run.
 189
 190 ### `Parser#inlineTokenizers`
 191
 192 An object mapping tokenizer names to [tokenizer][]s.  These tokenizers
 193 (for example: `url`, `reference`, and `emphasis`) eat from the start
 194 of a value.  To increase performance, they depend on [locator][]s.
 195
 196 ### `Parser#inlineMethods`
 197
 198 Array of `inlineTokenizers` names (`string`) specifying the order in
 199 which they run.
 200
 201 ### `function tokenizer(eat, value, silent)`
 202
 203 ```js
 204 tokenizeMention.notInLink = true;
 205 tokenizeMention.locator = locateMention;
 206
 207 function tokenizeMention(eat, value, silent) {
 208   var match = /^@(\w+)/.exec(value);
 209
 210   if (match) {
 211     if (silent) {
 212       return true;
 213     }
 214
 215     return eat(match[0])({
 216       type: 'link',
 217       url: 'https://social-network/' + match[1],
 218       children: [{type: 'text', value: match[0]}]
 219     });
 220   }
 221 }
 222 ```
 223
 224 The parser knows two types of tokenizers: block level and inline level.
 225 Block level tokenizers are the same as inline level tokenizers, with
 226 the exception that the latter must have a [locator][].
 227
 228 Tokenizers _test_ whether a document starts with a certain syntactic
 229 entity.  In _silent_ mode, they return whether that test passes.
 230 In _normal_ mode, they consume that token, a process which is called
 231 “eating”.  Locators enable tokenizers to function faster by providing
 232 information on where the next entity may occur.
 233
 234 ###### Signatures
 235
 236 *   `Node? = tokenizer(eat, value)`
 237 *   `boolean? = tokenizer(eat, value, silent)`
 238
 239 ###### Parameters
 240
 241 *   `eat` ([`Function`][eat]) — Eat, when applicable, an entity
 242 *   `value` (`string`) — Value which may start an entity
 243 *   `silent` (`boolean`, optional) — Whether to detect or consume
 244
 245 ###### Properties
 246
 247 *   `locator` ([`Function`][locator])
 248     — Required for inline tokenizers
 249 *   `onlyAtStart` (`boolean`)
 250     — Whether nodes can only be found at the beginning of the document
 251 *   `notInBlock` (`boolean`)
 252     — Whether nodes cannot be in blockquotes, lists, or footnote
 253     definitions
 254 *   `notInList` (`boolean`)
 255     — Whether nodes cannot be in lists
 256 *   `notInLink` (`boolean`)
 257     — Whether nodes cannot be in links
 258
 259 ###### Returns
 260
 261 *   In _silent_ mode, whether a node can be found at the start of `value`
 262 *   In _normal_ mode, a node if it can be found at the start of `value`
 263
 264 ### `tokenizer.locator(value, fromIndex)`
 265
 266 ```js
 267 function locateMention(value, fromIndex) {
 268   return value.indexOf('@', fromIndex);
 269 }
 270 ```
 271
 272 Locators are required for inline tokenization to keep the process
 273 performant.  Locators enable inline tokenizers to function faster by
 274 providing information on the where the next entity occurs.  Locators
 275 may be wrong, it’s OK if there actually isn’t a node to be found at
 276 the index they return, but they must skip any nodes.
 277
 278 ###### Parameters
 279
 280 *   `value` (`string`) — Value which may contain an entity
 281 *   `fromIndex` (`number`) — Position to start searching at
 282
 283 ###### Returns
 284
 285 Index at which an entity may start, and `-1` otherwise.
 286
 287 ### `eat(subvalue)`
 288
 289 ```js
 290 var add = eat('foo');
 291 ```
 292
 293 Eat `subvalue`, which is a string at the start of the
 294 [tokenize][tokenizer]d `value` (it’s tracked to ensure the correct
 295 value is eaten).
 296
 297 ###### Parameters
 298
 299 *   `subvalue` (`string`) - Value to eat.
 300
 301 ###### Returns
 302
 303 [`add`][add].
 304
 305 ### `add(node[, parent])`
 306
 307 ```js
 308 var add = eat('foo');
 309 add({type: 'text', value: 'foo'});
 310 ```
 311
 312 Add [positional information][location] to `node` and add it to `parent`.
 313
 314 ###### Parameters
 315
 316 *   `node` ([`Node`][node]) - Node to patch position on and insert
 317 *   `parent` ([`Node`][node], optional) - Place to add `node` to in
 318     the syntax tree.  Defaults to the currently processed node
 319
 320 ###### Returns
 321
 322 The given `node`.
 323
 324 ### `add.test()`
 325
 326 Get the [positional information][location] which would be patched on
 327 `node` by `add`.
 328
 329 ###### Returns
 330
 331 [`Location`][location].
 332
 333 ### `add.reset(node[, parent])`
 334
 335 `add`, but resets the internal location.  Useful for example in
 336 lists, where the same content is first eaten for a list, and later
 337 for list items
 338
 339 ###### Parameters
 340
 341 *   `node` ([`Node`][node]) - Node to patch position on and insert
 342 *   `parent` ([`Node`][node], optional) - Place to add `node` to in
 343     the syntax tree.  Defaults to the currently processed node
 344
 345 ###### Returns
 346
 347 The given `node`.
 348
 349 ### Turning off a tokenizer
 350
 351 In rare situations, you may want to turn off a tokenizer to avoid parsing
 352 that syntactic feature.  This can be done by deleting the tokenzier from
 353 your Parser’s `blockTokenizers` (or `blockMethods`) or `inlineTokenizers`
 354 (or `inlineMethods`).
 355
 356 The following example turns off indented code blocks:
 357
 358 ```js
 359 delete remarkParse.Parser.prototype.blockTokenizers.indentedCode;
 360 ```
 361
 362 ## License
 363
 364 [MIT][license] © [Titus Wormer][author]
 365
 366 <!-- Definitions -->
 367
 368 [build-badge]: https://img.shields.io/travis/wooorm/remark.svg
 369
 370 [build-status]: https://travis-ci.org/wooorm/remark
 371
 372 [coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/remark.svg
 373
 374 [coverage-status]: https://codecov.io/github/wooorm/remark
 375
 376 [chat-badge]: https://img.shields.io/gitter/room/wooorm/remark.svg
 377
 378 [chat]: https://gitter.im/wooorm/remark
 379
 380 [license]: https://github.com/wooorm/remark/blob/master/LICENSE
 381
 382 [author]: http://wooorm.com
 383
 384 [npm]: https://docs.npmjs.com/cli/install
 385
 386 [unified]: https://github.com/wooorm/unified
 387
 388 [data]: https://github.com/unifiedjs/unified#processordatakey-value
 389
 390 [processor]: https://github.com/wooorm/remark/blob/master/packages/remark
 391
 392 [mdast]: https://github.com/wooorm/mdast
 393
 394 [escapes]: http://spec.commonmark.org/0.25/#backslash-escapes
 395
 396 [node]: https://github.com/wooorm/unist#node
 397
 398 [location]: https://github.com/wooorm/unist#location
 399
 400 [parser]: https://github.com/wooorm/unified#processorparser
 401
 402 [extend]: #extending-the-parser
 403
 404 [tokenizer]: #function-tokenizereat-value-silent
 405
 406 [locator]: #tokenizerlocatorvalue-fromindex
 407
 408 [eat]: #eatsubvalue
 409
 410 [add]: #addnode-parent
 411
 412 [blocks]: https://github.com/wooorm/remark/blob/master/packages/remark-parse/lib/block-elements.json