@alexlit/lint-kit 190.0.0 → 191.0.0

package/packages/config-markdownlint/node_modules/markdownlint/README.md

@@ -1,1112 +0,0 @@
-# markdownlint
-
-> A Node.js style checker and lint tool for Markdown/CommonMark files.
-
-[![npm version][npm-image]][npm-url]
-[![License][license-image]][license-url]
-
-## Install
-
-```bash
-npm install markdownlint --save-dev
-```
-
-## Overview
-
-The [Markdown][markdown] markup language is designed to be easy to read, write,
-and understand. It succeeds - and its flexibility is both a benefit and a
-drawback. Many styles are possible, so formatting can be inconsistent; some
-constructs don't work well in all parsers and should be avoided.
-
-`markdownlint` is a [static analysis][static-analysis] tool for
-[Node.js][nodejs] with a library of rules to enforce standards and consistency
-for Markdown files. It was inspired by - and heavily influenced by - Mark
-Harrison's [markdownlint][markdownlint-ruby] for Ruby. The initial rules, rule
-documentation, and test cases came from that project.
-
-`markdownlint` uses the [`micromark` parser][micromark] and honors the
-[CommonMark][commonmark] specification for Markdown. It additionally supports
-popular [GitHub Flavored Markdown (GFM)][gfm] syntax like autolinks and tables
-as well as directives, footnotes, and math syntax - all implemented by
-[`micromark` extensions][micromark-extensions]. (Note that inline directives are
-not supported to avoid confusion due to over-matching.)
-
-[commonmark]: https://commonmark.org/
-[gfm]: https://github.github.com/gfm/
-[markdown]: https://wikipedia.org/wiki/Markdown
-[markdownlint-ruby]: https://github.com/markdownlint/markdownlint
-[micromark]: https://github.com/micromark/micromark
-[micromark-extensions]: https://github.com/micromark/micromark?tab=readme-ov-file#list-of-extensions
-[nodejs]: https://nodejs.org/
-[static-analysis]: https://wikipedia.org/wiki/Static_program_analysis
-
-### Related
-
-- CLI
-  - [markdownlint-cli][markdownlint-cli] command-line interface for Node.js
-    ([works with pre-commit][markdownlint-cli-precommit])
-  - [markdownlint-cli2][markdownlint-cli2] command-line interface for Node.js
-    ([works with pre-commit][markdownlint-cli2-precommit])
-- GitHub
-  - [GitHub Action for markdownlint-cli2][markdownlint-cli2-action]
-  - [GitHub Super-Linter Action][super-linter]
-  - [GitHub Actions problem matcher for
-    markdownlint-cli][markdownlint-problem-matcher]
-- Editor
-  - [vscode-markdownlint extension for VS Code][vscode-markdownlint]
-  - [Sublime Text markdownlint for Sublime Text][sublimelinter]
-  - [coc-markdownlint extension for Vim/Neovim][coc]
-  - [flymake-markdownlint-cli2 extension for Emacs][emacs-flymake]
-- Tooling
-  - [eslint-plugin-markdownlint for the ESLint analyzer][eslint-plugin]
-  - [grunt-markdownlint for the Grunt task runner][grunt-markdownlint]
-  - [Cake.Markdownlint addin for Cake build automation system][cake]
-  - [Lombiq Node.js Extensions for MSBuild (.NET builds)][nodejs-extensions]
-- Ruby
-  - [markdownlint/mdl gem for Ruby][rubygems-mdl]
-
-[cake]: https://github.com/cake-contrib/Cake.Markdownlint
-[coc]: https://github.com/fannheyward/coc-markdownlint
-[emacs-flymake]: https://github.com/ewilderj/flymake-markdownlint-cli2
-[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-action]: https://github.com/marketplace/actions/markdownlint-cli2-action
-[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://github.com/jonlabelle/SublimeLinter-contrib-markdownlint
-[super-linter]: https://github.com/super-linter/super-linter
-[vscode-markdownlint]: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
-
-### References
-
-The following specifications are considered authoritative in cases of ambiguity:
-
-- [CommonMark](https://spec.commonmark.org/current/)
-- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
-
-## Demonstration
-
-[`markdownlint` demo](https://dlaa.me/markdownlint/), an interactive, in-browser
-playground for learning and exploring.
-
-## Rules / Aliases
-
-<!-- markdownlint-disable line-length -->
-
-- **[MD001](doc/md001.md)** *heading-increment* - Heading levels should only increment by one level at a time
-- **[MD003](doc/md003.md)** *heading-style* - Heading style
-- **[MD004](doc/md004.md)** *ul-style* - Unordered list style
-- **[MD005](doc/md005.md)** *list-indent* - Inconsistent indentation for list items at the same level
-- **[MD007](doc/md007.md)** *ul-indent* - Unordered list indentation
-- **[MD009](doc/md009.md)** *no-trailing-spaces* - Trailing spaces
-- **[MD010](doc/md010.md)** *no-hard-tabs* - Hard tabs
-- **[MD011](doc/md011.md)** *no-reversed-links* - Reversed link syntax
-- **[MD012](doc/md012.md)** *no-multiple-blanks* - Multiple consecutive blank lines
-- **[MD013](doc/md013.md)** *line-length* - Line length
-- **[MD014](doc/md014.md)** *commands-show-output* - Dollar signs used before commands without showing output
-- **[MD018](doc/md018.md)** *no-missing-space-atx* - No space after hash on atx style heading
-- **[MD019](doc/md019.md)** *no-multiple-space-atx* - Multiple spaces after hash on atx style heading
-- **[MD020](doc/md020.md)** *no-missing-space-closed-atx* - No space inside hashes on closed atx style heading
-- **[MD021](doc/md021.md)** *no-multiple-space-closed-atx* - Multiple spaces inside hashes on closed atx style heading
-- **[MD022](doc/md022.md)** *blanks-around-headings* - Headings should be surrounded by blank lines
-- **[MD023](doc/md023.md)** *heading-start-left* - Headings must start at the beginning of the line
-- **[MD024](doc/md024.md)** *no-duplicate-heading* - Multiple headings with the same content
-- **[MD025](doc/md025.md)** *single-title/single-h1* - Multiple top-level headings in the same document
-- **[MD026](doc/md026.md)** *no-trailing-punctuation* - Trailing punctuation in heading
-- **[MD027](doc/md027.md)** *no-multiple-space-blockquote* - Multiple spaces after blockquote symbol
-- **[MD028](doc/md028.md)** *no-blanks-blockquote* - Blank line inside blockquote
-- **[MD029](doc/md029.md)** *ol-prefix* - Ordered list item prefix
-- **[MD030](doc/md030.md)** *list-marker-space* - Spaces after list markers
-- **[MD031](doc/md031.md)** *blanks-around-fences* - Fenced code blocks should be surrounded by blank lines
-- **[MD032](doc/md032.md)** *blanks-around-lists* - Lists should be surrounded by blank lines
-- **[MD033](doc/md033.md)** *no-inline-html* - Inline HTML
-- **[MD034](doc/md034.md)** *no-bare-urls* - Bare URL used
-- **[MD035](doc/md035.md)** *hr-style* - Horizontal rule style
-- **[MD036](doc/md036.md)** *no-emphasis-as-heading* - Emphasis used instead of a heading
-- **[MD037](doc/md037.md)** *no-space-in-emphasis* - Spaces inside emphasis markers
-- **[MD038](doc/md038.md)** *no-space-in-code* - Spaces inside code span elements
-- **[MD039](doc/md039.md)** *no-space-in-links* - Spaces inside link text
-- **[MD040](doc/md040.md)** *fenced-code-language* - Fenced code blocks should have a language specified
-- **[MD041](doc/md041.md)** *first-line-heading/first-line-h1* - First line in a file should be a top-level heading
-- **[MD042](doc/md042.md)** *no-empty-links* - No empty links
-- **[MD043](doc/md043.md)** *required-headings* - Required heading structure
-- **[MD044](doc/md044.md)** *proper-names* - Proper names should have the correct capitalization
-- **[MD045](doc/md045.md)** *no-alt-text* - Images should have alternate text (alt text)
-- **[MD046](doc/md046.md)** *code-block-style* - Code block style
-- **[MD047](doc/md047.md)** *single-trailing-newline* - Files should end with a single newline character
-- **[MD048](doc/md048.md)** *code-fence-style* - Code fence style
-- **[MD049](doc/md049.md)** *emphasis-style* - Emphasis style
-- **[MD050](doc/md050.md)** *strong-style* - Strong style
-- **[MD051](doc/md051.md)** *link-fragments* - Link fragments should be valid
-- **[MD052](doc/md052.md)** *reference-links-images* - Reference links and images should use a label that is defined
-- **[MD053](doc/md053.md)** *link-image-reference-definitions* - Link and image reference definitions should be needed
-- **[MD054](doc/md054.md)** *link-image-style* - Link and image style
-- **[MD055](doc/md055.md)** *table-pipe-style* - Table pipe style
-- **[MD056](doc/md056.md)** *table-column-count* - Table column count
-- **[MD058](doc/md058.md)** *blanks-around-tables* - Tables should be surrounded by blank lines
-- **[MD059](doc/md059.md)** *descriptive-link-text* - Link text should be descriptive
-- **[MD060](doc/md060.md)** *table-column-style* - Table column style
-
-<!-- markdownlint-restore -->
-
-See [Rules.md](doc/Rules.md) for more details.
-
-### Custom Rules
-
-In addition to built-in rules, custom rules can be used to address
-project-specific requirements. To find community-developed rules use
-[keyword `markdownlint-rule` on npm][markdownlint-rule].
-To implement your own rules, refer to [CustomRules.md](doc/CustomRules.md).
-
-[markdownlint-rule]: https://www.npmjs.com/search?q=keywords:markdownlint-rule
-
-## Tags
-
-Tags group related rules and can be used to enable/disable multiple
-rules at once.
-
-- **`accessibility`** - `MD045`, `MD059`
-- **`atx`** - `MD018`, `MD019`
-- **`atx_closed`** - `MD020`, `MD021`
-- **`blank_lines`** - `MD012`, `MD022`, `MD031`, `MD032`, `MD047`
-- **`blockquote`** - `MD027`, `MD028`
-- **`bullet`** - `MD004`, `MD005`, `MD007`, `MD032`
-- **`code`** - `MD014`, `MD031`, `MD038`, `MD040`, `MD046`, `MD048`
-- **`emphasis`** - `MD036`, `MD037`, `MD049`, `MD050`
-- **`hard_tab`** - `MD010`
-- **`headings`** - `MD001`, `MD003`, `MD018`, `MD019`, `MD020`, `MD021`,
-  `MD022`, `MD023`, `MD024`, `MD025`, `MD026`, `MD036`, `MD041`, `MD043`
-- **`hr`** - `MD035`
-- **`html`** - `MD033`
-- **`images`** - `MD045`, `MD052`, `MD053`, `MD054`
-- **`indentation`** - `MD005`, `MD007`, `MD027`
-- **`language`** - `MD040`
-- **`line_length`** - `MD013`
-- **`links`** - `MD011`, `MD034`, `MD039`, `MD042`, `MD051`, `MD052`, `MD053`,
-  `MD054`, `MD059`
-- **`ol`** - `MD029`, `MD030`, `MD032`
-- **`spaces`** - `MD018`, `MD019`, `MD020`, `MD021`, `MD023`
-- **`spelling`** - `MD044`
-- **`table`** - `MD055`, `MD056`, `MD058`, `MD060`
-- **`ul`** - `MD004`, `MD005`, `MD007`, `MD030`, `MD032`
-- **`url`** - `MD034`
-- **`whitespace`** - `MD009`, `MD010`, `MD012`, `MD027`, `MD028`, `MD030`,
-  `MD037`, `MD038`, `MD039`
-
-## Configuration
-
-Text passed to `markdownlint` is parsed as Markdown, analyzed, and any
-issues reported. Two kinds of text are ignored by most rules:
-
-- [HTML comments](https://www.w3.org/TR/html5/syntax.html#comments)
-- [Front matter](https://jekyllrb.com/docs/frontmatter/) (see
-  `options.frontMatter` below)
-
-All rules are enabled by default. Rules can be enabled, disabled, and configured
-for each call to the `lint` API by passing an `options.config` object (described
-below). To enable or disable rules within a file, use one of the following HTML
-comments (which are not rendered):
-
-- Disable all rules: `<!-- markdownlint-disable -->`
-- Enable all rules: `<!-- markdownlint-enable -->`
-- Disable all rules for the current line: `<!-- markdownlint-disable-line -->`
-- Disable all rules for the next line: `<!-- markdownlint-disable-next-line -->`
-- Disable one or more rules by name: `<!-- markdownlint-disable MD001 MD005 -->`
-- Enable one or more rules by name: `<!-- markdownlint-enable MD001 MD005 -->`
-- Disable one or more rules by name for the current line:
-  `<!-- markdownlint-disable-line MD001 MD005 -->`
-- Disable one or more rules by name for the next line:
-  `<!-- markdownlint-disable-next-line MD001 MD005 -->`
-- Capture the current rule configuration: `<!-- markdownlint-capture -->`
-- Restore the captured rule configuration: `<!-- markdownlint-restore -->`
-
-For example:
-
-```markdown
-<!-- markdownlint-disable-next-line no-space-in-emphasis -->
-space * in * emphasis
-```
-
-Or:
-
-```markdown
-space * in * emphasis <!-- markdownlint-disable-line no-space-in-emphasis -->
-```
-
-Or:
-
-```markdown
-<!-- markdownlint-disable no-space-in-emphasis -->
-space * in * emphasis
-<!-- markdownlint-enable no-space-in-emphasis -->
-```
-
-To temporarily disable rule(s), then restore the former configuration:
-
-```markdown
-<!-- markdownlint-capture -->
-<!-- markdownlint-disable -->
-any violations you want
-<!-- markdownlint-restore -->
-```
-
-The initial configuration is captured by default (as if every document
-began with `<!-- markdownlint-capture -->`), so the pattern above can
-be expressed more simply:
-
-```markdown
-<!-- markdownlint-disable -->
-any violations you want
-<!-- markdownlint-restore -->
-```
-
-Changes take effect starting with the line a comment is on, so the following
-has no effect:
-
-```markdown
-space * in * emphasis <!-- markdownlint-disable --> <!-- markdownlint-enable -->
-```
-
-To apply changes to an entire file regardless of where the comment is located,
-the following syntax is supported:
-
-- Disable all rules: `<!-- markdownlint-disable-file -->`
-- Enable all rules: `<!-- markdownlint-enable-file -->`
-- Disable one or more rules by name: `<!-- markdownlint-disable-file MD001 -->`
-- Enable one or more rules by name: `<!-- markdownlint-enable-file MD001 -->`
-
-This can be used to "hide" `markdownlint` comments at the bottom of a file.
-
-In cases where it is desirable to change the configuration of one or
-more rules for a file, the following more advanced syntax is supported:
-
-- Configure: `<!-- markdownlint-configure-file { options.config JSON } -->`
-
-For example:
-
-```markdown
-<!-- markdownlint-configure-file { "hr-style": { "style": "---" } } -->
-```
-
-or
-
-```markdown
-<!-- markdownlint-configure-file
-{
-  "hr-style": {
-    "style": "---"
-  },
-  "no-trailing-spaces": false
-}
--->
-```
-
-These changes apply to the entire file regardless of where the comment is
-located. Multiple such comments (if present) are applied top-to-bottom. By
-default, content of `markdownlint-configure-file` is assumed to be JSON, but
-[`options.configParsers`](#optionsconfigparsers) can be used to support
-alternate formats.
-
-## API
-
-### Linting
-
-Asynchronous API via `import { lint } from "markdownlint/async"`:
-
-```javascript
-/**
- * Lint specified Markdown files.
- *
- * @param {Options | null} options Configuration options.
- * @param {LintCallback} callback Callback (err, result) function.
- * @returns {void}
- */
-function lint(options, callback) { ... }
-```
-
-Synchronous API via `import { lint } from "markdownlint/sync"`:
-
-```javascript
-/**
- * Lint specified Markdown files.
- *
- * @param {Options | null} options Configuration options.
- * @returns {LintResults} Results object.
- */
-function lint(options) { ... }
-```
-
-Promise API via `import { lint } from "markdownlint/promise"`:
-
-```javascript
-/**
- * Lint specified Markdown files.
- *
- * @param {Options | null} options Configuration options.
- * @returns {Promise<LintResults>} Results object.
- */
-function lint(options) { ... }
-```
-
-#### options
-
-Type: `Object`
-
-Configures the function. All properties are optional, but at least one
-of `files` or `strings` should be set to provide input.
-
-##### options.config
-
-Type: `Object` mapping `String` to `Boolean | "error" | "warning" | Object`
-
-Configures the rules to use.
-
-Object keys are rule names/aliases; object values are the rule's configuration.
-The value `false` disables a rule. The values `true` or `"error"` enable a rule
-in its default configuration and report violations as errors. The value
-`"warning"` enables a rule in its default configuration and reports violations
-as warnings. Passing an object enables *and* customizes the rule; the properties
-`severity` (`"error" | "warning"`) and `enabled` (`false | true`) can be used in
-this context. The special `default` rule assigns the default for all rules.
-Using a tag name (e.g., `whitespace`) and a setting of `false`, `true`,
-`"error"`, or `"warning"` applies that setting to all rules with that tag. When
-no configuration object is passed or the optional `default` setting is not
-present, all rules are enabled.
-
-The following syntax disables the specified rule, tag, or `default`:
-
-```javascript
-{
-  "rule_tag_or_default": false
-}
-```
-
-The following syntax enables the specified rule, tag, or `default` to report
-violations as errors:
-
-```javascript
-{
-  "rule_tag_or_default": true
-  // OR
-  "rule_tag_or_default": "error"
-}
-```
-
-The following syntax enables the specified rule, tag, or `default` to report
-violations as warnings:
-
-```javascript
-{
-  "rule_tag_or_default": "warning"
-}
-```
-
-The following syntax enables and configures the specified rule to report
-violations as errors:
-
-```javascript
-{
-  "rule": {
-    "severity": "error"
-  }
-  // OR
-  "rule": {
-    "rule_parameter": "value"
-  }
-  // OR
-  "rule": {
-    "severity": "error",
-    "rule_parameter": "value"
-  }
-}
-```
-
-The following syntax enables and configures the specified rule to report
-violations as warnings:
-
-```javascript
-{
-  "rule": {
-    "severity": "warning"
-  }
-  // OR
-  "rule": {
-    "severity": "warning",
-    "rule_parameter": "value"
-  }
-}
-```
-
-> Note that values `"error"` and `"warning"` and the property `severity` are not
-> supported by library versions earlier than `0.39.0`. However, the examples
-> above behave the same there, with warnings being reported as errors.
-
-The following syntax disables and configures the specified rule:
-
-```javascript
-{
-  "rule": {
-    "enabled": false,
-    "rule_parameter": "value"
-  }
-  // OR
-  "rule": {
-    "enabled": false,
-    "severity": "warning",
-    "rule_parameter": "value"
-  }
-}
-```
-
-> Note that this example behaves **differently** with library versions earlier
-> than `0.39.0` because the property `enabled` is not supported: it **enables**
-> the rule instead of **disabling** it. As such, this syntax is discouraged when
-> interoperability is important.
-
-To evaluate a configuration object, the `default` setting is applied first, then
-keys are processed in order from top to bottom. If multiple values apply to a
-rule (because of tag names or duplication), later values override earlier ones.
-Keys (including rule names, aliases, tags, or `default`) are not case-sensitive.
-
-Example using `default`, rule names, and tag names together:
-
-```json
-{
-  "default": true,
-  "MD003": { "style": "atx_closed" },
-  "MD007": { "indent": 4 },
-  "no-hard-tabs": false,
-  "whitespace": false
-}
-```
-
-See [.markdownlint.jsonc](schema/.markdownlint.jsonc) and/or
-[.markdownlint.yaml](schema/.markdownlint.yaml) for an example
-configuration object with all properties set to the default value.
-
-Sets of rules (known as a "style") can be stored separately and loaded
-as [JSON](https://wikipedia.org/wiki/JSON).
-
-Example of referencing a built-in style from JavaScript:
-
-```javascript
-const options = {
-  "files": [ "..." ],
-  "config": require("style/relaxed.json")
-};
-```
-
-Example doing so from `.markdownlint.json` via `extends` (more on this below):
-
-```json
-{
-  "extends": "markdownlint/style/relaxed"
-}
-```
-
-See the [style](style) directory for more samples.
-
-See [markdownlint-config-schema.json](schema/markdownlint-config-schema.json)
-for the [JSON Schema](https://json-schema.org/) of the `options.config`
-object.
-
-See [ValidatingConfiguration.md](schema/ValidatingConfiguration.md) for ways to
-use the JSON Schema to validate configuration.
-
-For more advanced scenarios, styles can reference and build upon other styles
-via the `extends` keyword and a file path or (installed) package name. The
-`readConfig` function can be used to read such aggregate styles from code.
-
-For example, assuming a `base.json` configuration file:
-
-```json
-{
-  "default": true
-}
-```
-
-And a `custom.json` configuration file:
-
-```json
-{
-  "extends": "base.json",
-  "line-length": false
-}
-```
-
-Then code like the following:
-
-```javascript
-const options = {
-  "config": markdownlint.readConfigSync("./custom.json")
-};
-```
-
-Merges `custom.json` and `base.json` and is equivalent to:
-
-```javascript
-const options = {
-  "config": {
-    "default": true,
-    "line-length": false
-  }
-};
-```
-
-##### options.configParsers
-
-Type: *Optional* `Array` of `Function` taking (`String`) and returning `Object`
-
-Array of functions to parse the content of `markdownlint-configure-file` blocks.
-
-As shown in the [Configuration](#configuration) section, inline comments can be
-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.
-Content is passed to each parser function until one returns a value (vs.
-throwing an exception). As such, strict parsers should come before flexible
-ones.
-
-For example:
-
-```javascript
-[ JSON.parse, require("toml").parse, require("js-yaml").load ]
-```
-
-##### options.customRules
-
-Type: `Array` of `Object`
-
-List of custom rules to include with the default rule set for linting.
-
-Each array element should define a rule. Rules are typically exported
-by another package, but can be defined locally.
-
-Example:
-
-```javascript
-const extraRules = require("extraRules");
-const options = {
-  "customRules": [ extraRules.one, extraRules.two ]
-};
-```
-
-See [CustomRules.md](doc/CustomRules.md) for details about authoring
-custom rules.
-
-##### options.files
-
-Type: `Array` of `String`
-
-List of files to lint.
-
-Each array element should be a single file (via relative or absolute path);
-[globbing](https://wikipedia.org/wiki/Glob_%28programming%29) is the
-caller's responsibility.
-
-Example: `[ "one.md", "dir/two.md" ]`
-
-##### options.frontMatter
-
-Type: `RegExp`
-
-Matches any [front matter](https://jekyllrb.com/docs/frontmatter/)
-found at the beginning of a file.
-
-Some Markdown content begins with metadata; the default `RegExp` for
-this option ignores common forms of "front matter". To match differently,
-specify a custom `RegExp` or use the value `null` to disable the feature.
-
-The default value:
-
-```javascript
-/((^---[^\S\r\n\u2028\u2029]*$[\s\S]+?^---\s*)|(^\+\+\+[^\S\r\n\u2028\u2029]*$[\s\S]+?^(\+\+\+|\.\.\.)\s*)|(^\{[^\S\r\n\u2028\u2029]*$[\s\S]+?^\}\s*))(\r\n|\r|\n|$)/m
-```
-
-Ignores [YAML](https://wikipedia.org/wiki/YAML),
-[TOML](https://wikipedia.org/wiki/TOML), and
-[JSON](https://wikipedia.org/wiki/JSON) front matter such as:
-
-```text
----
-layout: post
-title: Title
----
-```
-
-Note: Matches must occur at the start of the file.
-
-##### options.fs
-
-Type: `Object` implementing the [file system API][node-fs-api]
-
-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 using `node:fs`.
-
-Note: The only methods called are `readFile` and `readFileSync`.
-
-[node-fs-api]: https://nodejs.org/api/fs.html
-
-##### options.handleRuleFailures
-
-Type: `Boolean`
-
-Catches exceptions thrown during rule processing and reports the problem
-as a rule violation.
-
-By default, exceptions thrown by rules (or the library itself) are unhandled
-and bubble up the stack to the caller in the conventional manner. By setting
-`handleRuleFailures` to `true`, exceptions thrown by failing rules will
-be handled by the library and the exception message logged as a rule violation.
-This setting can be useful in the presence of (custom) rules that encounter
-unexpected syntax and fail. By enabling this option, the linting process
-is allowed to continue and report any violations that were found.
-
-##### options.markdownItFactory
-
-Type: `Function` returning an instance of a [`markdown-it` parser][markdown-it]
-
-Provides a factory function for creating instances of the `markdown-it` parser.
-
-Previous versions of the `markdownlint` library declared `markdown-it` as a
-direct dependency. This function makes it possible to avoid that dependency
-entirely. In cases where `markdown-it` is needed, the caller is responsible for
-declaring the dependency and returning an instance from this factory. If any
-[`markdown-it` plugins][markdown-it-plugin] are needed, they should be `use`d by
-the caller before returning the `markdown-it` instance.
-
-For compatibility with previous versions of `markdownlint`, this function should
-be similar to:
-
-```javascript
-import markdownIt from "markdown-it";
-const markdownItFactory = () => markdownIt({ "html": true });
-```
-
-When an asynchronous implementation of `lint` is being invoked (e.g., via
-`markdownlint/async` or `markdownlint/promise`), this function can return a
-`Promise` in order to defer the import of `markdown-it`:
-
-```javascript
-const markdownItFactory = () => import("markdown-it").then((module) => module.default({ "html": true }));
-```
-
-> Note that this function is only invoked when a `markdown-it` parser is
-> needed. None of the built-in rules use the `markdown-it` parser, so it is only
-> invoked when one or more [custom rules][custom-rules] are present that use the
-> `markdown-it` parser.
-
-[custom-rules]: #custom-rules
-[markdown-it]: https://github.com/markdown-it/markdown-it
-[markdown-it-plugin]: https://www.npmjs.com/search?q=keywords:markdown-it-plugin
-
-##### options.noInlineConfig
-
-Type: `Boolean`
-
-Disables the use of HTML comments like `<!-- markdownlint-enable -->` to toggle
-rules within the body of Markdown content.
-
-By default, properly-formatted inline comments can be used to create exceptions
-for parts of a document. Setting `noInlineConfig` to `true` ignores all such
-comments.
-
-##### options.strings
-
-Type: `Object` mapping `String` to `String`
-
-Map of identifiers to strings for linting.
-
-When Markdown content is not available as files, it can be passed as
-strings. The keys of the `strings` object are used to identify each
-input value in the `result` summary.
-
-Example:
-
-```json
-{
-  "readme": "# README\n...",
-  "changelog": "# CHANGELOG\n..."
-}
-```
-
-#### callback
-
-Type: `Function` taking (`Error`, `Object`)
-
-Standard completion callback.
-
-#### result
-
-Type: `Object`
-
-Map of input file names and string identifiers to issues within.
-
-See the [Usage section](#usage) for an example of the structure of this object.
-
-### Config
-
-The `options.config` configuration object is simple and can be stored in a file
-for readability and easy reuse. The `readConfig` function loads configuration
-settings and supports the `extends` keyword for referencing files or packages
-(see above).
-
-By default, configuration files are parsed as JSON (and named
-`.markdownlint.json`). Custom parsers can be provided to handle other formats
-like JSONC, YAML, and TOML.
-
-Asynchronous API via `import { readConfig } from "markdownlint/async"`:
-
-```javascript
-/**
- * Read specified configuration file.
- *
- * @param {string} file Configuration file name.
- * @param {ConfigurationParser[] | ReadConfigCallback} [parsers] Parsing function(s).
- * @param {Object} [fs] File system implementation.
- * @param {ReadConfigCallback} [callback] Callback (err, result) function.
- * @returns {void}
- */
-function readConfig(file, parsers, fs, callback) { ... }
-```
-
-Synchronous API via `import { readConfig } from "markdownlint/sync"`:
-
-```javascript
-/**
- * Read specified configuration file.
- *
- * @param {string} file Configuration file name.
- * @param {ConfigurationParser[]} [parsers] Parsing function(s).
- * @param {Object} [fs] File system implementation.
- * @returns {Configuration} Configuration object.
- */
-function readConfig(file, parsers, fs) { ... }
-```
-
-Promise API via `import { readConfig } from "markdownlint/promise"`:
-
-```javascript
-/**
- * Read specified configuration file.
- *
- * @param {string} file Configuration file name.
- * @param {ConfigurationParser[]} [parsers] Parsing function(s).
- * @param {Object} [fs] File system implementation.
- * @returns {Promise<Configuration>} Configuration object.
- */
-function readConfig(file, parsers, fs) { ... }
-```
-
-#### file
-
-Type: `String`
-
-Location of configuration file to read.
-
-The `file` is resolved relative to the current working directory. If an
-`extends` key is present once read, its value will be resolved as a path
-relative to `file` and loaded recursively. Settings from a file referenced by
-`extends` are applied first, then those of `file` are applied on top (overriding
-any of the same keys appearing in the referenced file). If either the `file` or
-`extends` path begins with the `~` directory, it will act as a placeholder for
-the home directory.
-
-#### parsers
-
-Type: *Optional* `Array` of `Function` taking (`String`) and returning `Object`
-
-Array of functions to parse configuration files.
-
-The contents of a configuration file are passed to each parser function until
-one of them returns a value (vs. throwing an exception). Consequently, strict
-parsers should come before flexible parsers.
-
-For example:
-
-```javascript
-[ JSON.parse, require("toml").parse, require("js-yaml").load ]
-```
-
-#### fs
-
-Type: *Optional* `Object` implementing the [file system API][file-system-api]
-
-[file-system-api]: https://nodejs.org/api/fs.html
-
-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 `node:fs`.
-
-Note: The only methods called are `readFile`, `readFileSync`, `access`, and
-`accessSync`.
-
-#### callback
-
-Type: `Function` taking (`Error`, `Object`)
-
-Standard completion callback.
-
-#### result
-
-Type: `Object`
-
-Configuration object.
-
-### Fixing
-
-Rules that can be fixed automatically include a `fixInfo` property which is
-outlined in the [documentation for custom rules](doc/CustomRules.md#authoring).
-To apply fixes consistently, the `applyFix`/`applyFixes` methods may be used via
-`import { applyFix, applyFixes } from "markdownlint"`:
-
-```javascript
-/**
- * Applies the specified fix to a Markdown content line.
- *
- * @param {string} line Line of Markdown content.
- * @param {RuleOnErrorFixInfo} fixInfo RuleOnErrorFixInfo instance.
- * @param {string} [lineEnding] Line ending to use.
- * @returns {string | null} Fixed content or null if deleted.
- */
-function applyFix(line, fixInfo, lineEnding = "\n") { ... }
-
-/**
- * Applies as many of the specified fixes as possible to Markdown content.
- *
- * @param {string} input Lines of Markdown content.
- * @param {RuleOnErrorInfo[]} errors RuleOnErrorInfo instances.
- * @returns {string} Fixed content.
- */
-function applyFixes(input, errors) { ... }
-```
-
-Invoking `applyFixes` with the results of a call to lint can be done like so:
-
-```javascript
-import { applyFixes } from "markdownlint";
-import { lint as lintSync } from "markdownlint/sync";
-
-const results = lintSync({ "strings": { "content": original } });
-const fixed = applyFixes(original, results.content);
-```
-
-### Miscellaneous
-
-To get the [semantic version][semver] of the library, the `getVersion` method
-can be used:
-
-```javascript
-/**
- * Gets the (semantic) version of the library.
- *
- * @returns {string} SemVer string.
- */
-function getVersion() { ... }
-```
-
-Invoking `getVersion` is simple:
-
-```javascript
-import { getVersion } from "markdownlint";
-
-// Displays the library version
-console.log(getVersion());
-```
-
-[semver]: https://semver.org
-
-## Usage
-
-Invoke `lint` as an asynchronous call:
-
-```javascript
-import { lint as lintAsync } from "markdownlint/async";
-
-const options = {
-  "files": [ "good.md", "bad.md" ],
-  "strings": {
-    "good.string": "# good.string\n\nThis string passes all rules.",
-    "bad.string": "#bad.string\n\n#This string fails\tsome rules."
-  }
-};
-
-lintAsync(options, function callback(error, results) {
-  if (!error && results) {
-    console.dir(results, { "colors": true, "depth": null });
-  }
-});
-```
-
-Or as a synchronous call:
-
-```javascript
-import { lint as lintSync } from "markdownlint/sync";
-
-const results = lintSync(options);
-console.dir(results, { "colors": true, "depth": null });
-```
-
-Or as a `Promise`-based call:
-
-```javascript
-import { lint as lintPromise } from "markdownlint/promise";
-
-const results = await lintPromise(options);
-console.dir(results, { "colors": true, "depth": null });
-```
-
-All of which return an object like:
-
-```json
-{
-  "good.md": [],
-  "bad.md": [
-    { "lineNumber": 3,
-      "ruleNames": [ "MD010", "no-hard-tabs" ],
-      "ruleDescription": "Hard tabs",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.0/doc/md010.md",
-      "errorDetail": "Column: 17",
-      "errorContext": null,
-      "errorRange": [ 17, 1 ],
-      "fixInfo": { "editColumn": 17, "deleteCount": 1, "insertText": " " },
-      "severity": "error" },
-    { "lineNumber": 1,
-      "ruleNames": [ "MD018", "no-missing-space-atx" ],
-      "ruleDescription": "No space after hash on atx style heading",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.0/doc/md018.md",
-      "errorDetail": null,
-      "errorContext": "#bad.md",
-      "errorRange": [ 1, 2 ],
-      "fixInfo": { "editColumn": 2, "insertText": " " },
-      "severity": "error" },
-    { "lineNumber": 3,
-      "ruleNames": [ "MD018", "no-missing-space-atx" ],
-      "ruleDescription": "No space after hash on atx style heading",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.0/doc/md018.md",
-      "errorDetail": null,
-      "errorContext": "#This file fails\tsome rules.",
-      "errorRange": [ 1, 2 ],
-      "fixInfo": { "editColumn": 2, "insertText": " " },
-      "severity": "error" },
-    { "lineNumber": 1,
-      "ruleNames": [ "MD041", "first-line-heading", "first-line-h1" ],
-      "ruleDescription": "First line in a file should be a top-level heading",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.0/doc/md041.md",
-      "errorDetail": null,
-      "errorContext": "#bad.md",
-      "errorRange": null,
-      "fixInfo": null,
-      "severity": "error" }
-  ]
-}
-```
-
-## Browser
-
-`markdownlint` also works in the browser.
-
-Generate normal and minified scripts with:
-
-```bash
-npm run build-demo
-```
-
-Then reference the `markdownlint-browser` script:
-
-```html
-<script src="demo/markdownlint-browser.min.js"></script>
-```
-
-And call it like so:
-
-```javascript
-const options = {
-  "strings": {
-    "content": "Some Markdown to lint."
-  }
-};
-
-const results = globalThis.markdownlint.lintSync(options);
-```
-
-## Examples
-
-For ideas how to integrate `markdownlint` into your workflow, refer to the
-following projects or one of the tools in the [Related section](#related):
-
-- [.NET Documentation][dot-net-doc] ([Search repository][dot-net-doc-search])
-- [ally.js][ally-js] ([Search repository][ally-js-search])
-- [Apache Airflow][airflow] ([Search repository][airflow-search])
-- [CodiMD][codimd] ([Search repository][codimd-search])
-- [Electron][electron] ([Search repository][electron-search])
-- [ESLint][eslint] ([Search repository][eslint-search])
-- [Garden React Components][garden] ([Search repository][garden-search])
-- [MDN Web Docs][mdn] ([Search repository][mdn-search])
-- [MkDocs][mkdocs] ([Search repository][mkdocs-search])
-- [Pi-hole documentation][pi-hole] ([Search repository][pi-hole-search])
-- [Reactable][reactable] ([Search repository][reactable-search])
-- [V8][v8] ([Search repository][v8-search])
-- [webhint][webhint] ([Search repository][webhint-search])
-- [webpack][webpack] ([Search repository][webpack-search])
-- [WordPress][wordpress] ([Search repository][wordpress-search])
-
-For more advanced integration scenarios:
-
-- [GitHub Docs content linter][content-linter]
-- [GitHub's `markdownlint-github` repository][markdownlint-github]
-
-[ally-js]: https://allyjs.io/
-[ally-js-search]: https://github.com/medialize/ally.js/search?q=markdownlint
-[airflow]: https://airflow.apache.org
-[airflow-search]: https://github.com/apache/airflow/search?q=markdownlint
-[codimd]: https://github.com/hackmdio/codimd
-[codimd-search]: https://github.com/hackmdio/codimd/search?q=markdownlint
-[content-linter]: https://docs.github.com/en/contributing/collaborating-on-github-docs/using-the-content-linter
-[dot-net-doc]: https://docs.microsoft.com/en-us/dotnet/
-[dot-net-doc-search]: https://github.com/dotnet/docs/search?q=markdownlint
-[electron]: https://www.electronjs.org
-[electron-search]: https://github.com/electron/electron/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
-[markdownlint-github]: https://github.com/github/markdownlint-github
-[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
-[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
-[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
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
-
-## Releasing
-
-See [ReleaseProcess.md](doc/ReleaseProcess.md) for more information.
-
-## History
-
-See [CHANGELOG.md](CHANGELOG.md).
-
-[npm-image]: https://img.shields.io/npm/v/markdownlint.svg
-[npm-url]: https://www.npmjs.com/package/markdownlint
-[license-image]: https://img.shields.io/npm/l/markdownlint.svg
-[license-url]: https://opensource.org/licenses/MIT