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