Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
remark-message-control
Advanced tools
remark-message-control - npm Package Compare versions
Comparing version 7.1.0 to 7.1.1
| { | ||
| "name": "remark-message-control", | ||
| "version": "7.1.0", | ||
| "version": "7.1.1", | ||
| "description": "remark plugin to enable, disable, and ignore messages with remark", | ||
@@ -56,3 +56,3 @@ "license": "MIT", | ||
| "typescript": "^4.0.0", | ||
| "xo": "^0.44.0" | ||
| "xo": "^0.46.0" | ||
| }, | ||
@@ -59,0 +59,0 @@ "scripts": { |
179
readme.md
@@ -0,1 +1,3 @@ | ||
| <!--lint disable no-html--> | ||
| # remark-message-control | ||
@@ -11,17 +13,45 @@ | ||
| [**remark**][remark] plugin to enable, disable, and ignore messages. | ||
| **[remark][]** plugin to enable, disable, and ignore messages. | ||
| ## Note! | ||
| ## Contents | ||
| This plugin is ready for the new parser in remark | ||
| ([`remarkjs/remark#536`](https://github.com/remarkjs/remark/pull/536)). | ||
| No change is needed: it works exactly the same now as it did before! | ||
| * [What is this?](#what-is-this) | ||
| * [When should I use this?](#when-should-i-use-this) | ||
| * [Install](#install) | ||
| * [Use](#use) | ||
| * [API](#api) | ||
| * [`unified().use(remarkMessageControl, options)`](#unifieduseremarkmessagecontrol-options) | ||
| * [Syntax](#syntax) | ||
| * [Types](#types) | ||
| * [Compatibility](#compatibility) | ||
| * [Security](#security) | ||
| * [Related](#related) | ||
| * [Contribute](#contribute) | ||
| * [License](#license) | ||
| ## What is this? | ||
| This package is a [unified][] ([remark][]) plugin that lets authors write | ||
| comments in markdown to show and hide messages. | ||
| **unified** is a project that transforms content with abstract syntax trees | ||
| (ASTs). | ||
| **remark** adds support for markdown to unified. | ||
| **mdast** is the markdown AST that remark uses. | ||
| remark plugins can inspect the tree and emit warnings and other messages. | ||
| This is a remark plugin that gives authors the ability to configure those | ||
| messages from markdown. | ||
| ## When should I use this? | ||
| You can use this package when you’re building a linter such as | ||
| [`remark-lint`][remark-lint]. | ||
| But you probably don’t need to, because `remark-lint` already exists and it uses | ||
| this package. | ||
| ## Install | ||
| This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c): | ||
| Node 12+ is needed to use it and it must be `import`ed instead of `require`d. | ||
| This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). | ||
| In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: | ||
| [npm][]: | ||
| ```sh | ||
@@ -31,5 +61,19 @@ npm install remark-message-control | ||
| In Deno with [Skypack][]: | ||
| ```js | ||
| import remarkMessageControl from 'https://cdn.skypack.dev/remark-message-control@7?dts' | ||
| ``` | ||
| In browsers with [Skypack][]: | ||
| ```html | ||
| <script type="module"> | ||
| import remarkMessageControl from 'https://cdn.skypack.dev/remark-message-control@7?min' | ||
| </script> | ||
| ``` | ||
| ## Use | ||
| Say we have the following file, `example.md`: | ||
| Say we have the following file `example.md`: | ||
@@ -42,24 +86,25 @@ ```markdown | ||
| And our script, `example.js`, looks as follows: | ||
| And our module `example.js` looks as follows: | ||
| ```js | ||
| import {readSync} from 'to-vfile' | ||
| import {read} from 'to-vfile' | ||
| import {reporter} from 'vfile-reporter' | ||
| import remark from 'remark' | ||
| import control from 'remark-message-control' | ||
| import {remark} from 'remark' | ||
| import remarkMessageControl from 'remark-message-control' | ||
| const file = readSync('example.md') | ||
| main() | ||
| remark() | ||
| .use(() => (tree, file) => { | ||
| file.message('Whoops!', tree.children[1], 'foo:thing') | ||
| }) | ||
| .use(control, {name: 'foo'}) | ||
| .process(file) | ||
| .then((file) => { | ||
| console.error(reporter(file)) | ||
| }) | ||
| async function main() { | ||
| const file = await remark() | ||
| .use(() => (tree, file) => { | ||
| file.message('Whoops!', tree.children[1], 'foo:thing') | ||
| }) | ||
| .use(remarkMessageControl, {name: 'foo'}) | ||
| .process(await read('example.md')) | ||
| console.error(reporter(file)) | ||
| } | ||
| ``` | ||
| Now, running `node example` yields: | ||
| Now running `node example.js` yields: | ||
@@ -77,6 +122,8 @@ ```markdown | ||
| Let comment markers control messages from a certain sources. | ||
| Plugin to enable, disable, and ignore messages. | ||
| ##### Options | ||
| ##### `options` | ||
| Configuration (required). | ||
| ###### `options.name` | ||
@@ -94,3 +141,3 @@ | ||
| List of allowed `ruleId`s (`Array.<string>`, optional). | ||
| List of allowed `ruleId`s (`Array<string>`, optional). | ||
| When given, a warning is shown when someone tries to control an unknown rule. | ||
@@ -112,9 +159,9 @@ | ||
| List of `ruleId`s to initially turn on if `reset: true` (`Array.<string>`, | ||
| List of `ruleId`s to initially turn on if `reset: true` (`Array<string>`, | ||
| optional). | ||
| By default (`reset: false`), all rules are turned on. | ||
| All rules are turned on by default (`reset: false`). | ||
| ###### `options.disable` | ||
| List of `ruleId`s to turn on if `reset: false` (`Array.<string>`, optional). | ||
| List of `ruleId`s to turn on if `reset: false` (`Array<string>`, optional). | ||
@@ -124,6 +171,34 @@ ###### `options.sources` | ||
| Sources that can be controlled with `name` markers (`string` or | ||
| `Array.<string>`, default: `options.name`). | ||
| `Array<string>`, default: `options.name`). | ||
| ### Markers | ||
| <!--Old name of section--> | ||
| <a name="markers"></a> | ||
| ## Syntax | ||
| This plugin looks for comments in markdown (MDX is also supported). | ||
| If the first word in those comments does not match `options.name`, the comment | ||
| is skipped. | ||
| The second word is expected to be `disable`, `enable`, or `ignore`. | ||
| Further words are rule identifiers of messages which are configurated. | ||
| In EBNF, the grammar looks as follows: | ||
| <pre><code class=language-ebnf><a id=s-marker href=#s-marker>marker</a> ::= <a href=#s-identifier>identifier</a> <a href=#s-whitespace>whitespace</a>+ <a href=#s-keyword>keyword</a> <a href=#s-ruleidentifiers>ruleIdentifiers</a>? | ||
| <a id=s-identifier href=#s-identifier>identifier</a> ::= <a href=#s-word>word</a>+ /* restriction: must match `options.name` */ | ||
| <a id=s-keyword href=#s-keyword>keyword</a> ::= 'enable' | 'disable' | 'ignore' | ||
| <a id=s-ruleidentifiers href=#s-ruleidentifiers>ruleIdentifiers</a> ::= <a href=#s-word>word</a>+ (<a href=#s-whitespace>whitespace</a>+ <a href=#s-word>word</a>+)* | ||
| <a id=s-whitespace href=#s-whitespace>whitespace</a> ::= ' ' | '\t' | '\r' | '\n' | '\f' | ||
| <a id=s-word href=#s-word>word</a> ::= <a href=#s-letter>letter</a> | <a href=#s-digit>digit</a> | <a href=#s-punctuation>punctuation</a> | ||
| <a id=s-letter href=#s-letter>letter</a> ::= <a href=#s-letterlowercase>letterLowercase</a> | <a href=#s-letteruppercase>letterUppercase</a> | ||
| <a id=s-punctuation href=#s-punctuation>punctuation</a> ::= '-' | '_' | ||
| <a id=s-letterlowercase href=#s-letterlowercase>letterLowercase</a> ::= 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | ||
| <a id=s-letteruppercase href=#s-letteruppercase>letterUppercase</a> ::= 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | ||
| <a id=s-digit href=#s-digit>digit</a> ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | ||
| </code></pre> | ||
| Which keyword is used defines how messages with those rule identifiers are | ||
| handled: | ||
| ###### `disable` | ||
@@ -165,3 +240,3 @@ | ||
| After the end of the following node, messages are turned on again. | ||
| Messages are turned on again after the end of the following node. | ||
@@ -177,10 +252,32 @@ For example, to turn off certain messages for the next node: | ||
| ## Types | ||
| This package is fully typed with [TypeScript][]. | ||
| An extra `Options` type is exported which models the interface of the accepted | ||
| options. | ||
| ## Compatibility | ||
| Projects maintained by the unified collective are compatible with all maintained | ||
| versions of Node.js. | ||
| As of now, that is Node.js 12.20+, 14.14+, and 16.0+. | ||
| Our projects sometimes work with older versions, but this is not guaranteed. | ||
| This plugin works with `unified` version 6+ and `remark` version 7+. | ||
| ## Security | ||
| Use of `remark-message-control` does not involve [**rehype**][rehype] | ||
| ([**hast**][hast]) or user content so there are no openings for | ||
| [cross-site scripting (XSS)][xss] attacks. | ||
| Use of `remark-message-control` does not involve **[rehype][]** (**[hast][]**) | ||
| or user content so there are no openings for [cross-site scripting (XSS)][xss] | ||
| attacks. | ||
| Messages may be hidden from user content though, causing builds to fail or pass, | ||
| or changing a report. | ||
| ## Related | ||
| * [`remark-lint`][remark-lint] | ||
| — plugin to lint code style | ||
| * [`mdast-comment-marker`](https://github.com/syntax-tree/mdast-comment-marker) | ||
| — mdast utility to parse comment markers | ||
| ## Contribute | ||
@@ -230,2 +327,4 @@ | ||
| [skypack]: https://www.skypack.dev | ||
| [health]: https://github.com/remarkjs/.github | ||
@@ -245,2 +344,6 @@ | ||
| [unified]: https://github.com/unifiedjs/unified | ||
| [typescript]: https://www.typescriptlang.org | ||
| [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting | ||
@@ -251,1 +354,3 @@ | ||
| [hast]: https://github.com/syntax-tree/hast | ||
| [remark-lint]: https://github.com/remarkjs/remark-lint |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by39.55%
14975
- Number of lines in readme file
- increased by43.75%
345
No dependency changes