diff --git a/.remarkrc.js b/.remarkrc.js index 3eed5ff..f1635aa 100644 --- a/.remarkrc.js +++ b/.remarkrc.js @@ -11,7 +11,7 @@ import listOfRules from './script/plugin/list-of-rules.js' const plugins = [ remarkPresetLintRecommended, remarkPresetLintConsistent, - [remarkToc, {tight: true, maxDepth: 2, heading: 'contents'}], + [remarkToc, {tight: true, maxDepth: 3, heading: 'contents'}], remarkCommentConfig, [remarkGfm, {tablePipeAlign: false}], remarkGithub, diff --git a/doc/comparison-to-markdownlint.md b/doc/comparison-to-markdownlint.md index 457a259..684a912 100644 --- a/doc/comparison-to-markdownlint.md +++ b/doc/comparison-to-markdownlint.md @@ -1,7 +1,9 @@ -# [markdownlint](https://github.com/mivok/markdownlint) +# [markdownlint](https://github.com/markdownlint/markdownlint) + +> ⚠️ **Important**: this comparison hasn’t been updated in years. This table documents the similarity and difference between -[**markdownlint**](https://github.com/mivok/markdownlint/blob/HEAD/docs/RULES.md) +[**markdownlint**](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md) rules and **remark-lint**’s rules. | markdownlint | remark | note | diff --git a/doc/create-a-custom-rule.md b/doc/create-a-custom-rule.md index 5d4d0f3..63f9bc8 100644 --- a/doc/create-a-custom-rule.md +++ b/doc/create-a-custom-rule.md @@ -1,6 +1,7 @@ # Create a custom `remark-lint` rule -This guide is part of [a step-by-step tutorial](https://dev.to/floroz/how-to-create-a-custom-lint-rule-for-markdown-and-mdx-using-remark-and-eslint-2jim), and will help you getting started to create your first linting plugin for `remark`. +This guide is part of [a step-by-step tutorial][tutorial], and will help you +getting started to create your first linting plugin for `remark`. ## Contents @@ -31,8 +32,10 @@ Now we can start installing our dependencies: npm install remark-lint remark-cli ``` -* [`remark-lint`](https://github.com/remarkjs/remark-lint): Core lint plugin -* [`remark-cli`](https://github.com/remarkjs/remark/tree/main/packages/remark-cli): Command-line interface +* [`remark-lint`][remark-lint] + — core lint plugin +* [`remark-cli`][remark-cli] + — command line interface We will also use some utilities: @@ -42,13 +45,12 @@ npm install unified-lint-rule unist-util-generated unist-util-visit These will help us creating and managing our custom rules. -[Back to Top](#contents) - ## Set up remark -With everything installed, we can now create a `.remarkrc.js` that will contain the plugins we’ll use. +With everything installed, we can now create a `.remarkrc.js` that will contain +the plugins we’ll use. -For more info on configuration, see [Configuring `remark-lint`](https://github.com/remarkjs/remark-lint#configuring-remark-lint). +For more info on configuration, see [Examples in `remark-lint`][examples]. ```sh touch .remarkrc.js @@ -61,7 +63,8 @@ module.exports = { } ``` -Then, in our `package.json`, add the following script to process all the markdown files in our project: +Then, in our `package.json`, add the following script to process all the +markdown files in our project: ```json "scripts": { @@ -87,7 +90,8 @@ Some funny images of our favorite pets ![a lovely dog](lovely-dog.png) ``` -At this point, we have a working `remark` configuration and a markdown file in the project. +At this point, we have a working `remark` configuration and a markdown file in +the project. If we run `npm run lint` we should expect to see in our terminal: @@ -95,14 +99,15 @@ If we run `npm run lint` we should expect to see in our terminal: doc.md: no issues found ``` -All good, the file has been processed, and because we haven’t specified any plugins nor lint rules, no issues are found. - -[Back to Top](#contents) +All good, the file has been processed, and because we haven’t specified any +plugins nor lint rules, no issues are found. ## The `no-invalid-gif` rule -Let’s imagine we want to write a rule that checks whether a `.gif` file is used as an image. -Given the content of our `doc.md` file declared above, we would expect an *error* or *warning* pointing to: +Let’s imagine we want to write a rule that checks whether a `.gif` file is used +as an image. +Given the content of our `doc.md` file declared above, we would expect an +*error* or *warning* pointing to: ```markdown ![a funny cat](funny-cat.gif) @@ -110,11 +115,10 @@ Given the content of our `doc.md` file declared above, we would expect an *error Because the file extension `.gif` in the image violates our rule. -[Back to Top](#contents) - ## Create the custom rule -Let’s create a new folder `rules` under the root directory, where we will place all of our custom rules, and create a new file in it named `no-gif-allowed.js`. +Let’s create a new folder `rules` under the root directory, where we will place +all of our custom rules, and create a new file in it named `no-gif-allowed.js`. ```sh mkdir rules @@ -123,11 +127,14 @@ touch no-gif-allowed.js cd .. # return to project root ``` -*Note*: the name of folders and files, and where to place them within your project, is up to you. +*Note*: the name of folders and files, and where to place them within your +project, is up to you. In `./rules/no-gif-allowed.js`, let’s import `unified-lint-rule`. -We then export the result of calling `rule` by providing the *namespace and rule name* (`remark-lint:no-gif-allowed`) as the first argument, and our implementation of the rule (`noGifAllowed`) as the second argument. +We then export the result of calling `rule` by providing the *namespace and rule +name* (`remark-lint:no-gif-allowed`) as the first argument, and our +implementation of the rule (`noGifAllowed`) as the second argument. ```js // rules/no-gif-allowed.js @@ -143,7 +150,8 @@ const remarkLintNoGifAllowed = lintRule( export default remarkLintNoGifAllowed ``` -Let’s say you want all your custom rules to be defined as part of your project namespace. +Let’s say you want all your custom rules to be defined as part of your project +namespace. If your project was named `my-project`, then you can export your rule as: ```js @@ -152,9 +160,8 @@ const remarkLintNoGifAllowed = lintRule('my-project-name:no-gif-allowed', () => const remarkLintNoGifAllowed = lintRule('my-npm-published-package:no-gif-allowed', () => {}) ``` -This can help you when wanting to create a group of rules under the same *namespace*. - -[Back to Top](#contents) +This can help you when wanting to create a group of rules under the same +*namespace*. ## Rule arguments @@ -164,17 +171,20 @@ Your rule function will receive three arguments: (tree, file, options) => {} ``` -* `tree` (*required*): [mdast](https://github.com/syntax-tree/mdast) -* `file` (*required*): [virtual file](https://github.com/vfile/vfile) -* `options` (*optional*): additional information passed to the rule by users - -[Back to Top](#contents) +* `tree` (*required*): [mdast][] +* `file` (*required*): [virtual file][vfile] +* `options` (*optional*): additional info passed to the rule by users ## Rule implementation -Because we will be inspecting [mdast](https://github.com/syntax-tree/mdast), which is a markdown abstract syntax tree built upon [unist](https://github.com/syntax-tree/unist), we can take advantage of the many existing [unist utilities](https://github.com/syntax-tree/unist#utilities) to inspect our tree’s nodes. +Because we will be inspecting [mdast][], which is a markdown abstract syntax +tree built upon [unist][], we can take advantage of the many existing +[unist utilities][unist-util] to inspect our tree’s nodes. -For this example, we will use [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit) to recursively inspect all the image nodes, and [`unist-util-generated`](https://github.com/syntax-tree/unist-util-generated) to ensure we are not inspecting nodes that we have generated ourselves and do not belong to the `doc.md`. +For this example, we will use [`unist-util-visit`][unist-util-visit] to +recursively inspect all the image nodes, and +[`unist-util-generated`][unist-util-generated] to ensure we are not inspecting +nodes that we have generated ourselves and do not belong to the `doc.md`. ```js import {lintRule} from 'unified-lint-rule' @@ -205,7 +215,7 @@ const remarkLintNoGifAllowed = lintRule( // Remember to provide the node as second argument to the message, // in order to obtain the position and column where the violation occurred. file.message( - 'Invalid image file extentions. Please do not use gifs', + 'Invalid image file extensions. Please do not use gifs', node ) } @@ -217,11 +227,10 @@ const remarkLintNoGifAllowed = lintRule( export default remarkLintNoGifAllowed ``` -[Back to Top](#contents) - ## Import the rule in your remark config -Now that our custom rule is defined and ready to be used we need to add it to our `remark` configuration. +Now that our custom rule is defined and ready to be used we need to add it to +our `remark` configuration. You can do that by importing your rule and adding it in `plugins` array: @@ -238,16 +247,33 @@ const preset = {plugins} export default preset ``` -[Back to Top](#contents) - ## Apply the rule on the Markdown file If you run `npm run lint`, you should see the following message in the terminal: ```text -5:1-5:30 warning Invalid image file extentions. Please do not use gifs no-gif-allowed remark-lint +5:1-5:30 warning Invalid image file extensions. Please do not use gifs no-gif-allowed remark-lint ``` -**Congratulations! The rule works!** +**Congratulations! +The rule works!** -[Back to Top](#contents) +[tutorial]: https://dev.to/floroz/how-to-create-a-custom-lint-rule-for-markdown-and-mdx-using-remark-and-eslint-2jim + +[remark-lint]: https://github.com/remarkjs/remark-lint + +[remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli + +[examples]: https://github.com/remarkjs/remark-lint#examples + +[mdast]: https://github.com/syntax-tree/mdast + +[vfile]: https://github.com/vfile/vfile + +[unist]: https://github.com/syntax-tree/unist + +[unist-util]: https://github.com/syntax-tree/unist#utilities + +[unist-util-visit]: https://github.com/syntax-tree/unist-util-visit + +[unist-util-generated]: https://github.com/syntax-tree/unist-util-generated diff --git a/doc/rules.md b/doc/rules.md index cbaedd0..33d65f7 100644 --- a/doc/rules.md +++ b/doc/rules.md @@ -1,155 +1,13 @@ # Rules -This document describes how to configure rules and lists all available official -rules. Each rule is a separate package. See their readme’s for more -information. - -## Contents - -* [Configuration](#configuration) -* [List of rules](#list-of-rules) - ## Configuration -`false` turns rules off — the code no longer runs: - -```js -import remarkLintFinalNewline from 'remark-lint-final-newline' - -remark() - .use(remarkLintFinalNewline, false) - // … -``` - -`true` turns a rule on again: - -```js -import remarkLintFinalNewline from 'remark-lint-final-newline' - -remark() - .use(remarkLintFinalNewline, true) - // … -``` - -Rules can be configured with a severity too. The following ignores all -messages from the plugin: - -```js -import remarkLintFinalNewline from 'remark-lint-final-newline' - -remark() - .use(remarkLintFinalNewline, [0]) - // … -``` - -…and passing `[1]` explicitly sets the normal behavior (warn for problems). -To trigger an error instead of a warning, pass `2`: - -```js -import remarkLintFinalNewline from 'remark-lint-final-newline' - -remark() - .use(remarkLintFinalNewline, [2]) - // … -``` - -It’s also possible to pass both a severity and configuration: - -```js -import remarkLintMaximumLineLength from 'remark-lint-maximum-line-length' - -remark() - .use(remarkLintMaximumLineLength, [2, 70]) - // … -``` - -Lastly, strings can also be passed, instead of numbers: -`off` instead of `0`, `warn` or `on` instead of `1`, and -`error` instead of `2`. - -```js -import remarkLintMaximumLineLength from 'remark-lint-maximum-line-length' - -remark() - .use(remarkLintMaximumLineLength, ['error', 70]) - // … -``` +See the monorepo readme for [configuring rules][config]. ## List of rules -This lists contains all “official” rules, developed in this repository. -For rules developed outside of this repo, view the [List of External -Rules][external]. +See the monorepo readme for the [rules][]. - +[config]: https://github.com/remarkjs/remark-lint#configure -* [`blockquote-indentation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-blockquote-indentation) — warn when block quotes are either indented too much or too little -* [`checkbox-character-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-checkbox-character-style) — warn when list item checkboxes violate a given style -* [`checkbox-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-checkbox-content-indent) — warn when list item checkboxes are followed by too much whitespace -* [`code-block-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-code-block-style) — warn when code blocks do not adhere to a given style -* [`definition-case`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-case) — warn when definition labels are not lowercase -* [`definition-spacing`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-spacing) — warn when consecutive whitespace is used in a definition -* [`emphasis-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-emphasis-marker) — warn when emphasis markers violate the given style -* [`fenced-code-flag`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-flag) — warn when fenced code blocks occur without language flag -* [`fenced-code-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-marker) — warn when fenced code markers violate the given style -* [`file-extension`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-file-extension) — warn when the file’s extension violates the given style -* [`final-definition`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-definition) — warn when definitions are not placed at the end of the file -* [`final-newline`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-newline) — warn when a newline at the end of a file is missing -* [`first-heading-level`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-first-heading-level) — warn when the first heading has a level other than a specified value -* [`hard-break-spaces`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-hard-break-spaces) — warn when too many spaces are used to create a hard break -* [`heading-increment`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-increment) — warn when headings increment with more than 1 level at a time -* [`heading-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-style) — warn when heading style violates the given style -* [`linebreak-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-linebreak-style) — warn when linebreaks violate a given or detected style -* [`link-title-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-link-title-style) — warn when link and definition titles occur with incorrect quotes -* [`list-item-bullet-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-bullet-indent) — warn when list item bullets are indented -* [`list-item-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-content-indent) — warn when the content of a list item has mixed indentation -* [`list-item-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-indent) — warn when the spacing between a list item’s bullet and its content violates a given style -* [`list-item-spacing`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-spacing) — warn when list looseness is incorrect -* [`maximum-heading-length`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-heading-length) — warn when headings are too long -* [`maximum-line-length`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-line-length) — warn when lines are too long -* [`no-blockquote-without-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-blockquote-without-marker) — warn when blank lines without markers (\`>\`) are found in a block quote -* [`no-consecutive-blank-lines`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-consecutive-blank-lines) — warn for too many consecutive blank lines -* [`no-duplicate-defined-urls`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-defined-urls) — warn on definitions that define the same urls -* [`no-duplicate-definitions`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-definitions) — warn on duplicate definitions -* [`no-duplicate-headings`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings) — warn on duplicate headings -* [`no-duplicate-headings-in-section`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings-in-section) — warn on duplicate headings in a section -* [`no-emphasis-as-heading`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-emphasis-as-heading) — warn when emphasis or importance is used instead of a heading -* [`no-empty-url`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-empty-url) — warn on empty URLs in links and images -* [`no-file-name-articles`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-articles) — warn when file name start with an article -* [`no-file-name-consecutive-dashes`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-consecutive-dashes) — warn when file names contain consecutive dashes -* [`no-file-name-irregular-characters`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-irregular-characters) — warn when file names contain irregular characters -* [`no-file-name-mixed-case`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-mixed-case) — warn when file names use mixed case -* [`no-file-name-outer-dashes`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-outer-dashes) — warn when file names contain initial or final dashes -* [`no-heading-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-content-indent) — warn when heading content is indented -* [`no-heading-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-indent) — warn when headings are indented -* [`no-heading-like-paragraph`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-like-paragraph) — for too many hashes (h7+ “headings”) -* [`no-heading-punctuation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-punctuation) — warn when headings end in illegal characters -* [`no-html`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-html) — warn when HTML nodes are used -* [`no-inline-padding`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-inline-padding) — warn when inline nodes are padded with spaces -* [`no-literal-urls`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-literal-urls) — warn when URLs without angle brackets are used -* [`no-missing-blank-lines`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-missing-blank-lines) — warn when missing blank lines -* [`no-multiple-toplevel-headings`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-multiple-toplevel-headings) — warn when multiple top level headings are used -* [`no-paragraph-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-paragraph-content-indent) — warn when the content in paragraphs are indented -* [`no-reference-like-url`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-reference-like-url) — warn when URLs are also defined identifiers -* [`no-shell-dollars`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shell-dollars) — warn when shell code is prefixed by dollars -* [`no-shortcut-reference-image`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-image) — warn when shortcut reference images are used -* [`no-shortcut-reference-link`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-link) — warn when shortcut reference links are used -* [`no-table-indentation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-table-indentation) — warn when tables are indented -* [`no-tabs`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-tabs) — warn when hard tabs are used instead of spaces -* [`no-undefined-references`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-undefined-references) — warn when references to undefined definitions are found -* [`no-unneeded-full-reference-image`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-image) — warn when full reference images are used if they can be collapsed -* [`no-unneeded-full-reference-link`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-link) — warn when full reference links are used if they can be collapsed -* [`no-unused-definitions`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unused-definitions) — warn when unused definitions are found -* [`ordered-list-marker-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-style) — warn when the markers of ordered lists violate a given style -* [`ordered-list-marker-value`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-value) — warn when the marker value of ordered lists violates a given style -* [`rule-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-rule-style) — warn when horizontal rules violate a given style -* [`strikethrough-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strikethrough-marker) — warn when strikethrough markers violate the given style -* [`strong-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strong-marker) — warn when importance (strong) markers violate the given style -* [`table-cell-padding`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-cell-padding) — warn when table cells are incorrectly padded -* [`table-pipe-alignment`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipe-alignment) — warn when table pipes are not aligned -* [`table-pipes`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipes) — warn when table rows are not fenced with pipes -* [`unordered-list-marker-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-unordered-list-marker-style) — warn when markers of unordered lists violate a given style - - - -[external]: https://github.com/remarkjs/remark-lint#list-of-external-rules +[rules]: https://github.com/remarkjs/remark-lint#rules diff --git a/logo.svg b/logo.svg index e19ba5f..f94e641 100644 --- a/logo.svg +++ b/logo.svg @@ -1,5 +1,14 @@ - - - - + + + + + + diff --git a/packages/remark-lint-blockquote-indentation/index.js b/packages/remark-lint-blockquote-indentation/index.js index acc8656..d7c74a6 100644 --- a/packages/remark-lint-blockquote-indentation/index.js +++ b/packages/remark-lint-blockquote-indentation/index.js @@ -1,16 +1,46 @@ /** + * ## When should I use this? + * + * You can use this package to check that the “indent” of block quotes is + * consistent. + * Indent here is the `>` (greater than) marker and the spaces before content. + * + * ## API + * + * The following options (default: `'consistent'`) are accepted: + * + * * `number` (example: `2`) + * — preferred indent of `>` and spaces before content + * * `'consistent'` + * — detect the first used style and warn when further block quotes differ + * + * ## Recommendation + * + * CommonMark specifies that when block quotes are used the `>` markers can be + * followed by an optional space. + * No space at all arguably looks rather ugly: + * + * ```markdown + * >Mars and + * >Venus. + * ``` + * + * There is no specific handling of more that one space, so if 5 spaces were + * used after `>`, then indented code kicks in: + * + * ```markdown + * > neptune() + * ``` + * + * Due to this, it’s recommended to configure this rule with `2`. + * + * @module blockquote-indentation + * @summary + * remark-lint rule to warn when block quotes are indented too much or + * too little. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module blockquote-indentation - * @fileoverview - * Warn when block quotes are indented too much or too little. - * - * Options: `number` or `'consistent'`, default: `'consistent'`. - * - * `'consistent'` detects the first used indentation and will warn when - * other block quotes use a different indentation. - * * @example * {"name": "ok.md", "setting": 4} * diff --git a/packages/remark-lint-blockquote-indentation/readme.md b/packages/remark-lint-blockquote-indentation/readme.md index 673c68a..3dd7f90 100644 --- a/packages/remark-lint-blockquote-indentation/readme.md +++ b/packages/remark-lint-blockquote-indentation/readme.md @@ -10,12 +10,35 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when block quotes are indented too much or too little. +[`remark-lint`][mono] rule to warn when block quotes are indented too much or +too little. -Options: `number` or `'consistent'`, default: `'consistent'`. +## Contents -`'consistent'` detects the first used indentation and will warn when -other block quotes use a different indentation. +* [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(remarkLintBlockquoteIndentation[, config])`](#unifieduseremarklintblockquoteindentation-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that the “indent” of block quotes is +consistent. +Indent here is the `>` (greater than) marker and the spaces before content. ## Presets @@ -26,7 +49,111 @@ This rule is included in the following presets: | [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `2` | -## 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-blockquote-indentation +``` + +In Deno with [Skypack][]: + +```js +import remarkLintBlockquoteIndentation from 'https://cdn.skypack.dev/remark-lint-blockquote-indentation@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintBlockquoteIndentation from 'remark-lint-blockquote-indentation' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintBlockquoteIndentation) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-blockquote-indentation example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-blockquote-indentation", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintBlockquoteIndentation`. + +### `unified().use(remarkLintBlockquoteIndentation[, 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: + +* `number` (example: `2`) + — preferred indent of `>` and spaces before content +* `'consistent'` + — detect the first used style and warn when further block quotes differ + +## Recommendation + +CommonMark specifies that when block quotes are used the `>` markers can be +followed by an optional space. +No space at all arguably looks rather ugly: + +```markdown +>Mars and +>Venus. +``` + +There is no specific handling of more that one space, so if 5 spaces were +used after `>`, then indented code kicks in: + +```markdown +> neptune() +``` + +Due to this, it’s recommended to configure this rule with `2`. + +## Examples ##### `ok.md` @@ -87,59 +214,12 @@ Paragraph. 9:3: Add 1 space between block quote and content ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-blockquote-indentation -``` - -This package exports no identifiers. -The default export is `remarkLintBlockquoteIndentation`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-blockquote-indentation", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-blockquote-indentation readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintBlockquoteIndentation from 'remark-lint-blockquote-indentation' - - remark() - .use(remarkLint) -+ .use(remarkLintBlockquoteIndentation) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -181,17 +261,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-checkbox-character-style/index.js b/packages/remark-lint-checkbox-character-style/index.js index 5f685ae..e323c6c 100644 --- a/packages/remark-lint-checkbox-character-style/index.js +++ b/packages/remark-lint-checkbox-character-style/index.js @@ -1,31 +1,41 @@ /** + * ## When should I use this? + * + * You can use this package to check that the style of GFM tasklists is + * consistent. + * + * ## API + * + * The following options (default: `'consistent'`) are accepted: + * + * * `Object` with the following fields: + * * `checked` (`'x'`, `'X'`, or `'consistent'`, default: `'consistent'`) + * — preferred character to use for checked checkboxes + * * `unchecked` (`'·'` (a space), `'»'` (a tab), or `'consistent'`, + * default: `'consistent'`) + * — preferred character to use for unchecked checkboxes + * * `'consistent'` + * — detect the first used styles and warn when further checkboxes differ + * + * ## Recommendation + * + * It’s recommended to set `options.checked` to `'x'` (a lowercase X) as it + * prevents an extra keyboard press and `options.unchecked` to `'·'` (a space) + * to make all checkboxes align. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats checked checkboxes using `'x'` (lowercase X) and unchecked checkboxes + * using `'·'` (a space). + * + * @module checkbox-character-style + * @summary + * remark-lint rule to warn when list item checkboxes violate a given + * style. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module checkbox-character-style - * @fileoverview - * Warn when list item checkboxes violate a given style. - * - * Options: `Object` or `'consistent'`, default: `'consistent'`. - * - * `'consistent'` detects the first used checked and unchecked checkbox - * styles and warns when subsequent checkboxes use different styles. - * - * Styles can also be passed in like so: - * - * ```js - * {checked: 'x', unchecked: ' '} - * ``` - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * formats checked checkboxes using `x` (lowercase X) and unchecked checkboxes - * as `·` (a single space). - * - * 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. - * * @example * {"name": "ok.md", "setting": {"checked": "x"}, "gfm": true} * diff --git a/packages/remark-lint-checkbox-character-style/readme.md b/packages/remark-lint-checkbox-character-style/readme.md index eb472e7..32a06cd 100644 --- a/packages/remark-lint-checkbox-character-style/readme.md +++ b/packages/remark-lint-checkbox-character-style/readme.md @@ -10,27 +10,35 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when list item checkboxes violate a given style. +[`remark-lint`][mono] rule to warn when list item checkboxes violate a given +style. -Options: `Object` or `'consistent'`, default: `'consistent'`. +## Contents -`'consistent'` detects the first used checked and unchecked checkbox -styles and warns when subsequent checkboxes use 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(remarkLintCheckboxCharacterStyle[, config])`](#unifieduseremarklintcheckboxcharacterstyle-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -Styles can also be passed in like so: +## What is this? -```js -{checked: 'x', unchecked: ' '} -``` +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. -## Fix +## When should I use this? -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -formats checked checkboxes using `x` (lowercase X) and unchecked checkboxes -as `·` (a single space). - -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. +You can use this package to check that the style of GFM tasklists is +consistent. ## Presets @@ -40,7 +48,107 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` | -## 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-checkbox-character-style +``` + +In Deno with [Skypack][]: + +```js +import remarkLintCheckboxCharacterStyle from 'https://cdn.skypack.dev/remark-lint-checkbox-character-style@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintCheckboxCharacterStyle from 'remark-lint-checkbox-character-style' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintCheckboxCharacterStyle) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-checkbox-character-style example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-checkbox-character-style", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintCheckboxCharacterStyle`. + +### `unified().use(remarkLintCheckboxCharacterStyle[, 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: + +* `Object` with the following fields: + * `checked` (`'x'`, `'X'`, or `'consistent'`, default: `'consistent'`) + — preferred character to use for checked checkboxes + * `unchecked` (`'·'` (a space), `'»'` (a tab), or `'consistent'`, + default: `'consistent'`) + — preferred character to use for unchecked checkboxes +* `'consistent'` + — detect the first used styles and warn when further checkboxes differ + +## Recommendation + +It’s recommended to set `options.checked` to `'x'` (a lowercase X) as it +prevents an extra keyboard press and `options.unchecked` to `'·'` (a space) +to make all checkboxes align. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats checked checkboxes using `'x'` (lowercase X) and unchecked checkboxes +using `'·'` (a space). + +## Examples ##### `ok.md` @@ -48,7 +156,7 @@ When configured with `{ checked: 'x' }`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown - [x] List item @@ -65,7 +173,7 @@ When configured with `{ checked: 'X' }`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown - [X] List item @@ -82,9 +190,9 @@ When configured with `{ unchecked: ' ' }`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown - [ ] List item @@ -103,9 +211,9 @@ When configured with `{ unchecked: '\t' }`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). -Note: `»` represents a tab. +> 👉 **Note**: `»` represents a tab. ```markdown - [»] List item @@ -120,9 +228,9 @@ No messages. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). -Note: `»` represents a tab. +> 👉 **Note**: `»` represents a tab. ```markdown - [x] List item @@ -158,59 +266,12 @@ When configured with `{ checked: '💩' }`. 1:1: Incorrect checked checkbox marker `💩`: use either `'x'`, or `'X'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-checkbox-character-style -``` - -This package exports no identifiers. -The default export is `remarkLintCheckboxCharacterStyle`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-checkbox-character-style", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-checkbox-character-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 remarkLintCheckboxCharacterStyle from 'remark-lint-checkbox-character-style' - - remark() - .use(remarkLint) -+ .use(remarkLintCheckboxCharacterStyle) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -252,17 +313,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-checkbox-content-indent/index.js b/packages/remark-lint-checkbox-content-indent/index.js index a61f7a0..83223e7 100644 --- a/packages/remark-lint-checkbox-content-indent/index.js +++ b/packages/remark-lint-checkbox-content-indent/index.js @@ -1,11 +1,42 @@ /** + * ## When should I use this? + * + * You can use this package to check that the “indent” after a GFM tasklist + * checkbox is a single space. + * + * ## API + * + * There are no accepted options. + * + * ## Recommendation + * + * GFM allows zero or more spaces and tabs after checkboxes. + * No space at all arguably looks rather ugly: + * + * ```markdown + * * [x]Pluto + * ``` + * + * More that one space is superfluous: + * + * ```markdown + * * [x] Jupiter + * ``` + * + * Due to this, it’s recommended to turn this rule on. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats checkboxes and the content after them with a single space between. + * + * @module checkbox-content-indent + * @summary + * remark-lint rule to warn when GFM tasklist checkboxes are followed by + * more than one space. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module checkbox-content-indent - * @fileoverview - * Warn when list item checkboxes are followed by too much whitespace. - * * @example * {"name": "ok.md", "gfm": true} * diff --git a/packages/remark-lint-checkbox-content-indent/readme.md b/packages/remark-lint-checkbox-content-indent/readme.md index 3494500..762f3cd 100644 --- a/packages/remark-lint-checkbox-content-indent/readme.md +++ b/packages/remark-lint-checkbox-content-indent/readme.md @@ -10,19 +10,148 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when list item checkboxes are followed by too much whitespace. +[`remark-lint`][mono] rule to warn when GFM tasklist checkboxes are followed by +more than one space. + +## Contents + +* [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(remarkLintCheckboxContentIndent[, config])`](#unifieduseremarklintcheckboxcontentindent-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that the “indent” after a GFM tasklist +checkbox is a single space. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-checkbox-content-indent +``` + +In Deno with [Skypack][]: + +```js +import remarkLintCheckboxContentIndent from 'https://cdn.skypack.dev/remark-lint-checkbox-content-indent@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintCheckboxContentIndent from 'remark-lint-checkbox-content-indent' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintCheckboxContentIndent) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-checkbox-content-indent example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-checkbox-content-indent", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintCheckboxContentIndent`. + +### `unified().use(remarkLintCheckboxContentIndent[, 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). + +There are no accepted options. + +## Recommendation + +GFM allows zero or more spaces and tabs after checkboxes. +No space at all arguably looks rather ugly: + +```markdown +* [x]Pluto +``` + +More that one space is superfluous: + +```markdown +* [x] Jupiter +``` + +Due to this, it’s recommended to turn this rule on. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats checkboxes and the content after them with a single space between. + +## Examples ##### `ok.md` ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown - [ ] List item @@ -39,7 +168,7 @@ No messages. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown - [ ] List item @@ -56,59 +185,12 @@ Note: this example uses [GFM][]. 4:7-4:10: Checkboxes should be followed by a single character ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-checkbox-content-indent -``` - -This package exports no identifiers. -The default export is `remarkLintCheckboxContentIndent`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-checkbox-content-indent", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-checkbox-content-indent readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintCheckboxContentIndent from 'remark-lint-checkbox-content-indent' - - remark() - .use(remarkLint) -+ .use(remarkLintCheckboxContentIndent) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -150,17 +232,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-code-block-style/index.js b/packages/remark-lint-code-block-style/index.js index c757c16..a84472c 100644 --- a/packages/remark-lint-code-block-style/index.js +++ b/packages/remark-lint-code-block-style/index.js @@ -1,27 +1,52 @@ /** + * ## When should I use this? + * + * You can use this package to check that code blocks are consistent. + * + * ## API + * + * 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. + * + * @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 - * @module code-block-style - * @fileoverview - * Warn when code blocks do not adhere to a given style. - * - * Options: `'consistent'`, `'fenced'`, or `'indented'`, default: `'consistent'`. - * - * `'consistent'` detects the first used code block style and warns when - * subsequent code blocks uses different styles. - * - * ## Fix - * - * [`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. - * - * 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. * * @example * {"setting": "indented", "name": "ok.md"} diff --git a/packages/remark-lint-code-block-style/readme.md b/packages/remark-lint-code-block-style/readme.md index 2aa06fd..56c3fd3 100644 --- a/packages/remark-lint-code-block-style/readme.md +++ b/packages/remark-lint-code-block-style/readme.md @@ -10,24 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -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 @@ -38,7 +47,120 @@ This rule is included in the following presets: | [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'fenced'` | -## 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 [Skypack][]: + +```js +import remarkLintCodeBlockStyle from 'https://cdn.skypack.dev/remark-lint-code-block-style@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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` @@ -156,59 +278,12 @@ When configured with `'💩'`. 1:1: Incorrect code block style `💩`: use either `'consistent'`, `'fenced'`, or `'indented'` ``` -## 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. - -[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)) - }) -``` +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. ## Contribute @@ -250,17 +325,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-definition-case/index.js b/packages/remark-lint-definition-case/index.js index 093ac12..e1a626d 100644 --- a/packages/remark-lint-definition-case/index.js +++ b/packages/remark-lint-definition-case/index.js @@ -1,11 +1,26 @@ /** + * ## When should I use this? + * + * You can use this package to check that the labels used in definitions + * are lowercase. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Definitions and references are matched together regardless of casing. + * Using uppercase in labels might incorrectly indicate that casing is of + * importance. + * Due to this, it’s recommended to use lowercase and turn this rule on. + * + * @module definition-case + * @summary + * remark-lint rule to warn when definition labels are not lowercase. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module definition-case - * @fileoverview - * Warn when definition labels are not lowercase. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-definition-case/readme.md b/packages/remark-lint-definition-case/readme.md index 5dbc9e8..7f87124 100644 --- a/packages/remark-lint-definition-case/readme.md +++ b/packages/remark-lint-definition-case/readme.md @@ -10,7 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when definition labels are not lowercase. +[`remark-lint`][mono] rule to warn when definition labels are not lowercase. + +## Contents + +* [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(remarkLintDefinitionCase[, config])`](#unifieduseremarklintdefinitioncase-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that the labels used in definitions +are lowercase. ## Presets @@ -20,7 +46,93 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-definition-case +``` + +In Deno with [Skypack][]: + +```js +import remarkLintDefinitionCase from 'https://cdn.skypack.dev/remark-lint-definition-case@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintDefinitionCase from 'remark-lint-definition-case' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintDefinitionCase) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-definition-case example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-definition-case", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintDefinitionCase`. + +### `unified().use(remarkLintDefinitionCase[, 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). + +There are no options. + +## Recommendation + +Definitions and references are matched together regardless of casing. +Using uppercase in labels might incorrectly indicate that casing is of +importance. +Due to this, it’s recommended to use lowercase and turn this rule on. + +## Examples ##### `ok.md` @@ -48,59 +160,12 @@ No messages. 1:1-1:47: Do not use uppercase characters in definition labels ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-definition-case -``` - -This package exports no identifiers. -The default export is `remarkLintDefinitionCase`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-definition-case", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-definition-case readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintDefinitionCase from 'remark-lint-definition-case' - - remark() - .use(remarkLint) -+ .use(remarkLintDefinitionCase) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -142,17 +207,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-definition-spacing/index.js b/packages/remark-lint-definition-spacing/index.js index e54e10f..a340376 100644 --- a/packages/remark-lint-definition-spacing/index.js +++ b/packages/remark-lint-definition-spacing/index.js @@ -1,11 +1,28 @@ /** + * ## When should I use this? + * + * You can use this package to check that the labels used in definitions + * do not use meaningless white space. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Definitions and references are matched together by collapsing white space. + * Using more white space in labels might incorrectly indicate that they are of + * importance. + * Due to this, it’s recommended to use one space (or a line ending if needed) + * and turn this rule on. + * + * @module definition-spacing + * @summary + * remark-lint rule to warn when consecutive whitespace is used in + * a definition label. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module definition-spacing - * @fileoverview - * Warn when consecutive whitespace is used in a definition. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-definition-spacing/readme.md b/packages/remark-lint-definition-spacing/readme.md index 91e26f5..047cb4a 100644 --- a/packages/remark-lint-definition-spacing/readme.md +++ b/packages/remark-lint-definition-spacing/readme.md @@ -10,7 +10,34 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when consecutive whitespace is used in a definition. +[`remark-lint`][mono] rule to warn when consecutive whitespace is used in +a definition label. + +## Contents + +* [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(remarkLintDefinitionSpacing[, config])`](#unifieduseremarklintdefinitionspacing-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that the labels used in definitions +do not use meaningless white space. ## Presets @@ -20,7 +47,94 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-definition-spacing +``` + +In Deno with [Skypack][]: + +```js +import remarkLintDefinitionSpacing from 'https://cdn.skypack.dev/remark-lint-definition-spacing@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintDefinitionSpacing from 'remark-lint-definition-spacing' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintDefinitionSpacing) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-definition-spacing example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-definition-spacing", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintDefinitionSpacing`. + +### `unified().use(remarkLintDefinitionSpacing[, 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). + +There are no options. + +## Recommendation + +Definitions and references are matched together by collapsing white space. +Using more white space in labels might incorrectly indicate that they are of +importance. +Due to this, it’s recommended to use one space (or a line ending if needed) +and turn this rule on. + +## Examples ##### `ok.md` @@ -38,7 +152,7 @@ No messages. ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown [example····domain]: http://example.com "Example Domain" @@ -50,59 +164,12 @@ Note: `·` represents a space. 1:1-1:57: Do not use consecutive whitespace in definition labels ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-definition-spacing -``` - -This package exports no identifiers. -The default export is `remarkLintDefinitionSpacing`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-definition-spacing", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-definition-spacing readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintDefinitionSpacing from 'remark-lint-definition-spacing' - - remark() - .use(remarkLint) -+ .use(remarkLintDefinitionSpacing) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -144,17 +211,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-emphasis-marker/index.js b/packages/remark-lint-emphasis-marker/index.js index ca32455..2a9671e 100644 --- a/packages/remark-lint-emphasis-marker/index.js +++ b/packages/remark-lint-emphasis-marker/index.js @@ -1,27 +1,44 @@ /** + * ## When should I use this? + * + * You can use this package to check that emphasis markers are consistent. + * + * ## API + * + * The following options (default: `'consistent'`) are accepted: + * + * * `'*'` + * — prefer asterisks + * * `'_'` + * — prefer underscores + * * `'consistent'` + * — detect the first used style and warn when further emphasis differs + * + * ## Recommendation + * + * Underscores and asterisks work slightly different: asterisks can form + * emphasis in more cases than underscores. + * Because underscores are sometimes used to represent normal underscores inside + * words, there are extra rules supporting that. + * Asterisks can also be used as the marker of more constructs than underscores: + * lists. + * Due to having simpler parsing rules, looking more like syntax, and that they + * can be used for more constructs, it’s recommended to prefer asterisks. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats emphasis with asterisks by default. + * Pass + * [`emphasis: '_'`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsemphasis) + * to always use underscores. + * + * @module emphasis-marker + * @summary + * remark-lint rule to warn when emphasis markers are inconsistent. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module emphasis-marker - * @fileoverview - * Warn for violating emphasis markers. - * - * Options: `'consistent'`, `'*'`, or `'_'`, default: `'consistent'`. - * - * `'consistent'` detects the first used emphasis style and warns when - * subsequent emphasis use different styles. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * formats emphasis using `_` (underscore) by default. - * Pass - * [`emphasis: '*'`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsemphasis) - * to use `*` (asterisk) instead. - * - * 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. - * * @example * {"setting": "*", "name": "ok.md"} * diff --git a/packages/remark-lint-emphasis-marker/readme.md b/packages/remark-lint-emphasis-marker/readme.md index f3892b1..28ee727 100644 --- a/packages/remark-lint-emphasis-marker/readme.md +++ b/packages/remark-lint-emphasis-marker/readme.md @@ -10,23 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn for violating emphasis markers. +[`remark-lint`][mono] rule to warn when emphasis markers are inconsistent. -Options: `'consistent'`, `'*'`, or `'_'`, default: `'consistent'`. +## Contents -`'consistent'` detects the first used emphasis style and warns when -subsequent emphasis use 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(remarkLintEmphasisMarker[, config])`](#unifieduseremarklintemphasismarker-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 emphasis using `_` (underscore) by default. -Pass -[`emphasis: '*'`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsemphasis) -to use `*` (asterisk) instead. +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 emphasis markers are consistent. ## Presets @@ -37,7 +47,112 @@ This rule is included in the following presets: | [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'*'` | -## 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-emphasis-marker +``` + +In Deno with [Skypack][]: + +```js +import remarkLintEmphasisMarker from 'https://cdn.skypack.dev/remark-lint-emphasis-marker@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintEmphasisMarker from 'remark-lint-emphasis-marker' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintEmphasisMarker) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-emphasis-marker example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-emphasis-marker", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintEmphasisMarker`. + +### `unified().use(remarkLintEmphasisMarker[, 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: + +* `'*'` + — prefer asterisks +* `'_'` + — prefer underscores +* `'consistent'` + — detect the first used style and warn when further emphasis differs + +## Recommendation + +Underscores and asterisks work slightly different: asterisks can form +emphasis in more cases than underscores. +Because underscores are sometimes used to represent normal underscores inside +words, there are extra rules supporting that. +Asterisks can also be used as the marker of more constructs than underscores: +lists. +Due to having simpler parsing rules, looking more like syntax, and that they +can be used for more constructs, it’s recommended to prefer asterisks. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats emphasis with asterisks by default. +Pass +[`emphasis: '_'`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsemphasis) +to always use underscores. + +## Examples ##### `ok.md` @@ -124,59 +239,12 @@ When configured with `'💩'`. 1:1: Incorrect emphasis marker `💩`: use either `'consistent'`, `'*'`, or `'_'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-emphasis-marker -``` - -This package exports no identifiers. -The default export is `remarkLintEmphasisMarker`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-emphasis-marker", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-emphasis-marker readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintEmphasisMarker from 'remark-lint-emphasis-marker' - - remark() - .use(remarkLint) -+ .use(remarkLintEmphasisMarker) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -218,17 +286,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-fenced-code-flag/index.js b/packages/remark-lint-fenced-code-flag/index.js index d07adfa..316fcd9 100644 --- a/packages/remark-lint-fenced-code-flag/index.js +++ b/packages/remark-lint-fenced-code-flag/index.js @@ -1,19 +1,34 @@ /** + * ## When should I use this? + * + * You can use this package to check that language flags of fenced code + * are used and consistent. + * + * ## API + * + * The following options (default: `undefined`) are accepted: + * + * * `Array` + * — as if passing `{flags: options}` + * * `Object` with the following fields: + * * `allowEmpty` (`boolean`, default: `false`) + * — allow language flags to be omitted + * * `flags` (`Array` default: `[]`) + * — specific flags to allow (other flags will result in a warning) + * + * ## Recommendation + * + * While omitting the language flag is perfectly fine to signal that the code is + * plain text, it *could* point to a mistake. + * It’s recommended to instead use a certain flag for plain text (such as `txt`) + * and to turn this rule on. + * + * @module fenced-code-flag + * @summary + * remark-lint rule to check that language flags of fenced code are used. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module fenced-code-flag - * @fileoverview - * Check fenced code block flags. - * - * Options: `Array` or `Object`, optional. - * - * Providing an array is as passing `{flags: Array}`. - * - * The object can have an array of `'flags'` which are allowed: other flags - * will not be allowed. - * An `allowEmpty` field (`boolean`, default: `false`) can be set to allow - * code blocks without language flags. * * @example * {"name": "ok.md"} diff --git a/packages/remark-lint-fenced-code-flag/readme.md b/packages/remark-lint-fenced-code-flag/readme.md index f5238a7..346e1be 100644 --- a/packages/remark-lint-fenced-code-flag/readme.md +++ b/packages/remark-lint-fenced-code-flag/readme.md @@ -10,16 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Check fenced code block flags. +[`remark-lint`][mono] rule to check that language flags of fenced code are used. -Options: `Array` or `Object`, optional. +## Contents -Providing an array is as passing `{flags: Array}`. +* [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(remarkLintFencedCodeFlag[, config])`](#unifieduseremarklintfencedcodeflag-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -The object can have an array of `'flags'` which are allowed: other flags -will not be allowed. -An `allowEmpty` field (`boolean`, default: `false`) can be set to allow -code blocks without language flags. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that language flags of fenced code +are used and consistent. ## Presets @@ -29,7 +46,101 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `{ allowEmpty: false }` | -## 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-fenced-code-flag +``` + +In Deno with [Skypack][]: + +```js +import remarkLintFencedCodeFlag from 'https://cdn.skypack.dev/remark-lint-fenced-code-flag@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintFencedCodeFlag from 'remark-lint-fenced-code-flag' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintFencedCodeFlag) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-fenced-code-flag example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-fenced-code-flag", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintFencedCodeFlag`. + +### `unified().use(remarkLintFencedCodeFlag[, 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: `undefined`) are accepted: + +* `Array` + — as if passing `{flags: options}` +* `Object` with the following fields: + * `allowEmpty` (`boolean`, default: `false`) + — allow language flags to be omitted + * `flags` (`Array` default: `[]`) + — specific flags to allow (other flags will result in a warning) + +## Recommendation + +While omitting the language flag is perfectly fine to signal that the code is +plain text, it *could* point to a mistake. +It’s recommended to instead use a certain flag for plain text (such as `txt`) +and to turn this rule on. + +## Examples ##### `ok.md` @@ -145,59 +256,12 @@ bravo() 1:1-3:4: Incorrect code language flag ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-fenced-code-flag -``` - -This package exports no identifiers. -The default export is `remarkLintFencedCodeFlag`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-fenced-code-flag", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-fenced-code-flag readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintFencedCodeFlag from 'remark-lint-fenced-code-flag' - - remark() - .use(remarkLint) -+ .use(remarkLintFencedCodeFlag) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -239,17 +303,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-fenced-code-marker/index.js b/packages/remark-lint-fenced-code-marker/index.js index 01c5eae..118f493 100644 --- a/packages/remark-lint-fenced-code-marker/index.js +++ b/packages/remark-lint-fenced-code-marker/index.js @@ -1,27 +1,38 @@ /** + * ## When should I use this? + * + * You can use this package to check that fenced code markers are consistent. + * + * ## API + * + * The following options (default: `'consistent'`) are accepted: + * + * * ``'`'`` + * — prefer grave accents + * * `'~'` + * — prefer tildes + * * `'consistent'` + * — detect the first used style and warn when further fenced code differs + * + * ## Recommendation + * + * Tildes are extremely uncommon. + * Due to this, it’s recommended to configure this rule with ``'`'``. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats fenced code with grave accents by default. + * Pass + * [`fence: '~'`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsfence) + * to always use tildes. + * + * @module fenced-code-marker + * @summary + * remark-lint rule to warn when fenced code markers are inconsistent. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module fenced-code-marker - * @fileoverview - * Warn for violating fenced code markers. - * - * Options: `` '`' ``, `'~'`, or `'consistent'`, default: `'consistent'`. - * - * `'consistent'` detects the first used fenced code marker style and warns - * when subsequent fenced code blocks use different styles. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * formats fences using ``'`'`` (grave accent) by default. - * Pass - * [`fence: '~'`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsfence) - * to use `~` (tilde) instead. - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-fenced-code-marker/readme.md b/packages/remark-lint-fenced-code-marker/readme.md index 85556fa..981fa45 100644 --- a/packages/remark-lint-fenced-code-marker/readme.md +++ b/packages/remark-lint-fenced-code-marker/readme.md @@ -10,23 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn for violating fenced code markers. +[`remark-lint`][mono] rule to warn when fenced code markers are inconsistent. -Options: ``'`'``, `'~'`, or `'consistent'`, default: `'consistent'`. +## Contents -`'consistent'` detects the first used fenced code marker style and warns -when subsequent fenced code blocks use 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(remarkLintFencedCodeMarker[, config])`](#unifieduseremarklintfencedcodemarker-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 fences using ``'`'`` (grave accent) by default. -Pass -[`fence: '~'`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsfence) -to use `~` (tilde) instead. +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 fenced code markers are consistent. ## Presets @@ -37,7 +47,106 @@ This rule is included in the following presets: | [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | ``'`'`` | -## 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-fenced-code-marker +``` + +In Deno with [Skypack][]: + +```js +import remarkLintFencedCodeMarker from 'https://cdn.skypack.dev/remark-lint-fenced-code-marker@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintFencedCodeMarker from 'remark-lint-fenced-code-marker' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintFencedCodeMarker) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-fenced-code-marker example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-fenced-code-marker", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintFencedCodeMarker`. + +### `unified().use(remarkLintFencedCodeMarker[, 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: + +* ``'`'`` + — prefer grave accents +* `'~'` + — prefer tildes +* `'consistent'` + — detect the first used style and warn when further fenced code differs + +## Recommendation + +Tildes are extremely uncommon. +Due to this, it’s recommended to configure this rule with ``'`'``. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats fenced code with grave accents by default. +Pass +[`fence: '~'`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsfence) +to always use tildes. + +## Examples ##### `ok.md` @@ -143,59 +252,12 @@ When configured with `'💩'`. 1:1: Incorrect fenced code marker `💩`: use either `'consistent'`, `` '`' ``, or `'~'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-fenced-code-marker -``` - -This package exports no identifiers. -The default export is `remarkLintFencedCodeMarker`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-fenced-code-marker", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-fenced-code-marker readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintFencedCodeMarker from 'remark-lint-fenced-code-marker' - - remark() - .use(remarkLint) -+ .use(remarkLintFencedCodeMarker) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -237,17 +299,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-file-extension/index.js b/packages/remark-lint-file-extension/index.js index 2b8499d..5b4bd0a 100644 --- a/packages/remark-lint-file-extension/index.js +++ b/packages/remark-lint-file-extension/index.js @@ -1,16 +1,31 @@ /** + * ## When should I use this? + * + * You can use this package to check that file extensions are `md`. + * + * ## API + * + * The following options (default: `'md'`) are accepted: + * + * * `string` (example `'markdown'`) + * — preferred file extension (no dot) + * + * > 👉 **Note**: does not warn when files have no file extensions (such as + * > `AUTHORS` or `LICENSE`). + * + * ## Recommendation + * + * Use `md` as it’s the most common. + * Also use `md` when your markdown contains common syntax extensions (such as + * GFM, frontmatter, or math). + * Do not use `md` for MDX: use `mdx` instead. + * + * @module file-extension + * @summary + * remark-lint rule to check the file extension. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module file-extension - * @fileoverview - * Warn when the file extension differ from the preferred extension. - * - * Does not warn when given documents have no file extensions (such as - * `AUTHORS` or `LICENSE`). - * - * Options: `string`, default: `'md'` — Expected file extension. - * * @example * {"name": "readme.md"} * diff --git a/packages/remark-lint-file-extension/readme.md b/packages/remark-lint-file-extension/readme.md index 9aca8f0..c7cadb4 100644 --- a/packages/remark-lint-file-extension/readme.md +++ b/packages/remark-lint-file-extension/readme.md @@ -10,12 +10,32 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when the file extension differ from the preferred extension. +[`remark-lint`][mono] rule to check the file extension. -Does not warn when given documents have no file extensions (such as -`AUTHORS` or `LICENSE`). +## Contents -Options: `string`, default: `'md'` — Expected file extension. +* [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(remarkLintFileExtension[, config])`](#unifieduseremarklintfileextension-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that file extensions are `md`. ## Presets @@ -25,7 +45,99 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'md'` | -## 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-file-extension +``` + +In Deno with [Skypack][]: + +```js +import remarkLintFileExtension from 'https://cdn.skypack.dev/remark-lint-file-extension@2?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintFileExtension from 'remark-lint-file-extension' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintFileExtension) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-file-extension example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-file-extension", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintFileExtension`. + +### `unified().use(remarkLintFileExtension[, 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: `'md'`) are accepted: + +* `string` (example `'markdown'`) + — preferred file extension (no dot) + +> 👉 **Note**: does not warn when files have no file extensions (such as +> `AUTHORS` or `LICENSE`). + +## Recommendation + +Use `md` as it’s the most common. +Also use `md` when your markdown contains common syntax extensions (such as +GFM, frontmatter, or math). +Do not use `md` for MDX: use `mdx` instead. + +## Examples ##### `readme.md` @@ -55,59 +167,12 @@ When configured with `'mkd'`. No messages. -## 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. - -[npm][]: - -```sh -npm install remark-lint-file-extension -``` - -This package exports no identifiers. -The default export is `remarkLintFileExtension`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-file-extension", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-file-extension readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintFileExtension from 'remark-lint-file-extension' - - remark() - .use(remarkLint) -+ .use(remarkLintFileExtension) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -149,17 +214,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-final-definition/index.js b/packages/remark-lint-final-definition/index.js index ddb9b6c..5e93e3c 100644 --- a/packages/remark-lint-final-definition/index.js +++ b/packages/remark-lint-final-definition/index.js @@ -1,12 +1,26 @@ /** + * ## When should I use this? + * + * You can use this package to check that definitions are placed at the end of + * the document. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * There are different strategies for placing definitions. + * The simplest is perhaps to place them all at the bottem of documents. + * If you prefer that, turn on this rule. + * + * @module final-definition + * @summary + * remark-lint rule to warn when definitions are used *in* the document + * instead of at the end. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module final-definition - * @fileoverview - * Warn when definitions are placed somewhere other than at the end of - * the file. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-final-definition/readme.md b/packages/remark-lint-final-definition/readme.md index dde8a82..1e963fb 100644 --- a/packages/remark-lint-final-definition/readme.md +++ b/packages/remark-lint-final-definition/readme.md @@ -10,8 +10,34 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when definitions are placed somewhere other than at the end of -the file. +[`remark-lint`][mono] rule to warn when definitions are used *in* the document +instead of at the end. + +## Contents + +* [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(remarkLintFinalDefinition[, config])`](#unifieduseremarklintfinaldefinition-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that definitions are placed at the end of +the document. ## Presets @@ -21,7 +47,92 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-final-definition +``` + +In Deno with [Skypack][]: + +```js +import remarkLintFinalDefinition from 'https://cdn.skypack.dev/remark-lint-final-definition@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintFinalDefinition from 'remark-lint-final-definition' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintFinalDefinition) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-final-definition example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-final-definition", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintFinalDefinition`. + +### `unified().use(remarkLintFinalDefinition[, 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). + +There are no options. + +## Recommendation + +There are different strategies for placing definitions. +The simplest is perhaps to place them all at the bottem of documents. +If you prefer that, turn on this rule. + +## Examples ##### `ok.md` @@ -73,59 +184,12 @@ Paragraph. No messages. -## 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. - -[npm][]: - -```sh -npm install remark-lint-final-definition -``` - -This package exports no identifiers. -The default export is `remarkLintFinalDefinition`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-final-definition", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-final-definition readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintFinalDefinition from 'remark-lint-final-definition' - - remark() - .use(remarkLint) -+ .use(remarkLintFinalDefinition) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -167,17 +231,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-final-newline/index.js b/packages/remark-lint-final-newline/index.js index d663333..49fb4cc 100644 --- a/packages/remark-lint-final-newline/index.js +++ b/packages/remark-lint-final-newline/index.js @@ -1,53 +1,61 @@ /** + * ## When should I use this? + * + * You can use this package to check that fenced code markers are consistent. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Turn this rule on. + * See [StackExchange](https://unix.stackexchange.com/questions/18743) for more + * info. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * always adds final line endings. + * + * ## Example + * + * ##### `ok.md` + * + * ###### In + * + * > 👉 **Note**: `␊` represents a line feed (`\n`). + * + * ```markdown + * Alpha␊ + * ``` + * + * ###### Out + * + * No messages. + * + * ##### `not-ok.md` + * + * ###### In + * + * > 👉 **Note**: `␀` represents the end of the file. + * + * ```markdown + * Bravo␀ + * ``` + * + * ###### Out + * + * ```text + * 1:1: Missing newline character at end of file + * ``` + * + * @module final-newline + * @summary + * remark-lint rule to warn when files don’t end in a newline. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module final-newline - * @fileoverview - * Warn when a line feed at the end of a file is missing. - * Empty files are allowed. - * - * See [StackExchange](https://unix.stackexchange.com/questions/18743) for why. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * always adds a final line feed to files. - * - * 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. - * - * ## Example - * - * ##### `ok.md` - * - * ###### In - * - * Note: `␊` represents LF. - * - * ```markdown - * Alpha␊ - * ``` - * - * ###### Out - * - * No messages. - * - * ##### `not-ok.md` - * - * ###### In - * - * Note: The below file does not have a final newline. - * - * ```markdown - * Bravo - * ``` - * - * ###### Out - * - * ```text - * 1:1: Missing newline character at end of file - * ``` */ /** diff --git a/packages/remark-lint-final-newline/readme.md b/packages/remark-lint-final-newline/readme.md index 5c89acf..afa5c69 100644 --- a/packages/remark-lint-final-newline/readme.md +++ b/packages/remark-lint-final-newline/readme.md @@ -10,18 +10,131 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when a line feed at the end of a file is missing. -Empty files are allowed. +[`remark-lint`][mono] rule to warn when files don’t end in a newline. -See [StackExchange](https://unix.stackexchange.com/questions/18743) for why. +## Contents + +* [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(remarkLintFinalNewline[, config])`](#unifieduseremarklintfinalnewline-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Example](#example) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that fenced code markers are consistent. + +## Presets + +This rule is included in the following presets: + +| Preset | Setting | +| - | - | +| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | + +## 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-final-newline +``` + +In Deno with [Skypack][]: + +```js +import remarkLintFinalNewline from 'https://cdn.skypack.dev/remark-lint-final-newline@2?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintFinalNewline from 'remark-lint-final-newline' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintFinalNewline) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-final-newline example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-final-newline", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintFinalNewline`. + +### `unified().use(remarkLintFinalNewline[, 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). + +There are no options. + +## Recommendation + +Turn this rule on. +See [StackExchange](https://unix.stackexchange.com/questions/18743) for more +info. ## Fix -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -always adds a final line feed to files. - -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. +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +always adds final line endings. ## Example @@ -29,7 +142,7 @@ on how to automatically fix warnings for this rule. ###### In -Note: `␊` represents LF. +> 👉 **Note**: `␊` represents a line feed (`\n`). ```markdown Alpha␊ @@ -43,10 +156,10 @@ No messages. ###### In -Note: The below file does not have a final newline. +> 👉 **Note**: `␀` represents the end of the file. ```markdown -Bravo +Bravo␀ ``` ###### Out @@ -55,67 +168,12 @@ Bravo 1:1: Missing newline character at end of file ``` -## Presets +## Compatibility -This rule is included in the following presets: - -| Preset | Setting | -| - | - | -| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | - -## Install - -This package is [ESM only][esm]: -Node 12+ is needed to use it and it must be `imported`ed instead of `required`d. - -[npm][]: - -```sh -npm install remark-lint-final-newline -``` - -This package exports no identifiers. -The default export is `remarkLintFinalNewline`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-final-newline", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-final-newline readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintFinalNewline from 'remark-lint-final-newline' - - remark() - .use(remarkLint) -+ .use(remarkLintFinalNewline) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -157,17 +215,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-first-heading-level/index.js b/packages/remark-lint-first-heading-level/index.js index 7e86288..dbcf1d5 100644 --- a/packages/remark-lint-first-heading-level/index.js +++ b/packages/remark-lint-first-heading-level/index.js @@ -1,13 +1,29 @@ /** + * ## When should I use this? + * + * You can use this package to check the heading rank of the first heading. + * + * ## API + * + * The following options (default: `1`) are accepted: + * + * * `number` (example `1`) + * — expected rank of first heading + * + * ## Recommendation + * + * In most cases you’d want to first heading in a markdown document to start at + * rank 1. + * In some cases a different rank makes more sense, such as when building a blog + * and generating the primary heading from frontmatter metadata, in which case + * a value of `2` can be defined here. + * + * @module first-heading-level + * @summary + * remark-lint rule to warn when the first heading has an unexpected rank. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module first-heading-level - * @fileoverview - * Warn when the first heading has a level other than a specified value. - * - * Options: `number`, default: `1`. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-first-heading-level/readme.md b/packages/remark-lint-first-heading-level/readme.md index f7a237c..c660081 100644 --- a/packages/remark-lint-first-heading-level/readme.md +++ b/packages/remark-lint-first-heading-level/readme.md @@ -10,15 +10,128 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when the first heading has a level other than a specified value. +[`remark-lint`][mono] rule to warn when the first heading has an unexpected rank. -Options: `number`, default: `1`. +## Contents + +* [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(remarkLintFirstHeadingLevel[, config])`](#unifieduseremarklintfirstheadinglevel-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check the heading rank of the first heading. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-first-heading-level +``` + +In Deno with [Skypack][]: + +```js +import remarkLintFirstHeadingLevel from 'https://cdn.skypack.dev/remark-lint-first-heading-level@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintFirstHeadingLevel from 'remark-lint-first-heading-level' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintFirstHeadingLevel) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-first-heading-level example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-first-heading-level", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintFirstHeadingLevel`. + +### `unified().use(remarkLintFirstHeadingLevel[, 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: `1`) are accepted: + +* `number` (example `1`) + — expected rank of first heading + +## Recommendation + +In most cases you’d want to first heading in a markdown document to start at +rank 1. +In some cases a different rank makes more sense, such as when building a blog +and generating the primary heading from frontmatter metadata, in which case +a value of `2` can be defined here. + +## Examples ##### `ok.md` @@ -160,59 +273,12 @@ Paragraph. 1:1-1:17: First heading level should be `1` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-first-heading-level -``` - -This package exports no identifiers. -The default export is `remarkLintFirstHeadingLevel`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-first-heading-level", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-first-heading-level readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintFirstHeadingLevel from 'remark-lint-first-heading-level' - - remark() - .use(remarkLint) -+ .use(remarkLintFirstHeadingLevel) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -254,17 +320,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-hard-break-spaces/index.js b/packages/remark-lint-hard-break-spaces/index.js index 7892a33..4c29325 100644 --- a/packages/remark-lint-hard-break-spaces/index.js +++ b/packages/remark-lint-hard-break-spaces/index.js @@ -1,11 +1,26 @@ /** + * ## When should I use this? + * + * You can use this package to check that hard breaks use two spaces and + * not more. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Less than two spaces do not create a hard breaks and more than two spaces + * have no effect. + * Due to this, it’s recommended to turn this rule on. + * + * @module hard-break-spaces + * @summary + * remark-lint rule to warn when more spaces are used than needed + * for hard breaks. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module hard-break-spaces - * @fileoverview - * Warn when too many spaces are used to create a hard break. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-hard-break-spaces/readme.md b/packages/remark-lint-hard-break-spaces/readme.md index c207b25..3200134 100644 --- a/packages/remark-lint-hard-break-spaces/readme.md +++ b/packages/remark-lint-hard-break-spaces/readme.md @@ -10,7 +10,34 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when too many spaces are used to create a hard break. +[`remark-lint`][mono] rule to warn when more spaces are used than needed +for hard breaks. + +## Contents + +* [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(remarkLintHardBreakSpaces[, config])`](#unifieduseremarklinthardbreakspaces-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that hard breaks use two spaces and +not more. ## Presets @@ -21,13 +48,98 @@ This rule is included in the following presets: | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | -## 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-hard-break-spaces +``` + +In Deno with [Skypack][]: + +```js +import remarkLintHardBreakSpaces from 'https://cdn.skypack.dev/remark-lint-hard-break-spaces@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintHardBreakSpaces from 'remark-lint-hard-break-spaces' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintHardBreakSpaces) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-hard-break-spaces example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-hard-break-spaces", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintHardBreakSpaces`. + +### `unified().use(remarkLintHardBreakSpaces[, 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). + +There are no options. + +## Recommendation + +Less than two spaces do not create a hard breaks and more than two spaces +have no effect. +Due to this, it’s recommended to turn this rule on. + +## Examples ##### `ok.md` ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown Lorem ipsum·· @@ -42,7 +154,7 @@ No messages. ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown Lorem ipsum··· @@ -55,59 +167,12 @@ dolor sit amet. 1:12-2:1: Use two spaces for hard line breaks ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-hard-break-spaces -``` - -This package exports no identifiers. -The default export is `remarkLintHardBreakSpaces`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-hard-break-spaces", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-hard-break-spaces readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintHardBreakSpaces from 'remark-lint-hard-break-spaces' - - remark() - .use(remarkLint) -+ .use(remarkLintHardBreakSpaces) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -149,17 +214,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-heading-increment/index.js b/packages/remark-lint-heading-increment/index.js index 5fd2e20..c4634ea 100644 --- a/packages/remark-lint-heading-increment/index.js +++ b/packages/remark-lint-heading-increment/index.js @@ -1,11 +1,30 @@ /** + * ## When should I use this? + * + * You can use this package to check that heading ranks increment with one + * at a time. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * While markdown is not only used for HTML, HTML accessibility guidelines + * state that headings should increment by one at a time. + * As in, say the previous heading had a rank of 2 (so `

`), then the + * following heading that is to be considered “inside” it should have a rank of + * 3 (`

`). + * Due to this, it’s recommended that when HTML output is a goal of the + * document, that this rule is turned on. + * + * @module heading-increment + * @summary + * remark-lint rule to warn when heading ranks increment with more than + * 1 at a time. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module heading-increment - * @fileoverview - * Warn when headings increment with more than 1 level at a time. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-heading-increment/readme.md b/packages/remark-lint-heading-increment/readme.md index 9a3593a..fbbcc2f 100644 --- a/packages/remark-lint-heading-increment/readme.md +++ b/packages/remark-lint-heading-increment/readme.md @@ -10,7 +10,34 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when headings increment with more than 1 level at a time. +[`remark-lint`][mono] rule to warn when heading ranks increment with more than +1 at a time. + +## Contents + +* [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(remarkLintHeadingIncrement[, config])`](#unifieduseremarklintheadingincrement-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that heading ranks increment with one +at a time. ## Presets @@ -20,7 +47,96 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-heading-increment +``` + +In Deno with [Skypack][]: + +```js +import remarkLintHeadingIncrement from 'https://cdn.skypack.dev/remark-lint-heading-increment@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintHeadingIncrement from 'remark-lint-heading-increment' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintHeadingIncrement) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-heading-increment example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-heading-increment", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintHeadingIncrement`. + +### `unified().use(remarkLintHeadingIncrement[, 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). + +There are no options. + +## Recommendation + +While markdown is not only used for HTML, HTML accessibility guidelines +state that headings should increment by one at a time. +As in, say the previous heading had a rank of 2 (so `

`), then the +following heading that is to be considered “inside” it should have a rank of +3 (`

`). +Due to this, it’s recommended that when HTML output is a goal of the +document, that this rule is turned on. + +## Examples ##### `ok.md` @@ -52,59 +168,12 @@ No messages. 3:1-3:10: Heading levels should increment by one level at a time ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-heading-increment -``` - -This package exports no identifiers. -The default export is `remarkLintHeadingIncrement`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-heading-increment", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-heading-increment readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintHeadingIncrement from 'remark-lint-heading-increment' - - remark() - .use(remarkLint) -+ .use(remarkLintHeadingIncrement) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -146,17 +215,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-heading-style/index.js b/packages/remark-lint-heading-style/index.js index 429d84f..f2d2b91 100644 --- a/packages/remark-lint-heading-style/index.js +++ b/packages/remark-lint-heading-style/index.js @@ -1,30 +1,66 @@ /** + * ## When should I use this? + * + * You can use this package to check that headings are consistent. + * + * ## API + * + * The following options (default: `'consistent'`) are accepted: + * + * * `'atx'` + * — prefer ATX headings: + * ```markdown + * ## Hello + * ``` + * * `'atx-closed'` + * — prefer ATX headings with a closing sequence: + * ```markdown + * ## Hello ## + * ``` + * * `'setext'` + * — prefer setext headings: + * ```markdown + * Hello + * ----- + * ``` + * * `'consistent'` + * — detect the first used style and warn when further headings differ + * + * ## Recommendation + * + * Setext headings are limited in that they can only construct headings with a + * rank of one and two. + * On the other hand, they do allow multiple lines of content whereas ATX only + * allows one line. + * The number of used markers in their underline does not matter, leading to + * either: + * + * * 1 marker (`Hello\n-`), which is the bare minimum, and for rank 2 headings + * looks suspiciously like an empty list item + * * using as many markers as the content (`Hello\n-----`), which is hard to + * maintain + * * an arbitrary number (`Hello\n---`), which for rank 2 headings looks + * suspiciously like a thematic break + * + * Setext headings are also rather uncommon. + * Using a sequence of hashes at the end of ATX headings is even more uncommon. + * Due to this, it’s recommended to prefer ATX headings. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats headings as ATX by default. + * The other styles can be configured with + * [`setext: true`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionssetext) + * or + * [`closeAtx: true`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionscloseatx). + * + * @module heading-style + * @summary + * remark-lint rule to warn when headings violate a given style. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module heading-style - * @fileoverview - * Warn when a heading does not conform to a given style. - * - * Options: `'consistent'`, `'atx'`, `'atx-closed'`, or `'setext'`, - * default: `'consistent'`. - * - * `'consistent'` detects the first used heading style and warns when - * subsequent headings use different styles. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * formats headings as ATX by default. - * This can be configured with the - * [`setext`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionssetext) - * and - * [`closeAtx`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionscloseatx) - * options. - * - * 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. - * * @example * {"name": "ok.md", "setting": "atx"} * diff --git a/packages/remark-lint-heading-style/readme.md b/packages/remark-lint-heading-style/readme.md index 680df30..1eaa254 100644 --- a/packages/remark-lint-heading-style/readme.md +++ b/packages/remark-lint-heading-style/readme.md @@ -10,26 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when a heading does not conform to a given style. +[`remark-lint`][mono] rule to warn when headings violate a given style. -Options: `'consistent'`, `'atx'`, `'atx-closed'`, or `'setext'`, -default: `'consistent'`. +## Contents -`'consistent'` detects the first used heading style and warns when -subsequent headings use 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(remarkLintHeadingStyle[, config])`](#unifieduseremarklintheadingstyle-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 headings as ATX by default. -This can be configured with the -[`setext`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionssetext) -and -[`closeAtx`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionscloseatx) -options. +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 headings are consistent. ## Presets @@ -40,7 +47,134 @@ This rule is included in the following presets: | [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'atx'` | -## 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-heading-style +``` + +In Deno with [Skypack][]: + +```js +import remarkLintHeadingStyle from 'https://cdn.skypack.dev/remark-lint-heading-style@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintHeadingStyle from 'remark-lint-heading-style' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintHeadingStyle) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-heading-style example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-heading-style", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintHeadingStyle`. + +### `unified().use(remarkLintHeadingStyle[, 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: + +* `'atx'` + — prefer ATX headings: + ```markdown + ## Hello + ``` +* `'atx-closed'` + — prefer ATX headings with a closing sequence: + ```markdown + ## Hello ## + ``` +* `'setext'` + — prefer setext headings: + ```markdown + Hello + ----- + ``` +* `'consistent'` + — detect the first used style and warn when further headings differ + +## Recommendation + +Setext headings are limited in that they can only construct headings with a +rank of one and two. +On the other hand, they do allow multiple lines of content whereas ATX only +allows one line. +The number of used markers in their underline does not matter, leading to +either: + +* 1 marker (`Hello\n-`), which is the bare minimum, and for rank 2 headings + looks suspiciously like an empty list item +* using as many markers as the content (`Hello\n-----`), which is hard to + maintain +* an arbitrary number (`Hello\n---`), which for rank 2 headings looks + suspiciously like a thematic break + +Setext headings are also rather uncommon. +Using a sequence of hashes at the end of ATX headings is even more uncommon. +Due to this, it’s recommended to prefer ATX headings. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats headings as ATX by default. +The other styles can be configured with +[`setext: true`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionssetext) +or +[`closeAtx: true`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionscloseatx). + +## Examples ##### `ok.md` @@ -128,59 +262,12 @@ When configured with `'💩'`. 1:1: Incorrect heading style type `💩`: use either `'consistent'`, `'atx'`, `'atx-closed'`, or `'setext'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-heading-style -``` - -This package exports no identifiers. -The default export is `remarkLintHeadingStyle`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-heading-style", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-heading-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 remarkLintHeadingStyle from 'remark-lint-heading-style' - - remark() - .use(remarkLint) -+ .use(remarkLintHeadingStyle) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -222,17 +309,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-linebreak-style/index.js b/packages/remark-lint-linebreak-style/index.js index 6a4144e..ba89842 100644 --- a/packages/remark-lint-linebreak-style/index.js +++ b/packages/remark-lint-linebreak-style/index.js @@ -1,23 +1,37 @@ /** + * ## When should I use this? + * + * You can use this package to check that line endings are consistent. + * + * ## API + * + * + * The following options (default: `'consistent'`) are accepted: + * + * * `'unix'` + * — prefer Unix line endings (`\n`, `␊`): + * * `'window'` + * — prefer Windows line endings (`\r\n`, `␍␊`): + * * `'consistent'` + * — detect the first used style and warn when further line endings differ + * + * ## Recommendation + * + * In Git projects, you can configure it to automatically switch between line + * endings based on who checks the repo out. + * In other places, you might manually want to force that one or the other is + * used, in which case this rule can be used and configured. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * always uses Unix linebreaks. + * @module linebreak-style + * @summary + * remark-lint rule to warn when line endings don’t match a given style. * @author Titus Wormer * @copyright 2017 Titus Wormer * @license MIT - * @module linebreak-style - * @fileoverview - * Warn when linebreaks violate a given or detected style. - * - * Options: either `'unix'` (for `\n`, denoted as `␊`), `'windows'` (for `\r\n`, - * denoted as `␍␊`), or `'consistent'` (to detect the first used linebreak in - * a file). Default: `'consistent'`. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * always uses unix linebreaks. - * - * 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. - * * @example * {"name": "ok-consistent-as-windows.md"} * diff --git a/packages/remark-lint-linebreak-style/readme.md b/packages/remark-lint-linebreak-style/readme.md index 17a2351..93672f4 100644 --- a/packages/remark-lint-linebreak-style/readme.md +++ b/packages/remark-lint-linebreak-style/readme.md @@ -10,31 +10,143 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when linebreaks violate a given or detected style. +[`remark-lint`][mono] rule to warn when line endings don’t match a given style. -Options: either `'unix'` (for `\n`, denoted as `␊`), `'windows'` (for `\r\n`, -denoted as `␍␊`), or `'consistent'` (to detect the first used linebreak in -a file). Default: `'consistent'`. +## Contents -## Fix +* [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(remarkLintLinebreakStyle[, config])`](#unifieduseremarklintlinebreakstyle-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -always uses unix linebreaks. +## What is this? -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. +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that line endings are consistent. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-linebreak-style +``` + +In Deno with [Skypack][]: + +```js +import remarkLintLinebreakStyle from 'https://cdn.skypack.dev/remark-lint-linebreak-style@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintLinebreakStyle from 'remark-lint-linebreak-style' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintLinebreakStyle) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-linebreak-style example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-linebreak-style", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintLinebreakStyle`. + +### `unified().use(remarkLintLinebreakStyle[, 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: + +* `'unix'` + — prefer Unix line endings (`\n`, `␊`): +* `'window'` + — prefer Windows line endings (`\r\n`, `␍␊`): +* `'consistent'` + — detect the first used style and warn when further line endings differ + +## Recommendation + +In Git projects, you can configure it to automatically switch between line +endings based on who checks the repo out. +In other places, you might manually want to force that one or the other is +used, in which case this rule can be used and configured. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +always uses Unix linebreaks. + +## Examples ##### `ok-consistent-as-windows.md` ###### In -Note: `␍␊` represents a carriage return and a line feed. +> 👉 **Note**: `␍␊` represents a carriage return and a line feed. ```markdown Alpha␍␊ @@ -49,7 +161,7 @@ No messages. ###### In -Note: `␊` represents a line feed. +> 👉 **Note**: `␊` represents a line feed. ```markdown Alpha␊ @@ -66,7 +178,7 @@ When configured with `'unix'`. ###### In -Note: `␍␊` represents a carriage return and a line feed. +> 👉 **Note**: `␍␊` represents a carriage return and a line feed. ```markdown Alpha␍␊ @@ -84,7 +196,7 @@ When configured with `'windows'`. ###### In -Note: `␊` represents a line feed. +> 👉 **Note**: `␊` represents a line feed. ```markdown Alpha␊ @@ -96,59 +208,12 @@ Alpha␊ 1:6: Expected linebreaks to be windows (`\r\n`), not unix (`\n`) ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-linebreak-style -``` - -This package exports no identifiers. -The default export is `remarkLintLinebreakStyle`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-linebreak-style", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-linebreak-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 remarkLintLinebreakStyle from 'remark-lint-linebreak-style' - - remark() - .use(remarkLint) -+ .use(remarkLintLinebreakStyle) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -190,17 +255,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-link-title-style/index.js b/packages/remark-lint-link-title-style/index.js index 07e60ec..e13c721 100644 --- a/packages/remark-lint-link-title-style/index.js +++ b/packages/remark-lint-link-title-style/index.js @@ -1,25 +1,48 @@ /** + * ## When should I use this? + * + * You can use this package to check that title markers are consistent. + * + * ## API + * + * The following options (default: `'consistent'`) are accepted: + * + * * `'"'` + * — prefer double quotes + * * `"'"` + * — prefer single quotes + * * `'()'` + * — prefer parens + * * `'consistent'` + * — detect the first used style and warn when further titles differ + * + * ## Recommendation + * + * Parens in titles were not supported in markdown before CommonMark. + * While they should work in most places now, not all markdown parsers follow + * CommonMark. + * Parens for titles also arguably look a bit weird because they’re inside more + * parens: `[text](url (title))`. + * + * In HTML, attributes are commonly written with double quotes. + * Due to this, titles are almost exclusively wrapped in double quotes in + * markdown, so it’s recommended to configure this rule with `'"'`. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats titles with double quotes by default. + * Pass + * [`quote: "'"`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsquote) + * to use single quotes. + * There is no option to use parens. + * + * @module link-title-style + * @summary + * remark-lint rule to warn when title markers are inconsistent. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module link-title-style - * @fileoverview - * Warn when link and definition titles occur with incorrect quotes. - * - * Options: `'consistent'`, `'"'`, `'\''`, or `'()'`, default: `'consistent'`. - * - * `'consistent'` detects the first used quote style and warns when subsequent - * titles use different styles. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * uses `'` (single quote) for titles if they contain a double quote, and `"` - * (double quotes) otherwise. - * - * 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. - * * @example * {"name": "ok.md", "setting": "\""} * diff --git a/packages/remark-lint-link-title-style/readme.md b/packages/remark-lint-link-title-style/readme.md index c6d11e0..66cfec9 100644 --- a/packages/remark-lint-link-title-style/readme.md +++ b/packages/remark-lint-link-title-style/readme.md @@ -10,21 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when link and definition titles occur with incorrect quotes. +[`remark-lint`][mono] rule to warn when title markers are inconsistent. -Options: `'consistent'`, `'"'`, `'\''`, or `'()'`, default: `'consistent'`. +## Contents -`'consistent'` detects the first used quote style and warns when subsequent -titles use 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(remarkLintLinkTitleStyle[, config])`](#unifieduseremarklintlinktitlestyle-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) -uses `'` (single quote) for titles if they contain a double quote, and `"` -(double quotes) otherwise. +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 title markers are consistent. ## Presets @@ -35,7 +47,116 @@ This rule is included in the following presets: | [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'"'` | -## 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-link-title-style +``` + +In Deno with [Skypack][]: + +```js +import remarkLintLinkTitleStyle from 'https://cdn.skypack.dev/remark-lint-link-title-style@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintLinkTitleStyle from 'remark-lint-link-title-style' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintLinkTitleStyle) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-link-title-style example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-link-title-style", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintLinkTitleStyle`. + +### `unified().use(remarkLintLinkTitleStyle[, 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: + +* `'"'` + — prefer double quotes +* `"'"` + — prefer single quotes +* `'()'` + — prefer parens +* `'consistent'` + — detect the first used style and warn when further titles differ + +## Recommendation + +Parens in titles were not supported in markdown before CommonMark. +While they should work in most places now, not all markdown parsers follow +CommonMark. +Parens for titles also arguably look a bit weird because they’re inside more +parens: `[text](url (title))`. + +In HTML, attributes are commonly written with double quotes. +Due to this, titles are almost exclusively wrapped in double quotes in +markdown, so it’s recommended to configure this rule with `'"'`. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats titles with double quotes by default. +Pass +[`quote: "'"`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsquote) +to use single quotes. +There is no option to use parens. + +## Examples ##### `ok.md` @@ -168,59 +289,12 @@ When configured with `'💩'`. 1:1: Incorrect link title style marker `💩`: use either `'consistent'`, `'"'`, `'\''`, or `'()'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-link-title-style -``` - -This package exports no identifiers. -The default export is `remarkLintLinkTitleStyle`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-link-title-style", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-link-title-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 remarkLintLinkTitleStyle from 'remark-lint-link-title-style' - - remark() - .use(remarkLint) -+ .use(remarkLintLinkTitleStyle) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -262,17 +336,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-list-item-bullet-indent/index.js b/packages/remark-lint-list-item-bullet-indent/index.js index 5e8f8f0..fc849e7 100644 --- a/packages/remark-lint-list-item-bullet-indent/index.js +++ b/packages/remark-lint-list-item-bullet-indent/index.js @@ -1,19 +1,40 @@ /** + * ## When should I use this? + * + * You can use this package to check that list items are not indented. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * There is no specific handling of indented list items (or anything else) in + * markdown. + * While it is possible to use an indent to align ordered lists on their marker: + * + * ```markdown + * 1. One + * 10. Ten + * 100. Hundred + * ``` + * + * …such a style is uncommon and a bit hard to maintain: adding a 10th item + * means 9 other items have to change (more arduous, while unlikely, would be + * the 100th item). + * Hence, it’s recommended to not indent items and to turn this rule on. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats all items without indent. + * + * @module list-item-bullet-indent + * @summary + * remark-lint rule to warn when list items are indented. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module list-item-bullet-indent - * @fileoverview - * Warn when list item bullets are indented. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * removes all indentation before bullets. - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-list-item-bullet-indent/readme.md b/packages/remark-lint-list-item-bullet-indent/readme.md index 615757a..b1b6e2a 100644 --- a/packages/remark-lint-list-item-bullet-indent/readme.md +++ b/packages/remark-lint-list-item-bullet-indent/readme.md @@ -10,15 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when list item bullets are indented. +[`remark-lint`][mono] rule to warn when list items are indented. -## Fix +## Contents -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -removes all indentation before bullets. +* [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(remarkLintListItemBulletIndent[, config])`](#unifieduseremarklintlistitembulletindent-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -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. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that list items are not indented. ## Presets @@ -28,7 +46,108 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | -## 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-list-item-bullet-indent +``` + +In Deno with [Skypack][]: + +```js +import remarkLintListItemBulletIndent from 'https://cdn.skypack.dev/remark-lint-list-item-bullet-indent@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintListItemBulletIndent from 'remark-lint-list-item-bullet-indent' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintListItemBulletIndent) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-list-item-bullet-indent example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-list-item-bullet-indent", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintListItemBulletIndent`. + +### `unified().use(remarkLintListItemBulletIndent[, 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). + +There are no options. + +## Recommendation + +There is no specific handling of indented list items (or anything else) in +markdown. +While it is possible to use an indent to align ordered lists on their marker: + +```markdown + 1. One + 10. Ten +100. Hundred +``` + +…such a style is uncommon and a bit hard to maintain: adding a 10th item +means 9 other items have to change (more arduous, while unlikely, would be +the 100th item). +Hence, it’s recommended to not indent items and to turn this rule on. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats all items without indent. + +## Examples ##### `ok.md` @@ -49,7 +168,7 @@ No messages. ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown Paragraph. @@ -65,59 +184,12 @@ Paragraph. 4:2: Incorrect indentation before bullet: remove 1 space ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-list-item-bullet-indent -``` - -This package exports no identifiers. -The default export is `remarkLintListItemBulletIndent`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-list-item-bullet-indent", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-list-item-bullet-indent readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintListItemBulletIndent from 'remark-lint-list-item-bullet-indent' - - remark() - .use(remarkLint) -+ .use(remarkLintListItemBulletIndent) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -159,17 +231,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-list-item-content-indent/index.js b/packages/remark-lint-list-item-content-indent/index.js index 265e9f1..23fefd2 100644 --- a/packages/remark-lint-list-item-content-indent/index.js +++ b/packages/remark-lint-list-item-content-indent/index.js @@ -1,11 +1,28 @@ /** + * ## When should I use this? + * + * You can use this package to check that list item content is aligned. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * The position of the first child in a list item matters. + * Further children should align with it. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * aligns the content of items. + * + * @module list-item-content-indent + * @summary + * remark-lint rule to warn when list item content is not aligned. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module list-item-content-indent - * @fileoverview - * Warn when the content of a list item has mixed indentation. - * * @example * {"name": "ok.md", "gfm": true} * @@ -59,11 +76,12 @@ const remarkLintListItemContentIndent = lintRule( continue } - // Get indentation for the first child. Only the first item can have a - // checkbox, so here we remove that from the column. + // Get indentation for the first child. + // Only the first item can have a checkbox, so here we remove that from + // the column. if (index === 0) { - // If there’s a checkbox before the content, look backwards to find the - // start of that checkbox. + // If there’s a checkbox before the content, look backwards to find + // the start of that checkbox. if (typeof node.checked === 'boolean') { let char = begin.offset - 1 diff --git a/packages/remark-lint-list-item-content-indent/readme.md b/packages/remark-lint-list-item-content-indent/readme.md index 27a7552..ad2f7ee 100644 --- a/packages/remark-lint-list-item-content-indent/readme.md +++ b/packages/remark-lint-list-item-content-indent/readme.md @@ -10,7 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when the content of a list item has mixed indentation. +[`remark-lint`][mono] rule to warn when list item content is not aligned. + +## Contents + +* [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(remarkLintListItemContentIndent[, config])`](#unifieduseremarklintlistitemcontentindent-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that list item content is aligned. ## Presets @@ -21,15 +47,104 @@ This rule is included in the following presets: | [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-list-item-content-indent +``` + +In Deno with [Skypack][]: + +```js +import remarkLintListItemContentIndent from 'https://cdn.skypack.dev/remark-lint-list-item-content-indent@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintListItemContentIndent from 'remark-lint-list-item-content-indent' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintListItemContentIndent) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-list-item-content-indent example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-list-item-content-indent", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintListItemContentIndent`. + +### `unified().use(remarkLintListItemContentIndent[, 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). + +There are no options. + +## Recommendation + +The position of the first child in a list item matters. +Further children should align with it. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +aligns the content of items. + +## Examples ##### `ok.md` ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown 1.·[x] Alpha @@ -44,9 +159,9 @@ No messages. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown 1.·[x] Charlie @@ -59,59 +174,12 @@ Note: `·` represents a space. 2:5: Don’t use mixed indentation for children, remove 1 space ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-list-item-content-indent -``` - -This package exports no identifiers. -The default export is `remarkLintListItemContentIndent`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-list-item-content-indent", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-list-item-content-indent readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintListItemContentIndent from 'remark-lint-list-item-content-indent' - - remark() - .use(remarkLint) -+ .use(remarkLintListItemContentIndent) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -153,17 +221,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-list-item-indent/index.js b/packages/remark-lint-list-item-indent/index.js index 44e7c78..bec559b 100644 --- a/packages/remark-lint-list-item-indent/index.js +++ b/packages/remark-lint-list-item-indent/index.js @@ -1,27 +1,64 @@ /** + * ## When should I use this? + * + * You can use this package to check that the spacing between list item markers + * and content is inconsistent. + * + * ## API + * + * The following options (default: `'tab-size'`) are accepted: + * + * * `'space'` + * — prefer a single space + * * `'tab-size'` + * — prefer spaces the size of the next tab stop + * * `'mixed'` + * — prefer `'space'` for tight lists and `'tab-size'` for loose lists + * + * ## Recommendation + * + * First, some background. + * The number of spaces that occur after list markers (`*`, `-`, and `+` for + * unordered lists, or `.` and `)` for unordered lists) and before the content + * on the first line, defines how much indentation can be used for further + * lines. + * At least one space is required and up to 4 spaces are allowed (if there is no + * further content after the marker then it’s a blank line which is handled as + * if there was one space; if there are 5 or more spaces and then content, it’s + * also seen as one space and the rest is seen as indented code). + * + * There are two types of lists in markdown (other than ordered and unordered): + * tight and loose lists. + * Lists are tight by default but if there is a blank line between two list + * items or between two blocks inside an item, that turns the whole list into a + * loose list. + * When turning markdown into HTML, paragraphs in tight lists are not wrapped + * in `

` tags. + * + * Historically, how indentation of lists works in markdown has been a mess, + * especially with how they interact with indented code. + * CommonMark made that a *lot* better, but there remain (documented but + * complex) edge cases and some behavior intuitive. + * Due to this, the default of this list is `'tab-size'`, which worked the best + * in most markdown parsers. + * Currently, the situation between markdown parsers is better, so choosing + * `'space'` (which seems to be the most common style used by authors) should + * be okay. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * uses `'tab-size'` (named `'tab'` there) by default. + * [`listItemIndent: '1'` (for `'space'`) or `listItemIndent: 'mixed'`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionslistitemindent) + * is supported. + * + * @module list-item-indent + * @summary + * remark-lint rule to warn when spacing between list item markers and + * content is inconsistent. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module list-item-indent - * @fileoverview - * Warn when the spacing between a list item’s bullet and its content violates - * a given style. - * - * Options: `'tab-size'`, `'mixed'`, or `'space'`, default: `'tab-size'`. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * uses `'tab-size'` (named `'tab'` there) by default to ensure Markdown is - * seen the same way across vendors. - * This can be configured with the - * [`listItemIndent`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionslistitemindent) - * option. - * This rule’s `'space'` option is named `'1'` there. - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-list-item-indent/readme.md b/packages/remark-lint-list-item-indent/readme.md index e3e8971..cf15e41 100644 --- a/packages/remark-lint-list-item-indent/readme.md +++ b/packages/remark-lint-list-item-indent/readme.md @@ -10,23 +10,35 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when the spacing between a list item’s bullet and its content violates -a given style. +[`remark-lint`][mono] rule to warn when spacing between list item markers and +content is inconsistent. -Options: `'tab-size'`, `'mixed'`, or `'space'`, default: `'tab-size'`. +## Contents -## Fix +* [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(remarkLintListItemIndent[, config])`](#unifieduseremarklintlistitemindent-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -uses `'tab-size'` (named `'tab'` there) by default to ensure Markdown is -seen the same way across vendors. -This can be configured with the -[`listItemIndent`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionslistitemindent) -option. -This rule’s `'space'` option is named `'1'` there. +## What is this? -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. +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that the spacing between list item markers +and content is inconsistent. ## Presets @@ -37,13 +49,136 @@ This rule is included in the following presets: | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'mixed'` | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | `'tab-size'` | -## 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-list-item-indent +``` + +In Deno with [Skypack][]: + +```js +import remarkLintListItemIndent from 'https://cdn.skypack.dev/remark-lint-list-item-indent@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintListItemIndent from 'remark-lint-list-item-indent' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintListItemIndent) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-list-item-indent example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-list-item-indent", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintListItemIndent`. + +### `unified().use(remarkLintListItemIndent[, 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: `'tab-size'`) are accepted: + +* `'space'` + — prefer a single space +* `'tab-size'` + — prefer spaces the size of the next tab stop +* `'mixed'` + — prefer `'space'` for tight lists and `'tab-size'` for loose lists + +## Recommendation + +First, some background. +The number of spaces that occur after list markers (`*`, `-`, and `+` for +unordered lists, or `.` and `)` for unordered lists) and before the content +on the first line, defines how much indentation can be used for further +lines. +At least one space is required and up to 4 spaces are allowed (if there is no +further content after the marker then it’s a blank line which is handled as +if there was one space; if there are 5 or more spaces and then content, it’s +also seen as one space and the rest is seen as indented code). + +There are two types of lists in markdown (other than ordered and unordered): +tight and loose lists. +Lists are tight by default but if there is a blank line between two list +items or between two blocks inside an item, that turns the whole list into a +loose list. +When turning markdown into HTML, paragraphs in tight lists are not wrapped +in `

` tags. + +Historically, how indentation of lists works in markdown has been a mess, +especially with how they interact with indented code. +CommonMark made that a *lot* better, but there remain (documented but +complex) edge cases and some behavior intuitive. +Due to this, the default of this list is `'tab-size'`, which worked the best +in most markdown parsers. +Currently, the situation between markdown parsers is better, so choosing +`'space'` (which seems to be the most common style used by authors) should +be okay. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +uses `'tab-size'` (named `'tab'` there) by default. +[`listItemIndent: '1'` (for `'space'`) or `listItemIndent: 'mixed'`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionslistitemindent) +is supported. + +## Examples ##### `ok.md` ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown *···List @@ -73,7 +208,7 @@ When configured with `'mixed'`. ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown *·List item. @@ -101,7 +236,7 @@ When configured with `'mixed'`. ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown *···List item. @@ -119,7 +254,7 @@ When configured with `'space'`. ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown *·List item. @@ -147,7 +282,7 @@ When configured with `'space'`. ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown *···List @@ -166,7 +301,7 @@ When configured with `'tab-size'`. ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown *·List @@ -189,59 +324,12 @@ When configured with `'💩'`. 1:1: Incorrect list-item indent style `💩`: use either `'tab-size'`, `'space'`, or `'mixed'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-list-item-indent -``` - -This package exports no identifiers. -The default export is `remarkLintListItemIndent`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-list-item-indent", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-list-item-indent readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintListItemIndent from 'remark-lint-list-item-indent' - - remark() - .use(remarkLint) -+ .use(remarkLintListItemIndent) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -283,17 +371,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-list-item-spacing/index.js b/packages/remark-lint-list-item-spacing/index.js index 26e534d..8bb8f0e 100644 --- a/packages/remark-lint-list-item-spacing/index.js +++ b/packages/remark-lint-list-item-spacing/index.js @@ -1,25 +1,43 @@ /** + * ## When should I use this? + * + * You can use this package to check that lists are loose or tight when + * they should be. + * + * ## API + * + * The following options (default: `undefined`) are accepted: + * + * * `Object` with the following fields: + * * `checkBlanks` (`boolean`, default: `false`) + * — adhere to CommonMark looseness instead of markdown-style-guide + * preference + * + * ## Recommendation + * + * First, some background. + * There are two types of lists in markdown (other than ordered and unordered): + * tight and loose lists. + * Lists are tight by default but if there is a blank line between two list + * items or between two blocks inside an item, that turns the whole list into a + * loose list. + * When turning markdown into HTML, paragraphs in tight lists are not wrapped + * in `

` tags. + * + * This rule defaults to the + * [`markdown style guide`](https://cirosantilli.com/markdown-style-guide/) + * preference for which lists should be loose or not: loose when at least one + * item spans more than one line, tight otherwise. + * With `{checkBlanks: true}`, this rule dictates that when at least one item is + * loose, all items must be loose. + * + * @module list-item-spacing + * @summary + * remark-lint rule to warn when lists are loose when they should be tight, + * or vice versa. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module list-item-spacing - * @fileoverview - * Warn when list looseness is incorrect, such as being tight when it should - * be loose, and vice versa. - * - * According to the [`markdown-style-guide`](http://www.cirosantilli.com/markdown-style-guide/), - * if one or more list items in a list spans more than one line, the list is - * required to have blank lines between each item. - * And otherwise, there should not be blank lines between items. - * - * By default, all items must be spread out (a blank line must be between - * them) if one or more items are multiline (span more than one line). - * Otherwise, the list must be tight (no blank line must be between items). - * - * If you pass `{checkBlanks: true}`, all items must be spread out if one or - * more items contain blank lines. - * Otherwise, the list must be tight. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-list-item-spacing/readme.md b/packages/remark-lint-list-item-spacing/readme.md index 262f0b7..154c25d 100644 --- a/packages/remark-lint-list-item-spacing/readme.md +++ b/packages/remark-lint-list-item-spacing/readme.md @@ -10,21 +10,34 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when list looseness is incorrect, such as being tight when it should -be loose, and vice versa. +[`remark-lint`][mono] rule to warn when lists are loose when they should be tight, +or vice versa. -According to the [`markdown-style-guide`](http://www.cirosantilli.com/markdown-style-guide/), -if one or more list items in a list spans more than one line, the list is -required to have blank lines between each item. -And otherwise, there should not be blank lines between items. +## Contents -By default, all items must be spread out (a blank line must be between -them) if one or more items are multiline (span more than one line). -Otherwise, the list must be tight (no blank line must be between items). +* [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(remarkLintListItemSpacing[, config])`](#unifieduseremarklintlistitemspacing-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -If you pass `{checkBlanks: true}`, all items must be spread out if one or -more items contain blank lines. -Otherwise, the list must be tight. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that lists are loose or tight when +they should be. ## Presets @@ -34,7 +47,109 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-list-item-spacing +``` + +In Deno with [Skypack][]: + +```js +import remarkLintListItemSpacing from 'https://cdn.skypack.dev/remark-lint-list-item-spacing@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintListItemSpacing from 'remark-lint-list-item-spacing' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintListItemSpacing) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-list-item-spacing example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-list-item-spacing", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintListItemSpacing`. + +### `unified().use(remarkLintListItemSpacing[, 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: `undefined`) are accepted: + +* `Object` with the following fields: + * `checkBlanks` (`boolean`, default: `false`) + — adhere to CommonMark looseness instead of markdown-style-guide + preference + +## Recommendation + +First, some background. +There are two types of lists in markdown (other than ordered and unordered): +tight and loose lists. +Lists are tight by default but if there is a blank line between two list +items or between two blocks inside an item, that turns the whole list into a +loose list. +When turning markdown into HTML, paragraphs in tight lists are not wrapped +in `

` tags. + +This rule defaults to the +[`markdown style guide`](https://cirosantilli.com/markdown-style-guide/) +preference for which lists should be loose or not: loose when at least one +item spans more than one line, tight otherwise. +With `{checkBlanks: true}`, this rule dictates that when at least one item is +loose, all items must be loose. + +## Examples ##### `ok.md` @@ -154,59 +269,12 @@ A loose list: 14:15-16:1: Extraneous new line after list item ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-list-item-spacing -``` - -This package exports no identifiers. -The default export is `remarkLintListItemSpacing`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-list-item-spacing", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-list-item-spacing readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintListItemSpacing from 'remark-lint-list-item-spacing' - - remark() - .use(remarkLint) -+ .use(remarkLintListItemSpacing) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -248,17 +316,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-maximum-heading-length/index.js b/packages/remark-lint-maximum-heading-length/index.js index 84dcc70..a40ea02 100644 --- a/packages/remark-lint-maximum-heading-length/index.js +++ b/packages/remark-lint-maximum-heading-length/index.js @@ -1,15 +1,31 @@ /** + * ## When should I use this? + * + * You can use this package to check that heading text is within reason. + * + * ## API + * + * The following options (default: `60`) are accepted: + * + * * `number` (example: `72`) + * — max number of characters to accept in heading text + * + * Ignores syntax, only checks the plain text content. + * + * ## Recommendation + * + * While this rule is sometimes annoying, reasonable size headings + * do help SEO purposes (bots prefer reasonable headings), visual users + * (headings are typically displayed quite large), and users of screen readers + * (who typically use “jump to heading” features to navigate within a page, + * which reads every heading out loud). + * + * @module maximum-heading-length + * @summary + * remark-lint rule to warn when headings are too long. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module maximum-heading-length - * @fileoverview - * Warn when headings are too long. - * - * Options: `number`, default: `60`. - * - * Ignores Markdown syntax, only checks the plain text content. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-maximum-heading-length/readme.md b/packages/remark-lint-maximum-heading-length/readme.md index 109f9b8..11044fd 100644 --- a/packages/remark-lint-maximum-heading-length/readme.md +++ b/packages/remark-lint-maximum-heading-length/readme.md @@ -10,11 +10,32 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when headings are too long. +[`remark-lint`][mono] rule to warn when headings are too long. -Options: `number`, default: `60`. +## Contents -Ignores Markdown syntax, only checks the plain text content. +* [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(remarkLintMaximumHeadingLength[, config])`](#unifieduseremarklintmaximumheadinglength-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that heading text is within reason. ## Presets @@ -24,7 +45,99 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-maximum-heading-length +``` + +In Deno with [Skypack][]: + +```js +import remarkLintMaximumHeadingLength from 'https://cdn.skypack.dev/remark-lint-maximum-heading-length@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintMaximumHeadingLength from 'remark-lint-maximum-heading-length' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintMaximumHeadingLength) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-maximum-heading-length example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-maximum-heading-length", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintMaximumHeadingLength`. + +### `unified().use(remarkLintMaximumHeadingLength[, 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: `60`) are accepted: + +* `number` (example: `72`) + — max number of characters to accept in heading text + +Ignores syntax, only checks the plain text content. + +## Recommendation + +While this rule is sometimes annoying, reasonable size headings +do help SEO purposes (bots prefer reasonable headings), visual users +(headings are typically displayed quite large), and users of screen readers +(who typically use “jump to heading” features to navigate within a page, +which reads every heading out loud). + +## Examples ##### `not-ok.md` @@ -56,59 +169,12 @@ When configured with `40`. No messages. -## 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. - -[npm][]: - -```sh -npm install remark-lint-maximum-heading-length -``` - -This package exports no identifiers. -The default export is `remarkLintMaximumHeadingLength`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-maximum-heading-length", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-maximum-heading-length readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintMaximumHeadingLength from 'remark-lint-maximum-heading-length' - - remark() - .use(remarkLint) -+ .use(remarkLintMaximumHeadingLength) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -150,17 +216,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-maximum-line-length/index.js b/packages/remark-lint-maximum-line-length/index.js index e130e26..05a8652 100644 --- a/packages/remark-lint-maximum-line-length/index.js +++ b/packages/remark-lint-maximum-line-length/index.js @@ -1,19 +1,30 @@ /** + * ## When should I use this? + * + * You can use this package to check that lines do not exceed a certain size. + * + * ## API + * + * The following options (default: `80`) are accepted: + * + * * `number` (example: `72`) + * — max number of characters to accept in heading text + * + * Ignores nodes that cannot be wrapped, such as headings, tables, code, + * definitions, HTML, and JSX. + * Ignores images, links, and code (inline) if they start before the wrap, end + * after the wrap, and there’s no white space after them. + * + * ## Recommendation + * + * Whether to wrap prose or not is a stylistic choice. + * + * @module maximum-line-length + * @summary + * remark-lint rule to warn when lines are too long. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module maximum-line-length - * @fileoverview - * Warn when lines are too long. - * - * Options: `number`, default: `80`. - * - * Ignores nodes that cannot be wrapped, such as headings, tables, code, - * definitions, HTML, and JSX. - * - * Ignores images, links, and inline code if they start before the wrap, end - * after the wrap, and there’s no whitespace after them. - * * @example * {"name": "ok.md", "positionless": true, "gfm": true} * @@ -38,7 +49,7 @@ * *

alpha bravo charlie delta echo foxtrot golf

* - * The following is also fine, because there is no whitespace. + * The following is also fine (note the `.`), because there is no whitespace. * * . * diff --git a/packages/remark-lint-maximum-line-length/readme.md b/packages/remark-lint-maximum-line-length/readme.md index 4c1ec60..48790f0 100644 --- a/packages/remark-lint-maximum-line-length/readme.md +++ b/packages/remark-lint-maximum-line-length/readme.md @@ -10,15 +10,32 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when lines are too long. +[`remark-lint`][mono] rule to warn when lines are too long. -Options: `number`, default: `80`. +## Contents -Ignores nodes that cannot be wrapped, such as headings, tables, code, -definitions, HTML, and JSX. +* [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(remarkLintMaximumLineLength[, config])`](#unifieduseremarklintmaximumlinelength-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -Ignores images, links, and inline code if they start before the wrap, end -after the wrap, and there’s no whitespace after them. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that lines do not exceed a certain size. ## Presets @@ -28,7 +45,98 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `80` | -## 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-maximum-line-length +``` + +In Deno with [Skypack][]: + +```js +import remarkLintMaximumLineLength from 'https://cdn.skypack.dev/remark-lint-maximum-line-length@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintMaximumLineLength from 'remark-lint-maximum-line-length' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintMaximumLineLength) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-maximum-line-length example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-maximum-line-length", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintMaximumLineLength`. + +### `unified().use(remarkLintMaximumLineLength[, 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: `80`) are accepted: + +* `number` (example: `72`) + — max number of characters to accept in heading text + +Ignores nodes that cannot be wrapped, such as headings, tables, code, +definitions, HTML, and JSX. +Ignores images, links, and code (inline) if they start before the wrap, end +after the wrap, and there’s no white space after them. + +## Recommendation + +Whether to wrap prose or not is a stylistic choice. + +## Examples ##### `ok-mixed-line-endings.md` @@ -36,9 +144,9 @@ When configured with `10`. ###### In -Note: `␍␊` represents a carriage return and a line feed. +> 👉 **Note**: `␍␊` represents a carriage return and a line feed. -Note: `␊` represents a line feed. +> 👉 **Note**: `␊` represents a line feed. ```markdown 0123456789␍␊ @@ -57,9 +165,9 @@ When configured with `10`. ###### In -Note: `␍␊` represents a carriage return and a line feed. +> 👉 **Note**: `␍␊` represents a carriage return and a line feed. -Note: `␊` represents a line feed. +> 👉 **Note**: `␊` represents a line feed. ```markdown 012345678901␍␊ @@ -112,7 +220,7 @@ And this one is also very wrong: because the code starts aaaaaaafter the column: ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown This line is simply not toooooooooooooooooooooooooooooooooooooooooooo @@ -136,7 +244,7 @@ This is also fine:

alpha bravo charlie delta echo foxtrot golf

 -The following is also fine, because there is no whitespace. +The following is also fine (note the `.`), because there is no whitespace. . @@ -149,59 +257,12 @@ In addition, definitions are also fine: No messages. -## 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. - -[npm][]: - -```sh -npm install remark-lint-maximum-line-length -``` - -This package exports no identifiers. -The default export is `remarkLintMaximumLineLength`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-maximum-line-length", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-maximum-line-length readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintMaximumLineLength from 'remark-lint-maximum-line-length' - - remark() - .use(remarkLint) -+ .use(remarkLintMaximumLineLength) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -243,17 +304,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-auto-link-without-protocol/index.js b/packages/remark-lint-no-auto-link-without-protocol/index.js index e0149d8..bc151af 100644 --- a/packages/remark-lint-no-auto-link-without-protocol/index.js +++ b/packages/remark-lint-no-auto-link-without-protocol/index.js @@ -4,6 +4,7 @@ * @license MIT * @module no-auto-link-without-protocol * @deprecated + * **Stability: Legacy**. * This rule is no longer recommended for use. * With CommonMark, all autolinks (except for emails) are required to have a * protocol. diff --git a/packages/remark-lint-no-auto-link-without-protocol/readme.md b/packages/remark-lint-no-auto-link-without-protocol/readme.md index 913a94b..2964823 100644 --- a/packages/remark-lint-no-auto-link-without-protocol/readme.md +++ b/packages/remark-lint-no-auto-link-without-protocol/readme.md @@ -2,68 +2,17 @@ # remark-lint-no-auto-link-without-protocol -[![Build][build-badge]][build] -[![Coverage][coverage-badge]][coverage] -[![Downloads][downloads-badge]][downloads] -[![Size][size-badge]][size] -[![Sponsors][sponsors-badge]][collective] -[![Backers][backers-badge]][collective] -[![Chat][chat-badge]][chat] - +**Stability: Legacy**. This rule is no longer recommended for use. With CommonMark, all autolinks (except for emails) are required to have a protocol. Otherwise they don’t parse. The previous suggestion to add a protocol to email autolinks was wrong. -## Contribute - -See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways -to get started. -See [`support.md`][support] for ways to get help. - -This project has a [code of conduct][coc]. -By interacting with this repository, organization, or community you agree to -abide by its terms. - ## License [MIT][license] © [Titus Wormer][author] -[build-badge]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg - -[build]: https://github.com/remarkjs/remark-lint/actions - -[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg - -[coverage]: https://codecov.io/github/remarkjs/remark-lint - -[downloads-badge]: https://img.shields.io/npm/dm/remark-lint-no-auto-link-without-protocol.svg - -[downloads]: https://www.npmjs.com/package/remark-lint-no-auto-link-without-protocol - -[size-badge]: https://img.shields.io/bundlephobia/minzip/remark-lint-no-auto-link-without-protocol.svg - -[size]: https://bundlephobia.com/result?p=remark-lint-no-auto-link-without-protocol - -[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/chat-discussions-success.svg - -[chat]: https://github.com/remarkjs/remark/discussions - -[health]: https://github.com/remarkjs/.github - -[contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md - -[support]: https://github.com/remarkjs/.github/blob/HEAD/support.md - -[coc]: https://github.com/remarkjs/.github/blob/HEAD/code-of-conduct.md - [license]: https://github.com/remarkjs/remark-lint/blob/main/license [author]: https://wooorm.com diff --git a/packages/remark-lint-no-blockquote-without-marker/index.js b/packages/remark-lint-no-blockquote-without-marker/index.js index 122080a..f334a99 100644 --- a/packages/remark-lint-no-blockquote-without-marker/index.js +++ b/packages/remark-lint-no-blockquote-without-marker/index.js @@ -1,20 +1,28 @@ /** + * ## When should I use this? + * + * You can use this package to check that lines in block quotes start with `>`. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Rules around “lazy” lines are not straightforward and visually confusing, + * so it’s recommended to start each line with a `>`. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * adds `>` markers to every line in a block quote. + * + * @module no-blockquote-without-marker + * @summary + * remark-lint rule to warn when lines in block quotes start without `>`. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-blockquote-without-marker - * @fileoverview - * Warn when blank lines without `>` (greater than) markers are found in a - * block quote. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * adds markers to every line in a block quote. - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-blockquote-without-marker/readme.md b/packages/remark-lint-no-blockquote-without-marker/readme.md index e92b484..0d31f77 100644 --- a/packages/remark-lint-no-blockquote-without-marker/readme.md +++ b/packages/remark-lint-no-blockquote-without-marker/readme.md @@ -10,16 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when blank lines without `>` (greater than) markers are found in a -block quote. +[`remark-lint`][mono] rule to warn when lines in block quotes start without `>`. -## Fix +## Contents -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -adds markers to every line in a block quote. +* [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(remarkLintNoBlockquoteWithoutMarker[, config])`](#unifieduseremarklintnoblockquotewithoutmarker-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -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. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that lines in block quotes start with `>`. ## Presets @@ -30,7 +47,96 @@ This rule is included in the following presets: | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | -## 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-no-blockquote-without-marker +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoBlockquoteWithoutMarker from 'https://cdn.skypack.dev/remark-lint-no-blockquote-without-marker@5?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoBlockquoteWithoutMarker from 'remark-lint-no-blockquote-without-marker' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoBlockquoteWithoutMarker) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-blockquote-without-marker example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-blockquote-without-marker", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoBlockquoteWithoutMarker`. + +### `unified().use(remarkLintNoBlockquoteWithoutMarker[, 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). + +There are no options. + +## Recommendation + +Rules around “lazy” lines are not straightforward and visually confusing, +so it’s recommended to start each line with a `>`. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +adds `>` markers to every line in a block quote. + +## Examples ##### `ok.md` @@ -50,7 +156,7 @@ No messages. ###### In -Note: `»` represents a tab. +> 👉 **Note**: `»` represents a tab. ```markdown >»Foo… @@ -82,7 +188,7 @@ No messages. ###### In -Note: `»` represents a tab. +> 👉 **Note**: `»` represents a tab. ```markdown >»Foo… @@ -97,59 +203,12 @@ Note: `»` represents a tab. 3:1: Missing marker in block quote ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-blockquote-without-marker -``` - -This package exports no identifiers. -The default export is `remarkLintNoBlockquoteWithoutMarker`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-blockquote-without-marker", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-blockquote-without-marker readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoBlockquoteWithoutMarker from 'remark-lint-no-blockquote-without-marker' - - remark() - .use(remarkLint) -+ .use(remarkLintNoBlockquoteWithoutMarker) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -191,17 +250,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-consecutive-blank-lines/index.js b/packages/remark-lint-no-consecutive-blank-lines/index.js index 1ca99bd..097252a 100644 --- a/packages/remark-lint-no-consecutive-blank-lines/index.js +++ b/packages/remark-lint-no-consecutive-blank-lines/index.js @@ -1,22 +1,29 @@ /** + * ## When should I use this? + * + * You can use this package to check that no more blank lines than needed + * are used between blocks. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * More than one blank line has no effect between blocks. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * adds exactly one blank line between any block. + * + * @module no-consecutive-blank-lines + * @summary + * remark-lint rule to warn when more blank lines that needed are used + * between blocks. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-consecutive-blank-lines - * @fileoverview - * Warn for too many consecutive blank lines. - * Knows about the extra line needed between a list and indented code, and two - * lists. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * always uses one blank line between blocks if possible, or two lines when - * needed. - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-consecutive-blank-lines/readme.md b/packages/remark-lint-no-consecutive-blank-lines/readme.md index 0e111af..027c9cf 100644 --- a/packages/remark-lint-no-consecutive-blank-lines/readme.md +++ b/packages/remark-lint-no-consecutive-blank-lines/readme.md @@ -10,18 +10,35 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn for too many consecutive blank lines. -Knows about the extra line needed between a list and indented code, and two -lists. +[`remark-lint`][mono] rule to warn when more blank lines that needed are used +between blocks. -## Fix +## Contents -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -always uses one blank line between blocks if possible, or two lines when -needed. +* [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(remarkLintNoConsecutiveBlankLines[, config])`](#unifieduseremarklintnoconsecutiveblanklines-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -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. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that no more blank lines than needed +are used between blocks. ## Presets @@ -31,13 +48,101 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-no-consecutive-blank-lines +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoConsecutiveBlankLines from 'https://cdn.skypack.dev/remark-lint-no-consecutive-blank-lines@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoConsecutiveBlankLines from 'remark-lint-no-consecutive-blank-lines' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoConsecutiveBlankLines) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-consecutive-blank-lines example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-consecutive-blank-lines", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoConsecutiveBlankLines`. + +### `unified().use(remarkLintNoConsecutiveBlankLines[, 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). + +There are no options. + +## Recommendation + +More than one blank line has no effect between blocks. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +adds exactly one blank line between any block. + +## Examples ##### `ok.md` ###### In -Note: `␊` represents a line feed. +> 👉 **Note**: `␊` represents a line feed. ```markdown Foo… @@ -59,7 +164,7 @@ No messages. ###### In -Note: `␊` represents a line feed. +> 👉 **Note**: `␊` represents a line feed. ```markdown Foo… @@ -77,59 +182,12 @@ Foo… 4:5: Remove 2 lines after node ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-consecutive-blank-lines -``` - -This package exports no identifiers. -The default export is `remarkLintNoConsecutiveBlankLines`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-consecutive-blank-lines", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-consecutive-blank-lines readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoConsecutiveBlankLines from 'remark-lint-no-consecutive-blank-lines' - - remark() - .use(remarkLint) -+ .use(remarkLintNoConsecutiveBlankLines) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -171,17 +229,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-duplicate-defined-urls/index.js b/packages/remark-lint-no-duplicate-defined-urls/index.js index e074377..86f0c74 100644 --- a/packages/remark-lint-no-duplicate-defined-urls/index.js +++ b/packages/remark-lint-no-duplicate-defined-urls/index.js @@ -1,11 +1,23 @@ /** + * ## When should I use this? + * + * You can use this package to check that URLs are defined once. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * It’s likely a mistake when the same URL is defined with different + * identifiers. + * + * @module no-duplicate-defined-urls + * @summary + * remark-lint rule to warn when URLs are defined multiple times. * @author Titus Wormer * @copyright 2020 Titus Wormer * @license MIT - * @module no-duplicate-defined-urls - * @fileoverview - * Warn when definitions define the same URL. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-duplicate-defined-urls/readme.md b/packages/remark-lint-no-duplicate-defined-urls/readme.md index 12c1000..c349774 100644 --- a/packages/remark-lint-no-duplicate-defined-urls/readme.md +++ b/packages/remark-lint-no-duplicate-defined-urls/readme.md @@ -10,13 +10,122 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when definitions define the same URL. +[`remark-lint`][mono] rule to warn when URLs are defined multiple times. + +## Contents + +* [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(remarkLintNoDuplicateDefinedUrls[, config])`](#unifieduseremarklintnoduplicatedefinedurls-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that URLs are defined once. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-no-duplicate-defined-urls +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoDuplicateDefinedUrls from 'https://cdn.skypack.dev/remark-lint-no-duplicate-defined-urls@2?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoDuplicateDefinedUrls from 'remark-lint-no-duplicate-defined-urls' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoDuplicateDefinedUrls) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-duplicate-defined-urls example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-duplicate-defined-urls", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoDuplicateDefinedUrls`. + +### `unified().use(remarkLintNoDuplicateDefinedUrls[, 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). + +There are no options. + +## Recommendation + +It’s likely a mistake when the same URL is defined with different +identifiers. + +## Examples ##### `ok.md` @@ -46,59 +155,12 @@ No messages. 2:1-2:19: Do not use different definitions with the same URL (1:1) ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-duplicate-defined-urls -``` - -This package exports no identifiers. -The default export is `remarkLintNoDuplicateDefinedUrls`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-duplicate-defined-urls", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-duplicate-defined-urls readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoDuplicateDefinedUrls from 'remark-lint-no-duplicate-defined-urls' - - remark() - .use(remarkLint) -+ .use(remarkLintNoDuplicateDefinedUrls) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -140,17 +202,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-duplicate-definitions/index.js b/packages/remark-lint-no-duplicate-definitions/index.js index a9e7996..f2b9d3b 100644 --- a/packages/remark-lint-no-duplicate-definitions/index.js +++ b/packages/remark-lint-no-duplicate-definitions/index.js @@ -1,11 +1,22 @@ /** + * ## When should I use this? + * + * You can use this package to check that identifiers are defined once. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * It’s a mistake when the same identifier is defined multiple times. + * + * @module no-duplicate-definitions + * @summary + * remark-lint rule to warn when identifiers are defined multiple times. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-duplicate-definitions - * @fileoverview - * Warn when duplicate definitions are found. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-duplicate-definitions/readme.md b/packages/remark-lint-no-duplicate-definitions/readme.md index 52997bf..8f71e74 100644 --- a/packages/remark-lint-no-duplicate-definitions/readme.md +++ b/packages/remark-lint-no-duplicate-definitions/readme.md @@ -10,7 +10,32 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when duplicate definitions are found. +[`remark-lint`][mono] rule to warn when identifiers are defined multiple times. + +## Contents + +* [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(remarkLintNoDuplicateDefinitions[, config])`](#unifieduseremarklintnoduplicatedefinitions-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that identifiers are defined once. ## Presets @@ -20,7 +45,90 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | -## 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-no-duplicate-definitions +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoDuplicateDefinitions from 'https://cdn.skypack.dev/remark-lint-no-duplicate-definitions@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoDuplicateDefinitions from 'remark-lint-no-duplicate-definitions' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoDuplicateDefinitions) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-duplicate-definitions example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-duplicate-definitions", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoDuplicateDefinitions`. + +### `unified().use(remarkLintNoDuplicateDefinitions[, 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). + +There are no options. + +## Recommendation + +It’s a mistake when the same identifier is defined multiple times. + +## Examples ##### `ok.md` @@ -50,59 +158,12 @@ No messages. 2:1-2:11: Do not use definitions with the same identifier (1:1) ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-duplicate-definitions -``` - -This package exports no identifiers. -The default export is `remarkLintNoDuplicateDefinitions`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-duplicate-definitions", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-duplicate-definitions readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoDuplicateDefinitions from 'remark-lint-no-duplicate-definitions' - - remark() - .use(remarkLint) -+ .use(remarkLintNoDuplicateDefinitions) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -144,17 +205,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-duplicate-headings-in-section/index.js b/packages/remark-lint-no-duplicate-headings-in-section/index.js index 2a39495..c450283 100644 --- a/packages/remark-lint-no-duplicate-headings-in-section/index.js +++ b/packages/remark-lint-no-duplicate-headings-in-section/index.js @@ -1,12 +1,25 @@ /** + * ## When should I use this? + * + * You can use this package to check that headings with the same text are + * used once per section. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * It’s likely a mistake that the same heading text is used in the same + * section. + * + * @module no-duplicate-headings-in-section + * @summary + * remark-lint rule to warn when headings with the same text are used + * multiple times per section. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-duplicate-headings-in-section - * @fileoverview - * Warn when duplicate headings are found, but only when on the same level, - * “in” the same section. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-duplicate-headings-in-section/readme.md b/packages/remark-lint-no-duplicate-headings-in-section/readme.md index d23536e..d15463a 100644 --- a/packages/remark-lint-no-duplicate-headings-in-section/readme.md +++ b/packages/remark-lint-no-duplicate-headings-in-section/readme.md @@ -10,14 +10,124 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when duplicate headings are found, but only when on the same level, -“in” the same section. +[`remark-lint`][mono] rule to warn when headings with the same text are used +multiple times per section. + +## Contents + +* [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(remarkLintNoDuplicateHeadingsInSection[, config])`](#unifieduseremarklintnoduplicateheadingsinsection-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that headings with the same text are +used once per section. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-no-duplicate-headings-in-section +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoDuplicateHeadingsInSection from 'https://cdn.skypack.dev/remark-lint-no-duplicate-headings-in-section@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoDuplicateHeadingsInSection from 'remark-lint-no-duplicate-headings-in-section' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoDuplicateHeadingsInSection) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-duplicate-headings-in-section example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-duplicate-headings-in-section", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoDuplicateHeadingsInSection`. + +### `unified().use(remarkLintNoDuplicateHeadingsInSection[, 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). + +There are no options. + +## Recommendation + +It’s likely a mistake that the same heading text is used in the same +section. + +## Examples ##### `ok.md` @@ -85,59 +195,12 @@ No messages. 7:1-7:11: Do not use headings with similar content per section (3:1) ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-duplicate-headings-in-section -``` - -This package exports no identifiers. -The default export is `remarkLintNoDuplicateHeadingsInSection`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-duplicate-headings-in-section", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-duplicate-headings-in-section readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoDuplicateHeadingsInSection from 'remark-lint-no-duplicate-headings-in-section' - - remark() - .use(remarkLint) -+ .use(remarkLintNoDuplicateHeadingsInSection) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -179,17 +242,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-duplicate-headings/index.js b/packages/remark-lint-no-duplicate-headings/index.js index e246a14..e9685b5 100644 --- a/packages/remark-lint-no-duplicate-headings/index.js +++ b/packages/remark-lint-no-duplicate-headings/index.js @@ -1,11 +1,29 @@ /** + * ## When should I use this? + * + * You can use this package to check that headings with the same text are + * used once. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Headings having unique text helps screen reader users (who typically use + * “jump to heading” features to navigate within a page, which reads headings + * out loud). + * It also helps because often headings receive automatic unique IDs, and when + * the same heading text is used, they are suffixed with a number based on where + * they are positioned in the document, which makes linking to them prone to + * changes. + * + * @module no-duplicate-headings + * @summary + * remark-lint rule to warn when headings with the same text are found. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-duplicate-headings - * @fileoverview - * Warn when duplicate headings are found. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-duplicate-headings/readme.md b/packages/remark-lint-no-duplicate-headings/readme.md index 52407cf..5ac99ca 100644 --- a/packages/remark-lint-no-duplicate-headings/readme.md +++ b/packages/remark-lint-no-duplicate-headings/readme.md @@ -10,7 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when duplicate headings are found. +[`remark-lint`][mono] rule to warn when headings with the same text are found. + +## Contents + +* [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(remarkLintNoDuplicateHeadings[, config])`](#unifieduseremarklintnoduplicateheadings-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that headings with the same text are +used once. ## Presets @@ -20,7 +46,96 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-no-duplicate-headings +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoDuplicateHeadings from 'https://cdn.skypack.dev/remark-lint-no-duplicate-headings@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoDuplicateHeadings from 'remark-lint-no-duplicate-headings' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoDuplicateHeadings) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-duplicate-headings example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-duplicate-headings", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoDuplicateHeadings`. + +### `unified().use(remarkLintNoDuplicateHeadings[, 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). + +There are no options. + +## Recommendation + +Headings having unique text helps screen reader users (who typically use +“jump to heading” features to navigate within a page, which reads headings +out loud). +It also helps because often headings receive automatic unique IDs, and when +the same heading text is used, they are suffixed with a number based on where +they are positioned in the document, which makes linking to them prone to +changes. + +## Examples ##### `ok.md` @@ -55,59 +170,12 @@ No messages. 5:1-5:29: Do not use headings with similar content (3:1) ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-duplicate-headings -``` - -This package exports no identifiers. -The default export is `remarkLintNoDuplicateHeadings`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-duplicate-headings", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-duplicate-headings readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoDuplicateHeadings from 'remark-lint-no-duplicate-headings' - - remark() - .use(remarkLint) -+ .use(remarkLintNoDuplicateHeadings) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -149,17 +217,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-emphasis-as-heading/index.js b/packages/remark-lint-no-emphasis-as-heading/index.js index a8f3647..e168083 100644 --- a/packages/remark-lint-no-emphasis-as-heading/index.js +++ b/packages/remark-lint-no-emphasis-as-heading/index.js @@ -1,12 +1,26 @@ /** + * ## When should I use this? + * + * You can use this package to check that headings are used to introduce + * paragraphs instead of “fake” headings made with emphasis or strong. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * While not always the case, typically emphasis or strong around the text + * in a paragraph is used as a “faux” heading. + * It’s recommended to use actual headings instead. + * + * @module no-emphasis-as-heading + * @summary + * remark-lint rule to warn when emphasis or strong are used to introduce + * a paragraph. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-emphasis-as-heading - * @fileoverview - * Warn when emphasis (including strong), instead of a heading, introduces - * a paragraph. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-emphasis-as-heading/readme.md b/packages/remark-lint-no-emphasis-as-heading/readme.md index 9f19608..caa4a1d 100644 --- a/packages/remark-lint-no-emphasis-as-heading/readme.md +++ b/packages/remark-lint-no-emphasis-as-heading/readme.md @@ -10,9 +10,35 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when emphasis (including strong), instead of a heading, introduces +[`remark-lint`][mono] rule to warn when emphasis or strong are used to introduce a paragraph. +## Contents + +* [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(remarkLintNoEmphasisAsHeading[, config])`](#unifieduseremarklintnoemphasisasheading-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that headings are used to introduce +paragraphs instead of “fake” headings made with emphasis or strong. + ## Presets This rule is included in the following presets: @@ -21,7 +47,92 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-no-emphasis-as-heading +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoEmphasisAsHeading from 'https://cdn.skypack.dev/remark-lint-no-emphasis-as-heading@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoEmphasisAsHeading from 'remark-lint-no-emphasis-as-heading' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoEmphasisAsHeading) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-emphasis-as-heading example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-emphasis-as-heading", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoEmphasisAsHeading`. + +### `unified().use(remarkLintNoEmphasisAsHeading[, 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). + +There are no options. + +## Recommendation + +While not always the case, typically emphasis or strong around the text +in a paragraph is used as a “faux” heading. +It’s recommended to use actual headings instead. + +## Examples ##### `ok.md` @@ -58,59 +169,12 @@ Quux. 5:1-5:8: Don’t use emphasis to introduce a section, use a heading ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-emphasis-as-heading -``` - -This package exports no identifiers. -The default export is `remarkLintNoEmphasisAsHeading`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-emphasis-as-heading", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-emphasis-as-heading readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoEmphasisAsHeading from 'remark-lint-no-emphasis-as-heading' - - remark() - .use(remarkLint) -+ .use(remarkLintNoEmphasisAsHeading) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -152,17 +216,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-empty-url/index.js b/packages/remark-lint-no-empty-url/index.js index b3ca311..f07aada 100644 --- a/packages/remark-lint-no-empty-url/index.js +++ b/packages/remark-lint-no-empty-url/index.js @@ -1,11 +1,24 @@ /** + * ## When should I use this? + * + * You can use this package to check that links and images have URLs. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * While it is possible to omit URLs in links and images, that typically + * indicates a “placeholder” or todo that has to be filled out later. + * It’s recommended to fill them out. + * + * @module no-empty-url + * @summary + * remark-lint rule to warn for empty URLs in links and images. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-empty-url - * @fileoverview - * Warn for empty URLs in links and images. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-empty-url/readme.md b/packages/remark-lint-no-empty-url/readme.md index 486c545..5b50ae5 100644 --- a/packages/remark-lint-no-empty-url/readme.md +++ b/packages/remark-lint-no-empty-url/readme.md @@ -10,13 +10,123 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn for empty URLs in links and images. +[`remark-lint`][mono] rule to warn for empty URLs in links and images. + +## Contents + +* [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(remarkLintNoEmptyUrl[, config])`](#unifieduseremarklintnoemptyurl-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that links and images have URLs. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-no-empty-url +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoEmptyUrl from 'https://cdn.skypack.dev/remark-lint-no-empty-url@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoEmptyUrl from 'remark-lint-no-empty-url' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoEmptyUrl) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-empty-url example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-empty-url", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoEmptyUrl`. + +### `unified().use(remarkLintNoEmptyUrl[, 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). + +There are no options. + +## Recommendation + +While it is possible to omit URLs in links and images, that typically +indicates a “placeholder” or todo that has to be filled out later. +It’s recommended to fill them out. + +## Examples ##### `ok.md` @@ -49,59 +159,12 @@ No messages. 3:1-3:11: Don’t use images without URL ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-empty-url -``` - -This package exports no identifiers. -The default export is `remarkLintNoEmptyUrl`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-empty-url", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-empty-url readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoEmptyUrl from 'remark-lint-no-empty-url' - - remark() - .use(remarkLint) -+ .use(remarkLintNoEmptyUrl) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -143,17 +206,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-file-name-articles/index.js b/packages/remark-lint-no-file-name-articles/index.js index 0eea8b0..9743d28 100644 --- a/packages/remark-lint-no-file-name-articles/index.js +++ b/packages/remark-lint-no-file-name-articles/index.js @@ -1,11 +1,19 @@ /** + * ## When should I use this? + * + * You can use this package to check that file names do not start with + * articles (`a`, `the`, etc). + * + * ## API + * + * There are no options. + * + * @module no-file-name-articles + * @summary + * remark-lint rule to warn when file names start with articles. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-file-name-articles - * @fileoverview - * Warn when file names start with an article. - * * @example * {"name": "title.md"} * diff --git a/packages/remark-lint-no-file-name-articles/readme.md b/packages/remark-lint-no-file-name-articles/readme.md index 41913a3..aa7f2db 100644 --- a/packages/remark-lint-no-file-name-articles/readme.md +++ b/packages/remark-lint-no-file-name-articles/readme.md @@ -10,7 +10,32 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when file names start with an article. +[`remark-lint`][mono] rule to warn when file names start with articles. + +## Contents + +* [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(remarkLintNoFileNameArticles[, config])`](#unifieduseremarklintnofilenamearticles-config) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that file names do not start with +articles (`a`, `the`, etc). ## Presets @@ -20,7 +45,86 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-no-file-name-articles +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoFileNameArticles from 'https://cdn.skypack.dev/remark-lint-no-file-name-articles@2?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoFileNameArticles from 'remark-lint-no-file-name-articles' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoFileNameArticles) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-file-name-articles example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-file-name-articles", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoFileNameArticles`. + +### `unified().use(remarkLintNoFileNameArticles[, 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). + +There are no options. + +## Examples ##### `title.md` @@ -60,59 +164,12 @@ No messages. 1:1: Do not start file names with `an` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-file-name-articles -``` - -This package exports no identifiers. -The default export is `remarkLintNoFileNameArticles`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-file-name-articles", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-file-name-articles readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoFileNameArticles from 'remark-lint-no-file-name-articles' - - remark() - .use(remarkLint) -+ .use(remarkLintNoFileNameArticles) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -154,17 +211,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-file-name-consecutive-dashes/index.js b/packages/remark-lint-no-file-name-consecutive-dashes/index.js index 7756a50..1fb8eea 100644 --- a/packages/remark-lint-no-file-name-consecutive-dashes/index.js +++ b/packages/remark-lint-no-file-name-consecutive-dashes/index.js @@ -1,11 +1,19 @@ /** + * ## When should I use this? + * + * You can use this package to check that no consecutive dashes appear in + * file names. + * + * ## API + * + * There are no options. + * + * @module no-file-name-consecutive-dashes + * @summary + * remark-lint rule to warn when consecutive dashes appear in file names. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-file-name-consecutive-dashes - * @fileoverview - * Warn when file names contain consecutive dashes. - * * @example * {"name": "plug-ins.md"} * diff --git a/packages/remark-lint-no-file-name-consecutive-dashes/readme.md b/packages/remark-lint-no-file-name-consecutive-dashes/readme.md index a5589e7..097f26a 100644 --- a/packages/remark-lint-no-file-name-consecutive-dashes/readme.md +++ b/packages/remark-lint-no-file-name-consecutive-dashes/readme.md @@ -10,7 +10,32 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when file names contain consecutive dashes. +[`remark-lint`][mono] rule to warn when consecutive dashes appear in file names. + +## Contents + +* [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(remarkLintNoFileNameConsecutiveDashes[, config])`](#unifieduseremarklintnofilenameconsecutivedashes-config) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that no consecutive dashes appear in +file names. ## Presets @@ -20,7 +45,86 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-no-file-name-consecutive-dashes +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoFileNameConsecutiveDashes from 'https://cdn.skypack.dev/remark-lint-no-file-name-consecutive-dashes@2?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoFileNameConsecutiveDashes from 'remark-lint-no-file-name-consecutive-dashes' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoFileNameConsecutiveDashes) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-file-name-consecutive-dashes example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-file-name-consecutive-dashes", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoFileNameConsecutiveDashes`. + +### `unified().use(remarkLintNoFileNameConsecutiveDashes[, 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). + +There are no options. + +## Examples ##### `plug-ins.md` @@ -36,59 +140,12 @@ No messages. 1:1: Do not use consecutive dashes in a file name ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-file-name-consecutive-dashes -``` - -This package exports no identifiers. -The default export is `remarkLintNoFileNameConsecutiveDashes`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-file-name-consecutive-dashes", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-file-name-consecutive-dashes readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoFileNameConsecutiveDashes from 'remark-lint-no-file-name-consecutive-dashes' - - remark() - .use(remarkLint) -+ .use(remarkLintNoFileNameConsecutiveDashes) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -130,17 +187,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-file-name-irregular-characters/index.js b/packages/remark-lint-no-file-name-irregular-characters/index.js index f7d34f9..039ff9b 100644 --- a/packages/remark-lint-no-file-name-irregular-characters/index.js +++ b/packages/remark-lint-no-file-name-irregular-characters/index.js @@ -1,20 +1,24 @@ /** + * ## When should I use this? + * + * You can use this package to check that file names contain regular characters. + * + * ## API + * + * The following options (default: `'\\.a-zA-Z0-9-'`) are accepted: + * + * * `string` (example `'\w\\.'`) + * — allowed characters, wrapped in `new RegExp('[^' + x + ']')`, make sure + * to double escape regexp characters + * * `RegExp` (example `/[^\.a-zA-Z0-9-]/`) + * — disallowed pattern + * + * @module no-file-name-irregular-characters + * @summary + * remark-lint rule to warn when file names contain irregular characters. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-file-name-irregular-characters - * @fileoverview - * Warn when file names contain irregular characters: characters other than - * alphanumericals (`a-zA-Z0-9`), hyphen-minus (`-`), and dots (`.`, full - * stops). - * - * Options: `RegExp` or `string`, default: `'\\.a-zA-Z0-9-'`. - * - * If a string is given, it will be wrapped in - * `new RegExp('[^' + preferred + ']')`. - * - * Any match by the wrapped or given expressions creates a message. - * * @example * {"name": "plug-ins.md"} * diff --git a/packages/remark-lint-no-file-name-irregular-characters/readme.md b/packages/remark-lint-no-file-name-irregular-characters/readme.md index 5901269..52c7c71 100644 --- a/packages/remark-lint-no-file-name-irregular-characters/readme.md +++ b/packages/remark-lint-no-file-name-irregular-characters/readme.md @@ -10,16 +10,31 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when file names contain irregular characters: characters other than -alphanumericals (`a-zA-Z0-9`), hyphen-minus (`-`), and dots (`.`, full -stops). +[`remark-lint`][mono] rule to warn when file names contain irregular characters. -Options: `RegExp` or `string`, default: `'\\.a-zA-Z0-9-'`. +## Contents -If a string is given, it will be wrapped in -`new RegExp('[^' + preferred + ']')`. +* [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(remarkLintNoFileNameIrregularCharacters[, config])`](#unifieduseremarklintnofilenameirregularcharacters-config) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -Any match by the wrapped or given expressions creates a message. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that file names contain regular characters. ## Presets @@ -29,7 +44,92 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-no-file-name-irregular-characters +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoFileNameIrregularCharacters from 'https://cdn.skypack.dev/remark-lint-no-file-name-irregular-characters@2?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoFileNameIrregularCharacters from 'remark-lint-no-file-name-irregular-characters' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoFileNameIrregularCharacters) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-file-name-irregular-characters example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-file-name-irregular-characters", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoFileNameIrregularCharacters`. + +### `unified().use(remarkLintNoFileNameIrregularCharacters[, 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: `'\\.a-zA-Z0-9-'`) are accepted: + +* `string` (example `'\w\\.'`) + — allowed characters, wrapped in `new RegExp('[^' + x + ']')`, make sure + to double escape regexp characters +* `RegExp` (example `/[^\.a-zA-Z0-9-]/`) + — disallowed pattern + +## Examples ##### `plug-ins.md` @@ -69,59 +169,12 @@ When configured with `'\\.a-z0-9'`. 1:1: Do not use `R` in a file name ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-file-name-irregular-characters -``` - -This package exports no identifiers. -The default export is `remarkLintNoFileNameIrregularCharacters`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-file-name-irregular-characters", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-file-name-irregular-characters readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoFileNameIrregularCharacters from 'remark-lint-no-file-name-irregular-characters' - - remark() - .use(remarkLint) -+ .use(remarkLintNoFileNameIrregularCharacters) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -163,17 +216,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-file-name-mixed-case/index.js b/packages/remark-lint-no-file-name-mixed-case/index.js index 4b58901..ea669fd 100644 --- a/packages/remark-lint-no-file-name-mixed-case/index.js +++ b/packages/remark-lint-no-file-name-mixed-case/index.js @@ -1,11 +1,19 @@ /** + * ## When should I use this? + * + * You can use this package to check that file name casing is consistent + * (either lowercase or uppercase). + * + * ## API + * + * There are no options. + * + * @module no-file-name-mixed-case + * @summary + * remark-lint rule to warn when file name casing is inconsistent. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-file-name-mixed-case - * @fileoverview - * Warn when file names use mixed case: both upper- and lowercase characters. - * * @example * {"name": "README.md"} * diff --git a/packages/remark-lint-no-file-name-mixed-case/readme.md b/packages/remark-lint-no-file-name-mixed-case/readme.md index 9af8acb..1579f85 100644 --- a/packages/remark-lint-no-file-name-mixed-case/readme.md +++ b/packages/remark-lint-no-file-name-mixed-case/readme.md @@ -10,7 +10,32 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when file names use mixed case: both upper- and lowercase characters. +[`remark-lint`][mono] rule to warn when file name casing is inconsistent. + +## Contents + +* [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(remarkLintNoFileNameMixedCase[, config])`](#unifieduseremarklintnofilenamemixedcase-config) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that file name casing is consistent +(either lowercase or uppercase). ## Presets @@ -20,7 +45,86 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-no-file-name-mixed-case +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoFileNameMixedCase from 'https://cdn.skypack.dev/remark-lint-no-file-name-mixed-case@2?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoFileNameMixedCase from 'remark-lint-no-file-name-mixed-case' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoFileNameMixedCase) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-file-name-mixed-case example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-file-name-mixed-case", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoFileNameMixedCase`. + +### `unified().use(remarkLintNoFileNameMixedCase[, 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). + +There are no options. + +## Examples ##### `README.md` @@ -42,59 +146,12 @@ No messages. 1:1: Do not mix casing in file names ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-file-name-mixed-case -``` - -This package exports no identifiers. -The default export is `remarkLintNoFileNameMixedCase`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-file-name-mixed-case", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-file-name-mixed-case readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoFileNameMixedCase from 'remark-lint-no-file-name-mixed-case' - - remark() - .use(remarkLint) -+ .use(remarkLintNoFileNameMixedCase) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -136,17 +193,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-file-name-outer-dashes/index.js b/packages/remark-lint-no-file-name-outer-dashes/index.js index a6de9de..65b8db3 100644 --- a/packages/remark-lint-no-file-name-outer-dashes/index.js +++ b/packages/remark-lint-no-file-name-outer-dashes/index.js @@ -1,11 +1,19 @@ /** + * ## When should I use this? + * + * You can use this package to check that no initial or final dashes appear in + * file names. + * + * ## API + * + * There are no options. + * + * @module no-file-name-outer-dashes + * @summary + * remark-lint rule to warn when initial or final dashes appear in file names. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-file-name-outer-dashes - * @fileoverview - * Warn when file names contain initial or final dashes (hyphen-minus, `-`). - * * @example * {"name": "readme.md"} * diff --git a/packages/remark-lint-no-file-name-outer-dashes/readme.md b/packages/remark-lint-no-file-name-outer-dashes/readme.md index 270d189..66aff5e 100644 --- a/packages/remark-lint-no-file-name-outer-dashes/readme.md +++ b/packages/remark-lint-no-file-name-outer-dashes/readme.md @@ -10,7 +10,32 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when file names contain initial or final dashes (hyphen-minus, `-`). +[`remark-lint`][mono] rule to warn when initial or final dashes appear in file names. + +## Contents + +* [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(remarkLintNoFileNameOuterDashes[, config])`](#unifieduseremarklintnofilenameouterdashes-config) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that no initial or final dashes appear in +file names. ## Presets @@ -20,7 +45,86 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-no-file-name-outer-dashes +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoFileNameOuterDashes from 'https://cdn.skypack.dev/remark-lint-no-file-name-outer-dashes@2?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoFileNameOuterDashes from 'remark-lint-no-file-name-outer-dashes' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoFileNameOuterDashes) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-file-name-outer-dashes example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-file-name-outer-dashes", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoFileNameOuterDashes`. + +### `unified().use(remarkLintNoFileNameOuterDashes[, 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). + +There are no options. + +## Examples ##### `readme.md` @@ -44,59 +148,12 @@ No messages. 1:1: Do not use initial or final dashes in a file name ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-file-name-outer-dashes -``` - -This package exports no identifiers. -The default export is `remarkLintNoFileNameOuterDashes`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-file-name-outer-dashes", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-file-name-outer-dashes readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoFileNameOuterDashes from 'remark-lint-no-file-name-outer-dashes' - - remark() - .use(remarkLint) -+ .use(remarkLintNoFileNameOuterDashes) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -138,17 +195,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-heading-content-indent/index.js b/packages/remark-lint-no-heading-content-indent/index.js index 361209f..daf2e7a 100644 --- a/packages/remark-lint-no-heading-content-indent/index.js +++ b/packages/remark-lint-no-heading-content-indent/index.js @@ -1,19 +1,30 @@ /** + * ## When should I use this? + * + * You can use this package to check that there is on space between `#` + * characters and the content in headings. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * One space is required and more than one space has no effect. + * Due to this, it’s recommended to turn this rule on. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats headings with exactly one space. + * + * @module no-heading-content-indent + * @summary + * remark-lint rule to warn when there are too many spaces between + * hashes and content in headings. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-heading-content-indent - * @fileoverview - * Warn when content of headings is indented. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * removes all unneeded padding around content in headings. - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-heading-content-indent/readme.md b/packages/remark-lint-no-heading-content-indent/readme.md index a93eeba..a377a6c 100644 --- a/packages/remark-lint-no-heading-content-indent/readme.md +++ b/packages/remark-lint-no-heading-content-indent/readme.md @@ -10,15 +10,35 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when content of headings is indented. +[`remark-lint`][mono] rule to warn when there are too many spaces between +hashes and content in headings. -## Fix +## Contents -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -removes all unneeded padding around content in headings. +* [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(remarkLintNoHeadingContentIndent[, config])`](#unifieduseremarklintnoheadingcontentindent-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -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. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that there is on space between `#` +characters and the content in headings. ## Presets @@ -28,13 +48,102 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | -## 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-no-heading-content-indent +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoHeadingContentIndent from 'https://cdn.skypack.dev/remark-lint-no-heading-content-indent@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoHeadingContentIndent from 'remark-lint-no-heading-content-indent' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoHeadingContentIndent) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-heading-content-indent example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-heading-content-indent", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoHeadingContentIndent`. + +### `unified().use(remarkLintNoHeadingContentIndent[, 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). + +There are no options. + +## Recommendation + +One space is required and more than one space has no effect. +Due to this, it’s recommended to turn this rule on. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats headings with exactly one space. + +## Examples ##### `ok.md` ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown #·Foo @@ -57,7 +166,7 @@ No messages. ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown #··Foo @@ -79,7 +188,7 @@ Note: `·` represents a space. ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown #·· @@ -89,59 +198,12 @@ Note: `·` represents a space. No messages. -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-heading-content-indent -``` - -This package exports no identifiers. -The default export is `remarkLintNoHeadingContentIndent`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-heading-content-indent", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-heading-content-indent readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoHeadingContentIndent from 'remark-lint-no-heading-content-indent' - - remark() - .use(remarkLint) -+ .use(remarkLintNoHeadingContentIndent) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -183,17 +245,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-heading-indent/index.js b/packages/remark-lint-no-heading-indent/index.js index 1a5b9eb..51c708d 100644 --- a/packages/remark-lint-no-heading-indent/index.js +++ b/packages/remark-lint-no-heading-indent/index.js @@ -1,19 +1,40 @@ /** + * ## When should I use this? + * + * You can use this package to check that headings are not indented. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * There is no specific handling of indented headings (or anything else) in + * markdown. + * While it is possible to use an indent to headings on their text: + * + * ```markdown + * # One + * ## Two + * ### Three + * #### Four + * ``` + * + * …such style is uncommon, a bit hard to maintain, and it’s impossible to add a + * heading with a rank of 5 as it would form indented code instead. + * Hence, it’s recommended to not indent headings and to turn this rule on. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats all headings without indent. + * + * @module no-heading-indent + * @summary + * remark-lint rule to warn when headings are indented. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-heading-indent - * @fileoverview - * Warn when a heading is indented. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * removes all unneeded indentation before headings. - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-heading-indent/readme.md b/packages/remark-lint-no-heading-indent/readme.md index e57fc6c..3090204 100644 --- a/packages/remark-lint-no-heading-indent/readme.md +++ b/packages/remark-lint-no-heading-indent/readme.md @@ -10,27 +10,146 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when a heading is indented. +[`remark-lint`][mono] rule to warn when headings are indented. -## Fix +## Contents -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -removes all unneeded indentation before headings. +* [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(remarkLintNoHeadingIndent[, config])`](#unifieduseremarklintnoheadingindent-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -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. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that headings are not indented. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-no-heading-indent +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoHeadingIndent from 'https://cdn.skypack.dev/remark-lint-no-heading-indent@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoHeadingIndent from 'remark-lint-no-heading-indent' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoHeadingIndent) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-heading-indent example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-heading-indent", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoHeadingIndent`. + +### `unified().use(remarkLintNoHeadingIndent[, 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). + +There are no options. + +## Recommendation + +There is no specific handling of indented headings (or anything else) in +markdown. +While it is possible to use an indent to headings on their text: + +```markdown + # One + ## Two + ### Three +#### Four +``` + +…such style is uncommon, a bit hard to maintain, and it’s impossible to add a +heading with a rank of 5 as it would form indented code instead. +Hence, it’s recommended to not indent headings and to turn this rule on. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats all headings without indent. + +## Examples ##### `ok.md` ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown #·Hello world @@ -52,7 +171,7 @@ No messages. ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown ···# Hello world @@ -75,59 +194,12 @@ Note: `·` represents a space. 8:4: Remove 3 spaces before this heading ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-heading-indent -``` - -This package exports no identifiers. -The default export is `remarkLintNoHeadingIndent`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-heading-indent", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-heading-indent readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoHeadingIndent from 'remark-lint-no-heading-indent' - - remark() - .use(remarkLint) -+ .use(remarkLintNoHeadingIndent) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -169,17 +241,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-heading-like-paragraph/index.js b/packages/remark-lint-no-heading-like-paragraph/index.js index 067e66f..2090420 100644 --- a/packages/remark-lint-no-heading-like-paragraph/index.js +++ b/packages/remark-lint-no-heading-like-paragraph/index.js @@ -1,11 +1,20 @@ /** + * ## When should I use this? + * + * You can use this package to ensure that no heading-like constructs are + * created, which instead will result in paragraphs with the `#` characters + * shown. + * + * ## API + * + * There are no options. + * + * @module no-heading-like-paragraph + * @summary + * remark-lint rule to warn when h7+ “headings” are used. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-heading-like-paragraph - * @fileoverview - * Warn for h7+ “headings”. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-heading-like-paragraph/readme.md b/packages/remark-lint-no-heading-like-paragraph/readme.md index 8503ba8..a78120b 100644 --- a/packages/remark-lint-no-heading-like-paragraph/readme.md +++ b/packages/remark-lint-no-heading-like-paragraph/readme.md @@ -10,13 +10,118 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn for h7+ “headings”. +[`remark-lint`][mono] rule to warn when h7+ “headings” are used. + +## Contents + +* [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(remarkLintNoHeadingLikeParagraph[, config])`](#unifieduseremarklintnoheadinglikeparagraph-config) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to ensure that no heading-like constructs are +created, which instead will result in paragraphs with the `#` characters +shown. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-no-heading-like-paragraph +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoHeadingLikeParagraph from 'https://cdn.skypack.dev/remark-lint-no-heading-like-paragraph@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoHeadingLikeParagraph from 'remark-lint-no-heading-like-paragraph' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoHeadingLikeParagraph) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-heading-like-paragraph example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-heading-like-paragraph", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoHeadingLikeParagraph`. + +### `unified().use(remarkLintNoHeadingLikeParagraph[, 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). + +There are no options. + +## Examples ##### `ok.md` @@ -48,59 +153,12 @@ Delta. 1:1-1:16: This looks like a heading but has too many hashes ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-heading-like-paragraph -``` - -This package exports no identifiers. -The default export is `remarkLintNoHeadingLikeParagraph`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-heading-like-paragraph", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-heading-like-paragraph readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoHeadingLikeParagraph from 'remark-lint-no-heading-like-paragraph' - - remark() - .use(remarkLint) -+ .use(remarkLintNoHeadingLikeParagraph) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -142,17 +200,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-heading-punctuation/index.js b/packages/remark-lint-no-heading-punctuation/index.js index 9232fe4..da6f51b 100644 --- a/packages/remark-lint-no-heading-punctuation/index.js +++ b/packages/remark-lint-no-heading-punctuation/index.js @@ -1,16 +1,24 @@ /** + * ## When should I use this? + * + * You can use this package to check that headings don’t end in punctuation. + * + * ## API + * + * The following options (default: `'\\.,;:!?'`) are accepted: + * + * * `string` (example `'\\.,;:'`) + * — disallowed characters, wrapped in `new RegExp('[' + x + ']')`, make sure + * to double escape regexp characters + * * `RegExp` (example `/\p{P}/u`) + * — disallowed pattern + * + * @module no-heading-punctuation + * @summary + * remark-lint rule to warn headings end in certain punctuation. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-heading-punctuation - * @fileoverview - * Warn when a heading ends with a group of characters. - * - * Options: `string`, default: `'.,;:!?'`. - * - * Note: these are added to a regex, in a group (`'[' + char + ']'`), be - * careful to escape the string correctly. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-heading-punctuation/readme.md b/packages/remark-lint-no-heading-punctuation/readme.md index b5719dc..987968b 100644 --- a/packages/remark-lint-no-heading-punctuation/readme.md +++ b/packages/remark-lint-no-heading-punctuation/readme.md @@ -10,12 +10,31 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when a heading ends with a group of characters. +[`remark-lint`][mono] rule to warn headings end in certain punctuation. -Options: `string`, default: `'.,;:!?'`. +## Contents -Note: these are added to a regex, in a group (`'[' + char + ']'`), be -careful to escape the string correctly. +* [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(remarkLintNoHeadingPunctuation[, config])`](#unifieduseremarklintnoheadingpunctuation-config) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that headings don’t end in punctuation. ## Presets @@ -25,7 +44,92 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `':.'` | -## 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-no-heading-punctuation +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoHeadingPunctuation from 'https://cdn.skypack.dev/remark-lint-no-heading-punctuation@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoHeadingPunctuation from 'remark-lint-no-heading-punctuation' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoHeadingPunctuation) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-heading-punctuation example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-heading-punctuation", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoHeadingPunctuation`. + +### `unified().use(remarkLintNoHeadingPunctuation[, 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: `'\\.,;:!?'`) are accepted: + +* `string` (example `'\\.,;:'`) + — disallowed characters, wrapped in `new RegExp('[' + x + ']')`, make sure + to double escape regexp characters +* `RegExp` (example `/\p{P}/u`) + — disallowed pattern + +## Examples ##### `ok.md` @@ -79,59 +183,12 @@ When configured with `',;:!?'`. No messages. -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-heading-punctuation -``` - -This package exports no identifiers. -The default export is `remarkLintNoHeadingPunctuation`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-heading-punctuation", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-heading-punctuation readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoHeadingPunctuation from 'remark-lint-no-heading-punctuation' - - remark() - .use(remarkLint) -+ .use(remarkLintNoHeadingPunctuation) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -173,17 +230,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-html/index.js b/packages/remark-lint-no-html/index.js index e8364b5..b2af01e 100644 --- a/packages/remark-lint-no-html/index.js +++ b/packages/remark-lint-no-html/index.js @@ -1,13 +1,18 @@ /** + * ## When should I use this? + * + * You can use this package to check that no HTML (other than comments) is used. + * + * ## API + * + * There are no options. + * + * @module no-html + * @summary + * remark-lint rule to warn when HTML is used. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-html - * @fileoverview - * Warn when HTML nodes are used. - * - * Ignores comments, because they are used by `remark`, `remark-lint`, other - * Markdown tools, and because Markdown doesn’t have native comments. * * @example * {"name": "ok.md"} diff --git a/packages/remark-lint-no-html/readme.md b/packages/remark-lint-no-html/readme.md index 1d7bef3..cc4feb5 100644 --- a/packages/remark-lint-no-html/readme.md +++ b/packages/remark-lint-no-html/readme.md @@ -10,16 +10,116 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when HTML nodes are used. +[`remark-lint`][mono] rule to warn when HTML is used. -Ignores comments, because they are used by `remark`, `remark-lint`, other -Markdown tools, and because Markdown doesn’t have native comments. +## Contents + +* [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(remarkLintNoHtml[, config])`](#unifieduseremarklintnohtml-config) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that no HTML (other than comments) is used. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-no-html +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoHtml from 'https://cdn.skypack.dev/remark-lint-no-html@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoHtml from 'remark-lint-no-html' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoHtml) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-html example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-html", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoHtml`. + +### `unified().use(remarkLintNoHtml[, 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). + +There are no options. + +## Examples ##### `ok.md` @@ -49,59 +149,12 @@ No messages. 1:1-1:15: Do not use HTML in markdown ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-html -``` - -This package exports no identifiers. -The default export is `remarkLintNoHtml`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-html", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-html readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoHtml from 'remark-lint-no-html' - - remark() - .use(remarkLint) -+ .use(remarkLintNoHtml) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -143,17 +196,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-inline-padding/index.js b/packages/remark-lint-no-inline-padding/index.js index 9a29351..a8faab9 100644 --- a/packages/remark-lint-no-inline-padding/index.js +++ b/packages/remark-lint-no-inline-padding/index.js @@ -1,14 +1,21 @@ /** + * ## When should I use this? + * + * You can use this package to check that inline constructs (links) are + * not padded. + * Historically, it was possible to pad emphasis, strong, and strikethrough + * too, but this was removed in CommonMark, making this rule much less useful. + * + * ## API + * + * There are no options. + * + * @module no-inline-padding + * @summary + * remark-lint rule to warn when inline constructs are padded. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-inline-padding - * @fileoverview - * Warn when phrasing content is padded with spaces between their markers and - * content. - * - * Warns for emphasis, strong, delete, image, and link. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-inline-padding/readme.md b/packages/remark-lint-no-inline-padding/readme.md index af81691..8517619 100644 --- a/packages/remark-lint-no-inline-padding/readme.md +++ b/packages/remark-lint-no-inline-padding/readme.md @@ -10,10 +10,34 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when phrasing content is padded with spaces between their markers and -content. +[`remark-lint`][mono] rule to warn when inline constructs are padded. -Warns for emphasis, strong, delete, image, and link. +## Contents + +* [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(remarkLintNoInlinePadding[, config])`](#unifieduseremarklintnoinlinepadding-config) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that inline constructs (links) are +not padded. +Historically, it was possible to pad emphasis, strong, and strikethrough +too, but this was removed in CommonMark, making this rule much less useful. ## Presets @@ -24,7 +48,86 @@ This rule is included in the following presets: | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | -## 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-no-inline-padding +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoInlinePadding from 'https://cdn.skypack.dev/remark-lint-no-inline-padding@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoInlinePadding from 'remark-lint-no-inline-padding' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoInlinePadding) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-inline-padding example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-inline-padding", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoInlinePadding`. + +### `unified().use(remarkLintNoInlinePadding[, 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). + +There are no options. + +## Examples ##### `ok.md` @@ -52,59 +155,12 @@ Alpha [ bravo ](http://echo.fox/trot) 1:7-1:38: Don’t pad `link` with inner spaces ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-inline-padding -``` - -This package exports no identifiers. -The default export is `remarkLintNoInlinePadding`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-inline-padding", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-inline-padding readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoInlinePadding from 'remark-lint-no-inline-padding' - - remark() - .use(remarkLint) -+ .use(remarkLintNoInlinePadding) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -146,17 +202,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-literal-urls/index.js b/packages/remark-lint-no-literal-urls/index.js index 40efb7d..3410bfa 100644 --- a/packages/remark-lint-no-literal-urls/index.js +++ b/packages/remark-lint-no-literal-urls/index.js @@ -1,23 +1,30 @@ /** + * ## When should I use this? + * + * You can use this package to check that autolink literal URLs are not used. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Autolink literal URLs (just a URL) are a feature enabled by GFM. + * They don’t work everywhere. + * Due to this, it’s recommended to instead use normal autolinks + * (``) or links (`[text](url)`). + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * never creates autolink literals and always uses normal autolinks (``). + * + * @module no-literal-urls + * @summary + * remark-lint rule to warn for autolink literals. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-literal-urls - * @fileoverview - * Warn for literal URLs in text. - * URLs are treated as links in some Markdown vendors, but not in others. - * To make sure they are always linked, wrap them in `<` (less than) and `>` - * (greater than). - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * never creates literal URLs and always uses `<` (less than) and `>` - * (greater than). - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-literal-urls/readme.md b/packages/remark-lint-no-literal-urls/readme.md index 206d537..cc8ee09 100644 --- a/packages/remark-lint-no-literal-urls/readme.md +++ b/packages/remark-lint-no-literal-urls/readme.md @@ -10,19 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn for literal URLs in text. -URLs are treated as links in some Markdown vendors, but not in others. -To make sure they are always linked, wrap them in `<` (less than) and `>` -(greater than). +[`remark-lint`][mono] rule to warn for autolink literals. -## Fix +## Contents -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -never creates literal URLs and always uses `<` (less than) and `>` -(greater than). +* [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(remarkLintNoLiteralUrls[, config])`](#unifieduseremarklintnoliteralurls-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -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. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that autolink literal URLs are not used. ## Presets @@ -33,7 +47,98 @@ This rule is included in the following presets: | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | -## 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-no-literal-urls +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoLiteralUrls from 'https://cdn.skypack.dev/remark-lint-no-literal-urls@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoLiteralUrls from 'remark-lint-no-literal-urls' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoLiteralUrls) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-literal-urls example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-literal-urls", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoLiteralUrls`. + +### `unified().use(remarkLintNoLiteralUrls[, 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). + +There are no options. + +## Recommendation + +Autolink literal URLs (just a URL) are a feature enabled by GFM. +They don’t work everywhere. +Due to this, it’s recommended to instead use normal autolinks +(``) or links (`[text](url)`). + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +never creates autolink literals and always uses normal autolinks (``). + +## Examples ##### `ok.md` @@ -51,7 +156,7 @@ No messages. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown http://foo.bar/baz @@ -63,59 +168,12 @@ http://foo.bar/baz 1:1-1:19: Don’t use literal URLs without angle brackets ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-literal-urls -``` - -This package exports no identifiers. -The default export is `remarkLintNoLiteralUrls`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-literal-urls", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-literal-urls readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoLiteralUrls from 'remark-lint-no-literal-urls' - - remark() - .use(remarkLint) -+ .use(remarkLintNoLiteralUrls) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -157,17 +215,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-missing-blank-lines/index.js b/packages/remark-lint-no-missing-blank-lines/index.js index 4634dbd..a682b67 100644 --- a/packages/remark-lint-no-missing-blank-lines/index.js +++ b/packages/remark-lint-no-missing-blank-lines/index.js @@ -1,26 +1,34 @@ /** + * ## When should I use this? + * + * You can use this package to check that blank lines are used between blocks. + * + * ## API + * + * The following options (default: `undefined`) are accepted: + * + * * `Object` with the following fields: + * * `exceptTightLists` (`boolean`, default: `false`) + * — allow tight list items + * + * ## Recommendation + * + * While not always required, blank lines are required in certain, sometimes + * confusing, cases. + * Due to this, it’s recommended to always use blank lines between blocks. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * always uses blank lines between blocks. + * It has a `join` function to customize such behavior. + * + * @module no-missing-blank-lines + * @summary + * remark-lint rule to warn when blank lines are missing. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-missing-blank-lines - * @fileoverview - * Warn when missing blank lines before block content (and frontmatter - * content). - * - * This rule can be configured to allow tight list items without blank lines - * between their contents by passing `{exceptTightLists: true}` (default: - * `false`). - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * always uses one blank line between blocks if possible, or two lines when - * needed. - * The style of the list items persists. - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-missing-blank-lines/readme.md b/packages/remark-lint-no-missing-blank-lines/readme.md index 8d0068a..5b8cb6c 100644 --- a/packages/remark-lint-no-missing-blank-lines/readme.md +++ b/packages/remark-lint-no-missing-blank-lines/readme.md @@ -10,28 +10,134 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when missing blank lines before block content (and frontmatter -content). +[`remark-lint`][mono] rule to warn when blank lines are missing. -This rule can be configured to allow tight list items without blank lines -between their contents by passing `{exceptTightLists: true}` (default: -`false`). +## Contents -## Fix +* [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(remarkLintNoMissingBlankLines[, config])`](#unifieduseremarklintnomissingblanklines-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -always uses one blank line between blocks if possible, or two lines when -needed. -The style of the list items persists. +## What is this? -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. +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that blank lines are used between blocks. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-no-missing-blank-lines +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoMissingBlankLines from 'https://cdn.skypack.dev/remark-lint-no-missing-blank-lines@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoMissingBlankLines from 'remark-lint-no-missing-blank-lines' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoMissingBlankLines) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-missing-blank-lines example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-missing-blank-lines", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoMissingBlankLines`. + +### `unified().use(remarkLintNoMissingBlankLines[, 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: `undefined`) are accepted: + +* `Object` with the following fields: + * `exceptTightLists` (`boolean`, default: `false`) + — allow tight list items + +## Recommendation + +While not always required, blank lines are required in certain, sometimes +confusing, cases. +Due to this, it’s recommended to always use blank lines between blocks. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +always uses blank lines between blocks. +It has a `join` function to customize such behavior. + +## Examples ##### `ok.md` @@ -96,59 +202,12 @@ Paragraph. 2:1-2:7: Missing blank line before block node ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-missing-blank-lines -``` - -This package exports no identifiers. -The default export is `remarkLintNoMissingBlankLines`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-missing-blank-lines", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-missing-blank-lines readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoMissingBlankLines from 'remark-lint-no-missing-blank-lines' - - remark() - .use(remarkLint) -+ .use(remarkLintNoMissingBlankLines) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -190,17 +249,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-multiple-toplevel-headings/index.js b/packages/remark-lint-no-multiple-toplevel-headings/index.js index 65e805c..fef6544 100644 --- a/packages/remark-lint-no-multiple-toplevel-headings/index.js +++ b/packages/remark-lint-no-multiple-toplevel-headings/index.js @@ -1,13 +1,27 @@ /** + * ## When should I use this? + * + * You can use this package to check that no more than one top level heading + * is used. + * + * ## API + * + * The following options (default: `1`) are accepted: + * + * * `number` (example: `1`) + * — assumed top level heading rank + * + * ## Recommendation + * + * Documents should almost always have one main heading, which is typically a + * heading with a rank of `1`. + * + * @module no-multiple-toplevel-headings + * @summary + * remark-lint rule to warn when more than one top level heading is used. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-multiple-toplevel-headings - * @fileoverview - * Warn when multiple top level headings are used. - * - * Options: `number`, default: `1`. - * * @example * {"name": "ok.md", "setting": 1} * diff --git a/packages/remark-lint-no-multiple-toplevel-headings/readme.md b/packages/remark-lint-no-multiple-toplevel-headings/readme.md index 5bd6c7b..e278e0b 100644 --- a/packages/remark-lint-no-multiple-toplevel-headings/readme.md +++ b/packages/remark-lint-no-multiple-toplevel-headings/readme.md @@ -10,9 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when multiple top level headings are used. +[`remark-lint`][mono] rule to warn when more than one top level heading is used. -Options: `number`, default: `1`. +## Contents + +* [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(remarkLintNoMultipleToplevelHeadings[, config])`](#unifieduseremarklintnomultipletoplevelheadings-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that no more than one top level heading +is used. ## Presets @@ -22,7 +46,94 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-no-multiple-toplevel-headings +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoMultipleToplevelHeadings from 'https://cdn.skypack.dev/remark-lint-no-multiple-toplevel-headings@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoMultipleToplevelHeadings from 'remark-lint-no-multiple-toplevel-headings' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoMultipleToplevelHeadings) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-multiple-toplevel-headings example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-multiple-toplevel-headings", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoMultipleToplevelHeadings`. + +### `unified().use(remarkLintNoMultipleToplevelHeadings[, 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: `1`) are accepted: + +* `number` (example: `1`) + — assumed top level heading rank + +## Recommendation + +Documents should almost always have one main heading, which is typically a +heading with a rank of `1`. + +## Examples ##### `ok.md` @@ -58,59 +169,12 @@ When configured with `1`. 3:1-3:6: Don’t use multiple top level headings (1:1) ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-multiple-toplevel-headings -``` - -This package exports no identifiers. -The default export is `remarkLintNoMultipleToplevelHeadings`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-multiple-toplevel-headings", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-multiple-toplevel-headings readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoMultipleToplevelHeadings from 'remark-lint-no-multiple-toplevel-headings' - - remark() - .use(remarkLint) -+ .use(remarkLintNoMultipleToplevelHeadings) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -152,17 +216,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-paragraph-content-indent/index.js b/packages/remark-lint-no-paragraph-content-indent/index.js index 3ae28e5..9e56f0c 100644 --- a/packages/remark-lint-no-paragraph-content-indent/index.js +++ b/packages/remark-lint-no-paragraph-content-indent/index.js @@ -1,11 +1,24 @@ /** + * ## When should I use this? + * + * You can use this package to check that content in paragraphs is not + * indented. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Indenting further lines in a paragraph has no effect. + * Due to this, it’s recommended to turn this rule on. + * + * @module no-paragraph-content-indent + * @summary + * remark-lint rule to warn when content in paragraphs is indented. * @author Titus Wormer * @copyright 2017 Titus Wormer * @license MIT - * @module no-paragraph-content-indent - * @fileoverview - * Warn when the content in paragraphs is indented. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-paragraph-content-indent/readme.md b/packages/remark-lint-no-paragraph-content-indent/readme.md index 3da4435..fff95ed 100644 --- a/packages/remark-lint-no-paragraph-content-indent/readme.md +++ b/packages/remark-lint-no-paragraph-content-indent/readme.md @@ -10,13 +10,123 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when the content in paragraphs is indented. +[`remark-lint`][mono] rule to warn when content in paragraphs is indented. + +## Contents + +* [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(remarkLintNoParagraphContentIndent[, config])`](#unifieduseremarklintnoparagraphcontentindent-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that content in paragraphs is not +indented. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-no-paragraph-content-indent +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoParagraphContentIndent from 'https://cdn.skypack.dev/remark-lint-no-paragraph-content-indent@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoParagraphContentIndent from 'remark-lint-no-paragraph-content-indent' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoParagraphContentIndent) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-paragraph-content-indent example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-paragraph-content-indent", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoParagraphContentIndent`. + +### `unified().use(remarkLintNoParagraphContentIndent[, 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). + +There are no options. + +## Recommendation + +Indenting further lines in a paragraph has no effect. +Due to this, it’s recommended to turn this rule on. + +## Examples ##### `ok.md` @@ -58,7 +168,7 @@ No messages. ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown ·Alpha @@ -98,59 +208,12 @@ oscar 22:4: Expected no indentation in paragraph content ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-paragraph-content-indent -``` - -This package exports no identifiers. -The default export is `remarkLintNoParagraphContentIndent`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-paragraph-content-indent", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-paragraph-content-indent readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoParagraphContentIndent from 'remark-lint-no-paragraph-content-indent' - - remark() - .use(remarkLint) -+ .use(remarkLintNoParagraphContentIndent) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -192,17 +255,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-reference-like-url/index.js b/packages/remark-lint-no-reference-like-url/index.js index e46a19a..4277152 100644 --- a/packages/remark-lint-no-reference-like-url/index.js +++ b/packages/remark-lint-no-reference-like-url/index.js @@ -1,11 +1,27 @@ /** + * ## When should I use this? + * + * You can use this package to check for broken URLs that should likely + * have been references. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * While full URLs for definition identifiers are okay + * (`[https://example.com]: https://example.com`), and what looks like an + * identifier could be an actual URL (`[text](alpha)`), the more common case + * is that, assuming a definition `[alpha]: https://example.com`, then a link + * of (`[text](alpha)`) should instead’ve been `[text][alpha]`. + * + * @module no-reference-like-url + * @summary + * remark-lint rule to warn when URLs are also defined identifiers. * @author Titus Wormer * @copyright 2016 Titus Wormer * @license MIT - * @module no-reference-like-url - * @fileoverview - * Warn when URLs are also defined identifiers. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-reference-like-url/readme.md b/packages/remark-lint-no-reference-like-url/readme.md index 3243a04..238b88e 100644 --- a/packages/remark-lint-no-reference-like-url/readme.md +++ b/packages/remark-lint-no-reference-like-url/readme.md @@ -10,13 +10,126 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when URLs are also defined identifiers. +[`remark-lint`][mono] rule to warn when URLs are also defined identifiers. + +## Contents + +* [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(remarkLintNoReferenceLikeUrl[, config])`](#unifieduseremarklintnoreferencelikeurl-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check for broken URLs that should likely +have been references. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-no-reference-like-url +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoReferenceLikeUrl from 'https://cdn.skypack.dev/remark-lint-no-reference-like-url@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoReferenceLikeUrl from 'remark-lint-no-reference-like-url' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoReferenceLikeUrl) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-reference-like-url example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-reference-like-url", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoReferenceLikeUrl`. + +### `unified().use(remarkLintNoReferenceLikeUrl[, 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). + +There are no options. + +## Recommendation + +While full URLs for definition identifiers are okay +(`[https://example.com]: https://example.com`), and what looks like an +identifier could be an actual URL (`[text](alpha)`), the more common case +is that, assuming a definition `[alpha]: https://example.com`, then a link +of (`[text](alpha)`) should instead’ve been `[text][alpha]`. + +## Examples ##### `ok.md` @@ -48,59 +161,12 @@ No messages. 1:1-1:17: Did you mean to use `[delta]` instead of `(delta)`, a reference? ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-reference-like-url -``` - -This package exports no identifiers. -The default export is `remarkLintNoReferenceLikeUrl`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-reference-like-url", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-reference-like-url readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoReferenceLikeUrl from 'remark-lint-no-reference-like-url' - - remark() - .use(remarkLint) -+ .use(remarkLintNoReferenceLikeUrl) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -142,17 +208,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-shell-dollars/index.js b/packages/remark-lint-no-shell-dollars/index.js index bd73cf7..1df5525 100644 --- a/packages/remark-lint-no-shell-dollars/index.js +++ b/packages/remark-lint-no-shell-dollars/index.js @@ -1,13 +1,27 @@ /** + * ## When should I use this? + * + * You can use this package to check that not all lines in shell code are + * preceded by dollars (`$`). + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Dollars make copy/pasting hard. + * Either put both dollars in front of some lines (to indicate shell commands) + * and don’t put them in front of other lines, or use fenced code to indicate + * shell commands on their own, followed by another fenced code that contains + * just the output. + * + * @module no-shell-dollars + * @summary + * remark-lint rule to warn every line in shell code is preceded by `$`s. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-shell-dollars - * @fileoverview - * Warn when shell code is prefixed by `$` (dollar sign) characters. - * - * Ignores indented code blocks and fenced code blocks without language flag. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-shell-dollars/readme.md b/packages/remark-lint-no-shell-dollars/readme.md index 4b9217e..a5a131a 100644 --- a/packages/remark-lint-no-shell-dollars/readme.md +++ b/packages/remark-lint-no-shell-dollars/readme.md @@ -10,9 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when shell code is prefixed by `$` (dollar sign) characters. +[`remark-lint`][mono] rule to warn every line in shell code is preceded by `$`s. -Ignores indented code blocks and fenced code blocks without language flag. +## Contents + +* [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(remarkLintNoShellDollars[, config])`](#unifieduseremarklintnoshelldollars-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that not all lines in shell code are +preceded by dollars (`$`). ## Presets @@ -22,7 +46,94 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-no-shell-dollars +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoShellDollars from 'https://cdn.skypack.dev/remark-lint-no-shell-dollars@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoShellDollars from 'remark-lint-no-shell-dollars' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoShellDollars) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-shell-dollars example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-shell-dollars", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoShellDollars`. + +### `unified().use(remarkLintNoShellDollars[, 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). + +There are no options. + +## Recommendation + +Dollars make copy/pasting hard. +Either put both dollars in front of some lines (to indicate shell commands) +and don’t put them in front of other lines, or use fenced code to indicate +shell commands on their own, followed by another fenced code that contains +just the output. + +## Examples ##### `ok.md` @@ -82,59 +193,12 @@ $ echo a > file 5:1-8:4: Do not use dollar signs before shell commands ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-shell-dollars -``` - -This package exports no identifiers. -The default export is `remarkLintNoShellDollars`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-shell-dollars", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-shell-dollars readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoShellDollars from 'remark-lint-no-shell-dollars' - - remark() - .use(remarkLint) -+ .use(remarkLintNoShellDollars) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -176,17 +240,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-shortcut-reference-image/index.js b/packages/remark-lint-no-shortcut-reference-image/index.js index b9633a6..e4ef8fd 100644 --- a/packages/remark-lint-no-shortcut-reference-image/index.js +++ b/packages/remark-lint-no-shortcut-reference-image/index.js @@ -1,17 +1,27 @@ /** + * ## When should I use this? + * + * You can use this package to check that collapsed or full reference images + * are used. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Shortcut references use an implicit style that looks a lot like something + * that could occur as plain text instead of syntax. + * In some cases, plain text is intended instead of an image. + * Due to this, it’s recommended to use collapsed (or full) references + * instead. + * + * @module no-shortcut-reference-image + * @summary + * remark-lint rule to warn when shortcut reference images are used. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-shortcut-reference-image - * @fileoverview - * Warn when shortcut reference images are used. - * - * Shortcut references render as images when a definition is found, and as - * plain text without definition. - * Sometimes, you don’t intend to create an image from the reference, but this - * rule still warns anyway. - * In that case, you can escape the reference like so: `!\[foo]`. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-shortcut-reference-image/readme.md b/packages/remark-lint-no-shortcut-reference-image/readme.md index 97dda60..3d03087 100644 --- a/packages/remark-lint-no-shortcut-reference-image/readme.md +++ b/packages/remark-lint-no-shortcut-reference-image/readme.md @@ -10,13 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when shortcut reference images are used. +[`remark-lint`][mono] rule to warn when shortcut reference images are used. -Shortcut references render as images when a definition is found, and as -plain text without definition. -Sometimes, you don’t intend to create an image from the reference, but this -rule still warns anyway. -In that case, you can escape the reference like so: `!\[foo]`. +## Contents + +* [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(remarkLintNoShortcutReferenceImage[, config])`](#unifieduseremarklintnoshortcutreferenceimage-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that collapsed or full reference images +are used. ## Presets @@ -27,7 +47,94 @@ This rule is included in the following presets: | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | -## 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-no-shortcut-reference-image +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoShortcutReferenceImage from 'https://cdn.skypack.dev/remark-lint-no-shortcut-reference-image@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoShortcutReferenceImage from 'remark-lint-no-shortcut-reference-image' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoShortcutReferenceImage) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-shortcut-reference-image example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-shortcut-reference-image", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoShortcutReferenceImage`. + +### `unified().use(remarkLintNoShortcutReferenceImage[, 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). + +There are no options. + +## Recommendation + +Shortcut references use an implicit style that looks a lot like something +that could occur as plain text instead of syntax. +In some cases, plain text is intended instead of an image. +Due to this, it’s recommended to use collapsed (or full) references +instead. + +## Examples ##### `ok.md` @@ -59,59 +166,12 @@ No messages. 1:1-1:7: Use the trailing [] on reference images ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-shortcut-reference-image -``` - -This package exports no identifiers. -The default export is `remarkLintNoShortcutReferenceImage`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-shortcut-reference-image", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-shortcut-reference-image readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoShortcutReferenceImage from 'remark-lint-no-shortcut-reference-image' - - remark() - .use(remarkLint) -+ .use(remarkLintNoShortcutReferenceImage) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -153,17 +213,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-shortcut-reference-link/index.js b/packages/remark-lint-no-shortcut-reference-link/index.js index f9d58c8..6a72550 100644 --- a/packages/remark-lint-no-shortcut-reference-link/index.js +++ b/packages/remark-lint-no-shortcut-reference-link/index.js @@ -1,17 +1,27 @@ /** + * ## When should I use this? + * + * You can use this package to check that collapsed or full reference links + * are used. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Shortcut references use an implicit style that looks a lot like something + * that could occur as plain text instead of syntax. + * In some cases, plain text is intended instead of a link. + * Due to this, it’s recommended to use collapsed (or full) references + * instead. + * + * @module no-shortcut-reference-link + * @summary + * remark-lint rule to warn when shortcut reference links are used. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-shortcut-reference-link - * @fileoverview - * Warn when shortcut reference links are used. - * - * Shortcut references render as links when a definition is found, and as - * plain text without definition. - * Sometimes, you don’t intend to create a link from the reference, but this - * rule still warns anyway. - * In that case, you can escape the reference like so: `\[foo]`. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-shortcut-reference-link/readme.md b/packages/remark-lint-no-shortcut-reference-link/readme.md index 93ddaaa..2bacf6e 100644 --- a/packages/remark-lint-no-shortcut-reference-link/readme.md +++ b/packages/remark-lint-no-shortcut-reference-link/readme.md @@ -10,13 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when shortcut reference links are used. +[`remark-lint`][mono] rule to warn when shortcut reference links are used. -Shortcut references render as links when a definition is found, and as -plain text without definition. -Sometimes, you don’t intend to create a link from the reference, but this -rule still warns anyway. -In that case, you can escape the reference like so: `\[foo]`. +## Contents + +* [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(remarkLintNoShortcutReferenceLink[, config])`](#unifieduseremarklintnoshortcutreferencelink-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that collapsed or full reference links +are used. ## Presets @@ -27,7 +47,94 @@ This rule is included in the following presets: | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | -## 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-no-shortcut-reference-link +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoShortcutReferenceLink from 'https://cdn.skypack.dev/remark-lint-no-shortcut-reference-link@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoShortcutReferenceLink from 'remark-lint-no-shortcut-reference-link' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoShortcutReferenceLink) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-shortcut-reference-link example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-shortcut-reference-link", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoShortcutReferenceLink`. + +### `unified().use(remarkLintNoShortcutReferenceLink[, 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). + +There are no options. + +## Recommendation + +Shortcut references use an implicit style that looks a lot like something +that could occur as plain text instead of syntax. +In some cases, plain text is intended instead of a link. +Due to this, it’s recommended to use collapsed (or full) references +instead. + +## Examples ##### `ok.md` @@ -59,59 +166,12 @@ No messages. 1:1-1:6: Use the trailing `[]` on reference links ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-shortcut-reference-link -``` - -This package exports no identifiers. -The default export is `remarkLintNoShortcutReferenceLink`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-shortcut-reference-link", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-shortcut-reference-link readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoShortcutReferenceLink from 'remark-lint-no-shortcut-reference-link' - - remark() - .use(remarkLint) -+ .use(remarkLintNoShortcutReferenceLink) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -153,17 +213,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-table-indentation/index.js b/packages/remark-lint-no-table-indentation/index.js index e417eb3..dff9ffe 100644 --- a/packages/remark-lint-no-table-indentation/index.js +++ b/packages/remark-lint-no-table-indentation/index.js @@ -1,19 +1,31 @@ /** + * ## When should I use this? + * + * You can use this package to check that tables are not indented. + * Tables are a GFM feature enabled with + * [`remark-gfm`](https://github.com/remarkjs/remark-gfm). + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * There is no specific handling of indented tables (or anything else) in + * markdown. + * Hence, it’s recommended to not indent tables and to turn this rule on. + * + * ## Fix + * + * [`remark-gfm`](https://github.com/remarkjs/remark-gfm) + * formats all tables without indent. + * + * @module no-table-indentation + * @summary + * remark-lint rule to warn when tables are indented. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-table-indentation - * @fileoverview - * Warn when tables are indented. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * removes all unneeded indentation before tables. - * - * 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. - * * @example * {"name": "ok.md", "gfm": true} * diff --git a/packages/remark-lint-no-table-indentation/readme.md b/packages/remark-lint-no-table-indentation/readme.md index 5631983..b50cac5 100644 --- a/packages/remark-lint-no-table-indentation/readme.md +++ b/packages/remark-lint-no-table-indentation/readme.md @@ -10,15 +10,35 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when tables are indented. +[`remark-lint`][mono] rule to warn when tables are indented. -## Fix +## Contents -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -removes all unneeded indentation before tables. +* [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(remarkLintNoTableIndentation[, config])`](#unifieduseremarklintnotableindentation-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -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. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that tables are not indented. +Tables are a GFM feature enabled with +[`remark-gfm`](https://github.com/remarkjs/remark-gfm). ## Presets @@ -28,13 +48,103 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-no-table-indentation +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoTableIndentation from 'https://cdn.skypack.dev/remark-lint-no-table-indentation@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoTableIndentation from 'remark-lint-no-table-indentation' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoTableIndentation) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-table-indentation example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-table-indentation", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoTableIndentation`. + +### `unified().use(remarkLintNoTableIndentation[, 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). + +There are no options. + +## Recommendation + +There is no specific handling of indented tables (or anything else) in +markdown. +Hence, it’s recommended to not indent tables and to turn this rule on. + +## Fix + +[`remark-gfm`](https://github.com/remarkjs/remark-gfm) +formats all tables without indent. + +## Examples ##### `ok.md` ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown Paragraph. @@ -52,9 +162,9 @@ No messages. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown Paragraph. @@ -76,9 +186,9 @@ Paragraph. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown >··| A | @@ -95,9 +205,9 @@ Note: `·` represents a space. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown -···paragraph @@ -112,59 +222,12 @@ Note: `·` represents a space. 3:6: Do not indent table rows ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-table-indentation -``` - -This package exports no identifiers. -The default export is `remarkLintNoTableIndentation`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-table-indentation", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-table-indentation readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoTableIndentation from 'remark-lint-no-table-indentation' - - remark() - .use(remarkLint) -+ .use(remarkLintNoTableIndentation) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -206,17 +269,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-tabs/index.js b/packages/remark-lint-no-tabs/index.js index e87f7e8..ebb6e5a 100644 --- a/packages/remark-lint-no-tabs/index.js +++ b/packages/remark-lint-no-tabs/index.js @@ -1,20 +1,58 @@ /** + * ## When should I use this? + * + * You can use this package to check that tabs are not used. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Regardless of the debate in other languages of whether to use tabs vs. + * spaces, when it comes to markdown, tabs do not work as expected. + * Largely around contains such as block quotes and lists. + * Take for example block quotes: `>\ta` gives a paragraph with the text `a` + * in a blockquote, so one might expect that `>\t\ta` results in indented code + * with the text `a` in a block quote. + * + * ```markdown + * >\ta + * + * >\t\ta + * ``` + * + * Yields: + * + * ```html + *
+ *

a

+ *
+ *
+ * 
  a
+ *
+ *
+ * ``` + * + * Because markdown uses a hardcoded tab size of 4, the first tab could be + * represented as 3 spaces (because there’s a `>` before). + * One of those “spaces” is taken because block quotes allow the `>` to be + * followed by one space, leaving 2 spaces. + * The next tab can be represented as 4 spaces, so together we have 6 spaces. + * The indented code uses 4 spaces, so there are two spaces left, which are + * shown in the indented code. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * uses spaces exclusively for indentation. + * + * @module no-tabs + * @summary + * remark-lint rule to warn when tabs are used. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module no-tabs - * @fileoverview - * Warn when hard tabs (`\t`) are used instead of spaces. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * uses spaces where tabs are used for indentation, but retains tabs used in - * content. - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-tabs/readme.md b/packages/remark-lint-no-tabs/readme.md index fd8b57a..95e754b 100644 --- a/packages/remark-lint-no-tabs/readme.md +++ b/packages/remark-lint-no-tabs/readme.md @@ -10,28 +10,164 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when hard tabs (`\t`) are used instead of spaces. +[`remark-lint`][mono] rule to warn when tabs are used. -## Fix +## Contents -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -uses spaces where tabs are used for indentation, but retains tabs used in -content. +* [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(remarkLintNoTabs[, config])`](#unifieduseremarklintnotabs-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -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. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that tabs are not used. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-no-tabs +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoTabs from 'https://cdn.skypack.dev/remark-lint-no-tabs@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoTabs from 'remark-lint-no-tabs' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoTabs) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-tabs example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-tabs", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoTabs`. + +### `unified().use(remarkLintNoTabs[, 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). + +There are no options. + +## Recommendation + +Regardless of the debate in other languages of whether to use tabs vs. +spaces, when it comes to markdown, tabs do not work as expected. +Largely around contains such as block quotes and lists. +Take for example block quotes: `>\ta` gives a paragraph with the text `a` +in a blockquote, so one might expect that `>\t\ta` results in indented code +with the text `a` in a block quote. + +```markdown +>\ta + +>\t\ta +``` + +Yields: + +```html +
+

a

+
+
+
  a
+
+
+``` + +Because markdown uses a hardcoded tab size of 4, the first tab could be +represented as 3 spaces (because there’s a `>` before). +One of those “spaces” is taken because block quotes allow the `>` to be +followed by one space, leaving 2 spaces. +The next tab can be represented as 4 spaces, so together we have 6 spaces. +The indented code uses 4 spaces, so there are two spaces left, which are +shown in the indented code. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +uses spaces exclusively for indentation. + +## Examples ##### `ok.md` ###### In -Note: `·` represents a space. +> 👉 **Note**: `·` represents a space. ```markdown Foo Bar @@ -47,7 +183,7 @@ No messages. ###### In -Note: `»` represents a tab. +> 👉 **Note**: `»` represents a tab. ```markdown »Here's one before a code block. @@ -79,59 +215,12 @@ And this is a tab as the last character.» 13:41: Use spaces instead of tabs ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-tabs -``` - -This package exports no identifiers. -The default export is `remarkLintNoTabs`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-tabs", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-tabs readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoTabs from 'remark-lint-no-tabs' - - remark() - .use(remarkLint) -+ .use(remarkLintNoTabs) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -173,17 +262,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-undefined-references/index.js b/packages/remark-lint-no-undefined-references/index.js index 4e9faba..a2405d5 100644 --- a/packages/remark-lint-no-undefined-references/index.js +++ b/packages/remark-lint-no-undefined-references/index.js @@ -1,17 +1,46 @@ /** + * ## When should I use this? + * + * You can use this package to check that referenced definitions are defined. + * + * ## API + * + * The following options (default: `undefined`) are accepted: + * + * * `Object` with the following fields: + * * `allow` (`Array`, default: `[]`) + * — text that you want to allowed between `[` and `]` even though it’s + * undefined + * + * ## Recommendation + * + * Shortcut references use an implicit syntax that could also occur as plain + * text. + * For example, it is reasonable to expect an author adding `[…]` to abbreviate + * some text somewhere in a document: + * + * ```markdown + * > Some […] quote. + * ``` + * + * This isn’t a problem, but it might become one when an author later adds a + * definition: + * + * ```markdown + * Some text. […][] + * + * […] #read-more "Read more" + * ``` + * + * The second author might expect only their newly added text to form a link, + * but their changes also result in a link for the first author’s text. + * + * @module no-undefined-references + * @summary + * remark-lint rule to warn when undefined definitions are referenced. * @author Titus Wormer * @copyright 2016 Titus Wormer * @license MIT - * @module no-undefined-references - * @fileoverview - * Warn when references to undefined definitions are found. - * - * Options: `Object`, optional. - * - * The object can have an `allow` field, set to an array of strings that may - * appear between `[` and `]`, but that should not be treated as link - * identifiers. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-undefined-references/readme.md b/packages/remark-lint-no-undefined-references/readme.md index bec36f4..c90d2dd 100644 --- a/packages/remark-lint-no-undefined-references/readme.md +++ b/packages/remark-lint-no-undefined-references/readme.md @@ -10,13 +10,32 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when references to undefined definitions are found. +[`remark-lint`][mono] rule to warn when undefined definitions are referenced. -Options: `Object`, optional. +## Contents -The object can have an `allow` field, set to an array of strings that may -appear between `[` and `]`, but that should not be treated as link -identifiers. +* [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(remarkLintNoUndefinedReferences[, config])`](#unifieduseremarklintnoundefinedreferences-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that referenced definitions are defined. ## Presets @@ -26,7 +45,114 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | -## 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-no-undefined-references +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoUndefinedReferences from 'https://cdn.skypack.dev/remark-lint-no-undefined-references@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoUndefinedReferences from 'remark-lint-no-undefined-references' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoUndefinedReferences) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-undefined-references example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-undefined-references", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoUndefinedReferences`. + +### `unified().use(remarkLintNoUndefinedReferences[, 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: `undefined`) are accepted: + +* `Object` with the following fields: + * `allow` (`Array`, default: `[]`) + — text that you want to allowed between `[` and `]` even though it’s + undefined + +## Recommendation + +Shortcut references use an implicit syntax that could also occur as plain +text. +For example, it is reasonable to expect an author adding `[…]` to abbreviate +some text somewhere in a document: + +```markdown +> Some […] quote. +``` + +This isn’t a problem, but it might become one when an author later adds a +definition: + +```markdown +Some text. […][] + +[…] #read-more "Read more" +``` + +The second author might expect only their newly added text to form a link, +but their changes also result in a link for the first author’s text. + +## Examples ##### `ok.md` @@ -101,59 +227,12 @@ When configured with `{ allow: [ '...', '…' ] }`. No messages. -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-undefined-references -``` - -This package exports no identifiers. -The default export is `remarkLintNoUndefinedReferences`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-undefined-references", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-undefined-references readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoUndefinedReferences from 'remark-lint-no-undefined-references' - - remark() - .use(remarkLint) -+ .use(remarkLintNoUndefinedReferences) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -195,17 +274,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-unneeded-full-reference-image/index.js b/packages/remark-lint-no-unneeded-full-reference-image/index.js index 832105c..7f822b6 100644 --- a/packages/remark-lint-no-unneeded-full-reference-image/index.js +++ b/packages/remark-lint-no-unneeded-full-reference-image/index.js @@ -1,15 +1,25 @@ /** + * ## When should I use this? + * + * You can use this package to check that collapsed reference images are + * used instead of full references where possible. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Full reference syntax (`[Text][text]`) is quite verbose compared to + * the concise collapsed reference syntax (`[Text][]`). + * + * @module no-unneeded-full-reference-image + * @summary + * remark-lint rule to warn when full reference images are used that + * could be collapsed. * @author Titus Wormer * @copyright 2019 Titus Wormer * @license MIT - * @module no-unneeded-full-reference-image - * @fileoverview - * Warn when full reference images are used that could be collapsed. - * - * Full references (such as `[Remark][remark]`) can also be written as a - * collapsed reference (`[Remark][]`) if normalising the reference text yields - * the label. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-unneeded-full-reference-image/readme.md b/packages/remark-lint-no-unneeded-full-reference-image/readme.md index ed5dc2c..34bc0cb 100644 --- a/packages/remark-lint-no-unneeded-full-reference-image/readme.md +++ b/packages/remark-lint-no-unneeded-full-reference-image/readme.md @@ -10,17 +10,124 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when full reference images are used that could be collapsed. +[`remark-lint`][mono] rule to warn when full reference images are used that +could be collapsed. -Full references (such as `[Remark][remark]`) can also be written as a -collapsed reference (`[Remark][]`) if normalising the reference text yields -the label. +## Contents + +* [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(remarkLintNoUnneededFullReferenceImage[, config])`](#unifieduseremarklintnounneededfullreferenceimage-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that collapsed reference images are +used instead of full references where possible. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-no-unneeded-full-reference-image +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoUnneededFullReferenceImage from 'https://cdn.skypack.dev/remark-lint-no-unneeded-full-reference-image@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoUnneededFullReferenceImage from 'remark-lint-no-unneeded-full-reference-image' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoUnneededFullReferenceImage) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-unneeded-full-reference-image example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-unneeded-full-reference-image", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoUnneededFullReferenceImage`. + +### `unified().use(remarkLintNoUnneededFullReferenceImage[, 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). + +There are no options. + +## Recommendation + +Full reference syntax (`[Text][text]`) is quite verbose compared to +the concise collapsed reference syntax (`[Text][]`). + +## Examples ##### `ok.md` @@ -62,59 +169,12 @@ No messages. 3:1-3:20: Remove the image label as it matches the reference text ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-unneeded-full-reference-image -``` - -This package exports no identifiers. -The default export is `remarkLintNoUnneededFullReferenceImage`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-unneeded-full-reference-image", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-unneeded-full-reference-image readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoUnneededFullReferenceImage from 'remark-lint-no-unneeded-full-reference-image' - - remark() - .use(remarkLint) -+ .use(remarkLintNoUnneededFullReferenceImage) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -156,17 +216,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-unneeded-full-reference-link/index.js b/packages/remark-lint-no-unneeded-full-reference-link/index.js index 6743e76..62e933c 100644 --- a/packages/remark-lint-no-unneeded-full-reference-link/index.js +++ b/packages/remark-lint-no-unneeded-full-reference-link/index.js @@ -1,15 +1,25 @@ /** + * ## When should I use this? + * + * You can use this package to check that collapsed reference links are + * used instead of full references where possible. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Full reference syntax (`![Alt][alt]`) is quite verbose compared to + * the concise collapsed reference syntax (`![Alt][]`). + * + * @module no-unneeded-full-reference-link + * @summary + * remark-lint rule to warn when full reference links are used that + * could be collapsed. * @author Titus Wormer * @copyright 2019 Titus Wormer * @license MIT - * @module no-unneeded-full-reference-link - * @fileoverview - * Warn when full reference links are used that could be collapsed. - * - * Full references (such as `[Remark][remark]`) can also be written as a - * collapsed reference (`[Remark][]`) if normalising the reference text yields - * the label. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-unneeded-full-reference-link/readme.md b/packages/remark-lint-no-unneeded-full-reference-link/readme.md index 88ab973..343b4cb 100644 --- a/packages/remark-lint-no-unneeded-full-reference-link/readme.md +++ b/packages/remark-lint-no-unneeded-full-reference-link/readme.md @@ -10,17 +10,124 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when full reference links are used that could be collapsed. +[`remark-lint`][mono] rule to warn when full reference links are used that +could be collapsed. -Full references (such as `[Remark][remark]`) can also be written as a -collapsed reference (`[Remark][]`) if normalising the reference text yields -the label. +## Contents + +* [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(remarkLintNoUnneededFullReferenceLink[, config])`](#unifieduseremarklintnounneededfullreferencelink-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that collapsed reference links are +used instead of full references where possible. ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-no-unneeded-full-reference-link +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoUnneededFullReferenceLink from 'https://cdn.skypack.dev/remark-lint-no-unneeded-full-reference-link@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoUnneededFullReferenceLink from 'remark-lint-no-unneeded-full-reference-link' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoUnneededFullReferenceLink) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-unneeded-full-reference-link example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-unneeded-full-reference-link", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoUnneededFullReferenceLink`. + +### `unified().use(remarkLintNoUnneededFullReferenceLink[, 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). + +There are no options. + +## Recommendation + +Full reference syntax (`![Alt][alt]`) is quite verbose compared to +the concise collapsed reference syntax (`![Alt][]`). + +## Examples ##### `ok.md` @@ -68,59 +175,12 @@ No messages. 3:1-3:19: Remove the link label as it matches the reference text ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-unneeded-full-reference-link -``` - -This package exports no identifiers. -The default export is `remarkLintNoUnneededFullReferenceLink`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-unneeded-full-reference-link", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-unneeded-full-reference-link readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoUnneededFullReferenceLink from 'remark-lint-no-unneeded-full-reference-link' - - remark() - .use(remarkLint) -+ .use(remarkLintNoUnneededFullReferenceLink) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -162,17 +222,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-no-unused-definitions/index.js b/packages/remark-lint-no-unused-definitions/index.js index 8c3133a..8585a0f 100644 --- a/packages/remark-lint-no-unused-definitions/index.js +++ b/packages/remark-lint-no-unused-definitions/index.js @@ -1,11 +1,22 @@ /** + * ## When should I use this? + * + * You can use this package to check definitions are referenced. + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * Unused definitions do not contribute anything, so they can be removed. + * + * @module no-unused-definitions + * @summary + * remark-lint rule to warn when unreferenced definitions are used. * @author Titus Wormer * @copyright 2016 Titus Wormer * @license MIT - * @module no-unused-definitions - * @fileoverview - * Warn when unused definitions are found. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-no-unused-definitions/readme.md b/packages/remark-lint-no-unused-definitions/readme.md index 907a0ca..4c8445c 100644 --- a/packages/remark-lint-no-unused-definitions/readme.md +++ b/packages/remark-lint-no-unused-definitions/readme.md @@ -10,7 +10,32 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when unused definitions are found. +[`remark-lint`][mono] rule to warn when unreferenced definitions are used. + +## Contents + +* [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(remarkLintNoUnusedDefinitions[, config])`](#unifieduseremarklintnounuseddefinitions-config) +* [Recommendation](#recommendation) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check definitions are referenced. ## Presets @@ -20,7 +45,90 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | | -## 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-no-unused-definitions +``` + +In Deno with [Skypack][]: + +```js +import remarkLintNoUnusedDefinitions from 'https://cdn.skypack.dev/remark-lint-no-unused-definitions@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintNoUnusedDefinitions from 'remark-lint-no-unused-definitions' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintNoUnusedDefinitions) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-no-unused-definitions example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-no-unused-definitions", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintNoUnusedDefinitions`. + +### `unified().use(remarkLintNoUnusedDefinitions[, 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). + +There are no options. + +## Recommendation + +Unused definitions do not contribute anything, so they can be removed. + +## Examples ##### `ok.md` @@ -50,59 +158,12 @@ No messages. 1:1-1:27: Found unused definition ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-no-unused-definitions -``` - -This package exports no identifiers. -The default export is `remarkLintNoUnusedDefinitions`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-no-unused-definitions", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-no-unused-definitions readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintNoUnusedDefinitions from 'remark-lint-no-unused-definitions' - - remark() - .use(remarkLint) -+ .use(remarkLintNoUnusedDefinitions) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -144,17 +205,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-ordered-list-marker-style/index.js b/packages/remark-lint-ordered-list-marker-style/index.js index b026f55..6efb8e0 100644 --- a/packages/remark-lint-ordered-list-marker-style/index.js +++ b/packages/remark-lint-ordered-list-marker-style/index.js @@ -1,16 +1,40 @@ /** + * ## When should I use this? + * + * You can use this package to check that ordered list markers are consistent. + * + * ## API + * + * The following options (default: `'consistent'`) are accepted: + * + * * `'.'` + * — prefer dots + * * `')'` + * — prefer parens + * * `'consistent'` + * — detect the first used style and warn when further markers differ + * + * ## Recommendation + * + * Parens for list markers were not supported in markdown before CommonMark. + * While they should work in most places now, not all markdown parsers follow + * CommonMark. + * Due to this, it’s recommended to prefer dots. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats ordered lists with dots by default. + * Pass + * [`bulletOrdered: ')'`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsbulletordered) + * to always use parens. + * + * @module ordered-list-marker-style + * @summary + * remark-lint rule to warn when ordered list markers are inconsistent. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module ordered-list-marker-style - * @fileoverview - * Warn when the list item marker style of ordered lists violate a given style. - * - * Options: `'consistent'`, `'.'`, or `')'`, default: `'consistent'`. - * - * `'consistent'` detects the first used list style and warns when subsequent - * lists use different styles. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-ordered-list-marker-style/readme.md b/packages/remark-lint-ordered-list-marker-style/readme.md index 1c05919..e790e9c 100644 --- a/packages/remark-lint-ordered-list-marker-style/readme.md +++ b/packages/remark-lint-ordered-list-marker-style/readme.md @@ -10,12 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when the list item marker style of ordered lists violate a given style. +[`remark-lint`][mono] rule to warn when ordered list markers are inconsistent. -Options: `'consistent'`, `'.'`, or `')'`, default: `'consistent'`. +## Contents -`'consistent'` detects the first used list style and warns when subsequent -lists use 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(remarkLintOrderedListMarkerStyle[, config])`](#unifieduseremarklintorderedlistmarkerstyle-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that ordered list markers are consistent. ## Presets @@ -27,7 +48,108 @@ This rule is included in the following presets: | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'.'` | | [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | `'.'` | -## 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-ordered-list-marker-style +``` + +In Deno with [Skypack][]: + +```js +import remarkLintOrderedListMarkerStyle from 'https://cdn.skypack.dev/remark-lint-ordered-list-marker-style@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintOrderedListMarkerStyle from 'remark-lint-ordered-list-marker-style' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintOrderedListMarkerStyle) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-ordered-list-marker-style example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-ordered-list-marker-style", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintOrderedListMarkerStyle`. + +### `unified().use(remarkLintOrderedListMarkerStyle[, 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: + +* `'.'` + — prefer dots +* `')'` + — prefer parens +* `'consistent'` + — detect the first used style and warn when further markers differ + +## Recommendation + +Parens for list markers were not supported in markdown before CommonMark. +While they should work in most places now, not all markdown parsers follow +CommonMark. +Due to this, it’s recommended to prefer dots. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats ordered lists with dots by default. +Pass +[`bulletOrdered: ')'`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsbulletordered) +to always use parens. + +## Examples ##### `ok.md` @@ -106,59 +228,12 @@ When configured with `'💩'`. 1:1: Incorrect ordered list item marker style `💩`: use either `'.'` or `')'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-ordered-list-marker-style -``` - -This package exports no identifiers. -The default export is `remarkLintOrderedListMarkerStyle`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-ordered-list-marker-style", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-ordered-list-marker-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 remarkLintOrderedListMarkerStyle from 'remark-lint-ordered-list-marker-style' - - remark() - .use(remarkLint) -+ .use(remarkLintOrderedListMarkerStyle) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -200,17 +275,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-ordered-list-marker-value/index.js b/packages/remark-lint-ordered-list-marker-value/index.js index e83ea34..9536f58 100644 --- a/packages/remark-lint-ordered-list-marker-value/index.js +++ b/packages/remark-lint-ordered-list-marker-value/index.js @@ -1,32 +1,44 @@ /** + * ## When should I use this? + * + * You can use this package to check that ordered list values are consistent. + * + * ## API + * + * The following options (default: `'ordered'`) are accepted: + * + * * `'ordered'` + * — values should increment by one from the first item + * * `'single'` + * — values should stay the same as the first item + * * `'one'` + * — values should always be exactly `1` + * + * ## Recommendation + * + * While `'single'` might be the smartest style, as it makes it easier to move + * items around without having to renumber everything and doesn’t have + * problems with aligning content of the 9th and the 10th item, it’s not used a + * lot and arguably looks unnatural. + * `'one'` is like `'single'` but forces every list to start at `1`. + * While not often needed, starting lists at other values is sometimes useful. + * Due to this, `'ordered'` is recommended, although `'single'` is also a viable + * choice. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * retains the value of the first item and increments further items by default. + * Pass + * [`incrementListMarker: false`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsincrementlistmarker) + * to not increment further items. + * + * @module ordered-list-marker-value + * @summary + * remark-lint rule to warn when ordered list values are inconsistent. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module ordered-list-marker-value - * @fileoverview - * Warn when the list item marker values of ordered lists violate a given - * style. - * - * Options: `'single'`, `'one'`, or `'ordered'`, default: `'ordered'`. - * - * When set to `'ordered'`, list item bullets should increment by one, - * relative to the starting point. - * When set to `'single'`, bullets should be the same as the relative starting - * point. - * When set to `'one'`, bullets should always be `1`. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * retains the number of the first list item bullet, and by default - * increments the other items. - * Pass - * [`incrementListMarker: false`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsincrementlistmarker) - * to not increment further list items. - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-ordered-list-marker-value/readme.md b/packages/remark-lint-ordered-list-marker-value/readme.md index bdb1594..c16ee8c 100644 --- a/packages/remark-lint-ordered-list-marker-value/readme.md +++ b/packages/remark-lint-ordered-list-marker-value/readme.md @@ -10,28 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when the list item marker values of ordered lists violate a given -style. +[`remark-lint`][mono] rule to warn when ordered list values are inconsistent. -Options: `'single'`, `'one'`, or `'ordered'`, default: `'ordered'`. +## Contents -When set to `'ordered'`, list item bullets should increment by one, -relative to the starting point. -When set to `'single'`, bullets should be the same as the relative starting -point. -When set to `'one'`, bullets should always be `1`. +* [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(remarkLintOrderedListMarkerValue[, config])`](#unifieduseremarklintorderedlistmarkervalue-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) -retains the number of the first list item bullet, and by default -increments the other items. -Pass -[`incrementListMarker: false`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsincrementlistmarker) -to not increment further list items. +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 ordered list values are consistent. ## Presets @@ -41,7 +46,112 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'one'` | -## 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-ordered-list-marker-value +``` + +In Deno with [Skypack][]: + +```js +import remarkLintOrderedListMarkerValue from 'https://cdn.skypack.dev/remark-lint-ordered-list-marker-value@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintOrderedListMarkerValue from 'remark-lint-ordered-list-marker-value' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintOrderedListMarkerValue) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-ordered-list-marker-value example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-ordered-list-marker-value", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintOrderedListMarkerValue`. + +### `unified().use(remarkLintOrderedListMarkerValue[, 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: `'ordered'`) are accepted: + +* `'ordered'` + — values should increment by one from the first item +* `'single'` + — values should stay the same as the first item +* `'one'` + — values should always be exactly `1` + +## Recommendation + +While `'single'` might be the smartest style, as it makes it easier to move +items around without having to renumber everything and doesn’t have +problems with aligning content of the 9th and the 10th item, it’s not used a +lot and arguably looks unnatural. +`'one'` is like `'single'` but forces every list to start at `1`. +While not often needed, starting lists at other values is sometimes useful. +Due to this, `'ordered'` is recommended, although `'single'` is also a viable +choice. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +retains the value of the first item and increments further items by default. +Pass +[`incrementListMarker: false`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsincrementlistmarker) +to not increment further items. + +## Examples ##### `ok.md` @@ -209,59 +319,12 @@ When configured with `'💩'`. 1:1: Incorrect ordered list item marker value `💩`: use either `'ordered'`, `'one'`, or `'single'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-ordered-list-marker-value -``` - -This package exports no identifiers. -The default export is `remarkLintOrderedListMarkerValue`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-ordered-list-marker-value", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-ordered-list-marker-value readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintOrderedListMarkerValue from 'remark-lint-ordered-list-marker-value' - - remark() - .use(remarkLint) -+ .use(remarkLintOrderedListMarkerValue) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -303,17 +366,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-rule-style/index.js b/packages/remark-lint-rule-style/index.js index 1e18598..849e8fe 100644 --- a/packages/remark-lint-rule-style/index.js +++ b/packages/remark-lint-rule-style/index.js @@ -1,33 +1,47 @@ /** + * ## When should I use this? + * + * You can use this package to check that rules (thematic breaks, horizontal + * rules) are consistent. + * + * ## API + * + * The following options (default: `'consistent'`) are accepted: + * + * * `string` (example: `'** * **'`, `'___'`) + * — thematic break to prefer + * * `'consistent'` + * — detect the first used style and warn when further rules differ + * + * ## Recommendation + * + * Rules consist of a `*`, `-`, or `_` character, which occurs at least three + * times with nothing else except for arbitrary spaces or tabs on a single line. + * Using spaces, tabs, and more than three markers seems unnecessary work to + * type out. + * Because asterisks can be used as a marker for more markdown constructs, + * it’s recommended to use that for rules (and lists, emphasis, strong) too. + * Due to this, it’s recommended to pass `'***'`. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats rules with `***` by default. + * There are three settings to control rules: + * + * * [`rule`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsrule) + * (default: `'*'`) — marker + * * [`ruleRepetition`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsrulerepetition) + * (default: `3`) — repetitions + * * [`ruleSpaces`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsrulespaces) + * (default: `false`) — use spaces between markers + * + * @module rule-style + * @summary + * remark-lint rule to warn when rule markers are inconsistent. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module rule-style - * @fileoverview - * Warn when the thematic breaks (horizontal rules) violate a given or - * detected style. - * - * Options: `string`, either a corect thematic breaks such as `***`, or - * `'consistent'`, default: `'consistent'`. - * - * `'consistent'` detects the first used thematic break style and warns when - * subsequent rules use different styles. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * has three settings that define how rules are created: - * - * * [`rule`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsrule) - * (default: `*`) — Marker to use - * * [`ruleRepetition`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsrulerepetition) - * (default: `3`) — Number of markers to use - * * [`ruleSpaces`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsrulespaces) - * (default: `true`) — Whether to pad markers with spaces - * - * 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. - * * @example * {"name": "ok.md", "setting": "* * *"} * diff --git a/packages/remark-lint-rule-style/readme.md b/packages/remark-lint-rule-style/readme.md index f37fcbc..9003983 100644 --- a/packages/remark-lint-rule-style/readme.md +++ b/packages/remark-lint-rule-style/readme.md @@ -10,29 +10,34 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when the thematic breaks (horizontal rules) violate a given or -detected style. +[`remark-lint`][mono] rule to warn when rule markers are inconsistent. -Options: `string`, either a corect thematic breaks such as `***`, or -`'consistent'`, default: `'consistent'`. +## Contents -`'consistent'` detects the first used thematic break style and warns when -subsequent rules use 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(remarkLintRuleStyle[, config])`](#unifieduseremarklintrulestyle-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) -has three settings that define how rules are created: +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. -* [`rule`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsrule) - (default: `*`) — Marker to use -* [`ruleRepetition`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsrulerepetition) - (default: `3`) — Number of markers to use -* [`ruleSpaces`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsrulespaces) - (default: `true`) — Whether to pad markers with spaces +## When should I use this? -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. +You can use this package to check that rules (thematic breaks, horizontal +rules) are consistent. ## Presets @@ -43,7 +48,114 @@ This rule is included in the following presets: | [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'---'` | -## 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-rule-style +``` + +In Deno with [Skypack][]: + +```js +import remarkLintRuleStyle from 'https://cdn.skypack.dev/remark-lint-rule-style@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintRuleStyle from 'remark-lint-rule-style' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintRuleStyle) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-rule-style example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-rule-style", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintRuleStyle`. + +### `unified().use(remarkLintRuleStyle[, 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: + +* `string` (example: `'** * **'`, `'___'`) + — thematic break to prefer +* `'consistent'` + — detect the first used style and warn when further rules differ + +## Recommendation + +Rules consist of a `*`, `-`, or `_` character, which occurs at least three +times with nothing else except for arbitrary spaces or tabs on a single line. +Using spaces, tabs, and more than three markers seems unnecessary work to +type out. +Because asterisks can be used as a marker for more markdown constructs, +it’s recommended to use that for rules (and lists, emphasis, strong) too. +Due to this, it’s recommended to pass `'***'`. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats rules with `***` by default. +There are three settings to control rules: + +* [`rule`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsrule) + (default: `'*'`) — marker +* [`ruleRepetition`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsrulerepetition) + (default: `3`) — repetitions +* [`ruleSpaces`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsrulespaces) + (default: `false`) — use spaces between markers + +## Examples ##### `ok.md` @@ -103,59 +215,12 @@ When configured with `'💩'`. 1:1: Incorrect preferred rule style: provide a correct markdown rule or `'consistent'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-rule-style -``` - -This package exports no identifiers. -The default export is `remarkLintRuleStyle`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-rule-style", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-rule-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 remarkLintRuleStyle from 'remark-lint-rule-style' - - remark() - .use(remarkLint) -+ .use(remarkLintRuleStyle) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -197,17 +262,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-strikethrough-marker/index.js b/packages/remark-lint-strikethrough-marker/index.js index b744b05..1f823ab 100644 --- a/packages/remark-lint-strikethrough-marker/index.js +++ b/packages/remark-lint-strikethrough-marker/index.js @@ -1,21 +1,40 @@ /** + * ## When should I use this? + * + * You can use this package to check that the number of strikethrough + * markers is consistent. + * Strikethrough is a GFM feature enabled with + * [`remark-gfm`](https://github.com/remarkjs/remark-gfm). + * + * ## API + * + * The following options (default: `'consistent'`) are accepted: + * + * * `'~'` + * — prefer one strikethrough marker + * * `'~~'` + * — prefer two strikethrough markers + * * `'consistent'` + * — detect the first used style and warn when further strikethrough differs + * + * ## Recommendation + * + * GitHub flavored markdown (GFM) specifies that two tildes should be used, + * but `github.com` allows one tilde everywhere. + * It’s recommended to use two tildes. + * + * ## Fix + * + * [`remark-gfm`](https://github.com/remarkjs/remark-gfm) + * formats all strikethrough with two tildes. + * + * @module strikethrough-marker + * @summary + * remark-lint rule to warn when the number of strikethrough markers + * is inconsistent. * @author Denis Augsburger * @copyright 2021 Denis Augsburger * @license MIT - * @module strikethrough-marker - * @fileoverview - * Warn for violating strikethrough markers. - * - * Options: `'consistent'`, `'~'`, or `'~~'`, default: `'consistent'`. - * - * `'consistent'` detects the first used strikethrough style and warns when - * subsequent strikethrough use different styles. - * - * ## Fix - * - * 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. - * * @example * {"setting": "~", "name": "ok.md", "gfm": true} * diff --git a/packages/remark-lint-strikethrough-marker/readme.md b/packages/remark-lint-strikethrough-marker/readme.md index c8b6789..4342c92 100644 --- a/packages/remark-lint-strikethrough-marker/readme.md +++ b/packages/remark-lint-strikethrough-marker/readme.md @@ -10,23 +10,140 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn for violating strikethrough markers. +[`remark-lint`][mono] rule to warn when the number of strikethrough markers +is inconsistent. -Options: `'consistent'`, `'~'`, or `'~~'`, default: `'consistent'`. +## Contents -`'consistent'` detects the first used strikethrough style and warns when -subsequent strikethrough use 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(remarkLintStrikethroughMarker[, config])`](#unifieduseremarklintstrikethroughmarker-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -## Fix +## What is this? -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. +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that the number of strikethrough +markers is consistent. +Strikethrough is a GFM feature enabled with +[`remark-gfm`](https://github.com/remarkjs/remark-gfm). ## Presets -This rule is not included in any default preset +This rule is not included in a preset maintained here. -## 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-strikethrough-marker +``` + +In Deno with [Skypack][]: + +```js +import remarkLintStrikethroughMarker from 'https://cdn.skypack.dev/remark-lint-strikethrough-marker@2?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintStrikethroughMarker from 'remark-lint-strikethrough-marker' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintStrikethroughMarker) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-strikethrough-marker example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-strikethrough-marker", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintStrikethroughMarker`. + +### `unified().use(remarkLintStrikethroughMarker[, 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: + +* `'~'` + — prefer one strikethrough marker +* `'~~'` + — prefer two strikethrough markers +* `'consistent'` + — detect the first used style and warn when further strikethrough differs + +## Recommendation + +GitHub flavored markdown (GFM) specifies that two tildes should be used, +but `github.com` allows one tilde everywhere. +It’s recommended to use two tildes. + +## Fix + +[`remark-gfm`](https://github.com/remarkjs/remark-gfm) +formats all strikethrough with two tildes. + +## Examples ##### `ok.md` @@ -34,7 +151,7 @@ When configured with `'~'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown ~foo~ @@ -50,7 +167,7 @@ When configured with `'~'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown ~~foo~~ @@ -68,7 +185,7 @@ When configured with `'~~'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown ~~foo~~ @@ -84,7 +201,7 @@ When configured with `'~~'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown ~foo~ @@ -100,7 +217,7 @@ Note: this example uses [GFM][]. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown ~~foo~~ @@ -123,59 +240,12 @@ When configured with `'💩'`. 1:1: Incorrect strikethrough marker `💩`: use either `'consistent'`, `'~'`, or `'~~'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-strikethrough-marker -``` - -This package exports no identifiers. -The default export is `remarkLintStrikethroughMarker`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-strikethrough-marker", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-strikethrough-marker readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintStrikethroughMarker from 'remark-lint-strikethrough-marker' - - remark() - .use(remarkLint) -+ .use(remarkLintStrikethroughMarker) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -217,17 +287,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-strong-marker/index.js b/packages/remark-lint-strong-marker/index.js index 18b000e..2dc5fe6 100644 --- a/packages/remark-lint-strong-marker/index.js +++ b/packages/remark-lint-strong-marker/index.js @@ -1,27 +1,44 @@ /** + * ## When should I use this? + * + * You can use this package to check that strong markers are consistent. + * + * ## API + * + * The following options (default: `'consistent'`) are accepted: + * + * * `'*'` + * — prefer asterisks + * * `'_'` + * — prefer underscores + * * `'consistent'` + * — detect the first used style and warn when further strong differs + * + * ## Recommendation + * + * Underscores and asterisks work slightly different: asterisks can form strong + * in more cases than underscores. + * Because underscores are sometimes used to represent normal underscores inside + * words, there are extra rules supporting that. + * Asterisks can also be used as the marker of more constructs than underscores: + * lists. + * Due to having simpler parsing rules, looking more like syntax, and that they + * can be used for more constructs, it’s recommended to prefer asterisks. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats strong with asterisks by default. + * Pass + * [`strong: '_'`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsstrong) + * to always use underscores. + * + * @module strong-marker + * @summary + * remark-lint rule to warn when strong markers are inconsistent. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module strong-marker - * @fileoverview - * Warn for violating importance (strong) markers. - * - * Options: `'consistent'`, `'*'`, or `'_'`, default: `'consistent'`. - * - * `'consistent'` detects the first used importance style and warns when - * subsequent importance sequences use different styles. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * formats importance using an `*` (asterisk) by default. - * Pass - * [`strong: '_'`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsstrong) - * to use `_` (underscore) instead. - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-strong-marker/readme.md b/packages/remark-lint-strong-marker/readme.md index 11cc226..ad5ea61 100644 --- a/packages/remark-lint-strong-marker/readme.md +++ b/packages/remark-lint-strong-marker/readme.md @@ -10,23 +10,33 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn for violating importance (strong) markers. +[`remark-lint`][mono] rule to warn when strong markers are inconsistent. -Options: `'consistent'`, `'*'`, or `'_'`, default: `'consistent'`. +## Contents -`'consistent'` detects the first used importance style and warns when -subsequent importance sequences use 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(remarkLintStrongMarker[, config])`](#unifieduseremarklintstrongmarker-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 importance using an `*` (asterisk) by default. -Pass -[`strong: '_'`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsstrong) -to use `_` (underscore) instead. +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 strong markers are consistent. ## Presets @@ -37,7 +47,112 @@ This rule is included in the following presets: | [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'*'` | -## 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-strong-marker +``` + +In Deno with [Skypack][]: + +```js +import remarkLintStrongMarker from 'https://cdn.skypack.dev/remark-lint-strong-marker@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintStrongMarker from 'remark-lint-strong-marker' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintStrongMarker) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-strong-marker example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-strong-marker", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintStrongMarker`. + +### `unified().use(remarkLintStrongMarker[, 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: + +* `'*'` + — prefer asterisks +* `'_'` + — prefer underscores +* `'consistent'` + — detect the first used style and warn when further strong differs + +## Recommendation + +Underscores and asterisks work slightly different: asterisks can form strong +in more cases than underscores. +Because underscores are sometimes used to represent normal underscores inside +words, there are extra rules supporting that. +Asterisks can also be used as the marker of more constructs than underscores: +lists. +Due to having simpler parsing rules, looking more like syntax, and that they +can be used for more constructs, it’s recommended to prefer asterisks. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats strong with asterisks by default. +Pass +[`strong: '_'`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsstrong) +to always use underscores. + +## Examples ##### `ok.md` @@ -115,59 +230,12 @@ When configured with `'💩'`. 1:1: Incorrect strong marker `💩`: use either `'consistent'`, `'*'`, or `'_'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-strong-marker -``` - -This package exports no identifiers. -The default export is `remarkLintStrongMarker`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-strong-marker", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-strong-marker readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintStrongMarker from 'remark-lint-strong-marker' - - remark() - .use(remarkLint) -+ .use(remarkLintStrongMarker) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -209,17 +277,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-table-cell-padding/index.js b/packages/remark-lint-table-cell-padding/index.js index 04bbc02..5cf8724 100644 --- a/packages/remark-lint-table-cell-padding/index.js +++ b/packages/remark-lint-table-cell-padding/index.js @@ -1,27 +1,40 @@ /** + * ## When should I use this? + * + * You can use this package to check that table cells are padded consistently. + * Tables are a GFM feature enabled with + * [`remark-gfm`](https://github.com/remarkjs/remark-gfm). + * + * ## API + * + * The following options (default: `'consistent'`) are accepted: + * + * * `'padded'` + * — prefer at least one space between pipes and content + * * `'compact'` + * — prefer zero spaces between pipes and content + * * `'consistent'` + * — detect the first used style and warn when further tables differ + * + * ## Recommendation + * + * It’s recommended to use at least one space between pipes and content for + * legibility of the markup (`'padded'`). + * + * ## Fix + * + * [`remark-gfm`](https://github.com/remarkjs/remark-gfm) + * formats all table cells as padded by default. + * Pass + * [`tableCellPadding: false`](https://github.com/remarkjs/remark-gfm#optionstablecellpadding) + * to use a more compact style. + * + * @module table-cell-padding + * @summary + * remark-lint rule to warn when table cells are inconsistently padded. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module table-cell-padding - * @fileoverview - * Warn when table cells are incorrectly padded. - * - * Options: `'consistent'`, `'padded'`, or `'compact'`, default: `'consistent'`. - * - * `'consistent'` detects the first used cell padding style and warns when - * subsequent cells use different styles. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * formats tables with padding by default. - * Pass - * [`spacedTable: false`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsspacedtable) - * to not use padding. - * - * 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. - * * @example * {"name": "ok.md", "setting": "padded", "gfm": true} * diff --git a/packages/remark-lint-table-cell-padding/readme.md b/packages/remark-lint-table-cell-padding/readme.md index e4ff95a..d6cb809 100644 --- a/packages/remark-lint-table-cell-padding/readme.md +++ b/packages/remark-lint-table-cell-padding/readme.md @@ -10,23 +10,35 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when table cells are incorrectly padded. +[`remark-lint`][mono] rule to warn when table cells are inconsistently padded. -Options: `'consistent'`, `'padded'`, or `'compact'`, default: `'consistent'`. +## Contents -`'consistent'` detects the first used cell padding style and warns when -subsequent cells use 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(remarkLintTableCellPadding[, config])`](#unifieduseremarklinttablecellpadding-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 tables with padding by default. -Pass -[`spacedTable: false`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsspacedtable) -to not use padding. +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 table cells are padded consistently. +Tables are a GFM feature enabled with +[`remark-gfm`](https://github.com/remarkjs/remark-gfm). ## Presets @@ -37,7 +49,106 @@ This rule is included in the following presets: | [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'padded'` | -## 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-table-cell-padding +``` + +In Deno with [Skypack][]: + +```js +import remarkLintTableCellPadding from 'https://cdn.skypack.dev/remark-lint-table-cell-padding@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintTableCellPadding from 'remark-lint-table-cell-padding' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintTableCellPadding) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-table-cell-padding example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-table-cell-padding", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintTableCellPadding`. + +### `unified().use(remarkLintTableCellPadding[, 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: + +* `'padded'` + — prefer at least one space between pipes and content +* `'compact'` + — prefer zero spaces between pipes and content +* `'consistent'` + — detect the first used style and warn when further tables differ + +## Recommendation + +It’s recommended to use at least one space between pipes and content for +legibility of the markup (`'padded'`). + +## Fix + +[`remark-gfm`](https://github.com/remarkjs/remark-gfm) +formats all table cells as padded by default. +Pass +[`tableCellPadding: false`](https://github.com/remarkjs/remark-gfm#optionstablecellpadding) +to use a more compact style. + +## Examples ##### `ok.md` @@ -45,7 +156,7 @@ When configured with `'padded'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown | A | B | @@ -63,7 +174,7 @@ When configured with `'padded'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown | A | B | @@ -101,7 +212,7 @@ When configured with `'padded'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown @@ -125,7 +236,7 @@ When configured with `'padded'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown @@ -146,7 +257,7 @@ When configured with `'compact'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown |A |B | @@ -164,7 +275,7 @@ When configured with `'compact'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown | A | B | @@ -190,7 +301,7 @@ When configured with `'consistent'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown | A | B | @@ -212,7 +323,7 @@ When configured with `'consistent'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown | A | B | @@ -236,7 +347,7 @@ When configured with `'consistent'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown |A |B | @@ -258,7 +369,7 @@ When configured with `'consistent'`. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown |A |B | @@ -286,59 +397,12 @@ When configured with `'💩'`. 1:1: Incorrect table cell padding style `💩`, expected `'padded'`, `'compact'`, or `'consistent'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-table-cell-padding -``` - -This package exports no identifiers. -The default export is `remarkLintTableCellPadding`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-table-cell-padding", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-table-cell-padding readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintTableCellPadding from 'remark-lint-table-cell-padding' - - remark() - .use(remarkLint) -+ .use(remarkLintTableCellPadding) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -380,17 +444,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-table-pipe-alignment/index.js b/packages/remark-lint-table-pipe-alignment/index.js index 6e8c96c..5d420e3 100644 --- a/packages/remark-lint-table-pipe-alignment/index.js +++ b/packages/remark-lint-table-pipe-alignment/index.js @@ -1,30 +1,40 @@ /** + * ## When should I use this? + * + * You can use this package to check that table cell dividers are aligned. + * Tables are a GFM feature enabled with + * [`remark-gfm`](https://github.com/remarkjs/remark-gfm). + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * While aligning table dividers improves their legibility, it is somewhat + * hard to maintain manually, especially for tables with many rows. + * + * ## Fix + * + * [`remark-gfm`](https://github.com/remarkjs/remark-gfm) + * aligns table dividers by default. + * Pass + * [`tablePipeAlign: false`](https://github.com/remarkjs/remark-gfm#optionstablepipealign) + * to use a more compact style. + * + * Aligning characters is impossible because whether they look aligned or not + * depends on where the markup is shown: some characters (such as emoji or + * Chinese characters) show smaller or bigger in different places. + * You can pass your own + * [`stringLength`](https://github.com/remarkjs/remark-gfm#optionsstringlength) + * to `remark-gfm`, in which case this rule must be turned off. + * + * @module table-pipe-alignment + * @summary + * remark-lint rule to warn when table cells are inconsistently padded. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module table-pipe-alignment - * @fileoverview - * Warn when table pipes are not aligned. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * tries to align tables by default. - * Pass - * [`paddedTable: false`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionspaddedtable) - * to not align cells. - * - * Aligning cells perfectly is impossible as some characters (such as emoji or - * Chinese characters) are rendered differently in different browsers, - * terminals, and editors. - * You can pass your own - * [`stringLength`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsstringlength) - * function to customize how cells are aligned. - * In that case, this rule must be turned off. - * - * 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. - * * @example * {"name": "ok.md", "gfm": true} * @@ -48,8 +58,6 @@ /** * @typedef {import('mdast').Root} Root - * @typedef {'-'|'*'|'+'} Marker - * @typedef {'consistent'|Marker} Options */ import {lintRule} from 'unified-lint-rule' diff --git a/packages/remark-lint-table-pipe-alignment/readme.md b/packages/remark-lint-table-pipe-alignment/readme.md index b4646c7..ad55a66 100644 --- a/packages/remark-lint-table-pipe-alignment/readme.md +++ b/packages/remark-lint-table-pipe-alignment/readme.md @@ -10,26 +10,35 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when table pipes are not aligned. +[`remark-lint`][mono] rule to warn when table cells are inconsistently padded. -## Fix +## Contents -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -tries to align tables by default. -Pass -[`paddedTable: false`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionspaddedtable) -to not align cells. +* [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(remarkLintTablePipeAlignment[, config])`](#unifieduseremarklinttablepipealignment-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -Aligning cells perfectly is impossible as some characters (such as emoji or -Chinese characters) are rendered differently in different browsers, -terminals, and editors. -You can pass your own -[`stringLength`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsstringlength) -function to customize how cells are aligned. -In that case, this rule must be turned off. +## What is this? -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. +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that table cell dividers are aligned. +Tables are a GFM feature enabled with +[`remark-gfm`](https://github.com/remarkjs/remark-gfm). ## Presets @@ -39,13 +48,112 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-table-pipe-alignment +``` + +In Deno with [Skypack][]: + +```js +import remarkLintTablePipeAlignment from 'https://cdn.skypack.dev/remark-lint-table-pipe-alignment@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintTablePipeAlignment from 'remark-lint-table-pipe-alignment' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintTablePipeAlignment) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-table-pipe-alignment example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-table-pipe-alignment", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintTablePipeAlignment`. + +### `unified().use(remarkLintTablePipeAlignment[, 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). + +There are no options. + +## Recommendation + +While aligning table dividers improves their legibility, it is somewhat +hard to maintain manually, especially for tables with many rows. + +## Fix + +[`remark-gfm`](https://github.com/remarkjs/remark-gfm) +aligns table dividers by default. +Pass +[`tablePipeAlign: false`](https://github.com/remarkjs/remark-gfm#optionstablepipealign) +to use a more compact style. + +Aligning characters is impossible because whether they look aligned or not +depends on where the markup is shown: some characters (such as emoji or +Chinese characters) show smaller or bigger in different places. +You can pass your own +[`stringLength`](https://github.com/remarkjs/remark-gfm#optionsstringlength) +to `remark-gfm`, in which case this rule must be turned off. + +## Examples ##### `ok.md` ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown | A | B | @@ -61,7 +169,7 @@ No messages. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown | A | B | @@ -76,59 +184,12 @@ Note: this example uses [GFM][]. 3:17-3:18: Misaligned table fence ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-table-pipe-alignment -``` - -This package exports no identifiers. -The default export is `remarkLintTablePipeAlignment`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-table-pipe-alignment", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-table-pipe-alignment readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintTablePipeAlignment from 'remark-lint-table-pipe-alignment' - - remark() - .use(remarkLint) -+ .use(remarkLintTablePipeAlignment) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -170,17 +231,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-table-pipes/index.js b/packages/remark-lint-table-pipes/index.js index cb11121..ab2a2c0 100644 --- a/packages/remark-lint-table-pipes/index.js +++ b/packages/remark-lint-table-pipes/index.js @@ -1,19 +1,32 @@ /** + * ## When should I use this? + * + * You can use this package to check that tables have initial and final + * delimiters. + * Tables are a GFM feature enabled with + * [`remark-gfm`](https://github.com/remarkjs/remark-gfm). + * + * ## API + * + * There are no options. + * + * ## Recommendation + * + * While tables don’t require initial or final delimiters (pipes before the + * first and after the last cells in a row), it arguably does look weird. + * + * ## Fix + * + * [`remark-gfm`](https://github.com/remarkjs/remark-gfm) + * formats all tables with initial and final delimiters. + * + * @module table-pipes + * @summary + * remark-lint rule to warn when tables are missing initial and final + * delimiters. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module table-pipes - * @fileoverview - * Warn when table rows are not fenced with pipes. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * creates fenced rows with initial and final pipes by default. - * - * 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. - * * @example * {"name": "ok.md", "gfm": true} * diff --git a/packages/remark-lint-table-pipes/readme.md b/packages/remark-lint-table-pipes/readme.md index 5115658..b6bb0e1 100644 --- a/packages/remark-lint-table-pipes/readme.md +++ b/packages/remark-lint-table-pipes/readme.md @@ -10,15 +10,37 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when table rows are not fenced with pipes. +[`remark-lint`][mono] rule to warn when tables are missing initial and final +delimiters. -## Fix +## Contents -[`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) -creates fenced rows with initial and final pipes by default. +* [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(remarkLintTablePipes[, config])`](#unifieduseremarklinttablepipes-config) +* [Recommendation](#recommendation) +* [Fix](#fix) +* [Examples](#examples) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) -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. +## What is this? + +This package is a [unified][] ([remark][]) plugin, specifically a `remark-lint` +rule. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that tables have initial and final +delimiters. +Tables are a GFM feature enabled with +[`remark-gfm`](https://github.com/remarkjs/remark-gfm). ## Presets @@ -28,13 +50,102 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | | -## 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-table-pipes +``` + +In Deno with [Skypack][]: + +```js +import remarkLintTablePipes from 'https://cdn.skypack.dev/remark-lint-table-pipes@4?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintTablePipes from 'remark-lint-table-pipes' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintTablePipes) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-table-pipes example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-table-pipes", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintTablePipes`. + +### `unified().use(remarkLintTablePipes[, 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). + +There are no options. + +## Recommendation + +While tables don’t require initial or final delimiters (pipes before the +first and after the last cells in a row), it arguably does look weird. + +## Fix + +[`remark-gfm`](https://github.com/remarkjs/remark-gfm) +formats all tables with initial and final delimiters. + +## Examples ##### `ok.md` ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown | A | B | @@ -50,7 +161,7 @@ No messages. ###### In -Note: this example uses [GFM][]. +> 👉 **Note**: this example uses GFM ([`remark-gfm`][gfm]). ```markdown A | B @@ -67,59 +178,12 @@ Alpha | Bravo 3:14: Missing final pipe in table fence ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-table-pipes -``` - -This package exports no identifiers. -The default export is `remarkLintTablePipes`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-table-pipes", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-table-pipes readme.md -``` - -Or use this on the API: - -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remark-lint' - import remarkLintTablePipes from 'remark-lint-table-pipes' - - remark() - .use(remarkLint) -+ .use(remarkLintTablePipes) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -161,17 +225,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint-unordered-list-marker-style/index.js b/packages/remark-lint-unordered-list-marker-style/index.js index f94cfe2..4e3cb47 100644 --- a/packages/remark-lint-unordered-list-marker-style/index.js +++ b/packages/remark-lint-unordered-list-marker-style/index.js @@ -1,28 +1,42 @@ /** + * ## When should I use this? + * + * You can use this package to check that unordered list markers (bullets) + * are consistent. + * + * ## API + * + * The following options (default: `'consistent'`) are accepted: + * + * * `'*'` + * — prefer asterisks + * * `'+'` + * — prefer plusses + * * `'-'` + * — prefer dashes + * * `'consistent'` + * — detect the first used style and warn when further markers differ + * + * ## Recommendation + * + * Because asterisks can be used as a marker for more markdown constructs, + * it’s recommended to use that for lists (and thematic breaks, emphasis, + * strong) too. + * + * ## Fix + * + * [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) + * formats ordered lists with asterisks by default. + * Pass + * [`bullet: '+'` or `bullet: '-'`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsbullet) + * to always use plusses or dashes. + * + * @module unordered-list-marker-style + * @summary + * remark-lint rule to warn when unordered list markers are inconsistent. * @author Titus Wormer * @copyright 2015 Titus Wormer * @license MIT - * @module unordered-list-marker-style - * @fileoverview - * Warn when the list item marker style of unordered lists violate a given - * style. - * - * Options: `'consistent'`, `'-'`, `'*'`, or `'+'`, default: `'consistent'`. - * - * `'consistent'` detects the first used list style and warns when subsequent - * lists use different styles. - * - * ## Fix - * - * [`remark-stringify`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify) - * formats unordered lists using `-` (hyphen-minus) by default. - * Pass - * [`bullet: '*'` or `bullet: '+'`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsbullet) - * to use `*` (asterisk) or `+` (plus sign) instead. - * - * 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. - * * @example * {"name": "ok.md"} * diff --git a/packages/remark-lint-unordered-list-marker-style/readme.md b/packages/remark-lint-unordered-list-marker-style/readme.md index a3d92d2..8ce6077 100644 --- a/packages/remark-lint-unordered-list-marker-style/readme.md +++ b/packages/remark-lint-unordered-list-marker-style/readme.md @@ -10,24 +10,34 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Warn when the list item marker style of unordered lists violate a given -style. +[`remark-lint`][mono] rule to warn when unordered list markers are inconsistent. -Options: `'consistent'`, `'-'`, `'*'`, or `'+'`, default: `'consistent'`. +## Contents -`'consistent'` detects the first used list style and warns when subsequent -lists use 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(remarkLintUnorderedListMarkerStyle[, config])`](#unifieduseremarklintunorderedlistmarkerstyle-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 unordered lists using `-` (hyphen-minus) by default. -Pass -[`bullet: '*'` or `bullet: '+'`](https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#optionsbullet) -to use `*` (asterisk) or `+` (plus sign) instead. +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 unordered list markers (bullets) +are consistent. ## Presets @@ -37,7 +47,109 @@ This rule is included in the following presets: | - | - | | [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'-'` | -## 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-unordered-list-marker-style +``` + +In Deno with [Skypack][]: + +```js +import remarkLintUnorderedListMarkerStyle from 'https://cdn.skypack.dev/remark-lint-unordered-list-marker-style@3?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + +## 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 remarkLintUnorderedListMarkerStyle from 'remark-lint-unordered-list-marker-style' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .use(remarkLintUnorderedListMarkerStyle) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint --use remark-lint-unordered-list-marker-style example.md +``` + +On the CLI in a config file (here a `package.json`): + +```diff + … + "remarkConfig": { + "plugins": [ + … + "remark-lint", ++ "remark-lint-unordered-list-marker-style", + … + ] + } + … +``` + +## API + +This package exports no identifiers. +The default export is `remarkLintUnorderedListMarkerStyle`. + +### `unified().use(remarkLintUnorderedListMarkerStyle[, 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: + +* `'*'` + — prefer asterisks +* `'+'` + — prefer plusses +* `'-'` + — prefer dashes +* `'consistent'` + — detect the first used style and warn when further markers differ + +## Recommendation + +Because asterisks can be used as a marker for more markdown constructs, +it’s recommended to use that for lists (and thematic breaks, emphasis, +strong) too. + +## Fix + +[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) +formats ordered lists with asterisks by default. +Pass +[`bullet: '+'` or `bullet: '-'`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#optionsbullet) +to always use plusses or dashes. + +## Examples ##### `ok.md` @@ -131,59 +243,12 @@ When configured with `'💩'`. 1:1: Incorrect unordered list item marker style `💩`: use either `'-'`, `'*'`, or `'+'` ``` -## 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. - -[npm][]: - -```sh -npm install remark-lint-unordered-list-marker-style -``` - -This package exports no identifiers. -The default export is `remarkLintUnorderedListMarkerStyle`. - -## Use - -You probably want to use it on the CLI through a config file: - -```diff - … - "remarkConfig": { - "plugins": [ - … - "lint", -+ "lint-unordered-list-marker-style", - … - ] - } - … -``` - -Or use it on the CLI directly - -```sh -remark -u lint -u lint-unordered-list-marker-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 remarkLintUnorderedListMarkerStyle from 'remark-lint-unordered-list-marker-style' - - remark() - .use(remarkLint) -+ .use(remarkLintUnorderedListMarkerStyle) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +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. ## Contribute @@ -225,17 +290,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-lint/readme.md b/packages/remark-lint/readme.md index 6f98519..64ffeec 100644 --- a/packages/remark-lint/readme.md +++ b/packages/remark-lint/readme.md @@ -8,63 +8,116 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -[**remark**][remark] plugin to lint Markdown code style. +**[remark][]** plugin to support configuration comments for remark lint rules. -Read more about `remark-lint` on [the monorepo readme][readme]. +See the [monorepo readme][mono] for more info on remark lint. -This package doesn’t do much other than [suppressing messages][suppres] through -comments. +## Contents -If you’re using [presets][], they already include `remark-lint` itself. -If you’re using just plugins, you have to include `remark-lint` explicitly. +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`unified().use(remarkLint)`](#unifieduseremarklint) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) plugin to add support for +configuration comments to control remark lint rule messages. + +## When should I use this? + +This project is useful when you’re using remark lint rules and want to let +authors ignore messages in certain cases. +This package is already included in all our presets. +If you’re building a preset yourself, you should include 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. - -[npm][]: +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 ``` +In Deno with [Skypack][]: + +```js +import remarkLint from 'https://cdn.skypack.dev/remark-lint@9?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + ## Use -You probably want to use it on the CLI through a config file: +On the API: + +```js +import {read} from 'to-vfile' +import {reporter} from 'vfile-reporter' +import {remark} from 'remark' +import remarkLint from 'remark-lint' + +main() + +async function main() { + const file = await remark() + .use(remarkLint) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-lint example.md +``` + +On the CLI in a config file (here a `package.json`): ```diff … "remarkConfig": { "plugins": [ … -+ "lint", ++ "remark-lint", … ] } … ``` -Or use it on the CLI directly +## API -```sh -remark -u lint readme.md -``` +This package exports no identifiers. +The default export is `remarkLint`. -Or use this on the API: +### `unified().use(remarkLint)` -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkLint from 'remarkLint' +Add support for configuration comments. +There are no options. - remark() -+ .use(remarkLint) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +See [Ignore warnings][ignore] in the monorepo readme for how to use it. + +## 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. ## Contribute @@ -108,24 +161,28 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c + +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license [author]: https://wooorm.com +[unified]: https://github.com/unifiedjs/unified + [remark]: https://github.com/remarkjs/remark -[readme]: https://github.com/remarkjs/remark-lint#readme +[mono]: https://github.com/remarkjs/remark-lint -[suppres]: https://github.com/remarkjs/remark-lint#configuring-remark-lint - -[presets]: https://github.com/remarkjs/remark-lint#list-of-presets +[ignore]: https://github.com/remarkjs/remark-lint#ignore-warnings diff --git a/packages/remark-preset-lint-consistent/index.js b/packages/remark-preset-lint-consistent/index.js index a6ffd09..5e93577 100644 --- a/packages/remark-preset-lint-consistent/index.js +++ b/packages/remark-preset-lint-consistent/index.js @@ -1,7 +1,10 @@ /** - * @fileoverview - * remark preset to configure `remark-lint` with settings that enforce - * consistency. + * ## When should I use this? + * + * You can use this package to check that markdown is consistent. + * + * @summary + * Preset of remark-lint rules to warn for inconsistencies. */ /** diff --git a/packages/remark-preset-lint-consistent/readme.md b/packages/remark-preset-lint-consistent/readme.md index 5870e33..aecc50e 100644 --- a/packages/remark-preset-lint-consistent/readme.md +++ b/packages/remark-preset-lint-consistent/readme.md @@ -10,12 +10,34 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -remark preset to configure `remark-lint` with settings that enforce -consistency. +Preset of [`remark-lint`][mono] rules to warn for inconsistencies. + +## Contents + +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Rules](#rules) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`unified().use(remarkPresetLintConsistent)`](#unifieduseremarkpresetlintconsistent) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) preset, specifically consisting of +`remark-lint` rules. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that markdown is consistent. ## Rules -This preset configures [`remark-lint`](https://github.com/remarkjs/remark-lint) with the following rules: +This preset configures [`remark-lint`][mono] with the following rules: | Rule | Setting | | - | - | @@ -34,50 +56,86 @@ This preset configures [`remark-lint`](https://github.com/remarkjs/remark-lint) ## Install -This package is [ESM only][esm]: -Node 12+ is needed to use it and it must be `imported`ed instead of `required`d. - -[npm][]: +This package is [ESM only][esm]. +In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: ```sh npm install remark-preset-lint-consistent ``` -This package exports no identifiers. -The default export is `remarkPresetLintConsistent`. +In Deno with [Skypack][]: + +```js +import remarkPresetLintConsistent from 'https://cdn.skypack.dev/remark-preset-lint-consistent@5?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` ## Use -You probably want to use it on the CLI through a config file: +On the API: + +```js +import {read} from 'to-vfile' +import {reporter} from 'vfile-reporter' +import {remark} from 'remark' +import remarkPresetLintConsistent from 'remark-preset-lint-consistent' + +main() + +async function main() { + const file = await remark() + .use(remarkPresetLintConsistent) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-preset-lint-consistent example.md +``` + +On the CLI in a config file (here a `package.json`): ```diff … "remarkConfig": { -+ "plugins": ["preset-lint-consistent"] + "plugins": [ + … ++ "remark-preset-lint-consistent", + … + ] } … ``` -Or use it on the CLI directly +## API -```sh -remark -u preset-lint-consistent readme.md -``` +This package exports no identifiers. +The default export is `remarkPresetLintConsistent`. -Or use this on the API: +### `unified().use(remarkPresetLintConsistent)` -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkPresetLintConsistent from 'remark-preset-lint-consistent' +Use the preset. +Presets don’t have options. +You can reconfigure rules in them by using the afterwards with different +options. - remark() -+ .use(remarkPresetLintConsistent) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +## 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. ## Contribute @@ -119,17 +177,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-preset-lint-markdown-style-guide/index.js b/packages/remark-preset-lint-markdown-style-guide/index.js index 42543a8..adb0ad2 100644 --- a/packages/remark-preset-lint-markdown-style-guide/index.js +++ b/packages/remark-preset-lint-markdown-style-guide/index.js @@ -1,99 +1,100 @@ /** - * @fileoverview - * remark preset to configure `remark-lint` with settings that the - * [Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/) - * recommends. + * ## When should I use this? * - * This uses the following Style Guide option system: `wrap:space`, - * `header:atx`, `list-marker:hyphen`, `list-space:mixed`, and - * `code:fenced`. + * You can use this package to check that markdown follows the + * [Markdown Style Guide](https://cirosantilli.com/markdown-style-guide/). * - * ###### `space-sentence` + * This uses the following style guide option system: `wrap:space`, + * `header:atx`, `list-marker:hyphen`, `list-space:mixed`, and `code:fenced`. * - * Both `space-sentence:1` and `space-sentence:2` are not supported - * by `remark-lint`. - * You could set-up - * [`remark-retext`](https://github.com/remarkjs/remark-retext) - * with - * [`retext-sentence-spacing`](https://github.com/retextjs/retext-sentence-spacing) - * to check this though. + * ###### `space-sentence` * - * ###### `wrap` + * Both `space-sentence:1` and `space-sentence:2` are not supported by + * `remark-lint` as they relate to prose rather than markdown syntax. + * You could set-up + * [`remark-retext`](https://github.com/remarkjs/remark-retext) + * with + * [`retext-sentence-spacing`](https://github.com/retextjs/retext-sentence-spacing) + * to check this. * - * `wrap:inner-sentence` and `wrap:sentence` are not supported by - * `remark-lint`. + * ###### `wrap` * - * The default is `wrap:space`. - * To use `wrap:no`, turn off `remark-lint-maximum-line-length` like so: + * `wrap:inner-sentence` and `wrap:sentence` are not supported by `remark-lint`. * - * ```diff - * "plugins": [ - * … - * "preset-lint-markdown-style-guide", - * + ["lint-maximum-line-length", false] - * … - * ] - * ``` + * The default is `wrap:space`. + * To use `wrap:no`, turn off `remark-lint-maximum-line-length` like so: * - * ###### `header` + * ```diff + * "plugins": [ + * … + * "remark-preset-lint-markdown-style-guide", + * + ["remark-lint-maximum-line-length", false], + * … + * ] + * ``` * - * The default is `header:atx`. - * To use `header:setext`, change the setting for `remark-lint-heading-style` - * like so: + * ###### `header` * - * ```diff - * "plugins": [ - * … - * "preset-lint-markdown-style-guide", - * + ["lint-heading-style", "setext"] - * … - * ] - * ``` + * The default is `header:atx`. + * To use `header:setext`, change the setting for `remark-lint-heading-style` + * like so: * - * ###### `list-marker` + * ```diff + * "plugins": [ + * … + * "remark-preset-lint-markdown-style-guide", + * + ["remark-lint-heading-style", "setext"], + * … + * ] + * ``` * - * The default is `list-marker:hyphen`. - * For `list-marker:asterisk` or `list-marker:plus`, change the setting for - * `remark-lint-unordered-list-marker-style` like so: + * ###### `list-marker` * - * ```diff - * "plugins": [ - * … - * "preset-lint-markdown-style-guide", - * + ["lint-unordered-list-marker-style", "*"] - * … - * ] - * ``` + * The default is `list-marker:hyphen`. + * For `list-marker:asterisk` or `list-marker:plus`, change the setting for + * `remark-lint-unordered-list-marker-style` like so: * - * ###### `list-space` + * ```diff + * "plugins": [ + * … + * "remark-preset-lint-markdown-style-guide", + * + ["remark-lint-unordered-list-marker-style", "*"], + * … + * ] + * ``` * - * The default is `list-space:mixed`. - * For `list-space:1`, change the setting for `remark-lint-list-item-indent` - * like so: + * ###### `list-space` * - * ```diff - * "plugins": [ - * … - * "preset-lint-markdown-style-guide", - * + ["lint-list-item-indent", "space"] - * … - * ] - * ``` + * The default is `list-space:mixed`. + * For `list-space:1`, change the setting for `remark-lint-list-item-indent` + * like so: * - * ###### `code` + * ```diff + * "plugins": [ + * … + * "remark-preset-lint-markdown-style-guide", + * + ["remark-lint-list-item-indent", "space"], + * … + * ] + * ``` * - * The default is `code:fenced`. - * For `code:indented`, change the setting for `remark-lint-code-block-style` - * like so: + * ###### `code` * - * ```diff - * "plugins": [ - * … - * "preset-lint-markdown-style-guide", - * + ["lint-code-block-style", "indented"] - * … - * ] - * ``` + * The default is `code:fenced`. + * For `code:indented`, change the setting for `remark-lint-code-block-style` + * like so: + * + * ```diff + * "plugins": [ + * … + * "remark-preset-lint-markdown-style-guide", + * + ["remark-lint-code-block-style", "indented"], + * … + * ] + * ``` + * + * @summary + * Preset of remark-lint rules that follow an opinionated style guide. */ /** @@ -150,139 +151,139 @@ const remarkPresetLintMarkdownStyleGuide = { plugins: [ remarkLint, - // http://www.cirosantilli.com/markdown-style-guide/#file-extension + // https://cirosantilli.com/markdown-style-guide/#file-extension [remarkLintFileExtension, 'md'], - // http://www.cirosantilli.com/markdown-style-guide/#file-name + // https://cirosantilli.com/markdown-style-guide/#file-name remarkLintNoFileNameMixedCase, remarkLintNoFileNameArticles, remarkLintNoFileNameIrregularCharacters, remarkLintNoFileNameConsecutiveDashes, remarkLintNoFileNameOuterDashes, - // http://www.cirosantilli.com/markdown-style-guide/#newlines - // http://www.cirosantilli.com/markdown-style-guide/#empty-lines-around-lists - // http://www.cirosantilli.com/markdown-style-guide/#tables + // https://cirosantilli.com/markdown-style-guide/#newlines + // https://cirosantilli.com/markdown-style-guide/#empty-lines-around-lists + // https://cirosantilli.com/markdown-style-guide/#tables remarkLintNoConsecutiveBlankLines, - // http://www.cirosantilli.com/markdown-style-guide/#spaces-after-sentences. + // https://cirosantilli.com/markdown-style-guide/#spaces-after-sentences. // Not enforced, cannot be done properly without false positives, if you // want this, use remark-retext and retext-sentence-spacing. - // http://www.cirosantilli.com/markdown-style-guide/#line-wrapping + // https://cirosantilli.com/markdown-style-guide/#line-wrapping [remarkLintMaximumLineLength, 80], - // http://www.cirosantilli.com/markdown-style-guide/#dollar-signs-in-shell-code + // https://cirosantilli.com/markdown-style-guide/#dollar-signs-in-shell-code remarkLintNoShellDollars, - // http://www.cirosantilli.com/markdown-style-guide/#what-to-mark-as-code. + // https://cirosantilli.com/markdown-style-guide/#what-to-mark-as-code. // This is a tip, not a rule. - // http://www.cirosantilli.com/markdown-style-guide/#spelling-and-grammar. + // https://cirosantilli.com/markdown-style-guide/#spelling-and-grammar. // Spelling is not in the scope of remark-lint. If you want this, // use remark-retext and retext-spell. - // http://www.cirosantilli.com/markdown-style-guide/#line-breaks + // https://cirosantilli.com/markdown-style-guide/#line-breaks remarkLintHardBreakSpaces, - // http://www.cirosantilli.com/markdown-style-guide/#headers + // https://cirosantilli.com/markdown-style-guide/#headers [remarkLintHeadingStyle, 'atx'], remarkLintHeadingIncrement, remarkLintNoDuplicateHeadings, - // http://www.cirosantilli.com/markdown-style-guide/#top-level-header + // https://cirosantilli.com/markdown-style-guide/#top-level-header remarkLintNoMultipleToplevelHeadings, - // http://www.cirosantilli.com/markdown-style-guide/#header-case. + // https://cirosantilli.com/markdown-style-guide/#header-case. // Heading case isn’t tested yet: new rules to fix this are ok though! - // http://www.cirosantilli.com/markdown-style-guide/#end-of-a-header. + // https://cirosantilli.com/markdown-style-guide/#end-of-a-header. // Cannot be checked? - // http://www.cirosantilli.com/markdown-style-guide/#header-length + // https://cirosantilli.com/markdown-style-guide/#header-length remarkLintMaximumHeadingLength, - // http://www.cirosantilli.com/markdown-style-guide/#punctuation-at-the-end-of-headers + // https://cirosantilli.com/markdown-style-guide/#punctuation-at-the-end-of-headers [remarkLintNoHeadingPunctuation, ':.'], - // http://www.cirosantilli.com/markdown-style-guide/#header-synonyms. + // https://cirosantilli.com/markdown-style-guide/#header-synonyms. // Cannot be checked? - // http://www.cirosantilli.com/markdown-style-guide/#blockquotes + // https://cirosantilli.com/markdown-style-guide/#blockquotes [remarkLintBlockquoteIndentation, 2], remarkLintNoBlockquoteWithoutMarker, - // http://www.cirosantilli.com/markdown-style-guide/#unordered + // https://cirosantilli.com/markdown-style-guide/#unordered [remarkLintUnorderedListMarkerStyle, '-'], - // http://www.cirosantilli.com/markdown-style-guide/#ordered + // https://cirosantilli.com/markdown-style-guide/#ordered [remarkLintOrderedListMarkerStyle, '.'], [remarkLintOrderedListMarkerValue, 'one'], - // http://www.cirosantilli.com/markdown-style-guide/#spaces-after-list-marker + // https://cirosantilli.com/markdown-style-guide/#spaces-after-list-marker [remarkLintListItemIndent, 'mixed'], - // http://www.cirosantilli.com/markdown-style-guide/#indentation-of-content-inside-lists + // https://cirosantilli.com/markdown-style-guide/#indentation-of-content-inside-lists remarkLintListItemContentIndent, - // http://www.cirosantilli.com/markdown-style-guide/#empty-lines-inside-lists + // https://cirosantilli.com/markdown-style-guide/#empty-lines-inside-lists remarkLintListItemSpacing, - // http://www.cirosantilli.com/markdown-style-guide/#case-of-first-letter-of-list-item + // https://cirosantilli.com/markdown-style-guide/#case-of-first-letter-of-list-item // Not checked. - // http://www.cirosantilli.com/markdown-style-guide/#punctuation-at-the-end-of-list-items. + // https://cirosantilli.com/markdown-style-guide/#punctuation-at-the-end-of-list-items. // Not checked. - // http://www.cirosantilli.com/markdown-style-guide/#definition-lists. + // https://cirosantilli.com/markdown-style-guide/#definition-lists. // Not checked. - // http://www.cirosantilli.com/markdown-style-guide/#code-blocks + // https://cirosantilli.com/markdown-style-guide/#code-blocks [remarkLintCodeBlockStyle, 'fenced'], [remarkLintFencedCodeFlag, {allowEmpty: false}], [remarkLintFencedCodeMarker, '`'], - // http://www.cirosantilli.com/markdown-style-guide/#horizontal-rules + // https://cirosantilli.com/markdown-style-guide/#horizontal-rules [remarkLintRuleStyle, '---'], - // http://www.cirosantilli.com/markdown-style-guide/#tables + // https://cirosantilli.com/markdown-style-guide/#tables remarkLintNoTableIndentation, remarkLintTablePipes, remarkLintTablePipeAlignment, [remarkLintTableCellPadding, 'padded'], - // http://www.cirosantilli.com/markdown-style-guide/#separate-consecutive-elements. + // https://cirosantilli.com/markdown-style-guide/#separate-consecutive-elements. // Not checked. - // http://www.cirosantilli.com/markdown-style-guide/#span-elements + // https://cirosantilli.com/markdown-style-guide/#span-elements remarkLintNoInlinePadding, - // http://www.cirosantilli.com/markdown-style-guide/#reference-style-links + // https://cirosantilli.com/markdown-style-guide/#reference-style-links remarkLintNoShortcutReferenceImage, remarkLintNoShortcutReferenceLink, remarkLintFinalDefinition, remarkLintDefinitionCase, remarkLintDefinitionSpacing, - // http://www.cirosantilli.com/markdown-style-guide/#single-or-double-quote-titles + // https://cirosantilli.com/markdown-style-guide/#single-or-double-quote-titles [remarkLintLinkTitleStyle, '"'], - // http://www.cirosantilli.com/markdown-style-guide/#bold + // https://cirosantilli.com/markdown-style-guide/#bold [remarkLintStrongMarker, '*'], - // http://www.cirosantilli.com/markdown-style-guide/#italic + // https://cirosantilli.com/markdown-style-guide/#italic [remarkLintEmphasisMarker, '*'], - // http://www.cirosantilli.com/markdown-style-guide/#uppercase-for-emphasis. + // https://cirosantilli.com/markdown-style-guide/#uppercase-for-emphasis. // Not checked. - // http://www.cirosantilli.com/markdown-style-guide/#emphasis-vs-headers + // https://cirosantilli.com/markdown-style-guide/#emphasis-vs-headers remarkLintNoEmphasisAsHeading, - // http://www.cirosantilli.com/markdown-style-guide/#automatic-links-without-angle-brackets + // https://cirosantilli.com/markdown-style-guide/#automatic-links-without-angle-brackets remarkLintNoLiteralUrls - // http://www.cirosantilli.com/markdown-style-guide/#email-automatic-links. + // https://cirosantilli.com/markdown-style-guide/#email-automatic-links. // Not checked. ] } diff --git a/packages/remark-preset-lint-markdown-style-guide/readme.md b/packages/remark-preset-lint-markdown-style-guide/readme.md index 652cba7..bf0751e 100644 --- a/packages/remark-preset-lint-markdown-style-guide/readme.md +++ b/packages/remark-preset-lint-markdown-style-guide/readme.md @@ -10,28 +10,48 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -remark preset to configure `remark-lint` with settings that the -[Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/) -recommends. +Preset of [`remark-lint`][mono] rules that follow an opinionated style guide. -This uses the following Style Guide option system: `wrap:space`, -`header:atx`, `list-marker:hyphen`, `list-space:mixed`, and -`code:fenced`. +## Contents + +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Rules](#rules) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`unified().use(remarkPresetLintMarkdownStyleGuide)`](#unifieduseremarkpresetlintmarkdownstyleguide) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) preset, specifically consisting of +`remark-lint` rules. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that markdown follows the +[Markdown Style Guide](https://cirosantilli.com/markdown-style-guide/). + +This uses the following style guide option system: `wrap:space`, +`header:atx`, `list-marker:hyphen`, `list-space:mixed`, and `code:fenced`. ###### `space-sentence` -Both `space-sentence:1` and `space-sentence:2` are not supported -by `remark-lint`. +Both `space-sentence:1` and `space-sentence:2` are not supported by +`remark-lint` as they relate to prose rather than markdown syntax. You could set-up [`remark-retext`](https://github.com/remarkjs/remark-retext) with [`retext-sentence-spacing`](https://github.com/retextjs/retext-sentence-spacing) -to check this though. +to check this. ###### `wrap` -`wrap:inner-sentence` and `wrap:sentence` are not supported by -`remark-lint`. +`wrap:inner-sentence` and `wrap:sentence` are not supported by `remark-lint`. The default is `wrap:space`. To use `wrap:no`, turn off `remark-lint-maximum-line-length` like so: @@ -39,8 +59,8 @@ To use `wrap:no`, turn off `remark-lint-maximum-line-length` like so: ```diff "plugins": [ … - "preset-lint-markdown-style-guide", -+ ["lint-maximum-line-length", false] + "remark-preset-lint-markdown-style-guide", ++ ["remark-lint-maximum-line-length", false], … ] ``` @@ -54,8 +74,8 @@ like so: ```diff "plugins": [ … - "preset-lint-markdown-style-guide", -+ ["lint-heading-style", "setext"] + "remark-preset-lint-markdown-style-guide", ++ ["remark-lint-heading-style", "setext"], … ] ``` @@ -69,8 +89,8 @@ For `list-marker:asterisk` or `list-marker:plus`, change the setting for ```diff "plugins": [ … - "preset-lint-markdown-style-guide", -+ ["lint-unordered-list-marker-style", "*"] + "remark-preset-lint-markdown-style-guide", ++ ["remark-lint-unordered-list-marker-style", "*"], … ] ``` @@ -84,8 +104,8 @@ like so: ```diff "plugins": [ … - "preset-lint-markdown-style-guide", -+ ["lint-list-item-indent", "space"] + "remark-preset-lint-markdown-style-guide", ++ ["remark-lint-list-item-indent", "space"], … ] ``` @@ -99,15 +119,15 @@ like so: ```diff "plugins": [ … - "preset-lint-markdown-style-guide", -+ ["lint-code-block-style", "indented"] + "remark-preset-lint-markdown-style-guide", ++ ["remark-lint-code-block-style", "indented"], … ] ``` ## Rules -This preset configures [`remark-lint`](https://github.com/remarkjs/remark-lint) with the following rules: +This preset configures [`remark-lint`][mono] with the following rules: | Rule | Setting | | - | - | @@ -157,50 +177,86 @@ This preset configures [`remark-lint`](https://github.com/remarkjs/remark-lint) ## Install -This package is [ESM only][esm]: -Node 12+ is needed to use it and it must be `imported`ed instead of `required`d. - -[npm][]: +This package is [ESM only][esm]. +In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: ```sh npm install remark-preset-lint-markdown-style-guide ``` -This package exports no identifiers. -The default export is `remarkPresetLintMarkdownStyleGuide`. +In Deno with [Skypack][]: + +```js +import remarkPresetLintMarkdownStyleGuide from 'https://cdn.skypack.dev/remark-preset-lint-markdown-style-guide@5?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` ## Use -You probably want to use it on the CLI through a config file: +On the API: + +```js +import {read} from 'to-vfile' +import {reporter} from 'vfile-reporter' +import {remark} from 'remark' +import remarkPresetLintMarkdownStyleGuide from 'remark-preset-lint-markdown-style-guide' + +main() + +async function main() { + const file = await remark() + .use(remarkPresetLintMarkdownStyleGuide) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-preset-lint-markdown-style-guide example.md +``` + +On the CLI in a config file (here a `package.json`): ```diff … "remarkConfig": { -+ "plugins": ["preset-lint-markdown-style-guide"] + "plugins": [ + … ++ "remark-preset-lint-markdown-style-guide", + … + ] } … ``` -Or use it on the CLI directly +## API -```sh -remark -u preset-lint-markdown-style-guide readme.md -``` +This package exports no identifiers. +The default export is `remarkPresetLintMarkdownStyleGuide`. -Or use this on the API: +### `unified().use(remarkPresetLintMarkdownStyleGuide)` -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkPresetLintMarkdownStyleGuide from 'remark-preset-lint-markdown-style-guide' +Use the preset. +Presets don’t have options. +You can reconfigure rules in them by using the afterwards with different +options. - remark() -+ .use(remarkPresetLintMarkdownStyleGuide) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +## 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. ## Contribute @@ -242,17 +298,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/remark-preset-lint-recommended/index.js b/packages/remark-preset-lint-recommended/index.js index 36ca771..dae2874 100644 --- a/packages/remark-preset-lint-recommended/index.js +++ b/packages/remark-preset-lint-recommended/index.js @@ -1,7 +1,10 @@ /** - * @fileoverview - * remark preset to configure `remark-lint` with settings that prevent - * mistakes or stuff that fails across vendors. + * ## When should I use this? + * + * You can use this package to check that markdown follows some best practices. + * + * @summary + * Preset of remark-lint rules to warn for some likely problems. */ /** diff --git a/packages/remark-preset-lint-recommended/readme.md b/packages/remark-preset-lint-recommended/readme.md index 4ed7b0f..f0c4667 100644 --- a/packages/remark-preset-lint-recommended/readme.md +++ b/packages/remark-preset-lint-recommended/readme.md @@ -10,12 +10,34 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -remark preset to configure `remark-lint` with settings that prevent -mistakes or stuff that fails across vendors. +Preset of [`remark-lint`][mono] rules to warn for some likely problems. + +## Contents + +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Rules](#rules) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`unified().use(remarkPresetLintRecommended)`](#unifieduseremarkpresetlintrecommended) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] ([remark][]) preset, specifically consisting of +`remark-lint` rules. +Lint rules check markdown code style. + +## When should I use this? + +You can use this package to check that markdown follows some best practices. ## Rules -This preset configures [`remark-lint`](https://github.com/remarkjs/remark-lint) with the following rules: +This preset configures [`remark-lint`][mono] with the following rules: | Rule | Setting | | - | - | @@ -36,50 +58,86 @@ This preset configures [`remark-lint`](https://github.com/remarkjs/remark-lint) ## Install -This package is [ESM only][esm]: -Node 12+ is needed to use it and it must be `imported`ed instead of `required`d. - -[npm][]: +This package is [ESM only][esm]. +In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: ```sh npm install remark-preset-lint-recommended ``` -This package exports no identifiers. -The default export is `remarkPresetLintRecommended`. +In Deno with [Skypack][]: + +```js +import remarkPresetLintRecommended from 'https://cdn.skypack.dev/remark-preset-lint-recommended@6?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` ## Use -You probably want to use it on the CLI through a config file: +On the API: + +```js +import {read} from 'to-vfile' +import {reporter} from 'vfile-reporter' +import {remark} from 'remark' +import remarkPresetLintRecommended from 'remark-preset-lint-recommended' + +main() + +async function main() { + const file = await remark() + .use(remarkPresetLintRecommended) + .process(await read('example.md')) + + console.error(reporter(file)) +} +``` + +On the CLI: + +```sh +remark --use remark-preset-lint-recommended example.md +``` + +On the CLI in a config file (here a `package.json`): ```diff … "remarkConfig": { -+ "plugins": ["preset-lint-recommended"] + "plugins": [ + … ++ "remark-preset-lint-recommended", + … + ] } … ``` -Or use it on the CLI directly +## API -```sh -remark -u preset-lint-recommended readme.md -``` +This package exports no identifiers. +The default export is `remarkPresetLintRecommended`. -Or use this on the API: +### `unified().use(remarkPresetLintRecommended)` -```diff - import {remark} from 'remark' - import {reporter} from 'vfile-reporter' - import remarkPresetLintRecommended from 'remark-preset-lint-recommended' +Use the preset. +Presets don’t have options. +You can reconfigure rules in them by using the afterwards with different +options. - remark() -+ .use(remarkPresetLintRecommended) - .process('_Emphasis_ and **importance**') - .then((file) => { - console.error(reporter(file)) - }) -``` +## 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. ## Contribute @@ -121,17 +179,25 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[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 +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license diff --git a/packages/unified-lint-rule/readme.md b/packages/unified-lint-rule/readme.md index 2cb3f82..544d30f 100644 --- a/packages/unified-lint-rule/readme.md +++ b/packages/unified-lint-rule/readme.md @@ -8,21 +8,58 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -[**unified**][unified] plugin to make it a bit easier to create linting rules. +**[unified][]** plugin to help make lint rules. -Each rule in [`remark-lint`][lint] uses this project, so see that for examples! +See the [monorepo readme][mono] for more info on remark lint. + +## Contents + +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`lintRule(origin|meta, rule)`](#lintruleoriginmeta-rule) +* [Compatibility](#compatibility) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a [unified][] plugin that makes it a bit easier to create +linting rules. + +**unified** is a project that transforms content with abstract syntax trees +(ASTs). +This is a plugin that make it easier to inspect trees. + +## When should I use this? + +You can use this package when you want to make custom lint rules. ## 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. - -[npm][]: +This package is [ESM only][esm]. +In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: ```sh npm install unified-lint-rule ``` +In Deno with [Skypack][]: + +```js +import {lintRule} from 'https://cdn.skypack.dev/unified-lint-rule@2?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + ## Use ```js @@ -42,6 +79,42 @@ const remarkLintFileExtension = lintRule( export default remarkLintFileExtension ``` +## API + +This package exports the following identifier: `lintRule`. +There is no default export. + +### `lintRule(origin|meta, rule)` + +Create a plugin. + +###### Parameters + +* `origin` (`string`) + — treated as a `meta` of `{origin}` +* `meta` (`Object`) + — rule metadata +* `meta.origin` (`string`) + — message origin, either a rule name (`'file-extension'`) or both + a rule source and name joined with `:` (`'remark-lint:file-extension'`) +* `meta.url` (`string`, optional) + — URL to documentation for messages +* `rule` (`Function`, optional) + — your code, like a transform function, except that an extra `option` is + passed + +###### Returns + +A unified plugin that handles all kinds of options (see [Configure][configure] +in the monorepo readme for how them). + +## 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. + ## Contribute See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways @@ -82,15 +155,19 @@ abide by its terms. [chat]: https://github.com/remarkjs/remark/discussions +[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c + +[skypack]: https://www.skypack.dev + [npm]: https://docs.npmjs.com/cli/install [health]: https://github.com/remarkjs/.github -[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 [license]: https://github.com/remarkjs/remark-lint/blob/main/license @@ -98,4 +175,6 @@ abide by its terms. [unified]: https://github.com/unifiedjs/unified -[lint]: https://github.com/remarkjs/remark-lint +[mono]: https://github.com/remarkjs/remark-lint + +[configure]: https://github.com/remarkjs/remark-lint#configure diff --git a/readme.md b/readme.md index 9870ec9..ac149d7 100644 --- a/readme.md +++ b/readme.md @@ -7,349 +7,83 @@ [![Sponsors][sponsors-badge]][collective] [![Backers][backers-badge]][collective] -[**remark**][remark] plugins to lint Markdown. - -Ensuring the Markdown you (and contributors) write is of great quality will -provide better rendering in all the different markdown parsers, and makes sure -less refactoring is needed afterwards. - -What is quality? -That’s up to you, but there are sensible [presets][]. - -`remark-lint` is built on [**remark**][remark], a powerful Markdown processor -powered by [plugins][remark-plugins] (such as these). +**[remark][]** plugins to check (lint) markdown code style. ## Contents -* [Install](#install) -* [CLI](#cli) -* [API](#api) -* [Configuring `remark-lint`](#configuring-remark-lint) -* [Using remark to fix your Markdown](#using-remark-to-fix-your-markdown) -* [Integrations](#integrations) +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Presets](#presets) * [Rules](#rules) -* [List of presets](#list-of-presets) -* [List of external rules](#list-of-external-rules) -* [Create a custom rule](#create-a-custom-rule) +* [Configure](#configure) +* [Ignore warnings](#ignore-warnings) +* [Examples](#examples) + * [Example: check markdown on the API](#example-check-markdown-on-the-api) + * [Example: check and format markdown on the API](#example-check-and-format-markdown-on-the-api) + * [Example: check markdown on the CLI](#example-check-markdown-on-the-cli) + * [Example: check and format markdown on the CLI](#example-check-and-format-markdown-on-the-cli) +* [Integrations](#integrations) +* [Syntax](#syntax) +* [Compatibility](#compatibility) * [Security](#security) -* [Related](#related) * [Contribute](#contribute) * [License](#license) -## Install +## What is this? -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. +![](screenshot.png) -[npm][]: +You can use this to check markdown. +Say we have a markdown file `doc/example.md` that contains: + +```markdown +1) Hello, _Jupiter_ and *Neptune*! +``` + +Then assuming we installed dependencies and run: ```sh -npm install remark-lint +npx remark doc/ --use remark-preset-lint-consistent --use remark-preset-lint-recommended ``` -## CLI - -![][screenshot] - -Use `remark-lint` with [`remark-cli`][cli] through a -[preset][preset-recommended]. - -```sh -npm install --save-dev remark-cli remark-preset-lint-recommended -``` - -Then, configure **remark** in your `package.json`: - -```js - // … - "scripts": { - "lint-md": "remark ." - }, - // … - "remarkConfig": { - "plugins": ["remark-preset-lint-recommended"] - } - // … -``` - -Let’s say there’s an `example.md` that looks as follows: - -```markdown -* Hello - -[World][] -``` - -Now, running our `lint-md` script with `npm run lint-md` yields: +We would get a report like this: ```txt -example.md - 1:3 warning Incorrect list-item indent: add 2 spaces list-item-indent - 3:1-3:10 warning Found reference to undefined definition no-undefined-references -⚠ 2 warnings +doc/example.md + 1:1-1:35 warning Marker style should be `.` ordered-list-marker-style remark-lint + 1:4 warning Incorrect list-item indent: add 1 space list-item-indent remark-lint + 1:25-1:34 warning Emphasis should use `_` as a marker emphasis-marker remark-lint + +⚠ 3 warnings ``` -See [`doc/rules.md`][rules] for what those warnings are (and how to turn them -off). +This GitHub repository is a monorepo that contains ±70 plugins (each a rule that +checks one specific thing) and 3 presets (combinations of rules configured to +check for certain styles). -## API +These packages are build on [unified][] ([remark][]). +**unified** is a project that inspects and transforms content with abstract +syntax trees (ASTs). +**remark** adds support for markdown to unified. +**mdast** is the markdown AST that remark uses. +These lint rules inspect mdast. -Use `remark-lint` together with [`remark`][api]: +## When should I use this? -```sh -npm install remark remark-preset-lint-markdown-style-guide -``` +This project is useful when developers or technical writers are authoring +documentation in markdown and you want to ensure that the markdown is +consistent, free of bugs, and works well across different markdown parsers. -Let’s say `example.js` looks as follows: +These packages are quite good at checking markdown. +They especially shine when combined with other [remark plugins][remark-plugin] +and at letting you make your own rules. -```js -import {remark} from 'remark' -import {reporter} from 'vfile-reporter' -import remarkPresetLintMarkdownStyleGuide from 'remark-preset-lint-markdown-style-guide' +## Presets -const file = remark() - .use(remarkPresetLintMarkdownStyleGuide) - .processSync('_Hello world_') - -console.log(reporter(file)) -``` - -Now, running `node example.js` yields: - -```txt - 1:1-1:14 warning Emphasis should use `*` as a marker emphasis-marker remark-lint - -⚠ 1 warning -``` - -## Configuring `remark-lint` - -`remark-lint` is a **remark** plugin and when used on the CLI supports -configuration through its [configuration files][cli]. - -An example `.remarkrc` file could look as follows: - -```json -{ - "plugins": [ - "remark-preset-lint-recommended", - ["remark-lint-list-item-indent", false] - ] -} -``` - -The preset turns on `remark-lint-list-item-indent`, but setting a plugin to -`false` later turns it off again. - -Using our `example.md` from before: - -```markdown -* Hello - -[World][] -``` - -Now, running `npm run lint-md` yields: - -```bash -example.md - 3:1-3:10 warning Found reference to undefined definition no-undefined-references remark-lint - -⚠ 2 warnings -``` - -You can also provide configuration comments to turn a rule on or off inside a -file. -Note that you cannot change a setting, such as `maximum-line-length`, just -whether messages are shown or not. -Read more about configuration comments in -[`remark-message-control`][message-control]s documentation. - -The following file will warn twice for the duplicate headings: - -```markdown -# Hello - -## Hello - -### Hello -``` - -The following file will warn once (the second heading is ignored, but the third -is enabled again): - -```markdown -# Hello - - - -## Hello - - - -### Hello -``` - -> **Note**: You’ll need the blank lines between comments and other nodes! - -## Using remark to fix your Markdown - -[`remark-stringify`][remark-stringify] can format markdown syntax. -It ensures a single style is used: list items use one type of bullet (`*`, `-`, -`+`), emphasis (`*` or `_`) and importance (`__` or `**`) use a standard marker, -[and more][remark-stringify-options]. - -###### Example - -If you `import('remark')`, [`remark-stringify`][remark-stringify] is included -unless an output format other than markdown (such as HTML) is defined. - -Say we have the following file, `example.js`, showing how formatting rules can -be used: - -```js -import {reporter} from 'vfile-reporter' -import {remark} from 'remark' -import remarkLintEmphasisMarker from 'remark-lint-emphasis-marker' -import remarkLintStrongMarker from 'remark-lint-strong-marker' - -remark() - .use(remarkLintEmphasisMarker, '*') - .use(remarkLintStrongMarker, '*') - // ^ two `remark-lint` rules. - .use({ - settings: {emphasis: '*', strong: '*'} - // ^ `remark-stringify` settings. - }) - .process('_Hello_, __world__!') - .then((file) => { - console.error(reporter(file)) - console.log(String(file)) - }) -``` - -Now, running `node example` yields warnings and a formatted file: - -```txt - 1:1-1:8 warning Emphasis should use `*` as a marker emphasis-marker remark-lint - 1:10-1:19 warning Strong should use `*` as a marker strong-marker remark-lint - -⚠ 2 warnings -*Hello*, **world**! -``` - -###### Example - -If you’re using [`remark-stringify`][remark-stringify] explicitly, you can pass -options like any other plugin, like so: - -```js -import {reporter} from 'vfile-reporter' -import {unified} from 'unified' -import remarkParse from 'remark-parse' -import remarkStringify from 'remark-stringify' -import remarkLintEmphasisMarker from 'remark-lint-emphasis-marker' -import remarkLintStrongMarker from 'remark-lint-strong-marker' - -unified() - .use(remarkParse) - .use(remarkLintEmphasisMarker, '*') - .use(remarkLintStrongMarker, '*') - // ^ two `remark-lint` rules. - .use(remarkStringify, {emphasis: '*', strong: '*'}) - // ^ `remark-stringify` with settings. - .process('_Hello_, __world__!') - .then((file) => { - console.error(reporter(file)) - console.log(String(file)) - }) -``` - -Now, when running `node example`, this results in the same output as the -previous example. - -###### Example - -If you’re using [`remark-cli`][cli], [`remark-stringify`][remark-stringify] is -included unless an output format other than markdown (such as HTML) is defined. -In this case you can configure `remark-stringify` settings using the -[`-s, --settings`][cli-settings] flag or a `"settings"` field in [remark -configuration files][cli-config]. - -Say we have the following file, `example.md`: - -```markdown -_Hello_, __world__! -``` - -And our `package.json` looks as follows: - -```js - // … - "remarkConfig": { - "settings": { - "emphasis": "*", - "strong": "*" - }, - "plugins": [ - "remark-lint-emphasis-marker", - "remark-lint-strong-marker" - ] - } - // … -``` - -Now, running `remark example.md` yields warnings and a formatted file: - -```txt -*Hello*, **world**! -example.md - 1:1-1:8 warning Emphasis should use `*` as a marker emphasis-marker remark-lint - 1:10-1:19 warning Strong should use `*` as a marker strong-marker remark-lint - -⚠ 2 warnings -``` - -> Note: running `remark example.md -o` or `remark example.md --output` -> overwrites `example.md` and formats it. -> So, if you’d run that twice (the first pass lints and fixes the Markdown, the -> second pass checks it again), you’d see the output `example.md: written` as -> all warnings are now fixed. - -## Integrations - -* [`linter-remark`](https://github.com/wooorm/linter-remark) - ([Atom](https://atom.io)) - — use all of remark from Atom -* [`vscode-remark-lint`](https://github.com/drewbourne/vscode-remark-lint) - ([VS Code](https://code.visualstudio.com)) - — use `remark-lint` from Visual Studio Code -* [`SublimeLinter-contrib-remark-lint`](https://packagecontrol.io/packages/SublimeLinter-contrib-remark-lint) - ([Sublime](https://www.sublimetext.com)) - — use `remark-lint` from Sublime Text -* [`ale`](https://github.com/w0rp/ale) - ([Vim](https://www.vim.org)) - — use `remark-lint` from Vim -* [`gulp-remark`](https://github.com/remarkjs/gulp-remark) - ([Gulp](https://gulpjs.com)) - — use all of remark with Gulp -* [`grunt-remark`](https://github.com/remarkjs/grunt-remark) - ([Grunt](https://gruntjs.com/)) - — use all of remark with Grunt -* [`jest-runner-remark`](https://github.com/keplersj/jest-runner-remark) - ([Jest](https://jestjs.io)) - — use all of remark with Jest - -We’re interested in more integrations. -Let us know if we can help. - -## Rules - -[`doc/rules.md`][rules] lists all available official rules. - -## List of presets - -Presets can be loaded just like other plugins. +Presets are combinations of rules configured to check for certain styles. +The following presets only contain lint rules but you can make your own that +include any remark plugins or other presets. +The presets that are maintained here: @@ -359,74 +93,518 @@ Presets can be loaded just like other plugins. -## List of external rules +## Rules -External rules can be loaded just like normal rules. +The rules that are maintained here: + + + +* [`remark-lint-blockquote-indentation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-blockquote-indentation) — warn when block quotes are either indented too much or too little +* [`remark-lint-checkbox-character-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-checkbox-character-style) — warn when list item checkboxes violate a given style +* [`remark-lint-checkbox-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-checkbox-content-indent) — warn when list item checkboxes are followed by too much whitespace +* [`remark-lint-code-block-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-code-block-style) — warn when code blocks do not adhere to a given style +* [`remark-lint-definition-case`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-case) — warn when definition labels are not lowercase +* [`remark-lint-definition-spacing`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-spacing) — warn when consecutive whitespace is used in a definition +* [`remark-lint-emphasis-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-emphasis-marker) — warn when emphasis markers violate the given style +* [`remark-lint-fenced-code-flag`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-flag) — warn when fenced code blocks occur without language flag +* [`remark-lint-fenced-code-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-marker) — warn when fenced code markers violate the given style +* [`remark-lint-file-extension`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-file-extension) — warn when the file’s extension violates the given style +* [`remark-lint-final-definition`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-definition) — warn when definitions are not placed at the end of the file +* [`remark-lint-final-newline`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-newline) — warn when a newline at the end of a file is missing +* [`remark-lint-first-heading-level`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-first-heading-level) — warn when the first heading has a level other than a specified value +* [`remark-lint-hard-break-spaces`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-hard-break-spaces) — warn when too many spaces are used to create a hard break +* [`remark-lint-heading-increment`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-increment) — warn when headings increment with more than 1 level at a time +* [`remark-lint-heading-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-style) — warn when heading style violates the given style +* [`remark-lint-linebreak-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-linebreak-style) — warn when linebreaks violate a given or detected style +* [`remark-lint-link-title-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-link-title-style) — warn when link and definition titles occur with incorrect quotes +* [`remark-lint-list-item-bullet-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-bullet-indent) — warn when list item bullets are indented +* [`remark-lint-list-item-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-content-indent) — warn when the content of a list item has mixed indentation +* [`remark-lint-list-item-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-indent) — warn when the spacing between a list item’s bullet and its content violates a given style +* [`remark-lint-list-item-spacing`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-spacing) — warn when list looseness is incorrect +* [`remark-lint-maximum-heading-length`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-heading-length) — warn when headings are too long +* [`remark-lint-maximum-line-length`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-line-length) — warn when lines are too long +* [`remark-lint-no-blockquote-without-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-blockquote-without-marker) — warn when blank lines without markers (\`>\`) are found in a block quote +* [`remark-lint-no-consecutive-blank-lines`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-consecutive-blank-lines) — warn for too many consecutive blank lines +* [`remark-lint-no-duplicate-defined-urls`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-defined-urls) — warn on definitions that define the same urls +* [`remark-lint-no-duplicate-definitions`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-definitions) — warn on duplicate definitions +* [`remark-lint-no-duplicate-headings`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings) — warn on duplicate headings +* [`remark-lint-no-duplicate-headings-in-section`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings-in-section) — warn on duplicate headings in a section +* [`remark-lint-no-emphasis-as-heading`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-emphasis-as-heading) — warn when emphasis or importance is used instead of a heading +* [`remark-lint-no-empty-url`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-empty-url) — warn on empty URLs in links and images +* [`remark-lint-no-file-name-articles`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-articles) — warn when file name start with an article +* [`remark-lint-no-file-name-consecutive-dashes`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-consecutive-dashes) — warn when file names contain consecutive dashes +* [`remark-lint-no-file-name-irregular-characters`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-irregular-characters) — warn when file names contain irregular characters +* [`remark-lint-no-file-name-mixed-case`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-mixed-case) — warn when file names use mixed case +* [`remark-lint-no-file-name-outer-dashes`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-outer-dashes) — warn when file names contain initial or final dashes +* [`remark-lint-no-heading-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-content-indent) — warn when heading content is indented +* [`remark-lint-no-heading-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-indent) — warn when headings are indented +* [`remark-lint-no-heading-like-paragraph`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-like-paragraph) — for too many hashes (h7+ “headings”) +* [`remark-lint-no-heading-punctuation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-punctuation) — warn when headings end in illegal characters +* [`remark-lint-no-html`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-html) — warn when HTML nodes are used +* [`remark-lint-no-inline-padding`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-inline-padding) — warn when inline nodes are padded with spaces +* [`remark-lint-no-literal-urls`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-literal-urls) — warn when URLs without angle brackets are used +* [`remark-lint-no-missing-blank-lines`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-missing-blank-lines) — warn when missing blank lines +* [`remark-lint-no-multiple-toplevel-headings`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-multiple-toplevel-headings) — warn when multiple top level headings are used +* [`remark-lint-no-paragraph-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-paragraph-content-indent) — warn when the content in paragraphs are indented +* [`remark-lint-no-reference-like-url`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-reference-like-url) — warn when URLs are also defined identifiers +* [`remark-lint-no-shell-dollars`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shell-dollars) — warn when shell code is prefixed by dollars +* [`remark-lint-no-shortcut-reference-image`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-image) — warn when shortcut reference images are used +* [`remark-lint-no-shortcut-reference-link`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-link) — warn when shortcut reference links are used +* [`remark-lint-no-table-indentation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-table-indentation) — warn when tables are indented +* [`remark-lint-no-tabs`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-tabs) — warn when hard tabs are used instead of spaces +* [`remark-lint-no-undefined-references`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-undefined-references) — warn when references to undefined definitions are found +* [`remark-lint-no-unneeded-full-reference-image`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-image) — warn when full reference images are used if they can be collapsed +* [`remark-lint-no-unneeded-full-reference-link`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-link) — warn when full reference links are used if they can be collapsed +* [`remark-lint-no-unused-definitions`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unused-definitions) — warn when unused definitions are found +* [`remark-lint-ordered-list-marker-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-style) — warn when the markers of ordered lists violate a given style +* [`remark-lint-ordered-list-marker-value`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-value) — warn when the marker value of ordered lists violates a given style +* [`remark-lint-rule-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-rule-style) — warn when horizontal rules violate a given style +* [`remark-lint-strikethrough-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strikethrough-marker) — warn when strikethrough markers violate the given style +* [`remark-lint-strong-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strong-marker) — warn when importance (strong) markers violate the given style +* [`remark-lint-table-cell-padding`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-cell-padding) — warn when table cells are incorrectly padded +* [`remark-lint-table-pipe-alignment`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipe-alignment) — warn when table pipes are not aligned +* [`remark-lint-table-pipes`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipes) — warn when table rows are not fenced with pipes +* [`remark-lint-unordered-list-marker-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-unordered-list-marker-style) — warn when markers of unordered lists violate a given style + + + + + + + +You can make and share your own rules, which can be used just like the rules +maintained here. +The following rules are maintained by the community: + + * [`remark-lint-alphabetize-lists`](https://github.com/vhf/remark-lint-alphabetize-lists) - — Ensure list items are in alphabetical order + — ensure list items are in alphabetical order * [`remark-lint-appropriate-heading`](https://github.com/RichardLitt/remark-lint-appropriate-heading) - — Check that the top level heading matches the directory name + — check that the top level heading matches the directory name * [`remark-lint-blank-lines-1-0-2`](https://github.com/vhf/remark-lint-blank-lines-1-0-2) - — Ensure a specific number of lines between blocks + — ensure a specific number of lines between blocks * [`remark-lint-books-links`](https://github.com/vhf/remark-lint-books-links) - — Ensure links in lists of books follow a standard format + — ensure links in lists of books follow a standard format * [`remark-lint-code`](https://github.com/Qard/remark-lint-code) - — Lint fenced code blocks by corresponding language tags, + — lint fenced code blocks by corresponding language tags, currently supporting [ESLint](https://github.com/Qard/remark-lint-code-eslint) * [`remark-lint-match-punctuation`](https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-match-punctuation) - — Ensures punctuations are used in pairs if necessary. + — ensures punctuations are used in pairs if necessary. * [`remark-lint-mdash-style`](https://github.com/alexandrtovmach/remark-lint-mdash-style) - — Ensure em-dash (`—`) style follows a standard format + — ensure em-dash (`—`) style follows a standard format * [`remark-lint-no-chinese-punctuation-in-number`](https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-no-chinese-punctuation-in-number) - — Ensures that Chinese punctuation’s not used in numbers + — ensures that Chinese punctuation’s not used in numbers * [`remark-lint-no-dead-urls`](https://github.com/davidtheclark/remark-lint-no-dead-urls) - — Check that external links are alive + — check that external links are alive * [`remark-lint-no-long-code`](https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-no-long-code) - — Ensures that each line in code block won't be too long. + — ensures that each line in code block won't be too long. * [`remark-lint-no-repeat-punctuation`](https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-no-repeat-punctuation) - — Ensures punctuation is not repeated + — ensures punctuation is not repeated * [`remark-lint-emoji-limit`](https://github.com/zerok/remark-lint-emoji-limit) - — Enforce a limit of emoji per paragraph + — enforce a limit of emoji per paragraph * [`remark-lint-no-empty-sections`](https://github.com/vhf/remark-lint-no-empty-sections) - — Ensure every heading is followed by content (forming a section) + — ensure every heading is followed by content (forming a section) * [`remark-lint-heading-length`](https://github.com/zerok/remark-lint-heading-length) - — Ensure headings have the appropriate length + — ensure headings have the appropriate length * [`remark-lint-heading-whitespace`](https://github.com/vhf/remark-lint-heading-whitespace) - — Ensure heading parsing is not broken by weird whitespace + — ensure heading parsing is not broken by weird whitespace * [`remark-lint-are-links-valid`](https://github.com/wemake-services/remark-lint-are-links-valid) - — Check if your links are reachable and/or unique + — check if your links are reachable and/or unique * [`remark-lint-spaces-around-number`](https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-spaces-around-number) - — Ensures there are spaces around number and Chinese. + — ensures there are spaces around number and Chinese. * [`remark-lint-spaces-around-word`](https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-spaces-around-word) - — Ensures there are spaces around English word and Chinese. + — ensures there are spaces around English word and Chinese. * [`remark-lint-no-url-trailing-slash`](https://github.com/vhf/remark-lint-no-url-trailing-slash) - — Ensure that the `href` of links has no trailing slash + — ensure that the `href` of links has no trailing slash * [`remark-lint-write-good`](https://github.com/zerok/remark-lint-write-good) - — Wrapper for `write-good` + — wrapper for `write-good` * [`remark-lint-double-link`](https://github.com/Scrum/remark-lint-double-link) - — Ensure the same URL is not linked multiple times. + — ensure the same URL is not linked multiple times. -## Create a custom rule +For help creating your own rule, it’s suggested to look at existing rules and to +[follow this tutorial][tutorial]. -Follow this comprehensive [tutorial](https://github.com/remarkjs/remark-lint/blob/main/doc/create-a-custom-rule.md) on how to create your own custom rule for `remark`. +## Configure + + + + + +All rules can be configured in one standard way: + +```js +import {remark} from 'remark' +import remarkLintFinalNewline from 'remark-lint-final-newline' +import remarkLintMaximumLineLength from 'remark-lint-maximum-line-length' +import remarkLintUnorderedListMarkerStyle from 'remark-lint-unordered-list-marker-style' + +remark() + // Pass `false` to turn a rule off — the code no longer runs: + .use(remarkLintFinalNewline, false) + // Pass `true` to turn a rule on again: + .use(remarkLintFinalNewline, true) + // You can also configure whether messages by the rule should be ignored, + // are seen as code style warnings (default), or are seen as exceptions. + // Ignore messages with `'off'` or `0` as the first value of an array: + .use(remarkLintFinalNewline, ['off']) + .use(remarkLintFinalNewline, [0]) + // Use `'warn'`, `'on'`, or `1` to treat messages as code style warnings: + .use(remarkLintFinalNewline, ['warn']) + .use(remarkLintFinalNewline, ['on']) + .use(remarkLintFinalNewline, [1]) + // Use `'error'` or `2` to treat messages as exceptions: + .use(remarkLintFinalNewline, ['error']) + .use(remarkLintFinalNewline, [2]) + // Some rules accept options, and what they exactly accept is different for + // each rule (sometimes a string, a number, or an object). + // The following rule accepts a string: + .use(remarkLintUnorderedListMarkerStyle, '*') + .use(remarkLintUnorderedListMarkerStyle, ['on', '*']) + .use(remarkLintUnorderedListMarkerStyle, [1, '*']) + // The following rule accepts a number, numbers *must* be passed in arrays: + .use(remarkLintMaximumLineLength, ['on', 72]) + .use(remarkLintMaximumLineLength, [1, 72]) +``` + +See [`use()` in `unified`s readme][unified-use] for more info on how to use +plugins. + +> 🧑‍🏫 **Info**: messages in `remark-lint` are warnings instead of errors. +> Other linters (such as ESLint) almost always use errors. +> Why? +> Those tools *only* check code style. +> They don’t generate, transform, and format code, which is what remark and +> unified focus on, too. +> Errors in unified mean the same as an exception in your JavaScript code: a +> crash. +> That’s why we use warnings instead, because we continue checking more markdown +> and continue running more plugins. + +## Ignore warnings + +You can use HTML comments to hide or show warnings from within markdown. +Turn off all remark lint messages with `` and turn them on +again with ``: + +```markdown + + +[Naiad]: https://naiad.neptune + +[Thalassa]: https://thalassa.neptune + + +``` + +You can toggle specific rules by using their names without `remark-lint-`: + +```markdown + + +[Naiad]: https://naiad.neptune + +[Thalassa]: https://thalassa.neptune + + +``` + +You can ignore a message in the next block with ``: + +```markdown + + +[Naiad]: https://naiad.neptune +``` + +`ignore` also accepts a list of rules: + +```markdown + + +[Naiad]: https://naiad.neptune +``` + +> 👉 **Note**: you’ll typically need blank lines between HTML comments and other +> constructs. +> More info is available at the package that handles comments, +> [`remark-message-control`][remark-message-control]. + +> 💡 **Tip**: MDX comments are supported when [`remark-mdx`][remark-mdx] is +> used: +> +> ```mdx +> {/* lint ignore no-unused-definitions definition-case */} +> ``` + +## Examples + +### Example: check markdown on the API + +The following example checks that markdown code style is consistent and follows +some best practices. +It also reconfigures a rule. +First install dependencies: + +```sh +npm install vfile-reporter remark remark-preset-lint-consistent remark-preset-lint-recommended remark-lint-list-item-indent --save-dev +``` + +Then create a module `example.js` that contains: + +```js +import {reporter} from 'vfile-reporter' +import {remark} from 'remark' +import remarkPresetLintConsistent from 'remark-preset-lint-consistent' +import remarkPresetLintRecommended from 'remark-preset-lint-recommended' +import remarkLintListItemIndent from 'remark-lint-list-item-indent' + +main() + +async function main() { + const file = await remark() + // Check that markdown is consistent. + .use(remarkPresetLintConsistent) + // Few recommended rules. + .use(remarkPresetLintRecommended) + // `remark-lint-list-item-indent` is configured with `tab-size` in the + // recommended preset, but if we’d prefer something else, it can be + // reconfigured: + .use(remarkLintListItemIndent, 'space') + .process('1) Hello, _Jupiter_ and *Neptune*!') + + console.error(reporter(file)) +} +``` + +Running that with `node example.js` yields: + +```txt + 1:1 warning Missing newline character at end of file final-newline remark-lint + 1:1-1:35 warning Marker style should be `.` ordered-list-marker-style remark-lint + 1:25-1:34 warning Emphasis should use `_` as a marker emphasis-marker remark-lint + +⚠ 3 warnings +``` + +### Example: check and format markdown on the API + +remark lint rules *check* markdown. +[`remark-stringify`][remark-stringify] (used in remark) *formats* markdown. +When you configure lint rules and use remark to format markdown, you must +manually synchronize their configuration: + +```js +import {reporter} from 'vfile-reporter' +import {remark} from 'remark' +import remarkLintEmphasisMarker from 'remark-lint-emphasis-marker' +import remarkLintStrongMarker from 'remark-lint-strong-marker' + +main() + +async function main() { + const file = await remark() + .use(remarkLintEmphasisMarker, '*') + .use(remarkLintStrongMarker, '*') + .use({ + settings: {emphasis: '*', strong: '*'} // `remark-stringify` settings. + }) + .process('_Hello_, __world__!') + + console.error(reporter(file)) + console.log(String(file)) +} +``` + +Yields: + +```txt + 1:1-1:8 warning Emphasis should use `*` as a marker emphasis-marker remark-lint + 1:10-1:19 warning Strong should use `*` as a marker strong-marker remark-lint + +⚠ 2 warnings +``` + +```markdown +*Hello*, **world**! +``` + +Observe that the lint rules check the input and afterwards remark formats using +asterisks. +If that output was given the the processor, the lint rules would be satisfied. + +### Example: check markdown on the CLI + +This example checks markdown with [`remark-cli`][remark-cli]. +It assumes you’re in a Node.js package. +First install dependencies: + +```sh +npm install remark-cli remark-preset-lint-consistent remark-preset-lint-recommended remark-lint-list-item-indent --save-dev +``` + +Then add an npm script to your `package.json`: + +```js + /* … */ + "scripts": { + /* … */ + "check": "remark . --quiet --frail", + /* … */ + }, + /* … */ +``` + +> 💡 **Tip**: add ESLint and such in the `check` script too. + +Observe that the above change adds a `check` script, which can be run with +`npm run check`. +It runs remark on all markdown files (`.`), shows only warnings and errors +(`--quiet`), and exits as failed on warnings (`--frail`). +Run `./node_modules/.bin/remark --help` for more info on the CLI. + +Now add a `remarkConfig` to your `package.json` to configure remark: + +```js + /* … */ + "remarkConfig": { + "plugins": [ + "remark-preset-lint-consistent", // Check that markdown is consistent. + "remark-preset-lint-recommended", // Few recommended rules. + // `remark-lint-list-item-indent` is configured with `tab-size` in the + // recommended preset, but if we’d prefer something else, it can be + // reconfigured: + [ + "remark-lint-list-item-indent", + "space" + ] + ] + }, + /* … */ +``` + +> 👉 **Note**: you must remove the comments in the above examples when +> copy/pasting them, as comments are not supported in `package.json` files. + +Finally run the npm script to check markdown files in your project: + +```sh +npm run check +``` + +### Example: check and format markdown on the CLI + +remark lint rules *check* markdown. +The CLI can *format* markdown. +You can combine these features but have to manually synchronize their +configuration. +Please first follow the previous example (checking markdown on the CLI) and then +change the npm script: + +```js + /* … */ + "scripts": { + /* … */ + "format": "remark . --quiet --frail --output", + /* … */ + }, + /* … */ +``` + +The script is now called `format` to reflect what it does. +It now includes an `--output` flag, which means it will overwrite existing files +with changes. + +Update `remarkConfig`: + +```js + /* … */ + "remarkConfig": { + "settings": { + "emphasis": "*", + "strong": "*" + }, + "plugins": [ + "remark-preset-lint-consistent", + "remark-preset-lint-recommended", + ["remark-lint-list-item-indent", "space"] + ["remark-lint-emphasis-marker", "*"], + ["remark-lint-strong-marker", "*"] + ] + }, + /* … */ +``` + +This now includes `settings`, which configures +[`remark-stringify`][remark-stringify], and explicitly prefers asterisks +for emphasis and strong. +Install the new dependencies: + +```sh +npm install remark-lint-emphasis-marker remark-lint-strong-marker --save-dev +``` + +Finally run the npm script to format markdown files in your project: + +```sh +npm run format +``` + +> 👉 **Note**: running `npm run format` now checks *and* formats your files. +> The first time you run it, assuming you have underscores for emphasis and +> strong, it would first warn and then format. +> The second time you run it, no warnings should appear. + +## Integrations + +* [`linter-remark`](https://github.com/wooorm/linter-remark) + ([Atom](https://atom.io)) + — use remark from Atom +* [`vscode-remark-lint`](https://github.com/drewbourne/vscode-remark-lint) + ([VS Code](https://code.visualstudio.com)) + — use `remark-lint` from Visual Studio Code +* [`SublimeLinter-contrib-remark-lint`](https://packagecontrol.io/packages/SublimeLinter-contrib-remark-lint) + ([Sublime](https://www.sublimetext.com)) + — use `remark-lint` from Sublime Text +* [`ale`](https://github.com/w0rp/ale) + ([Vim](https://www.vim.org)) + — use `remark-lint` from Vim +* [`jest-runner-remark`](https://github.com/keplersj/jest-runner-remark) + ([Jest](https://jestjs.io)) + — use remark with Jest + +## Syntax + +Markdown is parsed by [`remark-parse`][remark-parse] (included in `remark`) +according to CommonMark. +You can combine it with other plugins to add syntax extensions. +Notable examples that deeply integrate with it are +[`remark-gfm`][remark-gfm], +[`remark-mdx`][remark-mdx], +[`remark-frontmatter`][remark-frontmatter], +[`remark-math`][remark-math], and +[`remark-directive`][remark-directive]. + +## 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. ## Security -Use of `remark-lint` does not mutate the tree so there are no openings for +Use of `remark-lint` does not change the tree so there are no openings for [cross-site scripting (XSS)][xss] attacks. Messages from linting rules may be hidden from user content though, causing -builds to fail or pass, or changing a report. - -## Related - -* [`remark-validate-links`](https://github.com/remarkjs/remark-validate-links) - — Validate if links point to existing headings and files in markdown +builds to fail or pass. ## Contribute @@ -466,46 +644,46 @@ abide by its terms. [collective]: https://opencollective.com/unified -[npm]: https://docs.npmjs.com/cli/install - [health]: https://github.com/remarkjs/.github -[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 [license]: license [author]: https://wooorm.com -[cli-settings]: https://github.com/unifiedjs/unified-args#--setting-settings +[unified]: https://github.com/unifiedjs/unified -[cli-config]: https://github.com/unifiedjs/unified-engine/blob/HEAD/doc/configure.md +[unified-use]: https://github.com/unifiedjs/unified#processoruseplugin-options [remark]: https://github.com/remarkjs/remark -[remark-plugins]: https://github.com/remarkjs/remark/blob/HEAD/doc/plugins.md +[remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli -[remark-stringify]: https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify +[remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse -[remark-stringify-options]: https://github.com/remarkjs/remark/tree/HEAD/packages/remark-stringify#options +[remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify -[api]: https://github.com/remarkjs/remark/tree/HEAD/packages/remark +[remark-plugin]: https://github.com/remarkjs/remark#plugins -[cli]: https://github.com/remarkjs/remark/tree/HEAD/packages/remark-cli +[remark-message-control]: https://github.com/remarkjs/remark-message-control -[message-control]: https://github.com/remarkjs/remark-message-control#markers +[remark-gfm]: https://github.com/remarkjs/remark-gfm -[preset-recommended]: https://github.com/remarkjs/remark-lint/blob/main/packages/remark-preset-lint-recommended +[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter + +[remark-math]: https://github.com/remarkjs/remark-math + +[remark-directive]: https://github.com/remarkjs/remark-directive + +[remark-mdx]: https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx [logo]: https://raw.githubusercontent.com/remarkjs/remark-lint/02295bc/logo.svg?sanitize=true -[screenshot]: https://raw.githubusercontent.com/remarkjs/remark-lint/02295bc/screenshot.png - -[rules]: doc/rules.md - -[presets]: #list-of-presets - [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting + +[tutorial]: doc/create-a-custom-rule.md diff --git a/screenshot.png b/screenshot.png index 982f63b..f6d601b 100644 Binary files a/screenshot.png and b/screenshot.png differ diff --git a/script/build-presets.js b/script/build-presets.js index 98568b5..46e815d 100644 --- a/script/build-presets.js +++ b/script/build-presets.js @@ -9,8 +9,11 @@ import path from 'node:path' import process from 'node:process' import {inspect} from 'node:util' import {parse} from 'comment-parser' +import {unified} from 'unified' import {remark} from 'remark' +import remarkParse from 'remark-parse' import remarkGfm from 'remark-gfm' +import {findAndReplace} from 'mdast-util-find-and-replace' import strip from 'strip-indent' import parseAuthor from 'parse-author' import {presets} from './util/presets.js' @@ -32,25 +35,44 @@ presets(root).then((presetObjects) => { const pack = JSON.parse( String(fs.readFileSync(path.join(base, 'package.json'))) ) + const version = (pack.version || '0').split('.')[0] const doc = fs.readFileSync(path.join(base, 'index.js'), 'utf8') - const tags = parse(doc, {spacing: 'preserve'})[0].tags + const fileInfo = parse(doc, {spacing: 'preserve'})[0] + const tags = fileInfo.tags + const summaryTag = tags.find((d) => d.tag === 'summary') const author = typeof pack.author === 'string' ? parseAuthor(pack.author) : pack.author - const fileoverviewTag = tags.find((d) => d.tag === 'fileoverview') + const descriptionTree = unified() + .use(remarkParse) + .parse(strip(fileInfo.description).trim()) + const summaryTree = unified() + .use(remarkParse) + .parse(strip(summaryTag ? summaryTag.description : '').trim()) - if (!fileoverviewTag) { - throw new Error('Expected `@fileoverview` in jsdoc') - } + // Autolink `remark-lint` + unified() + .use( + /** @type {import('unified').Plugin, import('mdast').Root>} */ + () => (tree) => { + findAndReplace(tree, /remark-lint/g, () => { + return { + type: 'linkReference', + identifier: 'mono', + referenceType: 'full', + children: [{type: 'inlineCode', value: 'remark-lint'}] + } + }) + } + ) + .runSync(summaryTree) - const description = strip(fileoverviewTag.description).trim() - const short = name.replace(/^remark-/, '') const camelcased = name.replace(/-(\w)/g, (_, /** @type {string} */ $1) => $1.toUpperCase() ) const org = remote.split('/').slice(0, -1).join('/') const main = remote + '/blob/main' const health = org + '/.github' - const hMain = health + '/blob/HEAD' + const hMain = health + '/blob/main' const slug = remote.split('/').slice(-2).join('/') if (name !== pack.name) { @@ -64,6 +86,13 @@ presets(root).then((presetObjects) => { ) } + const descriptionContent = /** @type {Array} */ ( + descriptionTree.children + ) + const summaryContent = /** @type {Array} */ ( + summaryTree.children + ) + /** @type {Array} */ const rows = [] @@ -110,10 +139,6 @@ presets(root).then((presetObjects) => { } } - /** @type {Array} */ - // @ts-expect-error: fine. - const descriptionContent = remark().parse(description).children - /** @type {Array} */ const children = [ {type: 'html', value: ''}, @@ -224,6 +249,48 @@ presets(root).then((presetObjects) => { } ] }, + ...summaryContent, + { + type: 'heading', + depth: 2, + children: [{type: 'text', value: 'Contents'}] + }, + { + type: 'heading', + depth: 2, + children: [{type: 'text', value: 'What is this?'}] + }, + { + type: 'paragraph', + children: [ + {type: 'text', value: 'This package is a '}, + { + type: 'linkReference', + identifier: 'unified', + referenceType: 'collapsed', + children: [{type: 'text', value: 'unified'}] + }, + {type: 'text', value: ' ('}, + { + type: 'linkReference', + identifier: 'remark', + referenceType: 'collapsed', + children: [{type: 'text', value: 'remark'}] + }, + { + type: 'text', + value: ') preset, specifically consisting of\n' + }, + { + type: 'inlineCode', + value: 'remark-lint' + }, + { + type: 'text', + value: ' rules.\nLint rules check markdown code style.' + } + ] + }, ...descriptionContent, { type: 'heading', @@ -235,8 +302,9 @@ presets(root).then((presetObjects) => { children: [ {type: 'text', value: 'This preset configures '}, { - type: 'link', - url: remote, + type: 'linkReference', + identifier: 'mono', + referenceType: 'full', children: [{type: 'inlineCode', value: 'remark-lint'}] }, {type: 'text', value: ' with the following rules:'} @@ -260,17 +328,10 @@ presets(root).then((presetObjects) => { }, { type: 'text', - value: ':\nNode 12+ is needed to use it and it must be ' + value: + '.\nIn Node.js (version 12.20+, 14.14+, or 16.0+), ' + + 'install with ' }, - {type: 'inlineCode', value: 'imported'}, - {type: 'text', value: 'ed instead of '}, - {type: 'inlineCode', value: 'required'}, - {type: 'text', value: 'd.'} - ] - }, - { - type: 'paragraph', - children: [ { type: 'linkReference', identifier: 'npm', @@ -284,28 +345,107 @@ presets(root).then((presetObjects) => { { type: 'paragraph', children: [ + {type: 'text', value: 'In Deno with '}, { - type: 'text', - value: - 'This package exports no identifiers.\nThe default export is ' + type: 'linkReference', + identifier: 'skypack', + label: 'Skypack', + referenceType: 'collapsed', + children: [{type: 'text', value: 'Skypack'}] }, - { - type: 'inlineCode', - value: name.replace(/-(\w)/g, (_, /** @type {string} */ $1) => - $1.toUpperCase() - ) - }, - {type: 'text', value: '.'} + {type: 'text', value: ':'} ] }, - {type: 'heading', depth: 2, children: [{type: 'text', value: 'Use'}]}, + { + type: 'code', + lang: 'js', + value: + 'import ' + + camelcased + + " from 'https://cdn.skypack.dev/" + + name + + '@' + + version + + "?dts'" + }, + { + type: 'paragraph', + children: [ + {type: 'text', value: 'In browsers with '}, + { + type: 'linkReference', + identifier: 'skypack', + label: 'Skypack', + referenceType: 'collapsed', + children: [{type: 'text', value: 'Skypack'}] + }, + {type: 'text', value: ':'} + ] + }, + { + type: 'code', + lang: 'html', + value: + '" + }, + { + type: 'heading', + depth: 2, + children: [{type: 'text', value: 'Use'}] + }, + { + type: 'paragraph', + children: [{type: 'text', value: 'On the API:'}] + }, + { + type: 'code', + lang: 'js', + value: [ + "import {read} from 'to-vfile'", + "import {reporter} from 'vfile-reporter'", + "import {remark} from 'remark'", + 'import ' + camelcased + " from '" + name + "'", + '', + 'main()', + '', + 'async function main() {', + ' const file = await remark()', + ' .use(' + camelcased + ')', + " .process(await read('example.md'))", + '', + ' console.error(reporter(file))', + '}' + ].join('\n') + }, + { + type: 'paragraph', + children: [{type: 'text', value: 'On the CLI:'}] + }, + { + type: 'code', + lang: 'sh', + value: 'remark --use ' + name + ' example.md' + }, { type: 'paragraph', children: [ { type: 'text', - value: - 'You probably want to use it on the CLI through a config file:' + value: 'On the CLI in a config file (here a ' + }, + { + type: 'inlineCode', + value: 'package.json' + }, + { + type: 'text', + value: '):' } ] }, @@ -315,35 +455,59 @@ presets(root).then((presetObjects) => { value: [ ' …', ' "remarkConfig": {', - '+ "plugins": ["' + short + '"]', + ' "plugins": [', + ' …', + '+ "' + name + '",', + ' …', + ' ]', ' }', ' …' ].join('\n') }, + {type: 'heading', depth: 2, children: [{type: 'text', value: 'API'}]}, { type: 'paragraph', - children: [{type: 'text', value: 'Or use it on the CLI directly'}] + children: [ + { + type: 'text', + value: + 'This package exports no identifiers.\nThe default export is ' + }, + {type: 'inlineCode', value: camelcased}, + {type: 'text', value: '.'} + ] + }, + { + type: 'heading', + depth: 3, + children: [ + {type: 'inlineCode', value: 'unified().use(' + camelcased + ')'} + ] }, - {type: 'code', lang: 'sh', value: 'remark -u ' + short + ' readme.md'}, { type: 'paragraph', - children: [{type: 'text', value: 'Or use this on the API:'}] + children: [ + { + type: 'text', + value: + 'Use the preset.\nPresets don’t have options.\nYou can reconfigure rules in them by using the afterwards with different\noptions.' + } + ] }, { - type: 'code', - lang: 'diff', - value: [ - " import {remark} from 'remark'", - " import {reporter} from 'vfile-reporter'", - ' import ' + camelcased + " from '" + name + "'", - '', - ' remark()', - '+ .use(' + camelcased + ')', - " .process('_Emphasis_ and **importance**')", - ' .then((file) => {', - ' console.error(reporter(file))', - ' })' - ].join('\n') + type: 'heading', + depth: 2, + children: [{type: 'text', value: 'Compatibility'}] + }, + { + type: 'paragraph', + children: [ + { + type: 'text', + value: + 'Projects maintained by the unified collective are compatible with all maintained\nversions of Node.js.\nAs of now, that is Node.js 12.20+, 14.14+, and 16.0+.\nOur projects sometimes work with older versions, but this is not guaranteed.' + } + ] }, { type: 'heading', @@ -366,7 +530,10 @@ presets(root).then((presetObjects) => { referenceType: 'collapsed', identifier: 'health', children: [ - {type: 'inlineCode', value: health.split('/').slice(-2).join('/')} + { + type: 'inlineCode', + value: health.split('/').slice(-2).join('/') + } ] }, {type: 'text', value: ' for ways\nto get started.\nSee '}, @@ -482,11 +649,31 @@ presets(root).then((presetObjects) => { identifier: 'chat', url: 'https://github.com/remarkjs/remark/discussions' }, + { + type: 'definition', + identifier: 'unified', + url: 'https://github.com/unifiedjs/unified' + }, + { + type: 'definition', + identifier: 'remark', + url: 'https://github.com/remarkjs/remark' + }, + { + type: 'definition', + identifier: 'mono', + url: 'https://github.com/' + slug + }, { type: 'definition', identifier: 'esm', url: 'https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c' }, + { + type: 'definition', + identifier: 'skypack', + url: 'https://www.skypack.dev' + }, { type: 'definition', identifier: 'npm', diff --git a/script/build-rules.js b/script/build-rules.js index 80583af..a48d569 100644 --- a/script/build-rules.js +++ b/script/build-rules.js @@ -8,8 +8,13 @@ import fs from 'node:fs' import path from 'node:path' import process from 'node:process' import {inspect} from 'node:util' +import {unified} from 'unified' import {remark} from 'remark' +import remarkParse from 'remark-parse' import remarkGfm from 'remark-gfm' +import {findAndReplace} from 'mdast-util-find-and-replace' +import {toString} from 'mdast-util-to-string' +import GitHubSlugger from 'github-slugger' import parseAuthor from 'parse-author' import {rules} from './util/rules.js' import {rule} from './util/rule.js' @@ -35,11 +40,11 @@ presets(root).then((presetObjects) => { const pack = JSON.parse( String(fs.readFileSync(path.join(base, 'package.json'))) ) + const version = (pack.version || '0').split('.')[0] const info = rule(base) const tests = info.tests const author = typeof pack.author === 'string' ? parseAuthor(pack.author) : pack.author - const short = basename.replace(/^remark-/, '') const camelcased = basename.replace( /-(\w)/g, (_, /** @type {string} */ $1) => $1.toUpperCase() @@ -47,13 +52,38 @@ presets(root).then((presetObjects) => { const org = remote.split('/').slice(0, -1).join('/') const main = remote + '/blob/main' const health = org + '/.github' - const hMain = health + '/blob/HEAD' + const hMain = health + '/blob/main' const slug = remote.split('/').slice(-2).join('/') let hasGfm = false - /** @type {Array} */ - // @ts-expect-error: fine. - const descriptionContent = remark().parse(info.description).children + const descriptionTree = unified().use(remarkParse).parse(info.description) + const summaryTree = unified() + .use(remarkParse) + .parse(info.summary || '') + + // Autolink `remark-lint` + unified() + .use( + /** @type {import('unified').Plugin, import('mdast').Root>} */ + () => (tree) => { + findAndReplace(tree, /remark-lint/g, () => { + return { + type: 'linkReference', + identifier: 'mono', + referenceType: 'full', + children: [{type: 'inlineCode', value: 'remark-lint'}] + } + }) + } + ) + .runSync(summaryTree) + + const descriptionContent = /** @type {Array} */ ( + descriptionTree.children + ) + const summaryContent = /** @type {Array} */ ( + summaryTree.children + ) if (basename !== pack.name) { throw new Error( @@ -65,6 +95,24 @@ presets(root).then((presetObjects) => { ) } + /** @type {Record>} */ + const categories = {} + let category = 'Intro' + let contentIndex = -1 + + while (++contentIndex < descriptionContent.length) { + const node = descriptionContent[contentIndex] + if (node.type === 'heading' && node.depth === 2) { + category = GitHubSlugger.slug(toString(node)) + } + + if (!(category in categories)) { + categories[category] = [] + } + + categories[category].push(node) + } + const includes = presetObjects.filter( (preset) => basename in preset.packages ) @@ -76,118 +124,164 @@ presets(root).then((presetObjects) => { type: 'heading', depth: 1, children: [{type: 'text', value: basename}] - }, - { - type: 'paragraph', - children: [ - { - type: 'linkReference', - identifier: 'build', - referenceType: 'full', - children: [ - { - type: 'imageReference', - identifier: 'build-badge', - referenceType: 'full', - alt: 'Build' - } - ] - }, - {type: 'text', value: '\n'}, - { - type: 'linkReference', - identifier: 'coverage', - referenceType: 'full', - children: [ - { - type: 'imageReference', - identifier: 'coverage-badge', - referenceType: 'full', - alt: 'Coverage' - } - ] - }, - {type: 'text', value: '\n'}, - { - type: 'linkReference', - identifier: 'downloads', - referenceType: 'full', - children: [ - { - type: 'imageReference', - identifier: 'downloads-badge', - referenceType: 'full', - alt: 'Downloads' - } - ] - }, - {type: 'text', value: '\n'}, - { - type: 'linkReference', - identifier: 'size', - referenceType: 'full', - children: [ - { - type: 'imageReference', - identifier: 'size-badge', - referenceType: 'full', - alt: 'Size' - } - ] - }, - {type: 'text', value: '\n'}, - { - type: 'linkReference', - identifier: 'collective', - referenceType: 'full', - children: [ - { - type: 'imageReference', - identifier: 'sponsors-badge', - referenceType: 'full', - alt: 'Sponsors' - } - ] - }, - {type: 'text', value: '\n'}, - { - type: 'linkReference', - identifier: 'collective', - referenceType: 'full', - children: [ - { - type: 'imageReference', - identifier: 'backers-badge', - referenceType: 'full', - alt: 'Backers' - } - ] - }, - {type: 'text', value: '\n'}, - { - type: 'linkReference', - identifier: 'chat', - referenceType: 'full', - children: [ - { - type: 'imageReference', - identifier: 'chat-badge', - referenceType: 'full', - alt: 'Chat' - } - ] - } - ] - }, - ...descriptionContent + } ] - if (!info.deprecated) { - children.push({ - type: 'heading', - depth: 2, - children: [{type: 'text', value: 'Presets'}] - }) + if (info.deprecated) { + children.push(...descriptionContent) + } else { + children.push( + { + type: 'paragraph', + children: [ + { + type: 'linkReference', + identifier: 'build', + referenceType: 'full', + children: [ + { + type: 'imageReference', + identifier: 'build-badge', + referenceType: 'full', + alt: 'Build' + } + ] + }, + {type: 'text', value: '\n'}, + { + type: 'linkReference', + identifier: 'coverage', + referenceType: 'full', + children: [ + { + type: 'imageReference', + identifier: 'coverage-badge', + referenceType: 'full', + alt: 'Coverage' + } + ] + }, + {type: 'text', value: '\n'}, + { + type: 'linkReference', + identifier: 'downloads', + referenceType: 'full', + children: [ + { + type: 'imageReference', + identifier: 'downloads-badge', + referenceType: 'full', + alt: 'Downloads' + } + ] + }, + {type: 'text', value: '\n'}, + { + type: 'linkReference', + identifier: 'size', + referenceType: 'full', + children: [ + { + type: 'imageReference', + identifier: 'size-badge', + referenceType: 'full', + alt: 'Size' + } + ] + }, + {type: 'text', value: '\n'}, + { + type: 'linkReference', + identifier: 'collective', + referenceType: 'full', + children: [ + { + type: 'imageReference', + identifier: 'sponsors-badge', + referenceType: 'full', + alt: 'Sponsors' + } + ] + }, + {type: 'text', value: '\n'}, + { + type: 'linkReference', + identifier: 'collective', + referenceType: 'full', + children: [ + { + type: 'imageReference', + identifier: 'backers-badge', + referenceType: 'full', + alt: 'Backers' + } + ] + }, + {type: 'text', value: '\n'}, + { + type: 'linkReference', + identifier: 'chat', + referenceType: 'full', + children: [ + { + type: 'imageReference', + identifier: 'chat-badge', + referenceType: 'full', + alt: 'Chat' + } + ] + } + ] + }, + ...summaryContent, + { + type: 'heading', + depth: 2, + children: [{type: 'text', value: 'Contents'}] + }, + { + type: 'heading', + depth: 2, + children: [{type: 'text', value: 'What is this?'}] + }, + { + type: 'paragraph', + children: [ + {type: 'text', value: 'This package is a '}, + { + type: 'linkReference', + identifier: 'unified', + referenceType: 'collapsed', + children: [{type: 'text', value: 'unified'}] + }, + {type: 'text', value: ' ('}, + { + type: 'linkReference', + identifier: 'remark', + referenceType: 'collapsed', + children: [{type: 'text', value: 'remark'}] + }, + { + type: 'text', + value: ') plugin, specifically a ' + }, + { + type: 'inlineCode', + value: 'remark-lint' + }, + { + type: 'text', + value: '\nrule.\nLint rules check markdown code style.' + } + ] + }, + ...(categories['when-should-i-use-this'] || []), + { + type: 'heading', + depth: 2, + children: [{type: 'text', value: 'Presets'}] + } + ) if (includes.length === 0) { children.push({ @@ -195,7 +289,7 @@ presets(root).then((presetObjects) => { children: [ { type: 'text', - value: 'This rule is not included in any default preset' + value: 'This rule is not included in a preset maintained here.' } ] }) @@ -261,6 +355,216 @@ presets(root).then((presetObjects) => { ) } + children.push( + { + type: 'heading', + depth: 2, + children: [{type: 'text', value: 'Install'}] + }, + { + type: 'paragraph', + children: [ + {type: 'text', value: 'This package is '}, + { + type: 'linkReference', + identifier: 'esm', + referenceType: 'full', + children: [{type: 'text', value: 'ESM only'}] + }, + { + type: 'text', + value: + '.\nIn Node.js (version 12.20+, 14.14+, or 16.0+), ' + + 'install with ' + }, + { + type: 'linkReference', + identifier: 'npm', + referenceType: 'collapsed', + children: [{type: 'text', value: 'npm'}] + }, + {type: 'text', value: ':'} + ] + }, + {type: 'code', lang: 'sh', value: 'npm install ' + basename}, + { + type: 'paragraph', + children: [ + {type: 'text', value: 'In Deno with '}, + { + type: 'linkReference', + identifier: 'skypack', + label: 'Skypack', + referenceType: 'collapsed', + children: [{type: 'text', value: 'Skypack'}] + }, + {type: 'text', value: ':'} + ] + }, + { + type: 'code', + lang: 'js', + value: + 'import ' + + camelcased + + " from 'https://cdn.skypack.dev/" + + basename + + '@' + + version + + "?dts'" + }, + { + type: 'paragraph', + children: [ + {type: 'text', value: 'In browsers with '}, + { + type: 'linkReference', + identifier: 'skypack', + label: 'Skypack', + referenceType: 'collapsed', + children: [{type: 'text', value: 'Skypack'}] + }, + {type: 'text', value: ':'} + ] + }, + { + type: 'code', + lang: 'html', + value: + '" + }, + { + type: 'heading', + depth: 2, + children: [{type: 'text', value: 'Use'}] + }, + { + type: 'paragraph', + children: [{type: 'text', value: 'On the API:'}] + }, + { + type: 'code', + lang: 'js', + value: [ + "import {read} from 'to-vfile'", + "import {reporter} from 'vfile-reporter'", + "import {remark} from 'remark'", + "import remarkLint from 'remark-lint'", + 'import ' + camelcased + " from '" + basename + "'", + '', + 'main()', + '', + 'async function main() {', + ' const file = await remark()', + ' .use(remarkLint)', + ' .use(' + camelcased + ')', + " .process(await read('example.md'))", + '', + ' console.error(reporter(file))', + '}' + ].join('\n') + }, + { + type: 'paragraph', + children: [{type: 'text', value: 'On the CLI:'}] + }, + { + type: 'code', + lang: 'sh', + value: 'remark --use remark-lint --use ' + basename + ' example.md' + }, + { + type: 'paragraph', + children: [ + { + type: 'text', + value: 'On the CLI in a config file (here a ' + }, + { + type: 'inlineCode', + value: 'package.json' + }, + { + type: 'text', + value: '):' + } + ] + }, + { + type: 'code', + lang: 'diff', + value: [ + ' …', + ' "remarkConfig": {', + ' "plugins": [', + ' …', + ' "remark-lint",', + '+ "' + basename + '",', + ' …', + ' ]', + ' }', + ' …' + ].join('\n') + } + ) + + if ('api' in categories) { + const [apiHeading, ...apiBody] = categories.api + + children.push( + apiHeading, + { + type: 'paragraph', + children: [ + { + type: 'text', + value: + 'This package exports no identifiers.\nThe default export is ' + }, + {type: 'inlineCode', value: camelcased}, + {type: 'text', value: '.'} + ] + }, + { + type: 'heading', + depth: 3, + children: [ + { + type: 'inlineCode', + value: 'unified().use(' + camelcased + '[, config])' + } + ] + }, + { + type: 'paragraph', + children: [ + { + type: 'text', + value: + 'This rule supports standard configuration that all remark lint rules accept\n(such as ' + }, + {type: 'inlineCode', value: 'false'}, + {type: 'text', value: ' to turn it off or '}, + {type: 'inlineCode', value: '[1, options]'}, + {type: 'text', value: ' to configure it).'} + ] + }, + ...apiBody + ) + } + + children.push( + ...(categories.recommendation || []), + ...(categories.fix || []), + ...(categories.example || []) + ) + let first = true /** @type {string} */ let setting @@ -273,7 +577,7 @@ presets(root).then((presetObjects) => { children.push({ type: 'heading', depth: 2, - children: [{type: 'text', value: 'Example'}] + children: [{type: 'text', value: 'Examples'}] }) first = false } @@ -318,17 +622,28 @@ presets(root).then((presetObjects) => { if (fixture.gfm) { hasGfm = true children.push({ - type: 'paragraph', + type: 'blockquote', children: [ - {type: 'text', value: 'Note: this example uses '}, { - type: 'linkReference', - label: 'GFM', - identifier: 'gfm', - referenceType: 'collapsed', - children: [{type: 'text', value: 'GFM'}] - }, - {type: 'text', value: '.'} + type: 'paragraph', + children: [ + {type: 'text', value: '👉 '}, + { + type: 'strong', + children: [{type: 'text', value: 'Note'}] + }, + {type: 'text', value: ': this example uses GFM ('}, + { + type: 'linkReference', + identifier: 'gfm', + referenceType: 'full', + children: [ + {type: 'inlineCode', value: 'remark-gfm'} + ] + }, + {type: 'text', value: ').'} + ] + } ] }) } @@ -340,11 +655,24 @@ presets(root).then((presetObjects) => { if (clean !== next) { children.push({ - type: 'paragraph', + type: 'blockquote', children: [ - {type: 'text', value: 'Note: '}, - {type: 'inlineCode', value: char.char}, - {type: 'text', value: ' represents ' + char.name + '.'} + { + type: 'paragraph', + children: [ + {type: 'text', value: '👉 '}, + { + type: 'strong', + children: [{type: 'text', value: 'Note'}] + }, + {type: 'text', value: ': '}, + {type: 'inlineCode', value: char.char}, + { + type: 'text', + value: ' represents ' + char.name + '.' + } + ] + } ] }) @@ -386,171 +714,76 @@ presets(root).then((presetObjects) => { { type: 'heading', depth: 2, - children: [{type: 'text', value: 'Install'}] + children: [{type: 'text', value: 'Compatibility'}] }, - { - type: 'paragraph', - children: [ - {type: 'text', value: 'This package is '}, - { - type: 'linkReference', - identifier: 'esm', - referenceType: 'full', - children: [{type: 'text', value: 'ESM only'}] - }, - { - type: 'text', - value: ':\nNode 12+ is needed to use it and it must be ' - }, - {type: 'inlineCode', value: 'imported'}, - {type: 'text', value: 'ed instead of '}, - {type: 'inlineCode', value: 'required'}, - {type: 'text', value: 'd.'} - ] - }, - { - type: 'paragraph', - children: [ - { - type: 'linkReference', - identifier: 'npm', - referenceType: 'collapsed', - children: [{type: 'text', value: 'npm'}] - }, - {type: 'text', value: ':'} - ] - }, - {type: 'code', lang: 'sh', value: 'npm install ' + basename}, { type: 'paragraph', children: [ { type: 'text', value: - 'This package exports no identifiers.\nThe default export is ' - }, - { - type: 'inlineCode', - value: basename.replace(/-(\w)/g, (_, /** @type {string} */ $1) => - $1.toUpperCase() - ) - }, - {type: 'text', value: '.'} - ] - }, - {type: 'heading', depth: 2, children: [{type: 'text', value: 'Use'}]}, - { - type: 'paragraph', - children: [ - { - type: 'text', - value: - 'You probably want to use it on the CLI through a config file:' + 'Projects maintained by the unified collective are compatible with all maintained\nversions of Node.js.\nAs of now, that is Node.js 12.20+, 14.14+, and 16.0+.\nOur projects sometimes work with older versions, but this is not guaranteed.' } ] }, { - type: 'code', - lang: 'diff', - value: [ - ' …', - ' "remarkConfig": {', - ' "plugins": [', - ' …', - ' "lint",', - '+ "' + short + '",', - ' …', - ' ]', - ' }', - ' …' - ].join('\n') + type: 'heading', + depth: 2, + children: [{type: 'text', value: 'Contribute'}] }, { type: 'paragraph', - children: [{type: 'text', value: 'Or use it on the CLI directly'}] - }, - { - type: 'code', - lang: 'sh', - value: 'remark -u lint -u ' + short + ' readme.md' + children: [ + {type: 'text', value: 'See '}, + { + type: 'linkReference', + referenceType: 'collapsed', + identifier: 'contributing', + children: [{type: 'inlineCode', value: 'contributing.md'}] + }, + {type: 'text', value: ' in '}, + { + type: 'linkReference', + referenceType: 'collapsed', + identifier: 'health', + children: [ + { + type: 'inlineCode', + value: health.split('/').slice(-2).join('/') + } + ] + }, + {type: 'text', value: ' for ways\nto get started.\nSee '}, + { + type: 'linkReference', + referenceType: 'collapsed', + identifier: 'support', + children: [{type: 'inlineCode', value: 'support.md'}] + }, + {type: 'text', value: ' for ways to get help.'} + ] }, { type: 'paragraph', - children: [{type: 'text', value: 'Or use this on the API:'}] - }, - { - type: 'code', - lang: 'diff', - value: [ - " import {remark} from 'remark'", - " import {reporter} from 'vfile-reporter'", - " import remarkLint from 'remark-lint'", - ' import ' + camelcased + " from '" + basename + "'", - '', - ' remark()', - ' .use(remarkLint)', - '+ .use(' + camelcased + ')', - " .process('_Emphasis_ and **importance**')", - ' .then((file) => {', - ' console.error(reporter(file))', - ' })' - ].join('\n') + children: [ + {type: 'text', value: 'This project has a '}, + { + type: 'linkReference', + referenceType: 'collapsed', + identifier: 'coc', + children: [{type: 'text', value: 'code of conduct'}] + }, + { + type: 'text', + value: + '.\nBy interacting with this repository, organization, or community you agree to\nabide by its terms.' + } + ] } ) } children.push( - { - type: 'heading', - depth: 2, - children: [{type: 'text', value: 'Contribute'}] - }, - { - type: 'paragraph', - children: [ - {type: 'text', value: 'See '}, - { - type: 'linkReference', - referenceType: 'collapsed', - identifier: 'contributing', - children: [{type: 'inlineCode', value: 'contributing.md'}] - }, - {type: 'text', value: ' in '}, - { - type: 'linkReference', - referenceType: 'collapsed', - identifier: 'health', - children: [ - {type: 'inlineCode', value: health.split('/').slice(-2).join('/')} - ] - }, - {type: 'text', value: ' for ways\nto get started.\nSee '}, - { - type: 'linkReference', - referenceType: 'collapsed', - identifier: 'support', - children: [{type: 'inlineCode', value: 'support.md'}] - }, - {type: 'text', value: ' for ways to get help.'} - ] - }, - { - type: 'paragraph', - children: [ - {type: 'text', value: 'This project has a '}, - { - type: 'linkReference', - referenceType: 'collapsed', - identifier: 'coc', - children: [{type: 'text', value: 'code of conduct'}] - }, - { - type: 'text', - value: - '.\nBy interacting with this repository, organization, or community you agree to\nabide by its terms.' - } - ] - }, {type: 'heading', depth: 2, children: [{type: 'text', value: 'License'}]}, { type: 'paragraph', @@ -571,110 +804,130 @@ presets(root).then((presetObjects) => { ] } ] - }, - { - type: 'definition', - identifier: 'build-badge', - url: 'https://github.com/' + slug + '/workflows/main/badge.svg' - }, - { - type: 'definition', - identifier: 'build', - url: 'https://github.com/' + slug + '/actions' - }, - { - type: 'definition', - identifier: 'coverage-badge', - url: 'https://img.shields.io/codecov/c/github/' + slug + '.svg' - }, - { - type: 'definition', - identifier: 'coverage', - url: 'https://codecov.io/github/' + slug - }, - { - type: 'definition', - identifier: 'downloads-badge', - url: 'https://img.shields.io/npm/dm/' + basename + '.svg' - }, - { - type: 'definition', - identifier: 'downloads', - url: 'https://www.npmjs.com/package/' + basename - }, - { - type: 'definition', - identifier: 'size-badge', - url: 'https://img.shields.io/bundlephobia/minzip/' + basename + '.svg' - }, - { - type: 'definition', - identifier: 'size', - url: 'https://bundlephobia.com/result?p=' + basename - }, - { - type: 'definition', - identifier: 'sponsors-badge', - url: 'https://opencollective.com/unified/sponsors/badge.svg' - }, - { - type: 'definition', - identifier: 'backers-badge', - url: 'https://opencollective.com/unified/backers/badge.svg' - }, - { - type: 'definition', - identifier: 'collective', - url: 'https://opencollective.com/unified' - }, - { - type: 'definition', - identifier: 'chat-badge', - url: 'https://img.shields.io/badge/chat-discussions-success.svg' - }, - { - type: 'definition', - identifier: 'chat', - url: 'https://github.com/remarkjs/remark/discussions' } ) if (!info.deprecated) { children.push( + { + type: 'definition', + identifier: 'build-badge', + url: 'https://github.com/' + slug + '/workflows/main/badge.svg' + }, + { + type: 'definition', + identifier: 'build', + url: 'https://github.com/' + slug + '/actions' + }, + { + type: 'definition', + identifier: 'coverage-badge', + url: 'https://img.shields.io/codecov/c/github/' + slug + '.svg' + }, + { + type: 'definition', + identifier: 'coverage', + url: 'https://codecov.io/github/' + slug + }, + { + type: 'definition', + identifier: 'downloads-badge', + url: 'https://img.shields.io/npm/dm/' + basename + '.svg' + }, + { + type: 'definition', + identifier: 'downloads', + url: 'https://www.npmjs.com/package/' + basename + }, + { + type: 'definition', + identifier: 'size-badge', + url: 'https://img.shields.io/bundlephobia/minzip/' + basename + '.svg' + }, + { + type: 'definition', + identifier: 'size', + url: 'https://bundlephobia.com/result?p=' + basename + }, + { + type: 'definition', + identifier: 'sponsors-badge', + url: 'https://opencollective.com/unified/sponsors/badge.svg' + }, + { + type: 'definition', + identifier: 'backers-badge', + url: 'https://opencollective.com/unified/backers/badge.svg' + }, + { + type: 'definition', + identifier: 'collective', + url: 'https://opencollective.com/unified' + }, + { + type: 'definition', + identifier: 'chat-badge', + url: 'https://img.shields.io/badge/chat-discussions-success.svg' + }, + { + type: 'definition', + identifier: 'chat', + url: 'https://github.com/remarkjs/remark/discussions' + }, + { + type: 'definition', + identifier: 'unified', + url: 'https://github.com/unifiedjs/unified' + }, + { + type: 'definition', + identifier: 'remark', + url: 'https://github.com/remarkjs/remark' + }, + { + type: 'definition', + identifier: 'mono', + url: 'https://github.com/' + slug + }, { type: 'definition', identifier: 'esm', url: 'https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c' }, + { + type: 'definition', + identifier: 'skypack', + url: 'https://www.skypack.dev' + }, { type: 'definition', identifier: 'npm', url: 'https://docs.npmjs.com/cli/install' + }, + { + type: 'definition', + identifier: 'health', + url: health + }, + { + type: 'definition', + identifier: 'contributing', + url: hMain + '/contributing.md' + }, + { + type: 'definition', + identifier: 'support', + url: hMain + '/support.md' + }, + { + type: 'definition', + identifier: 'coc', + url: hMain + '/code-of-conduct.md' } ) } children.push( - { - type: 'definition', - identifier: 'health', - url: health - }, - { - type: 'definition', - identifier: 'contributing', - url: hMain + '/contributing.md' - }, - { - type: 'definition', - identifier: 'support', - url: hMain + '/support.md' - }, - { - type: 'definition', - identifier: 'coc', - url: hMain + '/code-of-conduct.md' - }, { type: 'definition', identifier: 'license', diff --git a/script/plugin/list-of-rules.js b/script/plugin/list-of-rules.js index c8b83e4..9ccc8b4 100644 --- a/script/plugin/list-of-rules.js +++ b/script/plugin/list-of-rules.js @@ -25,7 +25,6 @@ export default function listOfRules() { spread: false, children: rules(root) .map((basename) => { - const name = basename.slice('remark-lint-'.length) /** @type {PackageJson} */ const pack = JSON.parse( String(fs.readFileSync(path.join(root, basename, 'package.json'))) @@ -49,7 +48,7 @@ export default function listOfRules() { { type: 'link', url: repoUrl(pack), - children: [{type: 'inlineCode', value: name}] + children: [{type: 'inlineCode', value: basename}] }, {type: 'text', value: ' — ' + description} ] diff --git a/script/util/rule.js b/script/util/rule.js index d545607..8c9ed05 100755 --- a/script/util/rule.js +++ b/script/util/rule.js @@ -2,6 +2,7 @@ * @typedef Rule * @property {string} ruleId * @property {string} description + * @property {string|undefined} summary * @property {boolean} deprecated * @property {Record} tests * @property {string} filePath @@ -27,15 +28,15 @@ import strip from 'strip-indent' * @param {string} filePath * @returns {Rule} */ -/* eslint-disable-next-line complexity */ export function rule(filePath) { const ruleId = path.basename(filePath).slice('remark-lint-'.length) /** @type {Record} */ const tests = {} const code = fs.readFileSync(path.join(filePath, 'index.js'), 'utf-8') - const tags = parse(code, {spacing: 'preserve'})[0].tags + const fileInfo = parse(code, {spacing: 'preserve'})[0] + const tags = fileInfo.tags const moduleTag = tags.find((d) => d.tag === 'module') - const fileoverviewTag = tags.find((d) => d.tag === 'fileoverview') + const summaryTag = tags.find((d) => d.tag === 'summary') const deprecatedTag = tags.find((d) => d.tag === 'deprecated') /* c8 ignore next 3 */ @@ -43,15 +44,9 @@ export function rule(filePath) { throw new Error('Expected `@module` in JSDoc') } - /* c8 ignore next 3 */ - if (!fileoverviewTag && !deprecatedTag) { - throw new Error('Expected `@fileoverview` (or `@deprecated`) in JSDoc') - } - const name = moduleTag.name let description = - (fileoverviewTag && fileoverviewTag.description) || - (deprecatedTag && deprecatedTag.description) + (deprecatedTag && deprecatedTag.description) || fileInfo.description /* c8 ignore next 3 */ if (name !== ruleId) { @@ -60,7 +55,7 @@ export function rule(filePath) { /* c8 ignore next 3 */ if (!description) { - throw new Error(ruleId + ' is missing a `@fileoverview` or `@deprecated`') + throw new Error(ruleId + ' is missing a description or `@deprecated`') } description = strip(description) @@ -69,6 +64,7 @@ export function rule(filePath) { const result = { ruleId, description: description.trim(), + summary: summaryTag ? strip(summaryTag.description).trim() : undefined, deprecated: Boolean(deprecatedTag), tests, filePath