--- /dev/null
+# remark-parse [![Build Status][build-badge]][build-status] [![Coverage Status][coverage-badge]][coverage-status] [![Chat][chat-badge]][chat]
+
+[Parser][] for [**unified**][unified]. Parses markdown to an
+[**MDAST**][mdast] syntax tree. Used in the [**remark**
+processor][processor]. Can be [extended][extend] to change how
+markdown is parsed.
+
+## Installation
+
+[npm][]:
+
+```sh
+npm install remark-parse
+```
+
+## Usage
+
+```js
+var unified = require('unified');
+var createStream = require('unified-stream');
+var markdown = require('remark-parse');
+var html = require('remark-html');
+
+var processor = unified()
+ .use(markdown, {commonmark: true})
+ .use(html)
+
+process.stdin
+ .pipe(createStream(processor))
+ .pipe(process.stdout);
+```
+
+## Table of Contents
+
+* [API](#api)
+ * [processor.use(parse\[, options\])](#processoruseparse-options)
+ * [parse.Parser](#parseparser)
+* [Extending the Parser](#extending-the-parser)
+ * [Parser#blockTokenizers](#parserblocktokenizers)
+ * [Parser#blockMethods](#parserblockmethods)
+ * [Parser#inlineTokenizers](#parserinlinetokenizers)
+ * [Parser#inlineMethods](#parserinlinemethods)
+ * [function tokenizer(eat, value, silent)](#function-tokenizereat-value-silent)
+ * [tokenizer.locator(value, fromIndex)](#tokenizerlocatorvalue-fromindex)
+ * [eat(subvalue)](#eatsubvalue)
+ * [add(node\[, parent\])](#addnode-parent)
+ * [add.test()](#addtest)
+ * [add.reset(node\[, parent\])](#addresetnode-parent)
+ * [Turning off a tokenizer](#turning-off-a-tokenizer)
+* [License](#license)
+
+## API
+
+### `processor.use(parse[, options])`
+
+Configure the `processor` to read markdown as input and process an
+[**MDAST**][mdast] syntax tree.
+
+##### `options`
+
+Options are passed directly, or passed later through [`processor.data()`][data].
+
+##### `options.gfm`
+
+```md
+hello ~~hi~~ world
+```
+
+GFM mode (`boolean`, default: `true`) turns on:
+
+* [Fenced code blocks](https://help.github.com/articles/github-flavored-markdown/#fenced-code-blocks)
+* [Autolinking of URLs](https://help.github.com/articles/github-flavored-markdown/#url-autolinking)
+* [Deletions (strikethrough)](https://help.github.com/articles/github-flavored-markdown/#strikethrough)
+* [Task lists](https://help.github.com/articles/writing-on-github/#task-lists)
+* [Tables](https://help.github.com/articles/github-flavored-markdown/#tables)
+
+##### `options.commonmark`
+
+```md
+This is a paragraph
+ and this is also part of the preceding paragraph.
+```
+
+CommonMark mode (`boolean`, default: `false`) allows:
+
+* Empty lines to split blockquotes
+* Parentheses (`(` and `)`) around for link and image titles
+* Any escaped [ASCII-punctuation][escapes] character
+* Closing parenthesis (`)`) as an ordered list marker
+* URL definitions (and footnotes, when enabled) in blockquotes
+
+CommonMark mode disallows:
+
+* Code directly following a paragraph
+* ATX-headings (`# Hash headings`) without spacing after opening hashes
+ or and before closing hashes
+* Setext headings (`Underline headings\n---`) when following a paragraph
+* Newlines in link and image titles
+* White space in link and image URLs in auto-links (links in brackets,
+ `<` and `>`)
+* Lazy blockquote continuation, lines not preceded by a closing angle
+ bracket (`>`), for lists, code, and thematicBreak
+
+##### `options.footnotes`
+
+```md
+Something something[^or something?].
+
+And something else[^1].
+
+[^1]: This reference footnote contains a paragraph...
+
+ * ...and a list
+```
+
+Footnotes mode (`boolean`, default: `false`) enables reference footnotes and
+inline footnotes. Both are wrapped in square brackets and preceded by a caret
+(`^`), and can be referenced from inside other footnotes.
+
+##### `options.blocks`
+
+```md
+<block>foo
+</block>
+```
+
+Blocks (`Array.<string>`, default: list of [block HTML elements][blocks])
+exposes let’s users define block-level HTML elements.
+
+##### `options.pedantic`
+
+```md
+Check out some_file_name.txt
+```
+
+Pedantic mode (`boolean`, default: `false`) turns on:
+
+* Emphasis (`_alpha_`) and importance (`__bravo__`) with underscores
+ in words
+* Unordered lists with different markers (`*`, `-`, `+`)
+* If `commonmark` is also turned on, ordered lists with different
+ markers (`.`, `)`)
+* And pedantic mode removes less spaces in list-items (at most four,
+ instead of the whole indent)
+
+### `parse.Parser`
+
+Access to the [parser][], if you need it.
+
+## Extending the Parser
+
+Most often, using transformers to manipulate a syntax tree produces
+the desired output. Sometimes, mainly when introducing new syntactic
+entities with a certain level of precedence, interfacing with the parser
+is necessary.
+
+If the `remark-parse` plug-in is used, it adds a [`Parser`][parser] constructor
+to the `processor`. Other plug-ins can add tokenizers to the parser’s prototype
+to change how markdown is parsed.
+
+The below plug-in adds a [tokenizer][] for at-mentions.
+
+```js
+module.exports = mentions;
+
+function mentions() {
+ var Parser = this.Parser;
+ var tokenizers = Parser.prototype.inlineTokenizers;
+ var methods = Parser.prototype.inlineMethods;
+
+ /* Add an inline tokenizer (defined in the following example). */
+ tokenizers.mention = tokenizeMention;
+
+ /* Run it just before `text`. */
+ methods.splice(methods.indexOf('text'), 0, 'mention');
+}
+```
+
+### `Parser#blockTokenizers`
+
+An object mapping tokenizer names to [tokenizer][]s. These
+tokenizers (for example: `fencedCode`, `table`, and `paragraph`) eat
+from the start of a value to a line ending.
+
+### `Parser#blockMethods`
+
+Array of `blockTokenizers` names (`string`) specifying the order in
+which they run.
+
+### `Parser#inlineTokenizers`
+
+An object mapping tokenizer names to [tokenizer][]s. These tokenizers
+(for example: `url`, `reference`, and `emphasis`) eat from the start
+of a value. To increase performance, they depend on [locator][]s.
+
+### `Parser#inlineMethods`
+
+Array of `inlineTokenizers` names (`string`) specifying the order in
+which they run.
+
+### `function tokenizer(eat, value, silent)`
+
+```js
+tokenizeMention.notInLink = true;
+tokenizeMention.locator = locateMention;
+
+function tokenizeMention(eat, value, silent) {
+ var match = /^@(\w+)/.exec(value);
+
+ if (match) {
+ if (silent) {
+ return true;
+ }
+
+ return eat(match[0])({
+ type: 'link',
+ url: 'https://social-network/' + match[1],
+ children: [{type: 'text', value: match[0]}]
+ });
+ }
+}
+```
+
+The parser knows two types of tokenizers: block level and inline level.
+Block level tokenizers are the same as inline level tokenizers, with
+the exception that the latter must have a [locator][].
+
+Tokenizers _test_ whether a document starts with a certain syntactic
+entity. In _silent_ mode, they return whether that test passes.
+In _normal_ mode, they consume that token, a process which is called
+“eating”. Locators enable tokenizers to function faster by providing
+information on where the next entity may occur.
+
+###### Signatures
+
+* `Node? = tokenizer(eat, value)`
+* `boolean? = tokenizer(eat, value, silent)`
+
+###### Parameters
+
+* `eat` ([`Function`][eat]) — Eat, when applicable, an entity
+* `value` (`string`) — Value which may start an entity
+* `silent` (`boolean`, optional) — Whether to detect or consume
+
+###### Properties
+
+* `locator` ([`Function`][locator])
+ — Required for inline tokenizers
+* `onlyAtStart` (`boolean`)
+ — Whether nodes can only be found at the beginning of the document
+* `notInBlock` (`boolean`)
+ — Whether nodes cannot be in blockquotes, lists, or footnote
+ definitions
+* `notInList` (`boolean`)
+ — Whether nodes cannot be in lists
+* `notInLink` (`boolean`)
+ — Whether nodes cannot be in links
+
+###### Returns
+
+* In _silent_ mode, whether a node can be found at the start of `value`
+* In _normal_ mode, a node if it can be found at the start of `value`
+
+### `tokenizer.locator(value, fromIndex)`
+
+```js
+function locateMention(value, fromIndex) {
+ return value.indexOf('@', fromIndex);
+}
+```
+
+Locators are required for inline tokenization to keep the process
+performant. Locators enable inline tokenizers to function faster by
+providing information on the where the next entity occurs. Locators
+may be wrong, it’s OK if there actually isn’t a node to be found at
+the index they return, but they must skip any nodes.
+
+###### Parameters
+
+* `value` (`string`) — Value which may contain an entity
+* `fromIndex` (`number`) — Position to start searching at
+
+###### Returns
+
+Index at which an entity may start, and `-1` otherwise.
+
+### `eat(subvalue)`
+
+```js
+var add = eat('foo');
+```
+
+Eat `subvalue`, which is a string at the start of the
+[tokenize][tokenizer]d `value` (it’s tracked to ensure the correct
+value is eaten).
+
+###### Parameters
+
+* `subvalue` (`string`) - Value to eat.
+
+###### Returns
+
+[`add`][add].
+
+### `add(node[, parent])`
+
+```js
+var add = eat('foo');
+add({type: 'text', value: 'foo'});
+```
+
+Add [positional information][location] to `node` and add it to `parent`.
+
+###### Parameters
+
+* `node` ([`Node`][node]) - Node to patch position on and insert
+* `parent` ([`Node`][node], optional) - Place to add `node` to in
+ the syntax tree. Defaults to the currently processed node
+
+###### Returns
+
+The given `node`.
+
+### `add.test()`
+
+Get the [positional information][location] which would be patched on
+`node` by `add`.
+
+###### Returns
+
+[`Location`][location].
+
+### `add.reset(node[, parent])`
+
+`add`, but resets the internal location. Useful for example in
+lists, where the same content is first eaten for a list, and later
+for list items
+
+###### Parameters
+
+* `node` ([`Node`][node]) - Node to patch position on and insert
+* `parent` ([`Node`][node], optional) - Place to add `node` to in
+ the syntax tree. Defaults to the currently processed node
+
+###### Returns
+
+The given `node`.
+
+### Turning off a tokenizer
+
+In rare situations, you may want to turn off a tokenizer to avoid parsing
+that syntactic feature. This can be done by deleting the tokenzier from
+your Parser’s `blockTokenizers` (or `blockMethods`) or `inlineTokenizers`
+(or `inlineMethods`).
+
+The following example turns off indented code blocks:
+
+```js
+delete remarkParse.Parser.prototype.blockTokenizers.indentedCode;
+```
+
+## License
+
+[MIT][license] © [Titus Wormer][author]
+
+<!-- Definitions -->
+
+[build-badge]: https://img.shields.io/travis/wooorm/remark.svg
+
+[build-status]: https://travis-ci.org/wooorm/remark
+
+[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/remark.svg
+
+[coverage-status]: https://codecov.io/github/wooorm/remark
+
+[chat-badge]: https://img.shields.io/gitter/room/wooorm/remark.svg
+
+[chat]: https://gitter.im/wooorm/remark
+
+[license]: https://github.com/wooorm/remark/blob/master/LICENSE
+
+[author]: http://wooorm.com
+
+[npm]: https://docs.npmjs.com/cli/install
+
+[unified]: https://github.com/wooorm/unified
+
+[data]: https://github.com/unifiedjs/unified#processordatakey-value
+
+[processor]: https://github.com/wooorm/remark/blob/master/packages/remark
+
+[mdast]: https://github.com/wooorm/mdast
+
+[escapes]: http://spec.commonmark.org/0.25/#backslash-escapes
+
+[node]: https://github.com/wooorm/unist#node
+
+[location]: https://github.com/wooorm/unist#location
+
+[parser]: https://github.com/wooorm/unified#processorparser
+
+[extend]: #extending-the-parser
+
+[tokenizer]: #function-tokenizereat-value-silent
+
+[locator]: #tokenizerlocatorvalue-fromindex
+
+[eat]: #eatsubvalue
+
+[add]: #addnode-parent
+
+[blocks]: https://github.com/wooorm/remark/blob/master/packages/remark-parse/lib/block-elements.json
projects / dotfiles / .git / blobdiff