Andreas/markdownlint
1
0
Fork 0
mirror of https://github.com/DavidAnson/markdownlint.git synced 2025-09-22 05:40:48 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Enable "line-length": { "strict": true } for all user-facing Markdown files in the repository.

Browse source
This commit is contained in:
David Anson 2022-11-05 17:34:37 -07:00
parent 72439f42c6
commit 91dd6dcb1d
49 changed files with 819 additions and 517 deletions
Download patch file Download diff file Expand all files Collapse all files

4
.markdownlint.json
View file

@ -1,5 +1,7 @@
{ {
"line-length": false, "line-length": {
"strict": true
},
"no-duplicate-heading": { "no-duplicate-heading": {
"siblings_only": true "siblings_only": true
}, },

116
CONTRIBUTING.md
View file

@ -1,63 +1,85 @@
# Contributing # Contributing
Interested in contributing? Great! Here are some suggestions to make it a good experience: Interested in contributing? Great! Here are some suggestions to make it a good
experience:
Start by [opening an issue](https://github.com/DavidAnson/markdownlint/issues), whether to identify a problem or outline a change. Start by [opening an issue](https://github.com/DavidAnson/markdownlint/issues),
That issue should be used to discuss the situation and agree on a plan of action before writing code or sending a pull request. whether to identify a problem or outline a change. That issue should be used to
Maybe the problem isn't really a problem, or maybe there are more things to consider. discuss the situation and agree on a plan of action before writing code or
If so, it's best to realize that before spending time and effort writing code that may not get used. sending a pull request. Maybe the problem isn't really a problem, or maybe there
are more things to consider. If so, it's best to realize that before spending
time and effort writing code that may not get used.
Match the coding style of the files you edit. Match the coding style of the files you edit. Although everyone has their own
Although everyone has their own preferences and opinions, a pull request is not the right forum to debate them. preferences and opinions, a pull request is not the right forum to debate them.
Do not add new [`dependencies` to `package.json`](https://docs.npmjs.com/files/package.json#dependencies). Do not add new [`dependencies` to `package.json`][dependencies]. The excellent
The excellent Markdown parser [markdown-it](https://www.npmjs.com/package/markdown-it) is this project's one and only dependency. Markdown parser [markdown-it][markdown-it] is this project's one and only
dependency.
If developing a new rule, start by creating a [custom rule](doc/CustomRules.md) in its own project. If developing a new rule, start by creating a [custom rule][custom-rules] in its
Once written, published, and tested in real world scenarios, open an issue to consider adding it to this project. own project. Once written, published, and tested in real world scenarios, open
For rule ideas, see [issues tagged with the `new rule` label](https://github.com/DavidAnson/markdownlint/labels/new%20rule). an issue to consider adding it to this project. For rule ideas, see [issues
tagged with the `new rule` label][new-rule].
Add tests for all new/changed functionality. Add tests for all new/changed functionality. Test positive and negative
Test positive and negative scenarios. scenarios. Try to break the new code now, or else it will get broken later.
Try to break the new code now, or else it will get broken later.
Run tests before sending a pull request via `npm test` in the [usual manner](https://docs.npmjs.com/misc/scripts). Run tests before sending a pull request via `npm test` in the [usual
Tests should all pass on all platforms. manner][npm-scripts]. Tests should all pass on all platforms. The test runner is
The test runner is [AVA](https://github.com/avajs/ava) and test cases are located in `test/markdownlint-test*.js`. [AVA][ava] and test cases are located in `test/markdownlint-test*.js`. When
When running tests, `test/*.md` files are enumerated, linted, and fail if any violations are missing a corresponding `{MD###}` marker in the test file. running tests, `test/*.md` files are enumerated, linted, and fail if any
For example, the line `### Heading {MD001}` is expected to trigger the rule `MD001`. violations are missing a corresponding `{MD###}` marker in the test file. For
For cases where the marker text can not be present on the same line, the syntax `{MD###:#}` can be used to include a line number. example, the line `### Heading {MD001}` is expected to trigger the rule `MD001`.
If `some-test.md` needs custom configuration, a `some-test.json` is used to provide a custom `options.config` for that scenario. For cases where the marker text can not be present on the same line, the syntax
Tests run by `markdownlint-test-scenarios.js` use [AVA's snapshot feature](https://github.com/avajs/ava/blob/main/docs/04-snapshot-testing.md). `{MD###:#}` can be used to include a line number. If `some-test.md` needs custom
To update snapshots (for example, after modifying a test file), run `npm run update-snapshots` and include the updated files with the pull request. configuration, a `some-test.json` is used to provide a custom `options.config`
for that scenario. Tests run by `markdownlint-test-scenarios.js` use [AVA's
snapshot feature][ava-snapshots]. To update snapshots (for example, after
modifying a test file), run `npm run update-snapshots` and include the updated
files with the pull request.
Lint before sending a pull request by running `npm run lint`. Lint before sending a pull request by running `npm run lint`. There should be no
There should be no issues. issues.
Run a full continuous integration pass before sending a pull request via `npm run ci`. Run a full continuous integration pass before sending a pull request via `npm
Code coverage should always be 100%. run ci`. Code coverage should always be 100%. As part of a continuous
As part of a continuous integration run, generated files may get updated and fail the run - commit them to the repository and rerun continuous integration. integration run, generated files may get updated and fail the run - commit them
to the repository and rerun continuous integration.
Pull requests should contain a single commit. Pull requests should contain a single commit. If necessary, squash multiple
If necessary, squash multiple commits before creating the pull request and when making changes. commits before creating the pull request and when making changes. (See [Git
(See [Git Tools - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) for details.) Tools - Rewriting History][rewriting-history] for details.)
Open pull requests against the `next` branch. Open pull requests against the `next` branch. That's where the latest changes
That's where the latest changes are staged for the next release. are staged for the next release. Include the text "(fixes #??)" at the end of
Include the text "(fixes #??)" at the end of the commit message so the pull request will be associated with the relevant issue. the commit message so the pull request will be associated with the relevant
End commit messages with a period (`.`). issue. End commit messages with a period (`.`). Once accepted, the tag `fixed in
Once accepted, the tag `fixed in next` will be added to the issue. next` will be added to the issue. When the commit is merged to the main branch
When the commit is merged to the main branch during the release process, the issue will be closed automatically. during the release process, the issue will be closed automatically. (See
(See [Closing issues using keywords](https://help.github.com/articles/closing-issues-using-keywords/) for details.) [Closing issues using keywords][closing-keywords] for details.)
Please refrain from using slang or meaningless placeholder words. Please refrain from using slang or meaningless placeholder words. Sample content
Sample content can be "text", "code", "heading", or the like. can be "text", "code", "heading", or the like. Sample URLs should use
Sample URLs should use [example.com](https://en.wikipedia.org/wiki/Example.com) which is safe for this purpose. [example.com][example-com] which is safe for this purpose. Profanity is not
Profanity is not allowed. allowed.
In order to maintain the permissive MIT license this project uses, all contributions must be your own and released under that license. In order to maintain the permissive MIT license this project uses, all
Code you add should be an original work and should not be copied from elsewhere. contributions must be your own and released under that license. Code you add
Taking code from a different project, Stack Overflow, or the like is not allowed. should be an original work and should not be copied from elsewhere. Taking code
The use of tools such as GitHub Copilot that generate code from other projects is not allowed. from a different project, Stack Overflow, or the like is not allowed. The use of
tools such as GitHub Copilot that generate code from other projects is not
allowed.
Thank you! Thank you!
[ava]: https://github.com/avajs/ava
[ava-snapshots]: https://github.com/avajs/ava/blob/main/docs/04-snapshot-testing.md
[closing-keywords]: https://help.github.com/articles/closing-issues-using-keywords/
[custom-rules]: doc/CustomRules.md
[dependencies]: https://docs.npmjs.com/files/package.json#dependencies
[example-com]: https://en.wikipedia.org/wiki/Example.com
[markdown-it]: https://www.npmjs.com/package/markdown-it
[new-rule]: https://github.com/DavidAnson/markdownlint/labels/new%20rule
[npm-scripts]: https://docs.npmjs.com/misc/scripts
[rewriting-history]: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History

424
README.md
View file

@ -33,24 +33,40 @@ and test cases came directly from that project.
### Related ### Related
* CLI * CLI
* [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) * [markdownlint-cli][markdownlint-cli] command-line interface for Node.js
command-line interface for Node.js ([works with pre-commit](https://github.com/igorshubovych/markdownlint-cli#use-with-pre-commit)) ([works with pre-commit][markdownlint-cli-precommit])
* [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) * [markdownlint-cli2][markdownlint-cli2] command-line interface for Node.js
command-line interface for Node.js ([works with pre-commit](https://github.com/DavidAnson/markdownlint-cli2#pre-commit)) ([works with pre-commit][markdownlint-cli2-precommit])
* GitHub * GitHub
* [GitHub Super-Linter Action](https://github.com/github/super-linter) * [GitHub Super-Linter Action][super-linter]
* [GitHub Actions problem matcher for markdownlint-cli](https://github.com/xt0rted/markdownlint-problem-matcher) * [GitHub Actions problem matcher for
markdownlint-cli][markdownlint-problem-matcher]
* Editor * Editor
* [vscode-markdownlint extension for VS Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) * [vscode-markdownlint extension for VS Code][vscode-markdownlint]
* [Sublime Text markdownlint for Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) * [Sublime Text markdownlint for Sublime Text][sublimelinter]
* [coc-markdownlint extension for Vim/Neovim](https://github.com/fannheyward/coc-markdownlint) * [coc-markdownlint extension for Vim/Neovim][coc]
* Tooling * Tooling
* [eslint-plugin-markdownlint for the ESLint analyzer](https://github.com/paweldrozd/eslint-plugin-markdownlint) * [eslint-plugin-markdownlint for the ESLint analyzer][eslint-plugin]
* [grunt-markdownlint for the Grunt task runner](https://github.com/sagiegurari/grunt-markdownlint) * [grunt-markdownlint for the Grunt task runner][grunt-markdownlint]
* [Cake.Markdownlint addin for Cake build automation system](https://github.com/cake-contrib/Cake.Markdownlint) * [Cake.Markdownlint addin for Cake build automation system][cake]
* [Lombiq Node.js Extensions for MSBuild (.NET builds)](https://github.com/Lombiq/NodeJs-Extensions) * [Lombiq Node.js Extensions for MSBuild (.NET builds)][nodejs-extensions]
* Ruby * Ruby
* [markdownlint/mdl gem for Ruby](https://rubygems.org/gems/mdl) * [markdownlint/mdl gem for Ruby][rubygems-mdl]
[cake]: https://github.com/cake-contrib/Cake.Markdownlint
[coc]: https://github.com/fannheyward/coc-markdownlint
[eslint-plugin]: https://github.com/paweldrozd/eslint-plugin-markdownlint
[grunt-markdownlint]: https://github.com/sagiegurari/grunt-markdownlint
[markdownlint-cli]: https://github.com/igorshubovych/markdownlint-cli
[markdownlint-cli-precommit]: https://github.com/igorshubovych/markdownlint-cli#use-with-pre-commit
[markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2
[markdownlint-cli2-precommit]: https://github.com/DavidAnson/markdownlint-cli2#pre-commit
[markdownlint-problem-matcher]: https://github.com/xt0rted/markdownlint-problem-matcher
[nodejs-extensions]: https://github.com/Lombiq/NodeJs-Extensions
[rubygems-mdl]: https://rubygems.org/gems/mdl
[sublimelinter]: https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint
[super-linter]: https://github.com/github/super-linter
[vscode-markdownlint]: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
## Demonstration ## Demonstration
@ -117,8 +133,8 @@ See [Rules.md](doc/Rules.md) for more details.
~~Struck through~~ rules are deprecated and provided for backward-compatibility. ~~Struck through~~ rules are deprecated and provided for backward-compatibility.
> All rules with `heading` as part of their name are also available as > All rules with `heading` as part of their name are also available as `header`
> `header` aliases (e.g. `heading-increment` is also available as `header-increment`). > aliases (e.g. `heading-increment` is also available as `header-increment`).
> The use of `header` is deprecated and provided for backward-compatibility. > The use of `header` is deprecated and provided for backward-compatibility.
## Tags ## Tags
@ -137,8 +153,9 @@ rules at once.
* **`hard_tab`** - `MD010` * **`hard_tab`** - `MD010`
* **`headers`** - `MD001`, `MD002`, `MD003`, `MD018`, `MD019`, `MD020`, `MD021`, * **`headers`** - `MD001`, `MD002`, `MD003`, `MD018`, `MD019`, `MD020`, `MD021`,
`MD022`, `MD023`, `MD024`, `MD025`, `MD026`, `MD036`, `MD041`, `MD043` `MD022`, `MD023`, `MD024`, `MD025`, `MD026`, `MD036`, `MD041`, `MD043`
* **`headings`** - `MD001`, `MD002`, `MD003`, `MD018`, `MD019`, `MD020`, `MD021`, * **`headings`** - `MD001`, `MD002`, `MD003`, `MD018`, `MD019`, `MD020`,
`MD022`, `MD023`, `MD024`, `MD025`, `MD026`, `MD036`, `MD041`, `MD043` `MD021`, `MD022`, `MD023`, `MD024`, `MD025`, `MD026`, `MD036`, `MD041`,
`MD043`
* **`hr`** - `MD035` * **`hr`** - `MD035`
* **`html`** - `MD033` * **`html`** - `MD033`
* **`images`** - `MD045`, `MD052`, `MD053` * **`images`** - `MD045`, `MD052`, `MD053`
@ -151,8 +168,8 @@ rules at once.
* **`spelling`** - `MD044` * **`spelling`** - `MD044`
* **`ul`** - `MD004`, `MD005`, `MD006`, `MD007`, `MD030`, `MD032` * **`ul`** - `MD004`, `MD005`, `MD006`, `MD007`, `MD030`, `MD032`
* **`url`** - `MD034` * **`url`** - `MD034`
* **`whitespace`** - `MD009`, `MD010`, `MD012`, `MD027`, `MD028`, `MD030`, `MD037`, * **`whitespace`** - `MD009`, `MD010`, `MD012`, `MD027`, `MD028`, `MD030`,
`MD038`, `MD039` `MD037`, `MD038`, `MD039`
## Configuration ## Configuration
@ -186,20 +203,20 @@ For example:
```markdown ```markdown
<!-- markdownlint-disable-next-line no-space-in-emphasis --> <!-- markdownlint-disable-next-line no-space-in-emphasis -->
deliberate space * in * emphasis space * in * emphasis
``` ```
Or: Or:
```markdown ```markdown
deliberate space * in * emphasis <!-- markdownlint-disable-line no-space-in-emphasis --> space * in * emphasis <!-- markdownlint-disable-line no-space-in-emphasis -->
``` ```
Or: Or:
```markdown ```markdown
<!-- markdownlint-disable no-space-in-emphasis --> <!-- markdownlint-disable no-space-in-emphasis -->
deliberate space * in * emphasis space * in * emphasis
<!-- markdownlint-enable no-space-in-emphasis --> <!-- markdownlint-enable no-space-in-emphasis -->
``` ```
@ -247,7 +264,7 @@ more rules for a file, the following more advanced syntax is supported:
For example: For example:
```markdown ```markdown
<!-- markdownlint-configure-file { "MD013": { "code_blocks": false } } --> <!-- markdownlint-configure-file { "hr-style": { "style": "---" } } -->
``` ```
or or
@ -426,8 +443,9 @@ Array of functions to parse the content of `markdownlint-configure-file` blocks.
As shown in the [Configuration](#configuration) section, inline comments can be As shown in the [Configuration](#configuration) section, inline comments can be
used to customize the [configuration object](#optionsconfig) for a document. By used to customize the [configuration object](#optionsconfig) for a document. By
default, the `JSON.parse` built-in is used, but custom parsers can be specified. default, the `JSON.parse` built-in is used, but custom parsers can be specified.
Content is passed to each parser function until one returns a value (vs. throwing Content is passed to each parser function until one returns a value (vs.
an exception). As such, strict parsers should come before flexible ones. throwing an exception). As such, strict parsers should come before flexible
ones.
For example: For example:
@ -443,8 +461,9 @@ List of custom rules to include with the default rule set for linting.
Each array element should define a rule. Rules are typically exported Each array element should define a rule. Rules are typically exported
by another package, but can be defined locally. Custom rules are by another package, but can be defined locally. Custom rules are
identified by the identified by the [keyword `markdownlint-rule` on npm][markdownlint-rule].
[keyword `markdownlint-rule` on npm](https://www.npmjs.com/search?q=keywords:markdownlint-rule).
[markdownlint-rule]: https://www.npmjs.com/search?q=keywords:markdownlint-rule
Example: Example:
@ -483,10 +502,14 @@ specify a custom `RegExp` or use the value `null` to disable the feature.
The default value: The default value:
<!-- markdownlint-disable line-length -->
```js ```js
/((^---\s*$[^]*?^---\s*$)|(^\+\+\+\s*$[^]*?^(\+\+\+|\.\.\.)\s*$)|(^\{\s*$[^]*?^\}\s*$))(\r\n|\r|\n|$)/m /((^---\s*$[^]*?^---\s*$)|(^\+\+\+\s*$[^]*?^(\+\+\+|\.\.\.)\s*$)|(^\{\s*$[^]*?^\}\s*$))(\r\n|\r|\n|$)/m
``` ```
<!-- markdownlint-restore -->
Ignores [YAML](https://en.wikipedia.org/wiki/YAML), Ignores [YAML](https://en.wikipedia.org/wiki/YAML),
[TOML](https://en.wikipedia.org/wiki/TOML), and [TOML](https://en.wikipedia.org/wiki/TOML), and
[JSON](https://en.wikipedia.org/wiki/JSON) front matter such as: [JSON](https://en.wikipedia.org/wiki/JSON) front matter such as:
@ -502,14 +525,16 @@ Note: Matches must occur at the start of the file.
##### options.fs ##### options.fs
Type: `Object` implementing the [file system API](https://nodejs.org/api/fs.html) Type: `Object` implementing the [file system API][node-fs-api]
In advanced scenarios, it may be desirable to bypass the default file system API. In advanced scenarios, it may be desirable to bypass the default file system
If a custom file system implementation is provided, `markdownlint` will use that API. If a custom file system implementation is provided, `markdownlint` will use
instead of invoking `require("fs")`. that instead of invoking `require("fs")`.
Note: The only methods called are `readFile` and `readFileSync`. Note: The only methods called are `readFile` and `readFileSync`.
[node-fs-api]: https://nodejs.org/api/fs.html
##### options.handleRuleFailures ##### options.handleRuleFailures
Type: `Boolean` Type: `Boolean`
@ -529,9 +554,11 @@ is allowed to continue and report any violations that were found.
Type: `Array` of `Array` of `Function` and plugin parameters Type: `Array` of `Array` of `Function` and plugin parameters
Specifies additional [markdown-it plugins](https://www.npmjs.com/search?q=keywords:markdown-it-plugin) Specifies additional [markdown-it plugins][markdown-it-plugin] to use when
to use when parsing input. Plugins can be used to support additional syntax and parsing input. Plugins can be used to support additional syntax and features for
features for advanced scenarios. advanced scenarios.
[markdown-it-plugin]: https://www.npmjs.com/search?q=keywords:markdown-it-plugin
Each item in the top-level `Array` should be of the form: Each item in the top-level `Array` should be of the form:
@ -543,7 +570,7 @@ Each item in the top-level `Array` should be of the form:
Type: `Boolean` Type: `Boolean`
Disables the use of HTML comments like `<!-- markdownlint-disable -->` to toggle Disables the use of HTML comments like `<!-- markdownlint-enable -->` to toggle
rules within the body of Markdown content. rules within the body of Markdown content.
By default, properly-formatted inline comments can be used to create exceptions By default, properly-formatted inline comments can be used to create exceptions
@ -554,24 +581,27 @@ comments.
Type: `Number` Type: `Number`
Specifies which version of the `result` object to return (see the "Usage" section Specifies which version of the `result` object to return (see the "Usage"
below for examples). section below for examples).
Passing a `resultVersion` of `0` corresponds to the original, simple format where Passing a `resultVersion` of `0` corresponds to the original, simple format
each error is identified by rule name and line number. *This is deprecated.* where each error is identified by rule name and line number. *This is
deprecated.*
Passing a `resultVersion` of `1` corresponds to a detailed format where each error Passing a `resultVersion` of `1` corresponds to a detailed format where each
includes information about the line number, rule name, alias, description, as well error includes information about the line number, rule name, alias, description,
as any additional detail or context that is available. *This is deprecated.* as well as any additional detail or context that is available. *This is
deprecated.*
Passing a `resultVersion` of `2` corresponds to a detailed format where each error Passing a `resultVersion` of `2` corresponds to a detailed format where each
includes information about the line number, rule names, description, as well as any error includes information about the line number, rule names, description, as
additional detail or context that is available. *This is deprecated.* well as any additional detail or context that is available. *This is
deprecated.*
Passing a `resultVersion` of `3` corresponds to the detailed version `2` format Passing a `resultVersion` of `3` corresponds to the detailed version `2` format
with additional information about how to fix automatically-fixable errors. In this with additional information about how to fix automatically-fixable errors. In
mode, all errors that occur on each line are reported (other versions report only this mode, all errors that occur on each line are reported (other versions
the first error for each rule). *This is the default.* report only the first error for each rule). *This is the default.*
##### options.strings ##### options.strings
@ -613,8 +643,9 @@ for readability and easy reuse. The `readConfig` and `readConfigSync` functions
load configuration settings and support the `extends` keyword for referencing load configuration settings and support the `extends` keyword for referencing
other files (see above). other files (see above).
By default, configuration files are parsed as JSON (and named `.markdownlint.json`). By default, configuration files are parsed as JSON (and named
Custom parsers can be provided to handle other formats like JSONC, YAML, and TOML. `.markdownlint.json`). Custom parsers can be provided to handle other formats
like JSONC, YAML, and TOML.
Asynchronous API: Asynchronous API:
@ -623,7 +654,7 @@ Asynchronous API:
* Read specified configuration file. * Read specified configuration file.
* *
* @param {string} file Configuration file name. * @param {string} file Configuration file name.
* @param {ConfigurationParser[] | ReadConfigCallback} parsers Parsing function(s). * @param {ConfigurationParser[] | ReadConfigCallback} parsers Parsing function.
* @param {Object} [fs] File system implementation. * @param {Object} [fs] File system implementation.
* @param {ReadConfigCallback} [callback] Callback (err, result) function. * @param {ReadConfigCallback} [callback] Callback (err, result) function.
* @returns {void} * @returns {void}
@ -666,12 +697,13 @@ Type: `String`
Location of configuration file to read. Location of configuration file to read.
The `file` is resolved relative to the current working directory. If an `extends` The `file` is resolved relative to the current working directory. If an
key is present once read, its value will be resolved as a path relative to `file` `extends` key is present once read, its value will be resolved as a path
and loaded recursively. Settings from a file referenced by `extends` are applied relative to `file` and loaded recursively. Settings from a file referenced by
first, then those of `file` are applied on top (overriding any of the same keys `extends` are applied first, then those of `file` are applied on top (overriding
appearing in the referenced file). If either the `file` or `extends` path begins any of the same keys appearing in the referenced file). If either the `file` or
with the `~` directory, it will act as a placeholder for the home directory. `extends` path begins with the `~` directory, it will act as a placeholder for
the home directory.
#### parsers #### parsers
@ -679,9 +711,9 @@ Type: *Optional* `Array` of `Function` taking (`String`) and returning `Object`
Array of functions to parse configuration files. Array of functions to parse configuration files.
The contents of a configuration file are passed to each parser function until one The contents of a configuration file are passed to each parser function until
of them returns a value (vs. throwing an exception). Consequently, strict parsers one of them returns a value (vs. throwing an exception). Consequently, strict
should come before flexible parsers. parsers should come before flexible parsers.
For example: For example:
@ -691,13 +723,16 @@ For example:
#### fs #### fs
Type: *Optional* `Object` implementing the [file system API](https://nodejs.org/api/fs.html) Type: *Optional* `Object` implementing the [file system API][file-system-api]
In advanced scenarios, it may be desirable to bypass the default file system API. [file-system-api]: https://nodejs.org/api/fs.html
If a custom file system implementation is provided, `markdownlint` will use that
instead of invoking `require("fs")`.
Note: The only methods called are `readFile`, `readFileSync`, `access`, and `accessSync`. In advanced scenarios, it may be desirable to bypass the default file system
API. If a custom file system implementation is provided, `markdownlint` will use
that instead of invoking `require("fs")`.
Note: The only methods called are `readFile`, `readFileSync`, `access`, and
`accessSync`.
#### callback #### callback
@ -735,6 +770,8 @@ markdownlint(options, function callback(err, result) {
Output: Output:
<!-- markdownlint-disable line-length -->
```text ```text
bad.string: 3: MD010/no-hard-tabs Hard tabs [Column: 19] bad.string: 3: MD010/no-hard-tabs Hard tabs [Column: 19]
bad.string: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.string"] bad.string: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.string"]
@ -746,6 +783,8 @@ bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [
bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "#bad.md"] bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "#bad.md"]
``` ```
<!-- markdownlint-restore -->
Or invoke `markdownlint.sync` for a synchronous call: Or invoke `markdownlint.sync` for a synchronous call:
```js ```js
@ -765,6 +804,8 @@ markdownlint(options, function callback(err, result) {
Output: Output:
<!-- markdownlint-disable line-length -->
```json ```json
{ {
"good.md": [], "good.md": [],
@ -801,7 +842,10 @@ Output:
} }
``` ```
Integration with the [gulp](https://gulpjs.com/) build system is straightforward: <!-- markdownlint-restore -->
Integration with the [gulp](https://gulpjs.com/) build system is
straightforward:
```js ```js
const gulp = require("gulp"); const gulp = require("gulp");
@ -826,6 +870,8 @@ gulp.task("markdownlint", function task() {
Output: Output:
<!-- markdownlint-disable line-length -->
```text ```text
[00:00:00] Starting 'markdownlint'... [00:00:00] Starting 'markdownlint'...
bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17] bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
@ -835,6 +881,8 @@ bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be
[00:00:00] Finished 'markdownlint' after 10 ms [00:00:00] Finished 'markdownlint' after 10 ms
``` ```
<!-- markdownlint-restore -->
Integration with the [Grunt](https://gruntjs.com/) build system is similar: Integration with the [Grunt](https://gruntjs.com/) build system is similar:
```js ```js
@ -866,6 +914,8 @@ module.exports = function wrapper(grunt) {
Output: Output:
<!-- markdownlint-disable line-length -->
```text ```text
Running "markdownlint:example" (markdownlint) task Running "markdownlint:example" (markdownlint) task
Warning: Warning:
@ -876,6 +926,8 @@ bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be
Use --force to continue. Use --force to continue.
``` ```
<!-- markdownlint-restore -->
## Browser ## Browser
`markdownlint` also works in the browser. `markdownlint` also works in the browser.
@ -909,23 +961,58 @@ const results = window.markdownlint.sync(options).toString();
For ideas how to integrate `markdownlint` into your workflow, refer to the For ideas how to integrate `markdownlint` into your workflow, refer to the
following projects or one of the tools in the [Related section](#related): following projects or one of the tools in the [Related section](#related):
* [.NET Documentation](https://docs.microsoft.com/en-us/dotnet/) ([Search repository](https://github.com/dotnet/docs/search?q=markdownlint)) * [.NET Documentation][dot-net-doc] ([Search repository][dot-net-doc-search])
* [ally.js](https://allyjs.io/) ([Search repository](https://github.com/medialize/ally.js/search?q=markdownlint)) * [ally.js][ally-js] ([Search repository][ally-js-search])
* [Boostnote](https://boostnote.io/) ([Search repository](https://github.com/BoostIO/Boostnote/search?q=markdownlint)) * [Boostnote][boostnote] ([Search repository][boostnote-search])
* [CodiMD](https://github.com/hackmdio/codimd) ([Search repository](https://github.com/hackmdio/codimd/search?q=markdownlint)) * [CodiMD][codimd] ([Search repository][codimd-search])
* [ESLint](https://eslint.org/) ([Search repository](https://github.com/eslint/eslint/search?q=markdownlint)) * [ESLint][eslint] ([Search repository][eslint-search])
* [Garden React Components](https://zendeskgarden.github.io/react-components/) ([Search repository](https://github.com/zendeskgarden/react-components/search?q=markdownlint)) * [Garden React Components][garden] ([Search repository][garden-search])
* [MDN Web Docs](https://developer.mozilla.org/) ([Search repository](https://github.com/mdn/content/search?q=markdownlint)) * [MDN Web Docs][mdn] ([Search repository][mdn-search])
* [MkDocs](https://www.mkdocs.org/) ([Search repository](https://github.com/mkdocs/mkdocs/search?q=markdownlint)) * [MkDocs][mkdocs] ([Search repository][mkdocs-search])
* [Mocha](https://mochajs.org/) ([Search repository](https://github.com/mochajs/mocha/search?q=markdownlint)) * [Mocha][mocha] ([Search repository][mocha-search])
* [Pi-hole documentation](https://docs.pi-hole.net) ([Search repository](https://github.com/pi-hole/docs/search?q=markdownlint)) * [Pi-hole documentation][pi-hole] ([Search repository][pi-hole-search])
* [Reactable](https://glittershark.github.io/reactable/) ([Search repository](https://github.com/glittershark/reactable/search?q=markdownlint)) * [Reactable][reactable] ([Search repository][reactable-search])
* [Sinon.JS](https://sinonjs.org/) ([Search repository](https://github.com/sinonjs/sinon/search?q=markdownlint)) * [Sinon.JS][sinon-js] ([Search repository][sinon-js-search])
* [TestCafe](https://devexpress.github.io/testcafe/) ([Search repository](https://github.com/DevExpress/testcafe/search?q=markdownlint)) * [TestCafe][testcafe] ([Search repository][testcafe-search])
* [V8](https://v8.dev/) ([Search repository](https://github.com/v8/v8.dev/search?q=markdownlint)) * [V8][v8] ([Search repository][v8-search])
* [webhint](https://webhint.io/) ([Search repository](https://github.com/webhintio/hint/search?q=markdownlint)) * [webhint][webhint] ([Search repository][webhint-search])
* [webpack](https://webpack.js.org/) ([Search repository](https://github.com/webpack/webpack.js.org/search?q=markdownlint)) * [webpack][webpack] ([Search repository][webpack-search])
* [WordPress](https://wordpress.org/gutenberg/) ([Search repository](https://github.com/WordPress/gutenberg/search?q=markdownlint)) * [WordPress][wordpress] ([Search repository][wordpress-search])
[ally-js]: https://allyjs.io/
[ally-js-search]: https://github.com/medialize/ally.js/search?q=markdownlint
[boostnote]: https://boostnote.io/
[boostnote-search]: https://github.com/BoostIO/Boostnote/search?q=markdownlint
[codimd]: https://github.com/hackmdio/codimd
[codimd-search]: https://github.com/hackmdio/codimd/search?q=markdownlint
[dot-net-doc]: https://docs.microsoft.com/en-us/dotnet/
[dot-net-doc-search]: https://github.com/dotnet/docs/search?q=markdownlint
[eslint]: https://eslint.org/
[eslint-search]: https://github.com/eslint/eslint/search?q=markdownlint
[garden]: https://zendeskgarden.github.io/react-components/
[garden-search]: https://github.com/zendeskgarden/react-components/search?q=markdownlint
[mdn]: https://developer.mozilla.org/
[mdn-search]: https://github.com/mdn/content/search?q=markdownlint
[mkdocs]: https://www.mkdocs.org/
[mkdocs-search]: https://github.com/mkdocs/mkdocs/search?q=markdownlint
[mocha]: https://mochajs.org/
[mocha-search]: https://github.com/mochajs/mocha/search?q=markdownlint
[pi-hole]: https://docs.pi-hole.net
[pi-hole-search]: https://github.com/pi-hole/docs/search?q=markdownlint
[reactable]: https://glittershark.github.io/reactable/
[reactable-search]: https://github.com/glittershark/reactable/search?q=markdownlint
[sinon-js]: https://sinonjs.org/
[sinon-js-search]: https://github.com/sinonjs/sinon/search?q=markdownlint
[testcafe]: https://devexpress.github.io/testcafe/
[testcafe-search]: https://github.com/DevExpress/testcafe/search?q=markdownlint
[v8]: https://v8.dev/
[v8-search]: https://github.com/v8/v8.dev/search?q=markdownlint
[webhint]: https://webhint.io/
[webhint-search]: https://github.com/webhintio/hint/search?q=markdownlint
[webpack]: https://webpack.js.org/
[webpack-search]: https://github.com/webpack/webpack.js.org/search?q=markdownlint
[wordpress]: https://wordpress.org/gutenberg/
[wordpress-search]: https://github.com/WordPress/gutenberg/search?q=markdownlint
## Contributing ## Contributing
@ -937,97 +1024,120 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
* 0.0.2 - Improve documentation, tests, and code. * 0.0.2 - Improve documentation, tests, and code.
* 0.0.3 - Add synchronous API, improve documentation and code. * 0.0.3 - Add synchronous API, improve documentation and code.
* 0.0.4 - Add tests MD033-MD040, update dependencies. * 0.0.4 - Add tests MD033-MD040, update dependencies.
* 0.0.5 - Add `strings` option to enable file-less scenarios, add in-browser demo. * 0.0.5 - Add `strings` option to enable file-less scenarios, add in-browser
demo.
* 0.0.6 - Improve performance, simplify in-browser, update dependencies. * 0.0.6 - Improve performance, simplify in-browser, update dependencies.
* 0.0.7 - Add MD041, improve MD003, ignore front matter, update dependencies. * 0.0.7 - Add MD041, improve MD003, ignore front matter, update dependencies.
* 0.0.8 - Support disabling/enabling rules inline, improve code fence, dependencies. * 0.0.8 - Support disabling/enabling rules inline, improve code fence,
dependencies.
* 0.1.0 - Add aliases, exceptions for MD033, exclusions for MD013, dependencies. * 0.1.0 - Add aliases, exceptions for MD033, exclusions for MD013, dependencies.
* 0.1.1 - Fix bug handling HTML in tables, reference markdownlint-cli. * 0.1.1 - Fix bug handling HTML in tables, reference markdownlint-cli.
* 0.2.0 - Add MD042/MD043, enhance MD002/MD003/MD004/MD007/MD011/MD025/MD041, dependencies. * 0.2.0 - Add MD042/MD043, enhance MD002/MD003/MD004/MD007/MD011/MD025/MD041,
* 0.3.0 - More detailed error reporting with `resultVersion`, enhance MD010/MD012/MD036, dependencies.
fixes for MD027/MD029/MD030, include JSON schema, dependencies. * 0.3.0 - More detailed error reporting with `resultVersion`, enhance
MD010/MD012/MD036, fixes for MD027/MD029/MD030, include JSON schema,
dependencies.
* 0.3.1 - Fix regressions in MD032/MD038, update dependencies. * 0.3.1 - Fix regressions in MD032/MD038, update dependencies.
* 0.4.0 - Add MD044, enhance MD013/MD032/MD041/MD042/MD043, fix for MD038, dependencies. * 0.4.0 - Add MD044, enhance MD013/MD032/MD041/MD042/MD043, fix for MD038,
* 0.4.1 - Fixes for MD038/front matter, improvements to MD044, update dependencies. dependencies.
* 0.5.0 - Add shareable configuration, `noInlineConfig` option, README links, fix MD030, * 0.4.1 - Fixes for MD038/front matter, improvements to MD044, update
improve MD009/MD041, update dependencies. dependencies.
* 0.6.0 - `resultVersion` defaults to 1 (breaking change), ignore HTML comments, TOML * 0.5.0 - Add shareable configuration, `noInlineConfig` option, README links,
front matter, fixes for MD044, update dependencies. fix MD030, improve MD009/MD041, update dependencies.
* 0.6.0 - `resultVersion` defaults to 1 (breaking change), ignore HTML comments,
TOML front matter, fixes for MD044, update dependencies.
* 0.6.1 - Update `markdown-it` versioning, exclude demo/test from publishing. * 0.6.1 - Update `markdown-it` versioning, exclude demo/test from publishing.
* 0.6.2 - Improve MD013/MD027/MD034/MD037/MD038/MD041/MD044, update dependencies. * 0.6.2 - Improve MD013/MD027/MD034/MD037/MD038/MD041/MD044, update
dependencies.
* 0.6.3 - Improve highlighting for MD020. * 0.6.3 - Improve highlighting for MD020.
* 0.6.4 - Improve MD029/MD042, update dependencies. * 0.6.4 - Improve MD029/MD042, update dependencies.
* 0.7.0 - `resultVersion` defaults to 2 (breaking change), add MD045, improve MD029, * 0.7.0 - `resultVersion` defaults to 2 (breaking change), add MD045, improve
remove trimLeft/trimRight, split rules, refactor, update dependencies. MD029, remove trimLeft/trimRight, split rules, refactor, update
* 0.8.0 - Add support for using and authoring custom rules, improve MD004/MD007/MD013, dependencies.
add `engines` to `package.json`, refactor, update dependencies. * 0.8.0 - Add support for using and authoring custom rules, improve
* 0.8.1 - Update item loop to be iterative, improve MD014, update dependencies. MD004/MD007/MD013, add `engines` to `package.json`, refactor, update
* 0.9.0 - Remove support for end-of-life Node versions 0.10/0.12/4, change "header" to dependencies.
"heading" per spec (non-breaking), improve MD003/MD009/MD041, handle uncommon * 0.8.1 - Update item loop to be iterative, improve MD014, update
line-break characters, refactor for ES6, update dependencies. dependencies.
* 0.10.0 - Add support for non-JSON configuration files, pass file/string name to custom * 0.9.0 - Remove support for end-of-life Node versions 0.10/0.12/4, change
rules, update dependencies. "header" to "heading" per spec (non-breaking), improve
* 0.11.0 - Improve MD005/MD024/MD029/MD038, improve custom rule example, add CONTRIBUTING.md, MD003/MD009/MD041, handle uncommon line-break characters, refactor for
update dependencies. ES6, update dependencies.
* 0.12.0 - Add `information` link for custom rules, `markdownItPlugins` for extensibility, * 0.10.0 - Add support for non-JSON configuration files, pass file/string name
improve MD023/MD032/MD038, update dependencies. to custom rules, update dependencies.
* 0.13.0 - Improve MD013/MD022/MD025/MD029/MD031/MD032/MD037/MD041/, deprecate MD002, * 0.11.0 - Improve MD005/MD024/MD029/MD038, improve custom rule example, add
improve pandoc YAML support, update dependencies. CONTRIBUTING.md, update dependencies.
* 0.14.0 - Remove support for end-of-life Node version 6, introduce `markdownlint-rule-helpers`, * 0.12.0 - Add `information` link for custom rules, `markdownItPlugins` for
add MD046/MD047, improve MD033/MD034/MD039, improve custom rule validation and extensibility, improve MD023/MD032/MD038, update dependencies.
in-browser demo, update dependencies. * 0.13.0 - Improve MD013/MD022/MD025/MD029/MD031/MD032/MD037/MD041/, deprecate
MD002, improve pandoc YAML support, update dependencies.
* 0.14.0 - Remove support for end-of-life Node version 6, introduce
`markdownlint-rule-helpers`, add MD046/MD047, improve
MD033/MD034/MD039, improve custom rule validation and in-browser
demo, update dependencies.
* 0.14.1 - Improve MD033. * 0.14.1 - Improve MD033.
* 0.14.2 - Improve MD047, add `handleRuleFailures` option. * 0.14.2 - Improve MD047, add `handleRuleFailures` option.
* 0.15.0 - Add `markdownlint-capture`/`markdownlint-restore` inline comments, improve * 0.15.0 - Add `markdownlint-capture`/`markdownlint-restore` inline comments,
MD009/MD013/MD026/MD033/MD036, update dependencies. improve MD009/MD013/MD026/MD033/MD036, update dependencies.
* 0.16.0 - Add custom rule sample for linting code, improve MD026/MD031/MD033/MD038, * 0.16.0 - Add custom rule sample for linting code, improve
update dependencies. MD026/MD031/MD033/MD038, update dependencies.
* 0.17.0 - Add `resultVersion` 3 to support fix information for default and custom rules, * 0.17.0 - Add `resultVersion` 3 to support fix information for default and
add fix information for 24 rules, update newline handling to match latest custom rules, add fix information for 24 rules, update newline
CommonMark specification, improve MD014/MD037/MD039, update dependencies. handling to match latest CommonMark specification, improve
MD014/MD037/MD039, update dependencies.
* 0.17.1 - Fix handling of front matter by fix information. * 0.17.1 - Fix handling of front matter by fix information.
* 0.17.2 - Improve MD020/MD033/MD044. * 0.17.2 - Improve MD020/MD033/MD044.
* 0.18.0 - Add MD048/code-fence-style, add fix information for MD007/ul-indent, add * 0.18.0 - Add MD048/code-fence-style, add fix information for MD007/ul-indent,
`markdownlint-disable-file`/`markdownlint-enable-file` inline comments, add add `markdownlint-disable-file`/`markdownlint-enable-file` inline
type declaration file (.d.ts) for TypeScript dependents, update schema, improve comments, add type declaration file (.d.ts) for TypeScript
MD006/MD007/MD009/MD013/MD030, update dependencies. dependents, update schema, improve MD006/MD007/MD009/MD013/MD030,
* 0.19.0 - Remove support for end-of-life Node version 8, add fix information for update dependencies.
MD005/list-indent, improve MD007/MD013/MD014, deprecate MD006/ul-start-left, add * 0.19.0 - Remove support for end-of-life Node version 8, add fix information
rationale for every rule, update test runner and code coverage, add more JSDoc for MD005/list-indent, improve MD007/MD013/MD014, deprecate
comments, update dependencies. MD006/ul-start-left, add rationale for every rule, update test runner
and code coverage, add more JSDoc comments, update dependencies.
* 0.20.0 - Add `markdownlint-configure-file` inline comment, reimplement MD037, * 0.20.0 - Add `markdownlint-configure-file` inline comment, reimplement MD037,
improve MD005/MD007/MD013/MD018/MD029/MD031/MD034/MD038/MD039, improve HTML improve MD005/MD007/MD013/MD018/MD029/MD031/MD034/MD038/MD039,
comment handling, update dependencies. improve HTML comment handling, update dependencies.
* 0.20.1 - Fix regression in MD037. * 0.20.1 - Fix regression in MD037.
* 0.20.2 - Fix regression in MD037, improve MD038. * 0.20.2 - Fix regression in MD037, improve MD038.
* 0.20.3 - Fix regression in MD037, improve MD044, add automatic regression testing. * 0.20.3 - Fix regression in MD037, improve MD044, add automatic regression
* 0.20.4 - Fix regression in MD037, improve MD034/MD044, improve documentation. testing.
* 0.21.0 - Lint concurrently for better performance (async only), add Promise-based APIs, * 0.20.4 - Fix regression in MD037, improve MD034/MD044, improve
update TypeScript declaration file, hide `toString` on `LintResults`, add ability documentation.
to fix in browser demo, allow custom rules in `.markdownlint.json` schema, improve * 0.21.0 - Lint concurrently for better performance (async only), add
Promise-based APIs, update TypeScript declaration file, hide
`toString` on `LintResults`, add ability to fix in browser demo,
allow custom rules in `.markdownlint.json` schema, improve
MD042/MD044, improve documentation, update dependencies. MD042/MD044, improve documentation, update dependencies.
* 0.21.1 - Improve MD011/MD031, export `getVersion` API. * 0.21.1 - Improve MD011/MD031, export `getVersion` API.
* 0.22.0 - Allow `extends` in config to reference installed packages by name, add * 0.22.0 - Allow `extends` in config to reference installed packages by name,
`markdownlint-disable-next-line` inline comment, support JSON front matter, improve add `markdownlint-disable-next-line` inline comment, support JSON
MD009/MD026/MD028/MD043, update dependencies (including `markdown-it` to v12). front matter, improve MD009/MD026/MD028/MD043, update dependencies
* 0.23.0 - Add comprehensive example `.markdownlint.jsonc`/`.markdownlint.yaml` files, add fix (including `markdown-it` to v12).
information for MD004/ul-style, improve MD018/MD019/MD020/MD021/MD037/MD041, improve * 0.23.0 - Add comprehensive example `.markdownlint.jsonc`/`.markdownlint.yaml`
HTML comment handling, update test runner and test suite, update dependencies. files, add fix information for MD004/ul-style, improve
* 0.23.1 - Work around lack of webpack support for dynamic calls to `require` (`.resolve`). MD018/MD019/MD020/MD021/MD037/MD041, improve HTML comment handling,
* 0.24.0 - Remove support for end-of-life Node version 10, add support for custom file system update test runner and test suite, update dependencies.
module, improve MD010/MD011/MD037/MD043/MD044, improve TypeScript declaration file * 0.23.1 - Work around lack of webpack support for dynamic calls to
and JSON schema, update dependencies. `require`(`.resolve`).
* 0.25.0 - Add MD049/MD050 for consistent emphasis/strong style (both auto-fixable), improve * 0.24.0 - Remove support for end-of-life Node version 10, add support for
MD007/MD010/MD032/MD033/MD035/MD037/MD039, support asynchronous custom rules, custom file system module, improve MD010/MD011/MD037/MD043/MD044,
improve performance, improve CI process, reduce dependencies, update dependencies. improve TypeScript declaration file and JSON schema, update
dependencies.
* 0.25.0 - Add MD049/MD050 for consistent emphasis/strong style (both
auto-fixable), improve MD007/MD010/MD032/MD033/MD035/MD037/MD039,
support asynchronous custom rules, improve performance, improve CI
process, reduce dependencies, update dependencies.
* 0.25.1 - Update dependencies for CVE-2022-21670. * 0.25.1 - Update dependencies for CVE-2022-21670.
* 0.26.0 - Add MD051/MD052/MD053 for validating link fragments & reference links/images & * 0.26.0 - Add MD051/MD052/MD053 for validating link fragments & reference
link/image reference definitions (MD053 is auto-fixable), improve links/images & link/image reference definitions (MD053 auto-fixable),
MD010/MD031/MD035/MD039/MD042/MD044/MD049/MD050, add `markdownlint-disable-line` improve MD010/MD031/MD035/MD039/MD042/MD044/MD049/MD050, add
inline comment, support `~` paths in `readConfig/Sync`, add `configParsers` option, `markdownlint-disable-line` inline comment, support `~` paths in
remove support for end-of-life Node version 12, default `resultVersion` to 3, update `readConfig/Sync`, add `configParsers` option, remove support for
browser script to use ES2015, simplify JSON schema, address remaining CodeQL issues, end-of-life Node version 12, default `resultVersion` to 3, update
improve performance, update dependencies. browser script to use ES2015, simplify JSON schema, address remaining
CodeQL issues, improve performance, update dependencies.
* 0.26.1 - Improve MD051. * 0.26.1 - Improve MD051.
* 0.26.2 - Improve MD037/MD051/MD053. * 0.26.2 - Improve MD037/MD051/MD053.

3
doc-build/.markdownlint.jsonc
View file

@ -1,3 +1,6 @@
{ {
"extends": "../.markdownlint.json",
// Headings are added by the "build-docs" script (build-rules.mjs)
"first-line-heading": false "first-line-heading": false
} }

55
doc-build/build-rules.mjs
View file

@ -4,10 +4,26 @@ import { default as rules } from "../lib/rules.js";
import { newLineRe } from "../helpers/helpers.js"; import { newLineRe } from "../helpers/helpers.js";
import { deprecatedRuleNames, fixableRuleNames } from "../lib/constants.js"; import { deprecatedRuleNames, fixableRuleNames } from "../lib/constants.js";
const maxLineLength = 80;
const pathFor = (relativePath) => new URL(relativePath, import.meta.url); const pathFor = (relativePath) => new URL(relativePath, import.meta.url);
const inCode = (items) => items.map((item) => `\`${item}\``); const inCode = (items) => items.map((item) => `\`${item}\``);
const sortedComma = (items) => items.sort().join(", "); const sortedComma = (items) => items.sort().join(", ");
const linesFrom = (text) => text.split(newLineRe); const linesFrom = (text) => text.split(newLineRe);
const wrapListItem = (line) => {
const wrappedLines = [];
let remainingLine = line;
while (remainingLine.length > maxLineLength) {
let index = maxLineLength - 1;
while (remainingLine[index] !== " ") {
index--;
}
wrappedLines.push(remainingLine.slice(0, index + 1).trimEnd());
remainingLine = " " + remainingLine.slice(index + 1).trimStart();
}
wrappedLines.push(remainingLine);
return wrappedLines;
};
// import { default as schema } from "file.json" assert { type: "json" }; // import { default as schema } from "file.json" assert { type: "json" };
const importJson = const importJson =
@ -48,24 +64,27 @@ for (const rule of rules) {
if (ruleData.properties) { if (ruleData.properties) {
section.push( section.push(
"Parameters:", "Parameters:",
"", ""
...Object.keys(ruleData.properties).sort().map((property) => { );
const propData = ruleData.properties[property]; for (const property of Object.keys(ruleData.properties).sort()) {
const propType = (propData.type === "array") ? const propData = ruleData.properties[property];
`${propData.items.type}[]` : const propType = (propData.type === "array") ?
propData.type; `${propData.items.type}[]` :
const defaultValue = Array.isArray(propData.default) ? propData.type;
JSON.stringify(propData.default) : const defaultValue = Array.isArray(propData.default) ?
propData.default; JSON.stringify(propData.default) :
const allValues = propData.enum?.sort(); propData.default;
return `* \`${property}\`: ${propData.description} (` + const allValues = propData.enum?.sort();
`\`${propType}\`, default \`${defaultValue}\`` + const listItem = `* \`${property}\`: ${propData.description} (` +
(propData.enum ? `\`${propType}\`, default \`${defaultValue}\`` +
`, values ${allValues.map((value) => `\`${value}\``).join("/")}` : (propData.enum ?
"" `, values ${allValues.map((value) => `\`${value}\``).join(" / ")}` :
) + ""
")"; ) +
}), ")";
section.push(...wrapListItem(listItem));
}
section.push(
"" ""
); );
} }

10
doc-build/md004.md
View file

@ -16,13 +16,13 @@ document:
* Item 3 * Item 3
``` ```
The configured list style can be a specific symbol to use (asterisk, plus, dash), The configured list style can be a specific symbol to use (asterisk, plus,
to ensure that all list styling is consistent, or to ensure that each dash), to ensure that all list styling is consistent, or to ensure that each
sublist has a consistent symbol that differs from its parent list. sublist has a consistent symbol that differs from its parent list.
For example, the following is valid for the `sublist` style because the outer-most For example, the following is valid for the `sublist` style because the
indent uses asterisk, the middle indent uses plus, and the inner-most indent uses outer-most indent uses asterisk, the middle indent uses plus, and the inner-most
dash: indent uses dash:
```markdown ```markdown
* Item 1 * Item 1

15
doc-build/md007.md
View file

@ -21,16 +21,19 @@ rule).
The `start_indented` parameter allows the first level of lists to be indented by The `start_indented` parameter allows the first level of lists to be indented by
the configured number of spaces rather than starting at zero (the inverse of the configured number of spaces rather than starting at zero (the inverse of
MD006). The `start_indent` parameter allows the first level of lists to be indented MD006). The `start_indent` parameter allows the first level of lists to be
by a different number of spaces than the rest (ignored when `start_indented` is not indented by a different number of spaces than the rest (ignored when
set). `start_indented` is not set).
Rationale: Indenting by 2 spaces allows the content of a nested list to be in Rationale: Indenting by 2 spaces allows the content of a nested list to be in
line with the start of the content of the parent list when a single space is line with the start of the content of the parent list when a single space is
used after the list marker. Indenting by 4 spaces is consistent with code blocks used after the list marker. Indenting by 4 spaces is consistent with code blocks
and simpler for editors to implement. Additionally, this can be a compatibility and simpler for editors to implement. Additionally, this can be a compatibility
issue for other Markdown parsers, which require 4-space indents. More information: issue for other Markdown parsers, which require 4-space indents. More
<https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists> information: [Markdown Style Guide][markdown-style-guide] and [Marked app\
and <http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting>. support][marked-app-support].
Note: See [Prettier.md](Prettier.md) for compatibility information. Note: See [Prettier.md](Prettier.md) for compatibility information.
[markdown-style-guide]: https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists
[marked-app-support]: http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting

16
doc-build/md009.md
View file

@ -1,5 +1,5 @@
This rule is triggered on any lines that end with unexpected whitespace. To fix this, This rule is triggered on any lines that end with unexpected whitespace. To fix
remove the trailing space from the end of the line. this, remove the trailing space from the end of the line.
Note: Trailing space is allowed in indented and fenced code blocks because some Note: Trailing space is allowed in indented and fenced code blocks because some
languages require it. languages require it.
@ -8,12 +8,14 @@ The `br_spaces` parameter allows an exception to this rule for a specific number
of trailing spaces, typically used to insert an explicit line break. The default of trailing spaces, typically used to insert an explicit line break. The default
value allows 2 spaces to indicate a hard break (\<br> element). value allows 2 spaces to indicate a hard break (\<br> element).
Note: You must set `br_spaces` to a value >= 2 for this parameter to take effect. Note: You must set `br_spaces` to a value >= 2 for this parameter to take
Setting `br_spaces` to 1 behaves the same as 0, disallowing any trailing spaces. effect. Setting `br_spaces` to 1 behaves the same as 0, disallowing any trailing
spaces.
By default, this rule will not trigger when the allowed number of spaces is used, By default, this rule will not trigger when the allowed number of spaces is
even when it doesn't create a hard break (for example, at the end of a paragraph). used, even when it doesn't create a hard break (for example, at the end of a
To report such instances as well, set the `strict` parameter to `true`. paragraph). To report such instances as well, set the `strict` parameter to
`true`.
```markdown ```markdown
Text text text Text text text

10
doc-build/md022.md
View file

@ -22,12 +22,12 @@ Some more text
## Heading 2 ## Heading 2
``` ```
The `lines_above` and `lines_below` parameters can be used to specify a different The `lines_above` and `lines_below` parameters can be used to specify a
number of blank lines (including 0) above or below each heading. different number of blank lines (including 0) above or below each heading.
Note: If `lines_above` or `lines_below` are configured to require more than one Note: If `lines_above` or `lines_below` are configured to require more than one
blank line, [MD012/no-multiple-blanks](md012.md) should also be customized. blank line, [MD012/no-multiple-blanks](md012.md) should also be customized.
Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`, will Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`,
not parse headings that don't have a blank line before, and will parse them as will not parse headings that don't have a blank line before, and will parse them
regular text. as regular text.

17
doc-build/md025.md
View file

@ -23,14 +23,15 @@ lower-level headings (h2, h3, etc.):
Note: The `level` parameter can be used to change the top-level (ex: to h2) in Note: The `level` parameter can be used to change the top-level (ex: to h2) in
cases where an h1 is added externally. cases where an h1 is added externally.
If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and contains If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
a `title` property (commonly used with blog posts), this rule treats that as a top contains a `title` property (commonly used with blog posts), this rule treats
level heading and will report a violation for any subsequent top-level headings. that as a top level heading and will report a violation for any subsequent
To use a different property name in the front matter, specify the text of a regular top-level headings. To use a different property name in the front matter,
expression via the `front_matter_title` parameter. To disable the use of front specify the text of a regular expression via the `front_matter_title` parameter.
matter by this rule, specify `""` for `front_matter_title`. To disable the use of front matter by this rule, specify `""` for
`front_matter_title`.
Rationale: A top-level heading is an h1 on the first line of the file, and Rationale: A top-level heading is an h1 on the first line of the file, and
serves as the title for the document. If this convention is in use, then there serves as the title for the document. If this convention is in use, then there
can not be more than one title for the document, and the entire document can not be more than one title for the document, and the entire document should
should be contained within this heading. be contained within this heading.

14
doc-build/md026.md
View file

@ -14,13 +14,15 @@ To fix this, remove the trailing punctuation:
Note: The `punctuation` parameter can be used to specify what characters count Note: The `punctuation` parameter can be used to specify what characters count
as punctuation at the end of a heading. For example, you can change it to as punctuation at the end of a heading. For example, you can change it to
`".,;:"` to allow headings that end with an exclamation point. `?` is `".,;:"` to allow headings that end with an exclamation point. `?` is
allowed by default because of how common it is in headings of FAQ-style documents. allowed by default because of how common it is in headings of FAQ-style
Setting the `punctuation` parameter to `""` allows all characters - and is documents. Setting the `punctuation` parameter to `""` allows all characters -
equivalent to disabling the rule. and is equivalent to disabling the rule.
Note: The trailing semicolon of Note: The trailing semicolon of [HTML entity references][html-entity-references]
[HTML entity references](https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references)
like `&copy;`, `&#169;`, and `&#x000A9;` is ignored by this rule. like `&copy;`, `&#169;`, and `&#x000A9;` is ignored by this rule.
Rationale: Headings are not meant to be full sentences. More information: Rationale: Headings are not meant to be full sentences. More information:
<https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers> [Punctuation at the end of headers][end-punctuation].
[end-punctuation]: https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers
[html-entity-references]: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

4
doc-build/md038.md
View file

@ -20,8 +20,8 @@ automatically trimmed (to allow for embedded backticks):
`` `backticks` `` `` `backticks` ``
``` ```
Note: A single leading or trailing space is allowed if used to separate code span Note: A single leading or trailing space is allowed if used to separate code
markers from an embedded backtick: span markers from an embedded backtick:
```markdown ```markdown
`` ` embedded backtick`` `` ` embedded backtick``

7
doc-build/md041.md
View file

@ -23,14 +23,15 @@ permitted by this rule. For example:
This is a file with a top-level HTML heading This is a file with a top-level HTML heading
``` ```
Note: The `level` parameter can be used to change the top-level (ex: to h2) in cases Note: The `level` parameter can be used to change the top-level (ex: to h2) in
where an h1 is added externally. cases where an h1 is added externally.
If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
contains a `title` property (commonly used with blog posts), this rule will not contains a `title` property (commonly used with blog posts), this rule will not
report a violation. To use a different property name in the front matter, report a violation. To use a different property name in the front matter,
specify the text of a regular expression via the `front_matter_title` parameter. specify the text of a regular expression via the `front_matter_title` parameter.
To disable the use of front matter by this rule, specify `""` for `front_matter_title`. To disable the use of front matter by this rule, specify `""` for
`front_matter_title`.
Rationale: The top-level heading often acts as the title of a document. More Rationale: The top-level heading often acts as the title of a document. More
information: <https://cirosantilli.com/markdown-style-guide#top-level-header>. information: <https://cirosantilli.com/markdown-style-guide#top-level-header>.

3
doc-build/md042.md
View file

@ -22,4 +22,5 @@ But non-empty fragments will not:
[a valid fragment](#fragment) [a valid fragment](#fragment)
``` ```
Rationale: Empty links do not lead anywhere and therefore don't function as links. Rationale: Empty links do not lead anywhere and therefore don't function as
links.

10
doc-build/md043.md
View file

@ -49,12 +49,12 @@ special value `"+"` meaning "one or more unspecified headings" and set the
When an error is detected, this rule outputs the line number of the first When an error is detected, this rule outputs the line number of the first
problematic heading (otherwise, it outputs the last line number of the file). problematic heading (otherwise, it outputs the last line number of the file).
Note that while the `headings` parameter uses the "## Text" ATX heading style for Note that while the `headings` parameter uses the "## Text" ATX heading style
simplicity, a file may use any supported heading style. for simplicity, a file may use any supported heading style.
By default, the case of headings in the document is not required to match that of By default, the case of headings in the document is not required to match that
`headings`. To require that case match exactly, set the `match_case` parameter to of `headings`. To require that case match exactly, set the `match_case`
`true`. parameter to `true`.
Rationale: Projects may wish to enforce a consistent document structure across Rationale: Projects may wish to enforce a consistent document structure across
a set of similar content. a set of similar content.

5
doc-build/md044.md
View file

@ -3,8 +3,9 @@ the specified capitalization. It can be used to enforce a standard letter case
for the names of projects and products. for the names of projects and products.
For example, the language "JavaScript" is usually written with both the 'J' and For example, the language "JavaScript" is usually written with both the 'J' and
'S' capitalized - though sometimes the 's' or 'j' appear in lower-case. To enforce 'S' capitalized - though sometimes the 's' or 'j' appear in lower-case. To
the proper capitalization, specify the desired letter case in the `names` array: enforce the proper capitalization, specify the desired letter case in the
`names` array:
```json ```json
[ [

12
doc-build/md045.md
View file

@ -1,4 +1,5 @@
This rule is triggered when an image is missing alternate text (alt text) information. This rule is triggered when an image is missing alternate text (alt text)
information.
Alternate text is commonly specified inline as: Alternate text is commonly specified inline as:
@ -16,9 +17,12 @@ Or with reference syntax as:
[ref]: image.jpg "Optional title" [ref]: image.jpg "Optional title"
``` ```
Guidance for writing alternate text is available from the [W3C](https://www.w3.org/WAI/alt/), Guidance for writing alternate text is available from the [W3C][w3c],
[Wikipedia](https://en.wikipedia.org/wiki/Alt_attribute), and [Wikipedia][wikipedia], and [other locations][phase2technology].
[other locations](https://www.phase2technology.com/blog/no-more-excuses).
Rationale: Alternate text is important for accessibility and describes the Rationale: Alternate text is important for accessibility and describes the
content of an image for people who may not be able to see it. content of an image for people who may not be able to see it.
[phase2technology]: https://www.phase2technology.com/blog/no-more-excuses
[w3c]: https://www.w3.org/WAI/alt/
[wikipedia]: https://en.wikipedia.org/wiki/Alt_attribute

3
doc-build/md046.md
View file

@ -1,7 +1,8 @@
This rule is triggered when unwanted or different code block styles are used in This rule is triggered when unwanted or different code block styles are used in
the same document. the same document.
In the default configuration this rule reports a violation for the following document: In the default configuration this rule reports a violation for the following
document:
<!-- markdownlint-disable code-block-style --> <!-- markdownlint-disable code-block-style -->

6
doc-build/md047.md
View file

@ -19,4 +19,8 @@ This file ends with a newline.
``` ```
Rationale: Some programs have trouble with files that do not end with a newline. Rationale: Some programs have trouble with files that do not end with a newline.
More information: <https://unix.stackexchange.com/questions/18743/whats-the-point-in-adding-a-new-line-to-the-end-of-a-file>.
More information: [What's the point in adding a new line to the end of a
file?][stack-exchange]
[stack-exchange]: https://unix.stackexchange.com/questions/18743/whats-the-point-in-adding-a-new-line-to-the-end-of-a-file

14
doc-build/md051.md
View file

@ -27,16 +27,16 @@ define a fragment:
An `a` tag can be useful in scenarios where a heading is not appropriate or for An `a` tag can be useful in scenarios where a heading is not appropriate or for
control over the text of the fragment identifier. control over the text of the fragment identifier.
Rationale: [GitHub section links][github-section-links] are created automatically Rationale: [GitHub section links][github-section-links] are created
for every heading when Markdown content is displayed on GitHub. This makes it automatically for every heading when Markdown content is displayed on GitHub.
easy to link directly to different sections within a document. However, section This makes it easy to link directly to different sections within a document.
links change if headings are renamed or removed. This rule helps identify broken However, section links change if headings are renamed or removed. This rule
section links within a document. helps identify broken section links within a document.
Section links are **not** part of the CommonMark specification. This rule Section links are **not** part of the CommonMark specification. This rule
enforces the [GitHub heading algorithm][github-heading-algorithm] which is: enforces the [GitHub heading algorithm][github-heading-algorithm] which is:
convert heading to lowercase, remove punctuation, convert spaces to dashes, append convert heading to lowercase, remove punctuation, convert spaces to dashes,
an incrementing integer as needed for uniqueness. append an incrementing integer as needed for uniqueness.
[github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links [github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
[github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/main/lib/html/pipeline/toc_filter.rb [github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/main/lib/html/pipeline/toc_filter.rb

138
doc/CustomRules.md
View file

@ -1,16 +1,18 @@
# Custom Rules # Custom Rules
In addition to its built-in rules, `markdownlint` lets you enhance the linting experience by passing a list of custom rules using the In addition to its built-in rules, `markdownlint` lets you enhance the linting
[`options.customRules` property](../README.md#optionscustomrules). experience by passing a list of custom rules using the [`options.customRules`
Custom rules can do everything the built-in rules can and are defined inline or imported from another package property][options-custom-rules]. Custom rules can do everything the built-in
([keyword `markdownlint-rule` on npm](https://www.npmjs.com/search?q=keywords:markdownlint-rule)). rules can and are defined inline or imported from another package ([keyword
Custom rules can be disabled, enabled, and customized using the same syntax as built-in rules. `markdownlint-rule` on npm][markdownlint-rule]). Custom rules can be disabled,
enabled, and customized using the same syntax as built-in rules.
## Authoring ## Authoring
Rules are defined by a name (or multiple names), a description, an optional link to more information, one or more tags, and a function that implements Rules are defined by a name (or multiple names), a description, an optional link
the rule's behavior. to more information, one or more tags, and a function that implements the rule's
That function is called once for each file/string input and is passed the parsed input and a function to log any violations. behavior. That function is called once for each file/string input and is passed
the parsed input and a function to log any violations.
A simple rule implementation looks like: A simple rule implementation looks like:
@ -35,62 +37,87 @@ module.exports = {
}; };
``` ```
A rule is implemented as an `Object` with one optional and four required properties: A rule is implemented as an `Object` with one optional and four required
properties:
- `names` is a required `Array` of `String` values that identify the rule in output messages and config. - `names` is a required `Array` of `String` values that identify the rule in
- `description` is a required `String` value that describes the rule in output messages. output messages and config.
- `information` is an optional (absolute) `URL` of a link to more information about the rule. - `description` is a required `String` value that describes the rule in output
- `tags` is a required `Array` of `String` values that groups related rules for easier customization. messages.
- `asynchronous` is an optional `Boolean` value that indicates whether the rule returns a `Promise` and runs asynchronously. - `information` is an optional (absolute) `URL` of a link to more information
- `function` is a required `Function` that implements the rule and is passed two parameters: about the rule.
- `params` is an `Object` with properties that describe the content being analyzed: - `tags` is a required `Array` of `String` values that groups related rules for
easier customization.
- `asynchronous` is an optional `Boolean` value that indicates whether the rule
returns a `Promise` and runs asynchronously.
- `function` is a required `Function` that implements the rule and is passed two
parameters:
- `params` is an `Object` with properties that describe the content being
analyzed:
- `name` is a `String` that identifies the input file/string. - `name` is a `String` that identifies the input file/string.
- `tokens` is an `Array` of [`markdown-it` `Token` objects](https://markdown-it.github.io/markdown-it/#Token) - `tokens` is an `Array` of [`markdown-it` `Token`s][markdown-it-token] with
with added `line` and `lineNumber` properties. added `line` and `lineNumber` properties.
- `lines` is an `Array` of `String` values corresponding to the lines of the input file/string. - `lines` is an `Array` of `String` values corresponding to the lines of the
- `frontMatterLines` is an `Array` of `String` values corresponding to any front matter (not present in `lines`). input file/string.
- `config` is an `Object` corresponding to the rule's entry in `options.config` (if present). - `frontMatterLines` is an `Array` of `String` values corresponding to any
- `onError` is a function that takes a single `Object` parameter with one required and four optional properties: front matter (not present in `lines`).
- `lineNumber` is a required `Number` specifying the 1-based line number of the error. - `config` is an `Object` corresponding to the rule's entry in
- `detail` is an optional `String` with information about what caused the error. `options.config` (if present).
- `context` is an optional `String` with relevant text surrounding the error location. - `onError` is a function that takes a single `Object` parameter with one
- `range` is an optional `Array` with two `Number` values identifying the 1-based column and length of the error. required and four optional properties:
- `fixInfo` is an optional `Object` with information about how to fix the error (all properties are optional, but - `lineNumber` is a required `Number` specifying the 1-based line number of
at least one of `deleteCount` and `insertText` should be present; when applying a fix, the delete should be the error.
- `detail` is an optional `String` with information about what caused the
error.
- `context` is an optional `String` with relevant text surrounding the error
location.
- `range` is an optional `Array` with two `Number` values identifying the
1-based column and length of the error.
- `fixInfo` is an optional `Object` with information about how to fix the
error (all properties are optional, but at least one of `deleteCount` and
`insertText` should be present; when applying a fix, the delete should be
performed before the insert): performed before the insert):
- `lineNumber` is an optional `Number` specifying the 1-based line number of the edit. - `lineNumber` is an optional `Number` specifying the 1-based line number
- `editColumn` is an optional `Number` specifying the 1-based column number of the edit. of the edit.
- `deleteCount` is an optional `Number` specifying the number of characters to delete (the value `-1` is used to delete the line). - `editColumn` is an optional `Number` specifying the 1-based column
- `insertText` is an optional `String` specifying the text to insert. `\n` is the platform-independent way to add number of the edit.
a line break; line breaks should be added at the beginning of a line instead of at the end). - `deleteCount` is an optional `Number` specifying the number of
characters to delete (the value `-1` is used to delete the line).
- `insertText` is an optional `String` specifying the text to insert. `\n`
is the platform-independent way to add a line break; line breaks should
be added at the beginning of a line instead of at the end).
The collection of helper functions shared by the built-in rules is available for use by custom rules in the The collection of helper functions shared by the built-in rules is available for
[markdownlint-rule-helpers package](https://www.npmjs.com/package/markdownlint-rule-helpers). use by custom rules in the [markdownlint-rule-helpers package][rule-helpers].
### Asynchronous Rules ### Asynchronous Rules
If a rule needs to perform asynchronous operations (such as fetching a network resource), it can specify the value `true` for its `asynchronous` property. If a rule needs to perform asynchronous operations (such as fetching a network
Asynchronous rules should return a `Promise` from their `function` implementation that is resolved when the rule completes. resource), it can specify the value `true` for its `asynchronous` property.
(The value passed to `resolve(...)` is ignored.) Asynchronous rules should return a `Promise` from their `function`
Linting violations from asynchronous rules are reported via the `onError` function just like for synchronous rules. implementation that is resolved when the rule completes. (The value passed to
`resolve(...)` is ignored.) Linting violations from asynchronous rules are
reported via the `onError` function just like for synchronous rules.
**Note**: Asynchronous rules cannot be referenced in a synchronous calling context (i.e., `markdownlint.sync(...)`). **Note**: Asynchronous rules cannot be referenced in a synchronous calling
Attempting to do so throws an exception. context (i.e., `markdownlint.sync(...)`). Attempting to do so throws an
exception.
## Examples ## Examples
- [Simple rules used by the project's test cases](../test/rules) - [Simple rules used by the project's test cases][test-rules]
- [Code for all `markdownlint` built-in rules](../lib) - [Code for all `markdownlint` built-in rules][lib]
- [Package configuration for publishing to npm](../test/rules/npm) - [Package configuration for publishing to npm][test-rules-npm]
- Packages should export a single rule object or an `Array` of rule objects - Packages should export a single rule object or an `Array` of rule objects
- [Custom rules from the Microsoft/vscode-docs-authoring repository](https://github.com/microsoft/vscode-docs-authoring/tree/main/packages/docs-linting/markdownlint-custom-rules) - [Custom rules from the Microsoft/vscode-docs-authoring
- [Custom rules from the axibase/docs-util repository](https://github.com/axibase/docs-util/tree/master/linting-rules) repository][vscode-docs-authoring]
- [Custom rules from the webhintio/hint repository](https://github.com/webhintio/hint/blob/main/scripts/lint-markdown.js) - [Custom rules from the axibase/docs-util repository][docs-util]
- [Custom rules from the webhintio/hint repository][hint]
## References ## References
- [CommonMark documentation and specification](https://commonmark.org/) - [CommonMark documentation and specification][commonmark]
- [`markdown-it` Markdown parser project page](https://github.com/markdown-it/markdown-it) - [`markdown-it` Markdown parser project page][markdown-it]
## Params ## Params
@ -324,3 +351,16 @@ Yields the `params` object:
} }
} }
``` ```
[commonmark]: https://commonmark.org/
[docs-util]: https://github.com/axibase/docs-util/tree/master/linting-rules
[hint]: https://github.com/webhintio/hint/blob/main/scripts/lint-markdown.js
[lib]: ../lib
[markdown-it]: https://github.com/markdown-it/markdown-it
[markdown-it-token]: https://markdown-it.github.io/markdown-it/#Token
[markdownlint-rule]: https://www.npmjs.com/search?q=keywords:markdownlint-rule
[rule-helpers]: https://www.npmjs.com/package/markdownlint-rule-helpers
[options-custom-rules]: ../README.md#optionscustomrules
[test-rules]: ../test/rules
[test-rules-npm]: ../test/rules/npm
[vscode-docs-authoring]: https://github.com/microsoft/vscode-docs-authoring/tree/main/packages/docs-linting/markdownlint-custom-rules

207
doc/Rules.md
View file

@ -95,7 +95,9 @@ Aliases: `header-style`, `heading-style`
Parameters: Parameters:
* `style`: Heading style (`string`, default `consistent`, values `atx`/`atx_closed`/`consistent`/`setext`/`setext_with_atx`/`setext_with_atx_closed`) * `style`: Heading style (`string`, default `consistent`, values `atx` /
`atx_closed` / `consistent` / `setext` / `setext_with_atx` /
`setext_with_atx_closed`)
This rule is triggered when different heading styles (atx, setext, and 'closed' This rule is triggered when different heading styles (atx, setext, and 'closed'
atx) are used in the same document: atx) are used in the same document:
@ -146,7 +148,8 @@ Aliases: `ul-style`
Parameters: Parameters:
* `style`: List style (`string`, default `consistent`, values `asterisk`/`consistent`/`dash`/`plus`/`sublist`) * `style`: List style (`string`, default `consistent`, values `asterisk` /
`consistent` / `dash` / `plus` / `sublist`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling
@ -168,13 +171,13 @@ document:
* Item 3 * Item 3
``` ```
The configured list style can be a specific symbol to use (asterisk, plus, dash), The configured list style can be a specific symbol to use (asterisk, plus,
to ensure that all list styling is consistent, or to ensure that each dash), to ensure that all list styling is consistent, or to ensure that each
sublist has a consistent symbol that differs from its parent list. sublist has a consistent symbol that differs from its parent list.
For example, the following is valid for the `sublist` style because the outer-most For example, the following is valid for the `sublist` style because the
indent uses asterisk, the middle indent uses plus, and the inner-most indent uses outer-most indent uses asterisk, the middle indent uses plus, and the inner-most
dash: indent uses dash:
```markdown ```markdown
* Item 1 * Item 1
@ -303,8 +306,10 @@ Aliases: `ul-indent`
Parameters: Parameters:
* `indent`: Spaces for indent (`integer`, default `2`) * `indent`: Spaces for indent (`integer`, default `2`)
* `start_indent`: Spaces for first level indent (when start_indented is set) (`integer`, default `2`) * `start_indent`: Spaces for first level indent (when start_indented is set)
* `start_indented`: Whether to indent the first level of the list (`boolean`, default `false`) (`integer`, default `2`)
* `start_indented`: Whether to indent the first level of the list (`boolean`,
default `false`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling
@ -331,20 +336,23 @@ rule).
The `start_indented` parameter allows the first level of lists to be indented by The `start_indented` parameter allows the first level of lists to be indented by
the configured number of spaces rather than starting at zero (the inverse of the configured number of spaces rather than starting at zero (the inverse of
MD006). The `start_indent` parameter allows the first level of lists to be indented MD006). The `start_indent` parameter allows the first level of lists to be
by a different number of spaces than the rest (ignored when `start_indented` is not indented by a different number of spaces than the rest (ignored when
set). `start_indented` is not set).
Rationale: Indenting by 2 spaces allows the content of a nested list to be in Rationale: Indenting by 2 spaces allows the content of a nested list to be in
line with the start of the content of the parent list when a single space is line with the start of the content of the parent list when a single space is
used after the list marker. Indenting by 4 spaces is consistent with code blocks used after the list marker. Indenting by 4 spaces is consistent with code blocks
and simpler for editors to implement. Additionally, this can be a compatibility and simpler for editors to implement. Additionally, this can be a compatibility
issue for other Markdown parsers, which require 4-space indents. More information: issue for other Markdown parsers, which require 4-space indents. More
<https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists> information: [Markdown Style Guide][markdown-style-guide] and [Marked app\
and <http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting>. support][marked-app-support].
Note: See [Prettier.md](Prettier.md) for compatibility information. Note: See [Prettier.md](Prettier.md) for compatibility information.
[markdown-style-guide]: https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists
[marked-app-support]: http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting
<a name="md009"></a> <a name="md009"></a>
## `MD009` - Trailing spaces ## `MD009` - Trailing spaces
@ -356,13 +364,14 @@ Aliases: `no-trailing-spaces`
Parameters: Parameters:
* `br_spaces`: Spaces for line break (`integer`, default `2`) * `br_spaces`: Spaces for line break (`integer`, default `2`)
* `list_item_empty_lines`: Allow spaces for empty lines in list items (`boolean`, default `false`) * `list_item_empty_lines`: Allow spaces for empty lines in list items
(`boolean`, default `false`)
* `strict`: Include unnecessary breaks (`boolean`, default `false`) * `strict`: Include unnecessary breaks (`boolean`, default `false`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling
This rule is triggered on any lines that end with unexpected whitespace. To fix this, This rule is triggered on any lines that end with unexpected whitespace. To fix
remove the trailing space from the end of the line. this, remove the trailing space from the end of the line.
Note: Trailing space is allowed in indented and fenced code blocks because some Note: Trailing space is allowed in indented and fenced code blocks because some
languages require it. languages require it.
@ -371,12 +380,14 @@ The `br_spaces` parameter allows an exception to this rule for a specific number
of trailing spaces, typically used to insert an explicit line break. The default of trailing spaces, typically used to insert an explicit line break. The default
value allows 2 spaces to indicate a hard break (\<br> element). value allows 2 spaces to indicate a hard break (\<br> element).
Note: You must set `br_spaces` to a value >= 2 for this parameter to take effect. Note: You must set `br_spaces` to a value >= 2 for this parameter to take
Setting `br_spaces` to 1 behaves the same as 0, disallowing any trailing spaces. effect. Setting `br_spaces` to 1 behaves the same as 0, disallowing any trailing
spaces.
By default, this rule will not trigger when the allowed number of spaces is used, By default, this rule will not trigger when the allowed number of spaces is
even when it doesn't create a hard break (for example, at the end of a paragraph). used, even when it doesn't create a hard break (for example, at the end of a
To report such instances as well, set the `strict` parameter to `true`. paragraph). To report such instances as well, set the `strict` parameter to
`true`.
```markdown ```markdown
Text text text Text text text
@ -407,7 +418,8 @@ Aliases: `no-hard-tabs`
Parameters: Parameters:
* `code_blocks`: Include code blocks (`boolean`, default `true`) * `code_blocks`: Include code blocks (`boolean`, default `true`)
* `ignore_code_languages`: Fenced code languages to ignore (`string[]`, default `[]`) * `ignore_code_languages`: Fenced code languages to ignore (`string[]`, default
`[]`)
* `spaces_per_tab`: Number of spaces for each hard tab (`integer`, default `1`) * `spaces_per_tab`: Number of spaces for each hard tab (`integer`, default `1`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling
@ -538,10 +550,12 @@ Aliases: `line-length`
Parameters: Parameters:
* `code_block_line_length`: Number of characters for code blocks (`integer`, default `80`) * `code_block_line_length`: Number of characters for code blocks (`integer`,
default `80`)
* `code_blocks`: Include code blocks (`boolean`, default `true`) * `code_blocks`: Include code blocks (`boolean`, default `true`)
* `headers`: Include headings (`boolean`, default `true`) * `headers`: Include headings (`boolean`, default `true`)
* `heading_line_length`: Number of characters for headings (`integer`, default `80`) * `heading_line_length`: Number of characters for headings (`integer`, default
`80`)
* `headings`: Include headings (`boolean`, default `true`) * `headings`: Include headings (`boolean`, default `true`)
* `line_length`: Number of characters (`integer`, default `80`) * `line_length`: Number of characters (`integer`, default `80`)
* `stern`: Stern length checking (`boolean`, default `false`) * `stern`: Stern length checking (`boolean`, default `false`)
@ -812,15 +826,15 @@ Some more text
## Heading 2 ## Heading 2
``` ```
The `lines_above` and `lines_below` parameters can be used to specify a different The `lines_above` and `lines_below` parameters can be used to specify a
number of blank lines (including 0) above or below each heading. different number of blank lines (including 0) above or below each heading.
Note: If `lines_above` or `lines_below` are configured to require more than one Note: If `lines_above` or `lines_below` are configured to require more than one
blank line, [MD012/no-multiple-blanks](md012.md) should also be customized. blank line, [MD012/no-multiple-blanks](md012.md) should also be customized.
Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`, will Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`,
not parse headings that don't have a blank line before, and will parse them as will not parse headings that don't have a blank line before, and will parse them
regular text. as regular text.
<a name="md023"></a> <a name="md023"></a>
@ -861,7 +875,8 @@ Aliases: `no-duplicate-header`, `no-duplicate-heading`
Parameters: Parameters:
* `allow_different_nesting`: Only check sibling headings (`boolean`, default `false`) * `allow_different_nesting`: Only check sibling headings (`boolean`, default
`false`)
* `siblings_only`: Only check sibling headings (`boolean`, default `false`) * `siblings_only`: Only check sibling headings (`boolean`, default `false`)
This rule is triggered if there are multiple headings in the document that have This rule is triggered if there are multiple headings in the document that have
@ -910,7 +925,8 @@ Aliases: `single-h1`, `single-title`
Parameters: Parameters:
* `front_matter_title`: RegExp for matching title in front matter (`string`, default `^\s*title\s*[:=]`) * `front_matter_title`: RegExp for matching title in front matter (`string`,
default `^\s*title\s*[:=]`)
* `level`: Heading level (`integer`, default `1`) * `level`: Heading level (`integer`, default `1`)
This rule is triggered when a top-level heading is in use (the first line of This rule is triggered when a top-level heading is in use (the first line of
@ -938,17 +954,18 @@ lower-level headings (h2, h3, etc.):
Note: The `level` parameter can be used to change the top-level (ex: to h2) in Note: The `level` parameter can be used to change the top-level (ex: to h2) in
cases where an h1 is added externally. cases where an h1 is added externally.
If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and contains If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
a `title` property (commonly used with blog posts), this rule treats that as a top contains a `title` property (commonly used with blog posts), this rule treats
level heading and will report a violation for any subsequent top-level headings. that as a top level heading and will report a violation for any subsequent
To use a different property name in the front matter, specify the text of a regular top-level headings. To use a different property name in the front matter,
expression via the `front_matter_title` parameter. To disable the use of front specify the text of a regular expression via the `front_matter_title` parameter.
matter by this rule, specify `""` for `front_matter_title`. To disable the use of front matter by this rule, specify `""` for
`front_matter_title`.
Rationale: A top-level heading is an h1 on the first line of the file, and Rationale: A top-level heading is an h1 on the first line of the file, and
serves as the title for the document. If this convention is in use, then there serves as the title for the document. If this convention is in use, then there
can not be more than one title for the document, and the entire document can not be more than one title for the document, and the entire document should
should be contained within this heading. be contained within this heading.
<a name="md026"></a> <a name="md026"></a>
@ -960,7 +977,8 @@ Aliases: `no-trailing-punctuation`
Parameters: Parameters:
* `punctuation`: Punctuation characters not allowed at end of headings (`string`, default `.,;:!。，；：！`) * `punctuation`: Punctuation characters not allowed at end of headings
(`string`, default `.,;:!。，；：！`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling
@ -980,16 +998,18 @@ To fix this, remove the trailing punctuation:
Note: The `punctuation` parameter can be used to specify what characters count Note: The `punctuation` parameter can be used to specify what characters count
as punctuation at the end of a heading. For example, you can change it to as punctuation at the end of a heading. For example, you can change it to
`".,;:"` to allow headings that end with an exclamation point. `?` is `".,;:"` to allow headings that end with an exclamation point. `?` is
allowed by default because of how common it is in headings of FAQ-style documents. allowed by default because of how common it is in headings of FAQ-style
Setting the `punctuation` parameter to `""` allows all characters - and is documents. Setting the `punctuation` parameter to `""` allows all characters -
equivalent to disabling the rule. and is equivalent to disabling the rule.
Note: The trailing semicolon of Note: The trailing semicolon of [HTML entity references][html-entity-references]
[HTML entity references](https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references)
like `&copy;`, `&#169;`, and `&#x000A9;` is ignored by this rule. like `&copy;`, `&#169;`, and `&#x000A9;` is ignored by this rule.
Rationale: Headings are not meant to be full sentences. More information: Rationale: Headings are not meant to be full sentences. More information:
<https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers> [Punctuation at the end of headers][end-punctuation].
[end-punctuation]: https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers
[html-entity-references]: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references
<a name="md027"></a> <a name="md027"></a>
@ -1071,7 +1091,8 @@ Aliases: `ol-prefix`
Parameters: Parameters:
* `style`: List style (`string`, default `one_or_ordered`, values `one`/`one_or_ordered`/`ordered`/`zero`) * `style`: List style (`string`, default `one_or_ordered`, values `one` /
`one_or_ordered` / `ordered` / `zero`)
This rule is triggered for ordered lists that do not either start with '1.' or This rule is triggered for ordered lists that do not either start with '1.' or
do not have a prefix that increases in numerical order (depending on the do not have a prefix that increases in numerical order (depending on the
@ -1172,9 +1193,12 @@ Aliases: `list-marker-space`
Parameters: Parameters:
* `ol_multi`: Spaces for multi-line ordered list items (`integer`, default `1`) * `ol_multi`: Spaces for multi-line ordered list items (`integer`, default `1`)
* `ol_single`: Spaces for single-line ordered list items (`integer`, default `1`) * `ol_single`: Spaces for single-line ordered list items (`integer`, default
* `ul_multi`: Spaces for multi-line unordered list items (`integer`, default `1`) `1`)
* `ul_single`: Spaces for single-line unordered list items (`integer`, default `1`) * `ul_multi`: Spaces for multi-line unordered list items (`integer`, default
`1`)
* `ul_single`: Spaces for single-line unordered list items (`integer`, default
`1`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling
@ -1579,8 +1603,8 @@ automatically trimmed (to allow for embedded backticks):
`` `backticks` `` `` `backticks` ``
``` ```
Note: A single leading or trailing space is allowed if used to separate code span Note: A single leading or trailing space is allowed if used to separate code
markers from an embedded backtick: span markers from an embedded backtick:
```markdown ```markdown
`` ` embedded backtick`` `` ` embedded backtick``
@ -1677,7 +1701,8 @@ Aliases: `first-line-h1`, `first-line-heading`
Parameters: Parameters:
* `front_matter_title`: RegExp for matching title in front matter (`string`, default `^\s*title\s*[:=]`) * `front_matter_title`: RegExp for matching title in front matter (`string`,
default `^\s*title\s*[:=]`)
* `level`: Heading level (`integer`, default `1`) * `level`: Heading level (`integer`, default `1`)
This rule is intended to ensure documents have a title and is triggered when This rule is intended to ensure documents have a title and is triggered when
@ -1705,14 +1730,15 @@ permitted by this rule. For example:
This is a file with a top-level HTML heading This is a file with a top-level HTML heading
``` ```
Note: The `level` parameter can be used to change the top-level (ex: to h2) in cases Note: The `level` parameter can be used to change the top-level (ex: to h2) in
where an h1 is added externally. cases where an h1 is added externally.
If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
contains a `title` property (commonly used with blog posts), this rule will not contains a `title` property (commonly used with blog posts), this rule will not
report a violation. To use a different property name in the front matter, report a violation. To use a different property name in the front matter,
specify the text of a regular expression via the `front_matter_title` parameter. specify the text of a regular expression via the `front_matter_title` parameter.
To disable the use of front matter by this rule, specify `""` for `front_matter_title`. To disable the use of front matter by this rule, specify `""` for
`front_matter_title`.
Rationale: The top-level heading often acts as the title of a document. More Rationale: The top-level heading often acts as the title of a document. More
information: <https://cirosantilli.com/markdown-style-guide#top-level-header>. information: <https://cirosantilli.com/markdown-style-guide#top-level-header>.
@ -1749,7 +1775,8 @@ But non-empty fragments will not:
[a valid fragment](#fragment) [a valid fragment](#fragment)
``` ```
Rationale: Empty links do not lead anywhere and therefore don't function as links. Rationale: Empty links do not lead anywhere and therefore don't function as
links.
<a name="md043"></a> <a name="md043"></a>
@ -1816,12 +1843,12 @@ special value `"+"` meaning "one or more unspecified headings" and set the
When an error is detected, this rule outputs the line number of the first When an error is detected, this rule outputs the line number of the first
problematic heading (otherwise, it outputs the last line number of the file). problematic heading (otherwise, it outputs the last line number of the file).
Note that while the `headings` parameter uses the "## Text" ATX heading style for Note that while the `headings` parameter uses the "## Text" ATX heading style
simplicity, a file may use any supported heading style. for simplicity, a file may use any supported heading style.
By default, the case of headings in the document is not required to match that of By default, the case of headings in the document is not required to match that
`headings`. To require that case match exactly, set the `match_case` parameter to of `headings`. To require that case match exactly, set the `match_case`
`true`. parameter to `true`.
Rationale: Projects may wish to enforce a consistent document structure across Rationale: Projects may wish to enforce a consistent document structure across
a set of similar content. a set of similar content.
@ -1847,8 +1874,9 @@ the specified capitalization. It can be used to enforce a standard letter case
for the names of projects and products. for the names of projects and products.
For example, the language "JavaScript" is usually written with both the 'J' and For example, the language "JavaScript" is usually written with both the 'J' and
'S' capitalized - though sometimes the 's' or 'j' appear in lower-case. To enforce 'S' capitalized - though sometimes the 's' or 'j' appear in lower-case. To
the proper capitalization, specify the desired letter case in the `names` array: enforce the proper capitalization, specify the desired letter case in the
`names` array:
```json ```json
[ [
@ -1871,7 +1899,8 @@ Tags: `accessibility`, `images`
Aliases: `no-alt-text` Aliases: `no-alt-text`
This rule is triggered when an image is missing alternate text (alt text) information. This rule is triggered when an image is missing alternate text (alt text)
information.
Alternate text is commonly specified inline as: Alternate text is commonly specified inline as:
@ -1889,13 +1918,16 @@ Or with reference syntax as:
[ref]: image.jpg "Optional title" [ref]: image.jpg "Optional title"
``` ```
Guidance for writing alternate text is available from the [W3C](https://www.w3.org/WAI/alt/), Guidance for writing alternate text is available from the [W3C][w3c],
[Wikipedia](https://en.wikipedia.org/wiki/Alt_attribute), and [Wikipedia][wikipedia], and [other locations][phase2technology].
[other locations](https://www.phase2technology.com/blog/no-more-excuses).
Rationale: Alternate text is important for accessibility and describes the Rationale: Alternate text is important for accessibility and describes the
content of an image for people who may not be able to see it. content of an image for people who may not be able to see it.
[phase2technology]: https://www.phase2technology.com/blog/no-more-excuses
[w3c]: https://www.w3.org/WAI/alt/
[wikipedia]: https://en.wikipedia.org/wiki/Alt_attribute
<a name="md046"></a> <a name="md046"></a>
## `MD046` - Code block style ## `MD046` - Code block style
@ -1906,12 +1938,14 @@ Aliases: `code-block-style`
Parameters: Parameters:
* `style`: Block style (`string`, default `consistent`, values `consistent`/`fenced`/`indented`) * `style`: Block style (`string`, default `consistent`, values `consistent` /
`fenced` / `indented`)
This rule is triggered when unwanted or different code block styles are used in This rule is triggered when unwanted or different code block styles are used in
the same document. the same document.
In the default configuration this rule reports a violation for the following document: In the default configuration this rule reports a violation for the following
document:
<!-- markdownlint-disable code-block-style --> <!-- markdownlint-disable code-block-style -->
@ -1968,7 +2002,11 @@ This file ends with a newline.
``` ```
Rationale: Some programs have trouble with files that do not end with a newline. Rationale: Some programs have trouble with files that do not end with a newline.
More information: <https://unix.stackexchange.com/questions/18743/whats-the-point-in-adding-a-new-line-to-the-end-of-a-file>.
More information: [What's the point in adding a new line to the end of a
file?][stack-exchange]
[stack-exchange]: https://unix.stackexchange.com/questions/18743/whats-the-point-in-adding-a-new-line-to-the-end-of-a-file
<a name="md048"></a> <a name="md048"></a>
@ -1980,7 +2018,8 @@ Aliases: `code-fence-style`
Parameters: Parameters:
* `style`: Code fence style (`string`, default `consistent`, values `backtick`/`consistent`/`tilde`) * `style`: Code fence style (`string`, default `consistent`, values `backtick`
/ `consistent` / `tilde`)
This rule is triggered when the symbols used in the document for fenced code This rule is triggered when the symbols used in the document for fenced code
blocks do not match the configured code fence style: blocks do not match the configured code fence style:
@ -2023,7 +2062,8 @@ Aliases: `emphasis-style`
Parameters: Parameters:
* `style`: Emphasis style should be consistent (`string`, default `consistent`, values `asterisk`/`consistent`/`underscore`) * `style`: Emphasis style should be consistent (`string`, default `consistent`,
values `asterisk` / `consistent` / `underscore`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling
@ -2057,7 +2097,8 @@ Aliases: `strong-style`
Parameters: Parameters:
* `style`: Strong style should be consistent (`string`, default `consistent`, values `asterisk`/`consistent`/`underscore`) * `style`: Strong style should be consistent (`string`, default `consistent`,
values `asterisk` / `consistent` / `underscore`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling
@ -2118,16 +2159,16 @@ define a fragment:
An `a` tag can be useful in scenarios where a heading is not appropriate or for An `a` tag can be useful in scenarios where a heading is not appropriate or for
control over the text of the fragment identifier. control over the text of the fragment identifier.
Rationale: [GitHub section links][github-section-links] are created automatically Rationale: [GitHub section links][github-section-links] are created
for every heading when Markdown content is displayed on GitHub. This makes it automatically for every heading when Markdown content is displayed on GitHub.
easy to link directly to different sections within a document. However, section This makes it easy to link directly to different sections within a document.
links change if headings are renamed or removed. This rule helps identify broken However, section links change if headings are renamed or removed. This rule
section links within a document. helps identify broken section links within a document.
Section links are **not** part of the CommonMark specification. This rule Section links are **not** part of the CommonMark specification. This rule
enforces the [GitHub heading algorithm][github-heading-algorithm] which is: enforces the [GitHub heading algorithm][github-heading-algorithm] which is:
convert heading to lowercase, remove punctuation, convert spaces to dashes, append convert heading to lowercase, remove punctuation, convert spaces to dashes,
an incrementing integer as needed for uniqueness. append an incrementing integer as needed for uniqueness.
[github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links [github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
[github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/main/lib/html/pipeline/toc_filter.rb [github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/main/lib/html/pipeline/toc_filter.rb

4
doc/md003.md
View file

@ -6,7 +6,9 @@ Aliases: `header-style`, `heading-style`
Parameters: Parameters:
* `style`: Heading style (`string`, default `consistent`, values `atx`/`atx_closed`/`consistent`/`setext`/`setext_with_atx`/`setext_with_atx_closed`) * `style`: Heading style (`string`, default `consistent`, values `atx` /
`atx_closed` / `consistent` / `setext` / `setext_with_atx` /
`setext_with_atx_closed`)
This rule is triggered when different heading styles (atx, setext, and 'closed' This rule is triggered when different heading styles (atx, setext, and 'closed'
atx) are used in the same document: atx) are used in the same document:

13
doc/md004.md
View file

@ -6,7 +6,8 @@ Aliases: `ul-style`
Parameters: Parameters:
* `style`: List style (`string`, default `consistent`, values `asterisk`/`consistent`/`dash`/`plus`/`sublist`) * `style`: List style (`string`, default `consistent`, values `asterisk` /
`consistent` / `dash` / `plus` / `sublist`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling
@ -28,13 +29,13 @@ document:
* Item 3 * Item 3
``` ```
The configured list style can be a specific symbol to use (asterisk, plus, dash), The configured list style can be a specific symbol to use (asterisk, plus,
to ensure that all list styling is consistent, or to ensure that each dash), to ensure that all list styling is consistent, or to ensure that each
sublist has a consistent symbol that differs from its parent list. sublist has a consistent symbol that differs from its parent list.
For example, the following is valid for the `sublist` style because the outer-most For example, the following is valid for the `sublist` style because the
indent uses asterisk, the middle indent uses plus, and the inner-most indent uses outer-most indent uses asterisk, the middle indent uses plus, and the inner-most
dash: indent uses dash:
```markdown ```markdown
* Item 1 * Item 1

21
doc/md007.md
View file

@ -7,8 +7,10 @@ Aliases: `ul-indent`
Parameters: Parameters:
* `indent`: Spaces for indent (`integer`, default `2`) * `indent`: Spaces for indent (`integer`, default `2`)
* `start_indent`: Spaces for first level indent (when start_indented is set) (`integer`, default `2`) * `start_indent`: Spaces for first level indent (when start_indented is set)
* `start_indented`: Whether to indent the first level of the list (`boolean`, default `false`) (`integer`, default `2`)
* `start_indented`: Whether to indent the first level of the list (`boolean`,
default `false`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling
@ -35,16 +37,19 @@ rule).
The `start_indented` parameter allows the first level of lists to be indented by The `start_indented` parameter allows the first level of lists to be indented by
the configured number of spaces rather than starting at zero (the inverse of the configured number of spaces rather than starting at zero (the inverse of
MD006). The `start_indent` parameter allows the first level of lists to be indented MD006). The `start_indent` parameter allows the first level of lists to be
by a different number of spaces than the rest (ignored when `start_indented` is not indented by a different number of spaces than the rest (ignored when
set). `start_indented` is not set).
Rationale: Indenting by 2 spaces allows the content of a nested list to be in Rationale: Indenting by 2 spaces allows the content of a nested list to be in
line with the start of the content of the parent list when a single space is line with the start of the content of the parent list when a single space is
used after the list marker. Indenting by 4 spaces is consistent with code blocks used after the list marker. Indenting by 4 spaces is consistent with code blocks
and simpler for editors to implement. Additionally, this can be a compatibility and simpler for editors to implement. Additionally, this can be a compatibility
issue for other Markdown parsers, which require 4-space indents. More information: issue for other Markdown parsers, which require 4-space indents. More
<https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists> information: [Markdown Style Guide][markdown-style-guide] and [Marked app\
and <http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting>. support][marked-app-support].
Note: See [Prettier.md](Prettier.md) for compatibility information. Note: See [Prettier.md](Prettier.md) for compatibility information.
[markdown-style-guide]: https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists
[marked-app-support]: http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting

19
doc/md009.md
View file

@ -7,13 +7,14 @@ Aliases: `no-trailing-spaces`
Parameters: Parameters:
* `br_spaces`: Spaces for line break (`integer`, default `2`) * `br_spaces`: Spaces for line break (`integer`, default `2`)
* `list_item_empty_lines`: Allow spaces for empty lines in list items (`boolean`, default `false`) * `list_item_empty_lines`: Allow spaces for empty lines in list items
(`boolean`, default `false`)
* `strict`: Include unnecessary breaks (`boolean`, default `false`) * `strict`: Include unnecessary breaks (`boolean`, default `false`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling
This rule is triggered on any lines that end with unexpected whitespace. To fix this, This rule is triggered on any lines that end with unexpected whitespace. To fix
remove the trailing space from the end of the line. this, remove the trailing space from the end of the line.
Note: Trailing space is allowed in indented and fenced code blocks because some Note: Trailing space is allowed in indented and fenced code blocks because some
languages require it. languages require it.
@ -22,12 +23,14 @@ The `br_spaces` parameter allows an exception to this rule for a specific number
of trailing spaces, typically used to insert an explicit line break. The default of trailing spaces, typically used to insert an explicit line break. The default
value allows 2 spaces to indicate a hard break (\<br> element). value allows 2 spaces to indicate a hard break (\<br> element).
Note: You must set `br_spaces` to a value >= 2 for this parameter to take effect. Note: You must set `br_spaces` to a value >= 2 for this parameter to take
Setting `br_spaces` to 1 behaves the same as 0, disallowing any trailing spaces. effect. Setting `br_spaces` to 1 behaves the same as 0, disallowing any trailing
spaces.
By default, this rule will not trigger when the allowed number of spaces is used, By default, this rule will not trigger when the allowed number of spaces is
even when it doesn't create a hard break (for example, at the end of a paragraph). used, even when it doesn't create a hard break (for example, at the end of a
To report such instances as well, set the `strict` parameter to `true`. paragraph). To report such instances as well, set the `strict` parameter to
`true`.
```markdown ```markdown
Text text text Text text text

3
doc/md010.md
View file

@ -7,7 +7,8 @@ Aliases: `no-hard-tabs`
Parameters: Parameters:
* `code_blocks`: Include code blocks (`boolean`, default `true`) * `code_blocks`: Include code blocks (`boolean`, default `true`)
* `ignore_code_languages`: Fenced code languages to ignore (`string[]`, default `[]`) * `ignore_code_languages`: Fenced code languages to ignore (`string[]`, default
`[]`)
* `spaces_per_tab`: Number of spaces for each hard tab (`integer`, default `1`) * `spaces_per_tab`: Number of spaces for each hard tab (`integer`, default `1`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling

6
doc/md013.md
View file

@ -6,10 +6,12 @@ Aliases: `line-length`
Parameters: Parameters:
* `code_block_line_length`: Number of characters for code blocks (`integer`, default `80`) * `code_block_line_length`: Number of characters for code blocks (`integer`,
default `80`)
* `code_blocks`: Include code blocks (`boolean`, default `true`) * `code_blocks`: Include code blocks (`boolean`, default `true`)
* `headers`: Include headings (`boolean`, default `true`) * `headers`: Include headings (`boolean`, default `true`)
* `heading_line_length`: Number of characters for headings (`integer`, default `80`) * `heading_line_length`: Number of characters for headings (`integer`, default
`80`)
* `headings`: Include headings (`boolean`, default `true`) * `headings`: Include headings (`boolean`, default `true`)
* `line_length`: Number of characters (`integer`, default `80`) * `line_length`: Number of characters (`integer`, default `80`)
* `stern`: Stern length checking (`boolean`, default `false`) * `stern`: Stern length checking (`boolean`, default `false`)

10
doc/md022.md
View file

@ -35,12 +35,12 @@ Some more text
## Heading 2 ## Heading 2
``` ```
The `lines_above` and `lines_below` parameters can be used to specify a different The `lines_above` and `lines_below` parameters can be used to specify a
number of blank lines (including 0) above or below each heading. different number of blank lines (including 0) above or below each heading.
Note: If `lines_above` or `lines_below` are configured to require more than one Note: If `lines_above` or `lines_below` are configured to require more than one
blank line, [MD012/no-multiple-blanks](md012.md) should also be customized. blank line, [MD012/no-multiple-blanks](md012.md) should also be customized.
Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`, will Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`,
not parse headings that don't have a blank line before, and will parse them as will not parse headings that don't have a blank line before, and will parse them
regular text. as regular text.

3
doc/md024.md
View file

@ -6,7 +6,8 @@ Aliases: `no-duplicate-header`, `no-duplicate-heading`
Parameters: Parameters:
* `allow_different_nesting`: Only check sibling headings (`boolean`, default `false`) * `allow_different_nesting`: Only check sibling headings (`boolean`, default
`false`)
* `siblings_only`: Only check sibling headings (`boolean`, default `false`) * `siblings_only`: Only check sibling headings (`boolean`, default `false`)
This rule is triggered if there are multiple headings in the document that have This rule is triggered if there are multiple headings in the document that have

20
doc/md025.md
View file

@ -6,7 +6,8 @@ Aliases: `single-h1`, `single-title`
Parameters: Parameters:
* `front_matter_title`: RegExp for matching title in front matter (`string`, default `^\s*title\s*[:=]`) * `front_matter_title`: RegExp for matching title in front matter (`string`,
default `^\s*title\s*[:=]`)
* `level`: Heading level (`integer`, default `1`) * `level`: Heading level (`integer`, default `1`)
This rule is triggered when a top-level heading is in use (the first line of This rule is triggered when a top-level heading is in use (the first line of
@ -34,14 +35,15 @@ lower-level headings (h2, h3, etc.):
Note: The `level` parameter can be used to change the top-level (ex: to h2) in Note: The `level` parameter can be used to change the top-level (ex: to h2) in
cases where an h1 is added externally. cases where an h1 is added externally.
If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and contains If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
a `title` property (commonly used with blog posts), this rule treats that as a top contains a `title` property (commonly used with blog posts), this rule treats
level heading and will report a violation for any subsequent top-level headings. that as a top level heading and will report a violation for any subsequent
To use a different property name in the front matter, specify the text of a regular top-level headings. To use a different property name in the front matter,
expression via the `front_matter_title` parameter. To disable the use of front specify the text of a regular expression via the `front_matter_title` parameter.
matter by this rule, specify `""` for `front_matter_title`. To disable the use of front matter by this rule, specify `""` for
`front_matter_title`.
Rationale: A top-level heading is an h1 on the first line of the file, and Rationale: A top-level heading is an h1 on the first line of the file, and
serves as the title for the document. If this convention is in use, then there serves as the title for the document. If this convention is in use, then there
can not be more than one title for the document, and the entire document can not be more than one title for the document, and the entire document should
should be contained within this heading. be contained within this heading.

17
doc/md026.md
View file

@ -6,7 +6,8 @@ Aliases: `no-trailing-punctuation`
Parameters: Parameters:
* `punctuation`: Punctuation characters not allowed at end of headings (`string`, default `.,;:!。，；：！`) * `punctuation`: Punctuation characters not allowed at end of headings
(`string`, default `.,;:!。，；：！`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling
@ -26,13 +27,15 @@ To fix this, remove the trailing punctuation:
Note: The `punctuation` parameter can be used to specify what characters count Note: The `punctuation` parameter can be used to specify what characters count
as punctuation at the end of a heading. For example, you can change it to as punctuation at the end of a heading. For example, you can change it to
`".,;:"` to allow headings that end with an exclamation point. `?` is `".,;:"` to allow headings that end with an exclamation point. `?` is
allowed by default because of how common it is in headings of FAQ-style documents. allowed by default because of how common it is in headings of FAQ-style
Setting the `punctuation` parameter to `""` allows all characters - and is documents. Setting the `punctuation` parameter to `""` allows all characters -
equivalent to disabling the rule. and is equivalent to disabling the rule.
Note: The trailing semicolon of Note: The trailing semicolon of [HTML entity references][html-entity-references]
[HTML entity references](https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references)
like `&copy;`, `&#169;`, and `&#x000A9;` is ignored by this rule. like `&copy;`, `&#169;`, and `&#x000A9;` is ignored by this rule.
Rationale: Headings are not meant to be full sentences. More information: Rationale: Headings are not meant to be full sentences. More information:
<https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers> [Punctuation at the end of headers][end-punctuation].
[end-punctuation]: https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers
[html-entity-references]: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

3
doc/md029.md
View file

@ -6,7 +6,8 @@ Aliases: `ol-prefix`
Parameters: Parameters:
* `style`: List style (`string`, default `one_or_ordered`, values `one`/`one_or_ordered`/`ordered`/`zero`) * `style`: List style (`string`, default `one_or_ordered`, values `one` /
`one_or_ordered` / `ordered` / `zero`)
This rule is triggered for ordered lists that do not either start with '1.' or This rule is triggered for ordered lists that do not either start with '1.' or
do not have a prefix that increases in numerical order (depending on the do not have a prefix that increases in numerical order (depending on the

9
doc/md030.md
View file

@ -7,9 +7,12 @@ Aliases: `list-marker-space`
Parameters: Parameters:
* `ol_multi`: Spaces for multi-line ordered list items (`integer`, default `1`) * `ol_multi`: Spaces for multi-line ordered list items (`integer`, default `1`)
* `ol_single`: Spaces for single-line ordered list items (`integer`, default `1`) * `ol_single`: Spaces for single-line ordered list items (`integer`, default
* `ul_multi`: Spaces for multi-line unordered list items (`integer`, default `1`) `1`)
* `ul_single`: Spaces for single-line unordered list items (`integer`, default `1`) * `ul_multi`: Spaces for multi-line unordered list items (`integer`, default
`1`)
* `ul_single`: Spaces for single-line unordered list items (`integer`, default
`1`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling

4
doc/md038.md
View file

@ -28,8 +28,8 @@ automatically trimmed (to allow for embedded backticks):
`` `backticks` `` `` `backticks` ``
``` ```
Note: A single leading or trailing space is allowed if used to separate code span Note: A single leading or trailing space is allowed if used to separate code
markers from an embedded backtick: span markers from an embedded backtick:
```markdown ```markdown
`` ` embedded backtick`` `` ` embedded backtick``

10
doc/md041.md
View file

@ -6,7 +6,8 @@ Aliases: `first-line-h1`, `first-line-heading`
Parameters: Parameters:
* `front_matter_title`: RegExp for matching title in front matter (`string`, default `^\s*title\s*[:=]`) * `front_matter_title`: RegExp for matching title in front matter (`string`,
default `^\s*title\s*[:=]`)
* `level`: Heading level (`integer`, default `1`) * `level`: Heading level (`integer`, default `1`)
This rule is intended to ensure documents have a title and is triggered when This rule is intended to ensure documents have a title and is triggered when
@ -34,14 +35,15 @@ permitted by this rule. For example:
This is a file with a top-level HTML heading This is a file with a top-level HTML heading
``` ```
Note: The `level` parameter can be used to change the top-level (ex: to h2) in cases Note: The `level` parameter can be used to change the top-level (ex: to h2) in
where an h1 is added externally. cases where an h1 is added externally.
If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
contains a `title` property (commonly used with blog posts), this rule will not contains a `title` property (commonly used with blog posts), this rule will not
report a violation. To use a different property name in the front matter, report a violation. To use a different property name in the front matter,
specify the text of a regular expression via the `front_matter_title` parameter. specify the text of a regular expression via the `front_matter_title` parameter.
To disable the use of front matter by this rule, specify `""` for `front_matter_title`. To disable the use of front matter by this rule, specify `""` for
`front_matter_title`.
Rationale: The top-level heading often acts as the title of a document. More Rationale: The top-level heading often acts as the title of a document. More
information: <https://cirosantilli.com/markdown-style-guide#top-level-header>. information: <https://cirosantilli.com/markdown-style-guide#top-level-header>.

3
doc/md042.md
View file

@ -28,4 +28,5 @@ But non-empty fragments will not:
[a valid fragment](#fragment) [a valid fragment](#fragment)
``` ```
Rationale: Empty links do not lead anywhere and therefore don't function as links. Rationale: Empty links do not lead anywhere and therefore don't function as
links.

10
doc/md043.md
View file

@ -61,12 +61,12 @@ special value `"+"` meaning "one or more unspecified headings" and set the
When an error is detected, this rule outputs the line number of the first When an error is detected, this rule outputs the line number of the first
problematic heading (otherwise, it outputs the last line number of the file). problematic heading (otherwise, it outputs the last line number of the file).
Note that while the `headings` parameter uses the "## Text" ATX heading style for Note that while the `headings` parameter uses the "## Text" ATX heading style
simplicity, a file may use any supported heading style. for simplicity, a file may use any supported heading style.
By default, the case of headings in the document is not required to match that of By default, the case of headings in the document is not required to match that
`headings`. To require that case match exactly, set the `match_case` parameter to of `headings`. To require that case match exactly, set the `match_case`
`true`. parameter to `true`.
Rationale: Projects may wish to enforce a consistent document structure across Rationale: Projects may wish to enforce a consistent document structure across
a set of similar content. a set of similar content.

5
doc/md044.md
View file

@ -17,8 +17,9 @@ the specified capitalization. It can be used to enforce a standard letter case
for the names of projects and products. for the names of projects and products.
For example, the language "JavaScript" is usually written with both the 'J' and For example, the language "JavaScript" is usually written with both the 'J' and
'S' capitalized - though sometimes the 's' or 'j' appear in lower-case. To enforce 'S' capitalized - though sometimes the 's' or 'j' appear in lower-case. To
the proper capitalization, specify the desired letter case in the `names` array: enforce the proper capitalization, specify the desired letter case in the
`names` array:
```json ```json
[ [

12
doc/md045.md
View file

@ -4,7 +4,8 @@ Tags: `accessibility`, `images`
Aliases: `no-alt-text` Aliases: `no-alt-text`
This rule is triggered when an image is missing alternate text (alt text) information. This rule is triggered when an image is missing alternate text (alt text)
information.
Alternate text is commonly specified inline as: Alternate text is commonly specified inline as:
@ -22,9 +23,12 @@ Or with reference syntax as:
[ref]: image.jpg "Optional title" [ref]: image.jpg "Optional title"
``` ```
Guidance for writing alternate text is available from the [W3C](https://www.w3.org/WAI/alt/), Guidance for writing alternate text is available from the [W3C][w3c],
[Wikipedia](https://en.wikipedia.org/wiki/Alt_attribute), and [Wikipedia][wikipedia], and [other locations][phase2technology].
[other locations](https://www.phase2technology.com/blog/no-more-excuses).
Rationale: Alternate text is important for accessibility and describes the Rationale: Alternate text is important for accessibility and describes the
content of an image for people who may not be able to see it. content of an image for people who may not be able to see it.
[phase2technology]: https://www.phase2technology.com/blog/no-more-excuses
[w3c]: https://www.w3.org/WAI/alt/
[wikipedia]: https://en.wikipedia.org/wiki/Alt_attribute

6
doc/md046.md
View file

@ -6,12 +6,14 @@ Aliases: `code-block-style`
Parameters: Parameters:
* `style`: Block style (`string`, default `consistent`, values `consistent`/`fenced`/`indented`) * `style`: Block style (`string`, default `consistent`, values `consistent` /
`fenced` / `indented`)
This rule is triggered when unwanted or different code block styles are used in This rule is triggered when unwanted or different code block styles are used in
the same document. the same document.
In the default configuration this rule reports a violation for the following document: In the default configuration this rule reports a violation for the following
document:
<!-- markdownlint-disable code-block-style --> <!-- markdownlint-disable code-block-style -->

6
doc/md047.md
View file

@ -27,4 +27,8 @@ This file ends with a newline.
``` ```
Rationale: Some programs have trouble with files that do not end with a newline. Rationale: Some programs have trouble with files that do not end with a newline.
More information: <https://unix.stackexchange.com/questions/18743/whats-the-point-in-adding-a-new-line-to-the-end-of-a-file>.
More information: [What's the point in adding a new line to the end of a
file?][stack-exchange]
[stack-exchange]: https://unix.stackexchange.com/questions/18743/whats-the-point-in-adding-a-new-line-to-the-end-of-a-file

3
doc/md048.md
View file

@ -6,7 +6,8 @@ Aliases: `code-fence-style`
Parameters: Parameters:
* `style`: Code fence style (`string`, default `consistent`, values `backtick`/`consistent`/`tilde`) * `style`: Code fence style (`string`, default `consistent`, values `backtick`
/ `consistent` / `tilde`)
This rule is triggered when the symbols used in the document for fenced code This rule is triggered when the symbols used in the document for fenced code
blocks do not match the configured code fence style: blocks do not match the configured code fence style:

3
doc/md049.md
View file

@ -6,7 +6,8 @@ Aliases: `emphasis-style`
Parameters: Parameters:
* `style`: Emphasis style should be consistent (`string`, default `consistent`, values `asterisk`/`consistent`/`underscore`) * `style`: Emphasis style should be consistent (`string`, default `consistent`,
values `asterisk` / `consistent` / `underscore`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling

3
doc/md050.md
View file

@ -6,7 +6,8 @@ Aliases: `strong-style`
Parameters: Parameters:
* `style`: Strong style should be consistent (`string`, default `consistent`, values `asterisk`/`consistent`/`underscore`) * `style`: Strong style should be consistent (`string`, default `consistent`,
values `asterisk` / `consistent` / `underscore`)
Fixable: Most violations can be fixed by tooling Fixable: Most violations can be fixed by tooling

14
doc/md051.md
View file

@ -33,16 +33,16 @@ define a fragment:
An `a` tag can be useful in scenarios where a heading is not appropriate or for An `a` tag can be useful in scenarios where a heading is not appropriate or for
control over the text of the fragment identifier. control over the text of the fragment identifier.
Rationale: [GitHub section links][github-section-links] are created automatically Rationale: [GitHub section links][github-section-links] are created
for every heading when Markdown content is displayed on GitHub. This makes it automatically for every heading when Markdown content is displayed on GitHub.
easy to link directly to different sections within a document. However, section This makes it easy to link directly to different sections within a document.
links change if headings are renamed or removed. This rule helps identify broken However, section links change if headings are renamed or removed. This rule
section links within a document. helps identify broken section links within a document.
Section links are **not** part of the CommonMark specification. This rule Section links are **not** part of the CommonMark specification. This rule
enforces the [GitHub heading algorithm][github-heading-algorithm] which is: enforces the [GitHub heading algorithm][github-heading-algorithm] which is:
convert heading to lowercase, remove punctuation, convert spaces to dashes, append convert heading to lowercase, remove punctuation, convert spaces to dashes,
an incrementing integer as needed for uniqueness. append an incrementing integer as needed for uniqueness.
[github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links [github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
[github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/main/lib/html/pipeline/toc_filter.rb [github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/main/lib/html/pipeline/toc_filter.rb

2
example/typescript/type-check.ts
View file

@ -10,7 +10,7 @@ assert(/^\d+\.\d+\.\d+$/.test(version));
function assertConfiguration(config: markdownlint.Configuration) { function assertConfiguration(config: markdownlint.Configuration) {
assert(!!config); assert(!!config);
assert.equal(config["line-length"], false); assert.deepEqual(config["line-length"], { "strict": true });
// config assignment is covered by markdownlint.Options // config assignment is covered by markdownlint.Options
} }

32
helpers/README.md
View file

@ -4,19 +4,18 @@
## Overview ## Overview
The [Markdown](https://en.wikipedia.org/wiki/Markdown) linter The [Markdown][markdown] linter [`markdownlint`][markdownlint] offers a variety
[`markdownlint`](https://github.com/DavidAnson/markdownlint) offers a variety of built-in validation of built-in validation [rules][rules] and supports the creation of [custom
[rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) and supports the rules][custom-rules]. The internal rules share various helper functions; this
creation of [custom rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/CustomRules.md). package exposes those for reuse by custom rules.
The internal rules share various helper functions; this package exposes those for reuse by custom rules.
## API ## API
_Undocumented_ - This package exports the internal functions as-is. The APIs were not originally meant _Undocumented_ - This package exports the internal functions as-is. The APIs
to be public, are not officially supported, and may change from release to release. There are brief were not originally meant to be public, are not officially supported, and may
descriptive comments above each function, but no [JSDoc](https://en.m.wikipedia.org/wiki/JSDoc) change from release to release. There are brief descriptive comments above each
annotations. That said, some of what's here will be useful to custom rule authors and may avoid function, but no [JSDoc][jsdoc] annotations. That said, some of what's here will
duplicating code. be useful to custom rule authors and may avoid duplicating code.
## Example ## Example
@ -42,9 +41,16 @@ module.exports = {
}; };
``` ```
See also: [`markdownlint` built-in rule implementations](https://github.com/DavidAnson/markdownlint/tree/main/lib). See also: [`markdownlint` built-in rule implementations][lib].
## Tests ## Tests
_None_ - The entire body of code is tested to 100% coverage by the core `markdownlint` project, _None_ - The entire body of code is tested to 100% coverage by the core
so there are no additional tests here. `markdownlint` project, so there are no additional tests here.
[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/main/doc/CustomRules.md
[jsdoc]: https://en.m.wikipedia.org/wiki/JSDoc
[lib]: https://github.com/DavidAnson/markdownlint/tree/main/lib
[markdown]: https://en.wikipedia.org/wiki/Markdown
[markdownlint]: https://github.com/DavidAnson/markdownlint
[rules]: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md

2
test/markdownlint-test.js
View file

@ -79,7 +79,6 @@ test("projectFilesNoInlineConfig", (t) => new Promise((resolve) => {
t.plan(2); t.plan(2);
const options = { const options = {
"files": [ "files": [
"README.md",
"CONTRIBUTING.md", "CONTRIBUTING.md",
"doc/CustomRules.md", "doc/CustomRules.md",
"doc/Prettier.md", "doc/Prettier.md",
@ -92,7 +91,6 @@ test("projectFilesNoInlineConfig", (t) => new Promise((resolve) => {
markdownlint(options, function callback(err, actual) { markdownlint(options, function callback(err, actual) {
t.falsy(err); t.falsy(err);
const expected = { const expected = {
"README.md": [],
"CONTRIBUTING.md": [], "CONTRIBUTING.md": [],
"doc/CustomRules.md": [], "doc/CustomRules.md": [],
"doc/Prettier.md": [], "doc/Prettier.md": [],