remark-lint-code-block-style - npm Package Compare versions

Comparing version 3.1.0 to 3.1.2

index.d.ts

 export default remarkLintCodeBlockStyle
 export type Root = import('mdast').Root
+/**
+ * Styles.
+ */
 export type Style = 'fenced' | 'indented'
+/**
+ * Options.
+ */
 export type Options = 'consistent' | Style
@@ -8,14 +14,12 @@ declare const remarkLintCodeBlockStyle: import('unified').Plugin<
   | [
-      | import('unified-lint-rule').Severity
-      | import('unified-lint-rule').Label
       | Options
+      | [
+          (
+            | boolean
+            | import('unified-lint-rule/lib/index.js').Label
+            | import('unified-lint-rule/lib/index.js').Severity
+          ),
+          (Options | undefined)?
+        ]
       | undefined
-    ]
-  | [
-      (
-        | boolean
-        | import('unified-lint-rule').Severity
-        | import('unified-lint-rule').Label
-      ),
-      Options | undefined
     ],
@@ -22,0 +26,0 @@ import('mdast').Root,

index.js

 /**
- * @author Titus Wormer
- * @copyright 2015 Titus Wormer
- * @license MIT
- * @module code-block-style
- * @fileoverview
- *   Warn when code blocks do not adhere to a given style.
+ * ## When should I use this?
  *
- *   Options: `'consistent'`, `'fenced'`, or `'indented'`, default: `'consistent'`.
+ * You can use this package to check that code blocks are consistent.
  *
- *   `'consistent'` detects the first used code block style and warns when
- *   subsequent code blocks uses different styles.
+ * ## API
  *
- *   ## Fix
+ * The following options (default: `'consistent'`) are accepted:
  *
- *   [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify)
- *   formats code blocks using a fence if they have a language flag and
- *   indentation if not.
- *   Pass
- *   [`fences: true`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsfences)
- *   to always use fences for code blocks.
+ * *   `'fenced'`
+ *     — prefer fenced code blocks:
+ *     ````markdown
+ *     ```js
+ *     code()
+ *     ```
+ *     ````
+ * *   `'indented'`
+ *     — prefer indented code blocks:
+ *     ```markdown
+ *         code()
+ *     ```
+ * *   `'consistent'`
+ *     — detect the first used style and warn when further code blocks differ
  *
- *   See [Using remark to fix your Markdown](https://github.com/remarkjs/remark-lint#using-remark-to-fix-your-markdown)
- *   on how to automatically fix warnings for this rule.
+ * ## Recommendation
  *
+ * Indentation in markdown is complex, especially because lists and indented
+ * code can interfere in unexpected ways.
+ * Fenced code has more features than indented code: importantly, specifying a
+ * programming language.
+ * Since CommonMark took the idea of fenced code from GFM, fenced code became
+ * widely supported.
+ * Due to this, it’s recommended to configure this rule with `'fenced'`.
+ *
+ * ## Fix
+ *
+ * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify)
+ * formats code blocks as fenced code when they have a language flag and as
+ * indented code otherwise.
+ * Pass
+ * [`fences: true`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsfences)
+ * to always use fenced code.
+ *
+ * @module code-block-style
+ * @summary
+ *   remark-lint rule to warn when code blocks violate a given style.
+ * @author Titus Wormer
+ * @copyright 2015 Titus Wormer
+ * @license MIT
+ *
  * @example
- *   {"setting": "indented", "name": "ok.md"}
+ *   {"config": "indented", "name": "ok.md"}
  *
@@ -36,3 +61,3 @@ *       alpha()
  * @example
- *   {"setting": "indented", "name": "not-ok.md", "label": "input"}
+ *   {"config": "indented", "name": "not-ok.md", "label": "input"}
  *
@@ -50,3 +75,3 @@ *   ```
  * @example
- *   {"setting": "indented", "name": "not-ok.md", "label": "output"}
+ *   {"config": "indented", "name": "not-ok.md", "label": "output"}
  *
@@ -57,3 +82,3 @@ *   1:1-3:4: Code blocks should be indented
  * @example
- *   {"setting": "fenced", "name": "ok.md"}
+ *   {"config": "fenced", "name": "ok.md"}
  *
@@ -71,3 +96,3 @@ *   ```
  * @example
- *   {"setting": "fenced", "name": "not-ok-fenced.md", "label": "input"}
+ *   {"config": "fenced", "name": "not-ok-fenced.md", "label": "input"}
  *
@@ -81,3 +106,3 @@ *       alpha()
  * @example
- *   {"setting": "fenced", "name": "not-ok-fenced.md", "label": "output"}
+ *   {"config": "fenced", "name": "not-ok-fenced.md", "label": "output"}
  *
@@ -104,3 +129,3 @@ *   1:1-1:12: Code blocks should be fenced
  * @example
- *   {"setting": "💩", "name": "not-ok-incorrect.md", "label": "output", "positionless": true}
+ *   {"config": "💩", "name": "not-ok-incorrect.md", "label": "output", "positionless": true}
  *
@@ -112,6 +137,11 @@ *   1:1: Incorrect code block style `💩`: use either `'consistent'`, `'fenced'`, or `'indented'`
  * @typedef {import('mdast').Root} Root
- * @typedef {'fenced'|'indented'} Style
- * @typedef {'consistent'|Style} Options
  */
 
