diff --git a/packages/remark-cli/readme.md b/packages/remark-cli/readme.md
index 9d05cefac..03c252f59 100644
--- a/packages/remark-cli/readme.md
+++ b/packages/remark-cli/readme.md
@@ -3,24 +3,19 @@
[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
-[![Chat][chat-badge]][chat]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
+[![Chat][chat-badge]][chat]
-Command-line interface for [**remark**][remark].
+Command line interface for [**remark**][remark].
* Loads [`remark-` plugins][plugins]
-* Searches for [markdown extensions][markdown-extensions]
+* Searches for [Markdown extensions][markdown-extensions]
* Ignores paths found in [`.remarkignore` files][ignore-file]
* Loads configuration from [`.remarkrc`, `.remarkrc.js` files][config-file]
* Uses configuration from [`remarkConfig` fields in `package.json`
files][config-file]
-* * *
-
-**Announcing the unified collective! 🎉
-[Read more about it on Medium »][announcement]**
-
## Sponsors
@@ -53,7 +48,9 @@ Command-line interface for [**remark**][remark].
-## Installation
+[**Read more about the unified collective on Medium »**][announcement]
+
+## Install
[npm][]:
@@ -61,7 +58,7 @@ Command-line interface for [**remark**][remark].
npm install remark-cli
```
-## Usage
+## Use
```sh
# Add a table of contents to `readme.md`
@@ -74,13 +71,13 @@ $ remark . --use preset-lint-markdown-style-guide
## CLI
-See [**unified-args**][unified-args], which provides the interface,
-for more information on all available options.
+See [`unified-args`][unified-args], which provides the interface, for more
+info on all available options.
```txt
Usage: remark [options] [path | glob ...]
- CLI to process markdown with remark using plugins
+ CLI to process Markdown with remark using plugins
Options:
@@ -119,6 +116,20 @@ Examples:
$ remark . -o
```
+## Contribute
+
+See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
+to get started.
+See [`support.md`][support] for ways to get help.
+Ideas for new plugins and tools can be posted in [`remarkjs/ideas`][ideas].
+
+A curated list of awesome remark resources can be found in [**awesome
+remark**][awesome].
+
+This project has a [Code of Conduct][coc].
+By interacting with this repository, organisation, or community you agree to
+abide by its terms.
+
## License
[MIT][license] © [Titus Wormer][author]
@@ -137,15 +148,27 @@ Examples:
[downloads]: https://www.npmjs.com/package/remark-cli
+[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
+
+[backers-badge]: https://opencollective.com/unified/backers/badge.svg
+
+[collective]: https://opencollective.com/unified
+
[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg
[chat]: https://spectrum.chat/unified/remark
-[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
+[health]: https://github.com/remarkjs/.github
-[backers-badge]: https://opencollective.com/unified/backers/badge.svg
+[contributing]: https://github.com/remarkjs/.github/blob/master/contributing.md
-[collective]: https://opencollective.com/unified
+[support]: https://github.com/remarkjs/.github/blob/master/support.md
+
+[coc]: https://github.com/remarkjs/.github/blob/master/code-of-conduct.md
+
+[ideas]: https://github.com/remarkjs/ideas
+
+[awesome]: https://github.com/remarkjs/awesome-remark
[license]: https://github.com/remarkjs/remark/blob/master/license
diff --git a/packages/remark-cli/test.js b/packages/remark-cli/test.js
index 4c06a0994..d0fd42102 100644
--- a/packages/remark-cli/test.js
+++ b/packages/remark-cli/test.js
@@ -20,7 +20,7 @@ test('remark-cli', function(t) {
[
'Usage: remark [options] [path | glob ...]',
'',
- ' CLI to process markdown with remark using plugins',
+ ' CLI to process Markdown with remark using plugins',
'',
'Options:',
'',
diff --git a/packages/remark-parse/readme.md b/packages/remark-parse/readme.md
index f997a258e..494c59e38 100644
--- a/packages/remark-parse/readme.md
+++ b/packages/remark-parse/readme.md
@@ -4,21 +4,15 @@
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
-[![Chat][chat-badge]][chat]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
+[![Chat][chat-badge]][chat]
[Parser][] for [**unified**][unified].
-Parses markdown to [**mdast**][mdast] syntax trees.
-Used in the [**remark** processor][processor] but can be used on its own as
-well.
+Parses Markdown to [**mdast**][mdast] syntax trees.
+Used in the [**remark** processor][remark] but can be used on its own as well.
Can be [extended][extend] to change how markdown is parsed.
-* * *
-
-**Announcing the unified collective! 🎉
-[Read more about it on Medium »][announcement]**
-
## Sponsors
@@ -51,7 +45,9 @@ Can be [extended][extend] to change how markdown is parsed.
-## Installation
+[**Read more about the unified collective on Medium »**][announcement]
+
+## Install
[npm][]:
@@ -59,16 +55,18 @@ Can be [extended][extend] to change how markdown is parsed.
npm install remark-parse
```
-## Usage
+## Use
```js
var unified = require('unified')
var createStream = require('unified-stream')
var markdown = require('remark-parse')
-var html = require('remark-html')
+var remark2rehype = require('remark-rehype')
+var html = require('rehype-stringify')
var processor = unified()
.use(markdown, {commonmark: true})
+ .use(remark2rehype)
.use(html)
process.stdin.pipe(createStream(processor)).pipe(process.stdout)
@@ -77,7 +75,7 @@ process.stdin.pipe(createStream(processor)).pipe(process.stdout)
## Table of Contents
* [API](#api)
- * [processor.use(parse\[, options\])](#processoruseparse-options)
+ * [processor().use(parse\[, options\])](#processoruseparse-options)
* [parse.Parser](#parseparser)
* [Extending the Parser](#extending-the-parser)
* [Parser#blockTokenizers](#parserblocktokenizers)
@@ -91,26 +89,32 @@ process.stdin.pipe(createStream(processor)).pipe(process.stdout)
* [add.test()](#addtest)
* [add.reset(node\[, parent\])](#addresetnode-parent)
* [Turning off a tokenizer](#turning-off-a-tokenizer)
+* [Contribute](#contribute)
* [License](#license)
## API
-### `processor.use(parse[, options])`
+[See **unified** for API docs »][unified]
+
+### `processor().use(parse[, options])`
-Configure the `processor` to read markdown as input and process
+Configure the `processor` to read Markdown as input and process
[**mdast**][mdast] syntax trees.
##### `options`
-Options are passed directly, or passed later through [`processor.data()`][data].
+Options can be passed directly, or passed later through
+[`processor.data()`][data].
+
+###### `options.gfm`
-##### `options.gfm`
+GFM mode (`boolean`, default: `true`).
-```md
+```markdown
hello ~~hi~~ world
```
-GFM mode (`boolean`, default: `true`) turns on:
+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)
@@ -118,36 +122,40 @@ GFM mode (`boolean`, default: `true`) turns on:
* [Task lists](https://help.github.com/articles/writing-on-github/#task-lists)
* [Tables](https://help.github.com/articles/github-flavored-markdown/#tables)
-##### `options.commonmark`
+###### `options.commonmark`
-```md
+CommonMark mode (`boolean`, default: `false`).
+
+```markdown
This is a paragraph
and this is also part of the preceding paragraph.
```
-CommonMark mode (`boolean`, default: `false`) allows:
+Allows:
* Empty lines to split blockquotes
-* Parentheses (`(` and `)`) around for link and image titles
-* Any escaped [ASCII-punctuation][escapes] character
+* Parentheses (`(` and `)`) around 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:
+Disallows:
-* Code directly following a paragraph
-* ATX-headings (`# Hash headings`) without spacing after opening hashes
- or and before closing hashes
+* Indented code blocks 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
+* White space in link and image URLs in auto-links (links in brackets, `<` and
+ `>`)
+* Lazy blockquote continuation, lines not preceded by a greater than character
+ (`>`), for lists, code, and thematic breaks
+
+###### `options.footnotes`
-##### `options.footnotes`
+Footnotes mode (`boolean`, default: `false`).
-```md
+```markdown
Something something[^or something?].
And something else[^1].
@@ -157,35 +165,37 @@ And something else[^1].
* ...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
-foo
-
-```
+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.
-Blocks (`Array.`, default: list of [block HTML elements][blocks])
-exposes let’s users define block-level HTML elements.
+###### `options.pedantic`
-##### `options.pedantic`
+Pedantic mode (`boolean`, default: `false`).
-```md
+```markdown
Check out some_file_name.txt
```
-Pedantic mode (`boolean`, default: `false`) turns on:
+Turns on:
-* Emphasis (`_alpha_`) and importance (`__bravo__`) with underscores
- in words
+* 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)
+* If `commonmark` is also turned on, ordered lists with different markers
+ (`.`, `)`)
+* And removes less spaces in list items (at most four, instead of the whole
+ indent)
+
+###### `options.blocks`
+
+Blocks (`Array.`, default: list of [block HTML elements][blocks]).
+
+```markdown
+foo
+
+```
+
+Defines which HTML elements are seen as block level.
### `parse.Parser`
@@ -193,14 +203,15 @@ 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.
+Typically, using [*transformers*][transformer] to manipulate a syntax tree
+produces the desired output.
+Sometimes, such as when introducing new syntactic entities with a certain
+precedence, interfacing with the parser is necessary.
If the `remark-parse` plugin is used, it adds a [`Parser`][parser] constructor
-to the `processor`. Other plugins can add tokenizers to the parser’s prototype
-to change how markdown is parsed.
+function to the `processor`.
+Other plugins can add tokenizers to its prototype to change how Markdown is
+parsed.
The below plugin adds a [tokenizer][] for at-mentions.
@@ -222,17 +233,18 @@ function mentions() {
### `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.
+Map of names to [tokenizer][]s (`Object.`).
+These tokenizers (such as `fencedCode`, `table`, and `paragraph`) eat from the
+start of a value to a line ending.
-See `#blockMethods` below for a list of methods that are included by
-default.
+See `#blockMethods` below for a list of methods that are included by default.
### `Parser#blockMethods`
-Array of `blockTokenizers` names (`string`) specifying the order in
-which they run.
+List of `blockTokenizers` names (`Array.`).
+Specifies the order in which tokenizers run.
+
+Precedence of default block methods is as follows:
@@ -254,17 +266,19 @@ 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.
+Map of names to [tokenizer][]s (`Object.`).
+These tokenizers (such as `url`, `reference`, and `emphasis`) eat from the start
+of a value.
+To increase performance, they depend on [locator][]s.
-See `#inlineMethods` below for a list of methods that are included by
-default.
+See `#inlineMethods` below for a list of methods that are included by default.
### `Parser#inlineMethods`
-Array of `inlineTokenizers` names (`string`) specifying the order in
-which they run.
+List of `inlineTokenizers` names (`Array.`).
+Specifies the order in which tokenizers run.
+
+Precedence of default inline methods is as follows:
@@ -285,6 +299,13 @@ which they run.
### `function tokenizer(eat, value, silent)`
+There are two types of tokenizers: block level and inline level.
+Both are functions, and work the same, but inline tokenizers must have a
+[locator][].
+
+The following example shows an inline tokenizer that is added by the mentions
+plugin above.
+
```js
tokenizeMention.notInLink = true
tokenizeMention.locator = locateMention
@@ -306,15 +327,12 @@ function tokenizeMention(eat, value, silent) {
}
```
-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”.
-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.
+Locators enable inline tokenizers to function faster by providing where the next
+entity may occur.
###### Signatures
@@ -329,36 +347,39 @@ information on where the next entity may occur.
###### 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
+* `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`
+* `boolean?`, in *silent* mode — whether a node can be found at the start of
+ `value`
+* [`Node?`][node], In *normal* mode — If it can be found at the start of
+ `value`
### `tokenizer.locator(value, fromIndex)`
+Locators are required for inline tokenizers.
+Their role is to keep parsing performant.
+
+The following example shows a locator that is added by the mentions tokenizer
+above.
+
```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.
+Locators enable inline tokenizers to function faster by providing information on
+where the next entity *may* occur.
+Locators may be wrong, it’s OK if there actually isn’t a node to be found at the
+index they return.
###### Parameters
@@ -367,7 +388,7 @@ the index they return, but they must skip any nodes.
###### Returns
-Index at which an entity may start, and `-1` otherwise.
+`number` — Index at which an entity may start, and `-1` otherwise.
### `eat(subvalue)`
@@ -375,13 +396,12 @@ Index at which an entity may start, and `-1` otherwise.
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).
+Eat `subvalue`, which is a string at the start of the [tokenized][tokenizer]
+`value`.
###### Parameters
-* `subvalue` (`string`) - Value to eat.
+* `subvalue` (`string`) - Value to eat
###### Returns
@@ -395,22 +415,23 @@ var add = eat('foo')
add({type: 'text', value: 'foo'})
```
-Add [positional information][position] to `node` and add it to `parent`.
+Add [positional information][position] to `node` and add `node` 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
+* `node` ([`Node`][node]) - Node to patch position on and to add
+* `parent` ([`Parent`][parent], optional) - Place to add `node` to in the
+ syntax tree.
+ Defaults to the currently processed node
###### Returns
-The given `node`.
+[`Node`][node] — The given `node`.
### `add.test()`
-Get the [positional information][position] which would be patched on
-`node` by `add`.
+Get the [positional information][position] that would be patched on `node` by
+`add`.
###### Returns
@@ -418,26 +439,32 @@ Get the [positional information][position] which would be patched on
### `add.reset(node[, parent])`
-`add`, but resets the internal position. Useful for example in
-lists, where the same content is first eaten for a list, and later
-for list items
+`add`, but resets the internal position.
+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
+ the syntax tree.
+ Defaults to the currently processed node
###### Returns
-The given `node`.
+[`Node`][node] — 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 replacing the tokenizer from
-your Parser’s `blockTokenizers` (or `blockMethods`) or `inlineTokenizers`
-(or `inlineMethods`).
+In some situations, you may want to turn off a tokenizer to avoid parsing that
+syntactic feature.
+
+Preferably, use the [`remark-disable-tokenizers`][remark-disable-tokenizers]
+plugin to turn off tokenizers.
+
+Alternatively, this can be done by replacing the tokenizer from
+`blockTokenizers` (or `blockMethods`) or `inlineTokenizers` (or
+`inlineMethods`).
The following example turns off indented code blocks:
@@ -449,7 +476,19 @@ function indentedCode() {
}
```
-Preferably, just use [this plugin](https://github.com/zestedesavoir/zmarkdown/tree/master/packages/remark-disable-tokenizers).
+## Contribute
+
+See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
+to get started.
+See [`support.md`][support] for ways to get help.
+Ideas for new plugins and tools can be posted in [`remarkjs/ideas`][ideas].
+
+A curated list of awesome remark resources can be found in [**awesome
+remark**][awesome].
+
+This project has a [Code of Conduct][coc].
+By interacting with this repository, organisation, or community you agree to
+abide by its terms.
## License
@@ -473,15 +512,27 @@ Preferably, just use [this plugin](https://github.com/zestedesavoir/zmarkdown/tr
[size]: https://bundlephobia.com/result?p=remark-parse
+[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
+
+[backers-badge]: https://opencollective.com/unified/backers/badge.svg
+
+[collective]: https://opencollective.com/unified
+
[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg
[chat]: https://spectrum.chat/unified/remark
-[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
+[health]: https://github.com/remarkjs/.github
-[backers-badge]: https://opencollective.com/unified/backers/badge.svg
+[contributing]: https://github.com/remarkjs/.github/blob/master/contributing.md
-[collective]: https://opencollective.com/unified
+[support]: https://github.com/remarkjs/.github/blob/master/support.md
+
+[coc]: https://github.com/remarkjs/.github/blob/master/code-of-conduct.md
+
+[ideas]: https://github.com/remarkjs/ideas
+
+[awesome]: https://github.com/remarkjs/awesome-remark
[license]: https://github.com/remarkjs/remark/blob/master/license
@@ -493,18 +544,24 @@ Preferably, just use [this plugin](https://github.com/zestedesavoir/zmarkdown/tr
[data]: https://github.com/unifiedjs/unified#processordatakey-value
-[processor]: https://github.com/remarkjs/remark/blob/master/packages/remark
+[remark]: https://github.com/remarkjs/remark/tree/master/packages/remark
+
+[blocks]: https://github.com/remarkjs/remark/blob/master/packages/remark-parse/lib/block-elements.js
[mdast]: https://github.com/syntax-tree/mdast
-[escapes]: https://spec.commonmark.org/0.28/#backslash-escapes
+[escapes]: https://spec.commonmark.org/0.29/#backslash-escapes
[node]: https://github.com/syntax-tree/unist#node
+[parent]: https://github.com/syntax-tree/unist#parent
+
[position]: https://github.com/syntax-tree/unist#position
[parser]: https://github.com/unifiedjs/unified#processorparser
+[transformer]: https://github.com/unifiedjs/unified#function-transformernode-file-next
+
[extend]: #extending-the-parser
[tokenizer]: #function-tokenizereat-value-silent
@@ -515,6 +572,6 @@ Preferably, just use [this plugin](https://github.com/zestedesavoir/zmarkdown/tr
[add]: #addnode-parent
-[blocks]: https://github.com/remarkjs/remark/blob/master/packages/remark-parse/lib/block-elements.js
-
[announcement]: https://medium.com/unifiedjs/collectively-evolving-through-crowdsourcing-22c359ea95cc
+
+[remark-disable-tokenizers]: https://github.com/zestedesavoir/zmarkdown/tree/master/packages/remark-disable-tokenizers
diff --git a/packages/remark-stringify/readme.md b/packages/remark-stringify/readme.md
index eeccd87a4..08d739982 100644
--- a/packages/remark-stringify/readme.md
+++ b/packages/remark-stringify/readme.md
@@ -9,15 +9,9 @@
[![Backers][backers-badge]][collective]
[Compiler][] for [**unified**][unified].
-Stringifies [**mdast**][mdast] syntax trees to markdown.
-Used in the [**remark** processor][processor] but can be used on its own as
-well.
-Can be [extended][extend] to change how markdown is parsed.
-
-* * *
-
-**Announcing the unified collective! 🎉
-[Read more about it on Medium »][announcement]**
+Stringifies [**mdast**][mdast] syntax trees to Markdown.
+Used in the [**remark** processor][remark] but can be used on its own as well.
+Can be [extended][extend] to change how Markdown is compiled.
## Sponsors
@@ -51,7 +45,9 @@ Can be [extended][extend] to change how markdown is parsed.
-## Installation
+[**Read more about the unified collective on Medium »**][announcement]
+
+## Install
[npm][]:
@@ -59,18 +55,18 @@ Can be [extended][extend] to change how markdown is parsed.
npm install remark-stringify
```
-## Usage
+## Use
```js
var unified = require('unified')
var createStream = require('unified-stream')
-var parse = require('remark-parse')
-var toc = require('remark-toc')
+var html = require('rehype-parse')
+var rehype2remark = require('rehype-remark')
var stringify = require('remark-stringify')
var processor = unified()
- .use(parse)
- .use(toc)
+ .use(html)
+ .use(rehype2remark)
.use(stringify, {
bullet: '*',
fence: '~',
@@ -84,27 +80,31 @@ process.stdin.pipe(createStream(processor)).pipe(process.stdout)
## Table of Contents
* [API](#api)
- * [processor.use(stringify\[, options\])](#processorusestringify-options)
+ * [processor().use(stringify\[, options\])](#processorusestringify-options)
* [stringify.Compiler](#stringifycompiler)
* [Extending the Compiler](#extending-the-compiler)
* [Compiler#visitors](#compilervisitors)
* [function visitor(node\[, parent\])](#function-visitornode-parent)
+* [Contribute](#contribute)
* [License](#license)
## API
-### `processor.use(stringify[, options])`
+[See **unified** for API docs »][unified]
+
+### `processor().use(stringify[, options])`
-Configure the `processor` to stringify [**mdast**][mdast] syntax trees
-to markdown.
+Configure the `processor` to stringify [**mdast**][mdast] syntax trees to
+Markdown.
##### `options`
-Options are passed directly, or passed later through [`processor.data()`][data].
+Options can be passed directly, or passed later through
+[`processor.data()`][data].
###### `options.gfm`
-Stringify with the required escapes for GFM compatible markdown (`boolean`,
+Stringify with the required escapes for GFM compatible Markdown (`boolean`,
default: `true`).
* Escape pipes (`|`, for tables)
@@ -113,7 +113,7 @@ default: `true`).
###### `options.commonmark`
-Stringify for CommonMark compatible markdown (`boolean`, default: `false`).
+Stringify for CommonMark compatible Markdown (`boolean`, default: `false`).
* Compile adjacent blockquotes separately
* Escape more characters using slashes, instead of as entities
@@ -128,20 +128,20 @@ Stringify for pedantic compatible markdown (`boolean`, default: `false`).
How to stringify entities (`string` or `boolean`, default: `false`):
-* `true` — Entities are generated for special HTML characters
- (`&` > `&`) and non-ASCII characters (`©` > `©`).
- If named entities are not (widely) supported, numbered character
- references are used (`’` > `’`)
-* `'numbers'` — Numbered entities are generated (`&` > `&`)
- for special HTML characters and non-ASCII characters
-* `'escape'` — Special HTML characters are encoded (`&` >
- `&`, `’` > `’`), non-ASCII characters not (ö persists)
+* `true` — Entities are generated for special HTML characters (`&` > `&`)
+ and non-ASCII characters (`©` > `©`).
+ If named entities are not (widely) supported, numbered character references
+ are used (`’` > `’`)
+* `'numbers'` — Numbered entities are generated (`&` > `&`) for special
+ HTML characters and non-ASCII characters
+* `'escape'` — Special HTML characters are encoded (`&` > `&`, `’` >
+ `’`), non-ASCII characters not (ö persists)
###### `options.setext`
Compile headings, when possible, in Setext-style (`boolean`, default: `false`).
-Uses `=` for level one headings and `-` for level two headings. Other heading
-levels are compiled as ATX (respecting `closeAtx`).
+Uses `=` for level one headings and `-` for level two headings.
+Other heading levels are compiled as ATX (respecting `closeAtx`).
###### `options.closeAtx`
@@ -155,45 +155,51 @@ Create tables without fences: initial and final pipes (`boolean`, default:
###### `options.spacedTable`
-Create tables without spacing between pipes and content (`boolean`, default:
+Create tables with a space between a pipe and content (`boolean`, default:
`true`).
###### `options.paddedTable`
-Create tables with padding in each cell so that they are the same size
-(`boolean`, default: `true`).
+Create tables with more spaces so that all cells in a column align (`boolean`,
+default: `true`).
###### `options.stringLength`
Function passed to [`markdown-table`][markdown-table] to detect the length of a
table cell (`Function`, default: [`s => s.length`][string-length]).
+Used to pad tables.
###### `options.fence`
-Fence marker to use for code blocks (`'~'` or ``'`'``, default: ``'`'``).
+Marker to use for fenced code blocks (`'~'` or ``'`'``, default: ``'`'``).
###### `options.fences`
-Stringify code blocks without language with fences (`boolean`, default:
-`false`).
+Create code blocks with a fence instead of indentation if they have no info
+string (`boolean`, default: `false`).
+
+When `false`, code blocks are indented.
+Code blocks with an info string are always fenced.
###### `options.bullet`
-Bullet marker to use for unordered list items (`'-'`, `'*'`, or `'+'`,
+Marker to use for the bullet of unordered list items (`'-'`, `'*'`, or `'+'`,
default: `'-'`).
###### `options.listItemIndent`
-How to indent the content from list items (`'tab'`, `'mixed'` or `'1'`,
-default: `'tab'`).
+Style of indentation for list items (`'tab'`, `'mixed'` or `'1'`, default:
+`'tab'`).
-* `'tab'`: use tab stops (4 spaces)
+* `'tab'`: use a tab stops (4 spaces)
* `'1'`: use one space
* `'mixed'`: use `1` for tight and `tab` for loose list items
###### `options.incrementListMarker`
-Whether to increment ordered list item bullets (`boolean`, default: `true`).
+Increment ordered list item numbers (`boolean`, default: `true`).
+
+When `false`, all list item numbers will be the same.
###### `options.rule`
@@ -203,11 +209,12 @@ default: `'*'`).
###### `options.ruleRepetition`
Number of markers to use for thematic breaks / horizontal rules (`number`,
-default: `3`). Should be `3` or more.
+default: `3`).
+Musts be `3` or more.
###### `options.ruleSpaces`
-Whether to pad thematic break (horizontal rule) markers with spaces (`boolean`,
+Place a space between thematic break (horizontal rule) markers (`boolean`,
default `true`).
###### `options.strong`
@@ -220,16 +227,17 @@ Marker to use for emphasis (`'_'` or `'*'`, default `'_'`).
### `stringify.Compiler`
-Access to the raw [compiler][], if you need it.
+Access to the [compiler][], if you need it.
## Extending the Compiler
-If this plugin is used, it adds a [`Compiler`][compiler] constructor
-to the `processor`. Other plugins can change and add visitors on
-the compiler’s prototype to change how markdown is stringified.
+If the `remark-stringify` plugin is used, it adds a [`Compiler`][compiler]
+constructor function to the `processor`.
+Other plugins can add visitors to its prototype to change how Markdown is
+compiled.
-The below plugin modifies a [visitor][] to add an extra blank line
-before level two headings.
+The below plugin modifies a [visitor][] to add an extra blank line before
+headings with a rank of `2`.
```js
module.exports = gap
@@ -249,7 +257,7 @@ function gap() {
### `Compiler#visitors`
-An object mapping [node][] types to [`visitor`][visitor]s.
+Map of types to [visitor][]s (`Object.`).
### `function visitor(node[, parent])`
@@ -258,11 +266,26 @@ Stringify `node`.
###### Parameters
* `node` ([`Node`][node]) — Node to compile
-* `parent` ([`Node`][node], optional) — Parent of `node`
+* `parent` ([`Parent`][parent], optional) — Parent of `node`.
+ Not available on the root node
###### Returns
-`string`, the compiled given `node`.
+`string` — Compiled given `node`.
+
+## Contribute
+
+See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
+to get started.
+See [`support.md`][support] for ways to get help.
+Ideas for new plugins and tools can be posted in [`remarkjs/ideas`][ideas].
+
+A curated list of awesome remark resources can be found in [**awesome
+remark**][awesome].
+
+This project has a [Code of Conduct][coc].
+By interacting with this repository, organisation, or community you agree to
+abide by its terms.
## License
@@ -286,15 +309,27 @@ Stringify `node`.
[size]: https://bundlephobia.com/result?p=remark-stringify
+[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
+
+[backers-badge]: https://opencollective.com/unified/backers/badge.svg
+
+[collective]: https://opencollective.com/unified
+
[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg
[chat]: https://spectrum.chat/unified/remark
-[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
+[health]: https://github.com/remarkjs/.github
-[backers-badge]: https://opencollective.com/unified/backers/badge.svg
+[contributing]: https://github.com/remarkjs/.github/blob/master/contributing.md
-[collective]: https://opencollective.com/unified
+[support]: https://github.com/remarkjs/.github/blob/master/support.md
+
+[coc]: https://github.com/remarkjs/.github/blob/master/code-of-conduct.md
+
+[ideas]: https://github.com/remarkjs/ideas
+
+[awesome]: https://github.com/remarkjs/awesome-remark
[license]: https://github.com/remarkjs/remark/blob/master/license
@@ -304,22 +339,24 @@ Stringify `node`.
[unified]: https://github.com/unifiedjs/unified
-[processor]: https://github.com/remarkjs/remark
-
[data]: https://github.com/unifiedjs/unified#processordatakey-value
+[remark]: https://github.com/remarkjs/remark/tree/master/packages/remark
+
[compiler]: https://github.com/unifiedjs/unified#processorcompiler
[mdast]: https://github.com/syntax-tree/mdast
[node]: https://github.com/syntax-tree/unist#node
+[parent]: https://github.com/syntax-tree/unist#parent
+
[extend]: #extending-the-compiler
[visitor]: #function-visitornode-parent
+[announcement]: https://medium.com/unifiedjs/collectively-evolving-through-crowdsourcing-22c359ea95cc
+
[markdown-table]: https://github.com/wooorm/markdown-table
[string-length]: https://github.com/wooorm/markdown-table#stringlengthcell
-
-[announcement]: https://medium.com/unifiedjs/collectively-evolving-through-crowdsourcing-22c359ea95cc
diff --git a/packages/remark/readme.md b/packages/remark/readme.md
index 6550809b9..263d80e55 100644
--- a/packages/remark/readme.md
+++ b/packages/remark/readme.md
@@ -4,25 +4,23 @@
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
-[![Chat][chat-badge]][chat]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
+[![Chat][chat-badge]][chat]
-[**remark**][remark] is a markdown processor powered by [plugins][] part of the
-[unified][] [collective][].
+[**unified**][unified] processor to parse and compile Markdown.
+Powered by [plugins][].
+Part of the [unified][] collective.
-* API by [`unified`][unified]
-* Parses markdown to the tree with [`remark-parse`][parse]
+* API by [**unified**][unified]
+* Parses Markdown to a syntax tree with [`remark-parse`][parse]
* [**mdast**][mdast] syntax tree
* [Plugins][] transform the tree
-* Compiles the tree to markdown using [`remark-stringify`][stringify]
-
-Don’t need the parser? Or the compiler? [That’s OK][unified-usage].
-
-* * *
+* Stringifies syntax trees to Markdown with [`remark-stringify`][stringify]
-**Announcing the unified collective! 🎉
-[Read more about it on Medium »][announcement]**
+Don’t need the parser?
+Or compiler?
+[That’s OK: use **unified** directly][unified-usage].
## Sponsors
@@ -56,7 +54,9 @@ Don’t need the parser? Or the compiler? [That’s OK][unified-usage].
-## Installation
+[**Read more about the unified collective on Medium »**][announcement]
+
+## Install
[npm][]:
@@ -64,11 +64,11 @@ Don’t need the parser? Or the compiler? [That’s OK][unified-usage].
npm install remark
```
-## Usage
+## Use
###### Common example
-This example lints markdown and turns it into HTML.
+This example lints Markdown and turns it into HTML.
```js
var remark = require('remark')
@@ -99,7 +99,7 @@ Yields:
###### Settings through data
-This example prettifies markdown and configures [`remark-parse`][parse] and
+This example prettifies Markdown and configures [`remark-parse`][parse] and
[`remark-stringify`][stringify] through [data][].
```js
@@ -121,7 +121,7 @@ Yields:
###### Settings through a preset
-This example prettifies markdown and configures [`remark-parse`][parse] and
+This example prettifies Markdown and configures [`remark-parse`][parse] and
[`remark-stringify`][stringify] through a [preset][].
```js
@@ -143,6 +143,24 @@ Yields:
*Emphasis* and **importance**
```
+## API
+
+[See **unified** for API docs »][unified]
+
+## Contribute
+
+See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
+to get started.
+See [`support.md`][support] for ways to get help.
+Ideas for new plugins and tools can be posted in [`remarkjs/ideas`][ideas].
+
+A curated list of awesome remark resources can be found in [**awesome
+remark**][awesome].
+
+This project has a [Code of Conduct][coc].
+By interacting with this repository, organisation, or community you agree to
+abide by its terms.
+
## License
[MIT][license] © [Titus Wormer][author]
@@ -165,13 +183,27 @@ Yields:
[size]: https://bundlephobia.com/result?p=remark
+[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
+
+[backers-badge]: https://opencollective.com/unified/backers/badge.svg
+
+[collective]: https://opencollective.com/unified
+
[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg
[chat]: https://spectrum.chat/unified/remark
-[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
+[health]: https://github.com/remarkjs/.github
-[backers-badge]: https://opencollective.com/unified/backers/badge.svg
+[contributing]: https://github.com/remarkjs/.github/blob/master/contributing.md
+
+[support]: https://github.com/remarkjs/.github/blob/master/support.md
+
+[coc]: https://github.com/remarkjs/.github/blob/master/code-of-conduct.md
+
+[ideas]: https://github.com/remarkjs/ideas
+
+[awesome]: https://github.com/remarkjs/awesome-remark
[license]: https://github.com/remarkjs/remark/blob/master/license
@@ -179,8 +211,6 @@ Yields:
[npm]: https://docs.npmjs.com/cli/install
-[remark]: https://github.com/remarkjs/remark
-
[unified]: https://github.com/unifiedjs/unified
[mdast]: https://github.com/syntax-tree/mdast
@@ -197,6 +227,4 @@ Yields:
[data]: https://github.com/unifiedjs/unified#processordatakey-value
-[collective]: https://opencollective.com/unified
-
[announcement]: https://medium.com/unifiedjs/collectively-evolving-through-crowdsourcing-22c359ea95cc
diff --git a/readme.md b/readme.md
index d43111e93..4b3f0c4be 100644
--- a/readme.md
+++ b/readme.md
@@ -4,17 +4,34 @@
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
-[![Chat][chat-badge]][chat]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
+[![Chat][chat-badge]][chat]
+
+**remark** is a Markdown processor powered by [plugins][] part of the
+[unified][] collective.
+
+## Intro
-**remark** is a markdown processor powered by [plugins][] part of the
-[unified][] [collective][].
+**remark** is not another Markdown to HTML compiler.
+It can generate and reformat Markdown too.
+Powered by plugins to do all kinds of things: [check Markdown code
+style][remark-lint], [transform safely to React][remark-react], [add a table of
+contents][remark-toc], or [compile to man pages][remark-man].
+
+* Visit [`unified.js.org`][website] and try its [guides][] for an overview
+* Read [unified][]’s readme for a technical intro
+* Browse [awesome remark][awesome] to find out more about the ecosystem
+* Follow us on [Medium][] and [Twitter][] to see what we’re up to
+* Check out [Contribute][] below to find out how to help out
-* * *
+This repository contains the following projects:
-**Announcing the unified collective! 🎉
-[Read more about it on Medium »][announcement]**
+* [`remark-parse`][parse] — Parse Markdown documents to syntax trees
+* [`remark-stringify`][stringify] — Stringify syntax trees to Markdown
+ documents
+* [`remark`][api] — Programmatic interface with both `remark-parse` and `remark-stringify`
+* [`remark-cli`][cli] — Command-line interface wrapping `remark`
## Sponsors
@@ -48,45 +65,23 @@
-## Intro
-
-**remark** not another markdown to HTML compiler.
-It can generate and reformat markdown too.
-Powered by plugins to do all kinds of things: [check markdown code
-style][remark-lint], [transform safely to React][remark-react], [add a table of
-contents][remark-toc], or [compile to man pages][remark-man].
-
-* Visit [`unified.js.org`][website] and try its [guides][] for an overview
-* Read [unified][]’s readme for a technical intro
-* Browse [awesome remark][awesome] to find out more about the ecosystem
-* Follow us on [Medium][] and [Twitter][] to see what we’re up to
-* Check out [Contribute][] below to find out how to help out
-
-This repository contains the following projects:
-
-* [`remark-parse`][parse] — Parse a markdown document to a syntax tree
-* [`remark-stringify`][stringify]
- — Stringify a syntax tree to a markdown document
-* [`remark`][api] — Programmatic interface with both `remark-parse` and `remark-stringify`
-* [`remark-cli`][cli] — Command-line interface wrapping `remark`
+[**Read more about the unified collective on Medium »**][announcement]
## Contribute
-**remark** is built by people just like you!
-Check out [`contributing.md`][contributing] for ways to get started.
+See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
+to get started.
+See [`support.md`][support] for ways to get help.
+Ideas for new plugins and tools can be posted in [`remarkjs/ideas`][ideas].
+Join us in [spectrum][chat] to chat with the community and contributors.
+
+A curated list of awesome resources can be found in [**awesome
+remark**][awesome].
This project has a [Code of Conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.
-Want to chat with the community and contributors?
-Join us in [spectrum][chat]!
-
-Have an idea for a cool new utility or tool?
-That’s great!
-If you want feedback, help, or just to share it with the world you can do so by
-creating an issue in the [`remarkjs/ideas`][ideas] repository!
-
## License
[MIT](license) © [Titus Wormer](https://wooorm.com)
@@ -145,13 +140,17 @@ creating an issue in the [`remarkjs/ideas`][ideas] repository!
[contribute]: #contribute
-[contributing]: contributing.md
+[health]: https://github.com/remarkjs/.github
+
+[contributing]: https://github.com/remarkjs/.github/blob/master/contributing.md
+
+[support]: https://github.com/remarkjs/.github/blob/master/support.md
-[coc]: code-of-conduct.md
+[coc]: https://github.com/remarkjs/.github/blob/master/code-of-conduct.md
[ideas]: https://github.com/remarkjs/ideas
-[awesome]: https://github.com/remarkjs/awesome
+[awesome]: https://github.com/remarkjs/awesome-remark
[collective]: https://opencollective.com/unified