## File: README.md # 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 - **[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 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: `` - Enable all rules: `` - Disable all rules for the current line: `` - Disable all rules for the next line: `` - Disable one or more rules by name: `` - Enable one or more rules by name: `` - Disable one or more rules by name for the current line: `` - Disable one or more rules by name for the next line: `` - Capture the current rule configuration: `` - Restore the captured rule configuration: `` For example: ```markdown space * in * emphasis ``` Or: ```markdown space * in * emphasis ``` Or: ```markdown space * in * emphasis ``` To temporarily disable rule(s), then restore the former configuration: ```markdown any violations you want ``` The initial configuration is captured by default (as if every document began with ``), so the pattern above can be expressed more simply: ```markdown any violations you want ``` Changes take effect starting with the line a comment is on, so the following has no effect: ```markdown space * in * emphasis ``` To apply changes to an entire file regardless of where the comment is located, the following syntax is supported: - Disable all rules: `` - Enable all rules: `` - Disable one or more rules by name: `` - Enable one or more rules by name: `` 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: `` For example: ```markdown ``` or ```markdown ``` 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} 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 `` 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 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.1/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.1/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.1/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.1/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 ``` 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 --- ## File: doc/CustomRules.md # Custom Rules In addition to its built-in rules, `markdownlint` lets you enhance the linting experience by passing an array of custom rules using the [`options.customRules` property][options-custom-rules]. Custom rules can do everything the built-in rules can and are defined inline or imported from another package ([keyword `markdownlint-rule` on npm][markdownlint-rule]). When defined by a file or package, the export can be a single rule object (see below) or an array of them. Custom rules can be disabled, enabled, and customized using the same syntax as built-in rules. ## Implementing Simple Rules For simple requirements like disallowing certain characters or patterns, the community-developed [markdownlint-rule-search-replace][markdownlint-rule-search-replace] plug-in can be used. This plug-in allows anyone to create a set of simple text-replacement rules without needing to write code. [markdownlint-rule-search-replace]: https://www.npmjs.com/package/markdownlint-rule-search-replace ## 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 the rule's behavior. That function is called once for each file/string input and is passed the parsed input and a function to log any violations. Custom rules can (should) operate on a structured set of tokens based on the [`micromark`][micromark] `parser` (this is preferred). Alternatively, custom rules can operate on a structured set of tokens based on the [`markdown-it`][markdown-it] `parser` (legacy support). Finally, custom rules can operate directly on text with the `none` `parser`. A simple rule implementation using the `micromark` parser to report a violation for any use of blockquotes might look like: ```javascript /** @type {import("markdownlint").Rule} */ module.exports = { "names": [ "any-blockquote-micromark" ], "description": "Rule that reports an error for any blockquote", "information": new URL("https://example.com/rules/any-blockquote"), "tags": [ "test" ], "parser": "micromark", "function": (params, onError) => { const blockquotes = params.parsers.micromark.tokens .filter((token) => token.type === "blockQuote"); for (const blockquote of blockquotes) { const lines = blockquote.endLine - blockquote.startLine + 1; onError({ "lineNumber": blockquote.startLine, "detail": "Blockquote spans " + lines + " line(s).", "context": params.lines[blockquote.startLine - 1] }); } } } ``` That same rule implemented using the `markdown-it` parser might look like: ```javascript /** @type {import("markdownlint").Rule} */ module.exports = { "names": [ "any-blockquote-markdown-it" ], "description": "Rule that reports an error for any blockquote", "information": new URL("https://example.com/rules/any-blockquote"), "tags": [ "test" ], "parser": "markdownit", "function": (params, onError) => { const blockquotes = params.parsers.markdownit.tokens .filter((token) => token.type === "blockquote_open"); for (const blockquote of blockquotes) { const [ startIndex, endIndex ] = blockquote.map; const lines = endIndex - startIndex; onError({ "lineNumber": blockquote.lineNumber, "detail": "Blockquote spans " + lines + " line(s).", "context": blockquote.line }); } } } ``` A rule is implemented as an `Object`: - `names` is a required `Array` of `String` values that identify the rule in output messages and config. - `description` is a required `String` value that describes the rule in output messages. - `information` is an optional (absolute) `URL` of a link to more information about the rule. - `tags` is a required `Array` of `String` values that groups related rules for easier customization. - `parser` is a required `String` value `"markdownit" | "micromark" | "none"` that specifies the parser data used via `params.parsers` (see below). - `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. - `parsers` is an `Object` with properties corresponding to the value of `parser` in the rule definition (see above). - `markdownit` is an `Object` that provides access to output from the [`markdown-it`][markdown-it] parser. - `tokens` is an `Array` of [`markdown-it` `Token`s][markdown-it-token] with added `line` and `lineNumber` properties. (This property was previously on the `params` object.) - `micromark` is an `Object` that provides access to output from the [`micromark`][micromark] parser. - `tokens` is an `Array` of [`MicromarkToken`][micromark-token] objects. - Samples for both `tokens` are available via [test snapshots][tokens]. - `lines` is an `Array` of `String` values corresponding to the lines of the input file/string. - `frontMatterLines` is an `Array` of `String` values corresponding to any front matter (not present in `lines`). - `config` is an `Object` corresponding to the rule's entry in `options.config` (if present). - `version` is a `String` that corresponds to the version of `markdownlint` - `onError` is a function that takes a single `Object` parameter with one required and four optional properties: - `lineNumber` is a required `Number` specifying the 1-based line number of 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. - `information` is an optional (absolute) `URL` of a link to override the same-named value provided by the rule definition. (Uncommon) - `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): - `lineNumber` is an optional `Number` specifying the 1-based line number of the edit. - `editColumn` is an optional `Number` specifying the 1-based column number of the edit. - `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 [markdownlint-rule-helpers package][rule-helpers]. ### 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. Asynchronous rules should return a `Promise` from their `function` 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., `import { lint } from "markdownlint/sync"`). Attempting to do so throws an exception. ## Examples - [Simple rules used by the project's test cases][test-rules] - [Code for all `markdownlint` built-in rules][lib] - [Complete example rule including npm configuration][extended-ascii] - [Custom rules from the github/docs repository][github-docs] - [Custom rules from the electron/lint-roller repository][electron] - [Custom rules from the webhintio/hint repository][hint] ## References - [CommonMark documentation and specification][commonmark] - [`markdown-it` Markdown parser project page][markdown-it] [commonmark]: https://commonmark.org/ [electron]: https://github.com/electron/lint-roller/tree/main/markdownlint-rules [extended-ascii]: https://github.com/DavidAnson/markdownlint-rule-extended-ascii [github-docs]: https://github.com/github/docs/tree/main/src/content-linter/lib/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 [micromark]: https://github.com/micromark/micromark [micromark-token]: ../lib/markdownlint.d.mts [rule-helpers]: https://www.npmjs.com/package/markdownlint-rule-helpers [options-custom-rules]: ../README.md#optionscustomrules [test-rules]: ../test/rules [tokens]: ../test/markdownlint-test-custom-rules.mjs.snapshot --- ## File: doc/md001.md # `MD001` - Heading levels should only increment by one level at a time Tags: `headings` Aliases: `heading-increment` Parameters: - `front_matter_title`: RegExp for matching title in front matter (`string`, default `^\s*title\s*[:=]`) This rule is triggered when you skip heading levels in a Markdown document, for example: ```markdown # Heading 1 ### Heading 3 We skipped out a 2nd level heading in this document ``` When using multiple heading levels, nested headings should increase by only one level at a time: ```markdown # Heading 1 ## Heading 2 ### Heading 3 #### Heading 4 ## Another Heading 2 ### Another Heading 3 ``` If [YAML](https://wikipedia.org/wiki/YAML) front matter is present and contains a `title` property (commonly used with blog posts), this rule treats that as a top level heading and will report a violation if the actual first heading is not a level 2 heading. To use a different property name in the front matter, 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`. When front matter is not present, the first heading can be any level. Rationale: Headings represent the structure of a document and can be confusing when skipped - especially for accessibility scenarios. More information: . --- ## File: doc/md003.md # `MD003` - Heading style Tags: `headings` Aliases: `heading-style` Parameters: - `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 are used in the same document: ```markdown # ATX style H1 ## Closed ATX style H2 ## Setext style H1 =============== ``` To fix the issue, use consistent heading styles throughout the document: ```markdown # ATX style H1 ## ATX style H2 ``` The `setext_with_atx` and `setext_with_atx_closed` settings allow ATX-style headings of level 3 or more in documents with setext-style headings (which only support level 1 and 2 headings): ```markdown Setext style H1 =============== Setext style H2 --------------- ### ATX style H3 ``` Note: The configured heading style can be a specific style to require (`atx`, `atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or can require that all heading styles match the first heading style via `consistent`. Note: The placement of a horizontal rule directly below a line of text can trigger this rule by turning that text into a level 2 setext-style heading: ```markdown A line of text followed by a horizontal rule becomes a heading --- ``` Rationale: Consistent formatting makes it easier to understand a document. --- ## File: doc/md004.md # `MD004` - Unordered list style Tags: `bullet`, `ul` Aliases: `ul-style` Parameters: - `style`: List style (`string`, default `consistent`, values `asterisk` / `consistent` / `dash` / `plus` / `sublist`) Fixable: Some violations can be fixed by tooling This rule is triggered when the symbols used in the document for unordered list items do not match the configured unordered list style: ```markdown * Item 1 + Item 2 - Item 3 ``` To fix this issue, use the configured style for list items throughout the document: ```markdown * Item 1 * Item 2 * Item 3 ``` The configured list style can ensure all list styling is a specific symbol (`asterisk`, `plus`, `dash`), ensure each sublist has a consistent symbol that differs from its parent list (`sublist`), or ensure all list styles match the first list style (`consistent`). For example, the following is valid for the `sublist` style because the outer-most indent uses asterisk, the middle indent uses plus, and the inner-most indent uses dash: ```markdown * Item 1 + Item 2 - Item 3 + Item 4 * Item 4 + Item 5 ``` Rationale: Consistent formatting makes it easier to understand a document. --- ## File: doc/md005.md # `MD005` - Inconsistent indentation for list items at the same level Tags: `bullet`, `indentation`, `ul` Aliases: `list-indent` Fixable: Some violations can be fixed by tooling This rule is triggered when list items are parsed as being at the same level, but don't have the same indentation: ```markdown * Item 1 * Nested Item 1 * Nested Item 2 * A misaligned item ``` Usually, this rule will be triggered because of a typo. Correct the indentation for the list to fix it: ```markdown * Item 1 * Nested Item 1 * Nested Item 2 * Nested Item 3 ``` Sequentially-ordered list markers are usually left-aligned such that all items have the same starting column: ```markdown ... 8. Item 9. Item 10. Item 11. Item ... ``` This rule also supports right-alignment of list markers such that all items have the same ending column: ```markdown ... 8. Item 9. Item 10. Item 11. Item ... ``` Rationale: Violations of this rule can lead to improperly rendered content. --- ## File: doc/md007.md # `MD007` - Unordered list indentation Tags: `bullet`, `indentation`, `ul` Aliases: `ul-indent` Parameters: - `indent`: Spaces for indent (`integer`, default `2`) - `start_indent`: Spaces for first level indent (when start_indented is set) (`integer`, default `2`) - `start_indented`: Whether to indent the first level of the list (`boolean`, default `false`) Fixable: Some violations can be fixed by tooling This rule is triggered when list items are not indented by the configured number of spaces (default: 2). Example: ```markdown * List item * Nested list item indented by 3 spaces ``` Corrected Example: ```markdown * List item * Nested list item indented by 2 spaces ``` Note: This rule applies to a sublist only if its parent lists are all also unordered (otherwise, extra indentation of ordered lists interferes with the rule). 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 `start_indent` parameter allows the first level of lists to be indented by a different number of spaces than the rest (ignored when `start_indented` is not set). 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 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 issue for other Markdown parsers, which require 4-space indents. More information: [Markdown Style Guide][markdown-style-guide]. Note: See [Prettier.md](Prettier.md) for compatibility information. [markdown-style-guide]: https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists --- ## File: doc/md009.md # `MD009` - Trailing spaces Tags: `whitespace` Aliases: `no-trailing-spaces` Parameters: - `br_spaces`: Spaces for line break (`integer`, default `2`) - `code_blocks`: Include code blocks (`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`) Fixable: Some violations can be fixed by tooling This rule is triggered on any lines that end with unexpected whitespace. To fix this, remove the trailing space from the end of the line. 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 value allows 2 spaces to indicate a hard break (\ element). (You must set `br_spaces` to a value >= 2 for this parameter to take effect. Setting `br_spaces` to 1 behaves the same as 0, disallowing any trailing spaces.) By default, trailing space is allowed in indented and fenced code blocks because some programming languages require that. To report such instances, set the `code_blocks` parameter to `true`. By default, this rule will not trigger when the allowed number of spaces is used, even when it doesn't create a hard break (for example, at the end of a paragraph). To report such instances, set the `strict` parameter to `true`. ```markdown Text text text text[2 spaces] ``` Using spaces to indent blank lines inside a list item is usually not necessary, but some parsers require it. Set the `list_item_empty_lines` parameter to `true` to allow this (even when `strict` is `true`): ```markdown - list item text [2 spaces] list item text ``` Rationale: Except when being used to create a line break, trailing whitespace has no purpose and does not affect the rendering of content. --- ## File: doc/md010.md # `MD010` - Hard tabs Tags: `hard_tab`, `whitespace` Aliases: `no-hard-tabs` Parameters: - `code_blocks`: Include code blocks (`boolean`, default `true`) - `ignore_code_languages`: Fenced code languages to ignore (`string[]`, default `[]`) - `spaces_per_tab`: Number of spaces for each hard tab (`integer`, default `1`) Fixable: Some violations can be fixed by tooling This rule is triggered by any lines that contain hard tab characters instead of using spaces for indentation. To fix this, replace any hard tab characters with spaces instead. Example: ```markdown Some text * hard tab character used to indent the list item ``` Corrected example: ```markdown Some text * Spaces used to indent the list item instead ``` You have the option to exclude this rule for code blocks and spans. To do so, set the `code_blocks` parameter to `false`. Code blocks and spans are included by default since handling of tabs by Markdown tools can be inconsistent (e.g., using 4 vs. 8 spaces). When code blocks are scanned (e.g., by default or if `code_blocks` is `true`), the `ignore_code_languages` parameter can be set to a list of languages that should be ignored (i.e., hard tabs will be allowed, though not required). This makes it easier for documents to include code for languages that require hard tabs. By default, violations of this rule are fixed by replacing the tab with 1 space character. To use a different number of spaces, set the `spaces_per_tab` parameter to the desired value. Rationale: Hard tabs are often rendered inconsistently by different editors and can be harder to work with than spaces. More information: - - --- ## File: doc/md011.md # `MD011` - Reversed link syntax Tags: `links` Aliases: `no-reversed-links` Fixable: Some violations can be fixed by tooling This rule is triggered when text that appears to be a link is encountered, but where the syntax appears to have been reversed (the `[]` and `()` are reversed): ```markdown (Incorrect link syntax)[https://www.example.com/] ``` To fix this, swap the `[]` and `()` around: ```markdown [Correct link syntax](https://www.example.com/) ``` Note: [Markdown Extra](https://wikipedia.org/wiki/Markdown_Extra)-style footnotes do not trigger this rule: ```markdown For (example)[^1] ``` Rationale: Reversed links are not rendered as usable links.