+/**
+ * @typedef {'fenced' | 'indented'} Style
+ *   Styles.
+ * @typedef {'consistent' | Style} Options
+ *   Options.
+ */
+
 import {lintRule} from 'unified-lint-rule'
@@ -118,0 +148,0 @@ import {visit} from 'unist-util-visit'

package.json

 {
   "name": "remark-lint-code-block-style",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "remark-lint rule to warn when code blocks do not adhere to a given style",
@@ -44,5 +44,3 @@ "license": "MIT",
   },
-  "scripts": {
-    "build": "rimraf \"*.d.ts\" && tsc && type-coverage"
-  },
+  "scripts": {},
   "xo": false,
@@ -49,0 +47,0 @@ "typeCoverage": {

readme.md

@@ -13,21 +13,30 @@ <!--This file is generated-->
 
-Warn when code blocks do not adhere to a given style.
+[`remark-lint`][mono] rule to warn when code blocks violate a given style.
 
-Options: `'consistent'`, `'fenced'`, or `'indented'`, default: `'consistent'`.
+## Contents
 
-`'consistent'` detects the first used code block style and warns when
-subsequent code blocks uses different styles.
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Presets](#presets)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`unified().use(remarkLintCodeBlockStyle[, config])`](#unifieduseremarklintcodeblockstyle-config)
+*   [Recommendation](#recommendation)
+*   [Fix](#fix)
+*   [Examples](#examples)
+*   [Compatibility](#compatibility)
+*   [Contribute](#contribute)
+*   [License](#license)
 
-## Fix
+## What is this?
 
-[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify)
-formats code blocks using a fence if they have a language flag and
-indentation if not.
-Pass
-[`fences: true`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsfences)
-to always use fences for code blocks.
+This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint`
+rule.
+Lint rules check markdown code style.
 
-See [Using remark to fix your Markdown](https://github.com/remarkjs/remark-lint#using-remark-to-fix-your-markdown)
-on how to automatically fix warnings for this rule.
+## When should I use this?
 
+You can use this package to check that code blocks are consistent.
+
 ## Presets
@@ -42,4 +51,117 @@
 
-## Example
+## Install
 
+This package is [ESM only][esm].
+In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
+
+```sh
+npm install remark-lint-code-block-style
+```
+
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import remarkLintCodeBlockStyle from 'https://esm.sh/remark-lint-code-block-style@3'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import remarkLintCodeBlockStyle from 'https://esm.sh/remark-lint-code-block-style@3?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import {read} from 'to-vfile'
+import {reporter} from 'vfile-reporter'
+import {remark} from 'remark'
+import remarkLint from 'remark-lint'
+import remarkLintCodeBlockStyle from 'remark-lint-code-block-style'
+
+main()
+
+async function main() {
+  const file = await remark()
+    .use(remarkLint)
+    .use(remarkLintCodeBlockStyle)
+    .process(await read('example.md'))
+
+  console.error(reporter(file))
+}
+```
+
+On the CLI:
+
+```sh
+remark --use remark-lint --use remark-lint-code-block-style example.md
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+   "plugins": [
+     …
+     "remark-lint",
++    "remark-lint-code-block-style",
+     …
+   ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+The default export is `remarkLintCodeBlockStyle`.
+
+### `unified().use(remarkLintCodeBlockStyle[, config])`
+
+This rule supports standard configuration that all remark lint rules accept
+(such as `false` to turn it off or `[1, options]` to configure it).
+
+The following options (default: `'consistent'`) are accepted:
+
+*   `'fenced'`
+    — prefer fenced code blocks:
+    ````markdown
+    ```js
+    code()
+    ```
+    ````
+*   `'indented'`
+    — prefer indented code blocks:
+    ```markdown
+        code()
+    ```
+*   `'consistent'`
+    — detect the first used style and warn when further code blocks differ
+
+## Recommendation
+
+Indentation in markdown is complex, especially because lists and indented
+code can interfere in unexpected ways.
+Fenced code has more features than indented code: importantly, specifying a
+programming language.
+Since CommonMark took the idea of fenced code from GFM, fenced code became
+widely supported.
+Due to this, it’s recommended to configure this rule with `'fenced'`.
+
+## Fix
+
+[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify)
+formats code blocks as fenced code when they have a language flag and as
+indented code otherwise.
+Pass
+[`fences: true`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsfences)
+to always use fenced code.
+
+## Examples
+
 ##### `ok.md`
@@ -161,56 +283,9 @@
 
-## Install
+## Compatibility
 
-This package is [ESM only][esm]:
-Node 12+ is needed to use it and it must be `imported`ed instead of `required`d.
+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.
 
-[npm][]:
-
-```sh
-npm install remark-lint-code-block-style
-```
-
-This package exports no identifiers.
-The default export is `remarkLintCodeBlockStyle`.
-
-## Use
-
-You probably want to use it on the CLI through a config file:
-
-```diff
- …
- "remarkConfig": {
-   "plugins": [
-     …
-     "lint",
-+    "lint-code-block-style",
-     …
-   ]
- }
- …
-```
-
-Or use it on the CLI directly
-
-```sh
-remark -u lint -u lint-code-block-style readme.md
-```
-
-Or use this on the API:
-
-```diff
- import {remark} from 'remark'
- import {reporter} from 'vfile-reporter'
- import remarkLint from 'remark-lint'
- import remarkLintCodeBlockStyle from 'remark-lint-code-block-style'
-
- remark()
-   .use(remarkLint)
-+  .use(remarkLintCodeBlockStyle)
-   .process('_Emphasis_ and **importance**')
-   .then((file) => {
-     console.error(reporter(file))
-   })
-```
-
 ## Contribute
@@ -256,4 +331,12 @@
 
+[unified]: https://github.com/unifiedjs/unified
+
+[remark]: https://github.com/remarkjs/remark
+
+[mono]: https://github.com/remarkjs/remark-lint
+
 [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
 
+[esmsh]: https://esm.sh
+
 [npm]: https://docs.npmjs.com/cli/install
@@ -263,7 +346,7 @@
 
-[contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md
+[contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
 
-[support]: https://github.com/remarkjs/.github/blob/HEAD/support.md
+[support]: https://github.com/remarkjs/.github/blob/main/support.md
 
-[coc]: https://github.com/remarkjs/.github/blob/HEAD/code-of-conduct.md
+[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
 
@@ -270,0 +353,0 @@ [license]: https://github.com/remarkjs/remark-lint/blob/main/license

New alerts

License Policy Violation

License

This 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

License

This 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

13669

increased by23.47%

Lines of code

205

increased by19.19%

Number of lines in readme file

351

increased by30.97%

No dependency changes