{"id":15034665,"url":"https://github.com/davidanson/markdownlint","last_synced_at":"2025-09-09T20:57:30.053Z","repository":{"id":28725667,"uuid":"32246828","full_name":"DavidAnson/markdownlint","owner":"DavidAnson","description":"A Node.js style checker and lint tool for Markdown/CommonMark files.","archived":false,"fork":false,"pushed_at":"2025-05-05T06:44:49.000Z","size":32915,"stargazers_count":5129,"open_issues_count":72,"forks_count":760,"subscribers_count":66,"default_branch":"main","last_synced_at":"2025-05-05T20:45:57.608Z","etag":null,"topics":["commonmark","lint","markdown","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DavidAnson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"DavidAnson"}},"created_at":"2015-03-15T05:37:49.000Z","updated_at":"2025-05-04T15:46:19.000Z","dependencies_parsed_at":"2023-01-16T22:16:33.913Z","dependency_job_id":"b82f7fd1-2376-4afe-b0c2-c0e897bd452a","html_url":"https://github.com/DavidAnson/markdownlint","commit_stats":{"total_commits":1551,"total_committers":53,"mean_commits":"29.264150943396228","dds":"0.25725338491295935","last_synced_commit":"b2305efafb034b1f328845aec9928b5363ffd646"},"previous_names":[],"tags_count":76,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidAnson%2Fmarkdownlint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidAnson%2Fmarkdownlint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidAnson%2Fmarkdownlint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidAnson%2Fmarkdownlint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DavidAnson","download_url":"https://codeload.github.com/DavidAnson/markdownlint/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253929323,"owners_count":21985801,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["commonmark","lint","markdown","nodejs"],"created_at":"2024-09-24T20:25:56.100Z","updated_at":"2025-05-13T10:55:27.553Z","avatar_url":"https://github.com/DavidAnson.png","language":"JavaScript","funding_links":["https://github.com/sponsors/DavidAnson"],"categories":[],"sub_categories":[],"readme":"# markdownlint\n\n\u003e A Node.js style checker and lint tool for Markdown/CommonMark files.\n\n[![npm version][npm-image]][npm-url]\n[![License][license-image]][license-url]\n\n## Install\n\n```bash\nnpm install markdownlint --save-dev\n```\n\n## Overview\n\nThe [Markdown][markdown] markup language is designed to be easy to read, write,\nand understand. It succeeds - and its flexibility is both a benefit and a\ndrawback. Many styles are possible, so formatting can be inconsistent; some\nconstructs don't work well in all parsers and should be avoided.\n\n`markdownlint` is a [static analysis][static-analysis] tool for\n[Node.js][nodejs] with a library of rules to enforce standards and consistency\nfor Markdown files. It was inspired by - and heavily influenced by - Mark\nHarrison's [markdownlint][markdownlint-ruby] for Ruby. The initial rules, rule\ndocumentation, and test cases came from that project.\n\n`markdownlint` uses the [`micromark` parser][micromark] and honors the\n[CommonMark][commonmark] specification for Markdown. It additionally supports\npopular [GitHub Flavored Markdown (GFM)][gfm] syntax like autolinks and tables\nas well as directives, footnotes, and math syntax - all implemented by\n[`micromark` extensions][micromark-extensions].\n\n[commonmark]: https://commonmark.org/\n[gfm]: https://github.github.com/gfm/\n[markdown]: https://en.wikipedia.org/wiki/Markdown\n[markdownlint-ruby]: https://github.com/markdownlint/markdownlint\n[micromark]: https://github.com/micromark/micromark\n[micromark-extensions]: https://github.com/micromark/micromark?tab=readme-ov-file#list-of-extensions\n[nodejs]: https://nodejs.org/\n[static-analysis]: https://en.wikipedia.org/wiki/Static_program_analysis\n\n### Related\n\n- CLI\n  - [markdownlint-cli][markdownlint-cli] command-line interface for Node.js\n    ([works with pre-commit][markdownlint-cli-precommit])\n  - [markdownlint-cli2][markdownlint-cli2] command-line interface for Node.js\n    ([works with pre-commit][markdownlint-cli2-precommit])\n- GitHub\n  - [GitHub Action for markdownlint-cli2][markdownlint-cli2-action]\n  - [GitHub Super-Linter Action][super-linter]\n  - [GitHub Actions problem matcher for\n    markdownlint-cli][markdownlint-problem-matcher]\n- Editor\n  - [vscode-markdownlint extension for VS Code][vscode-markdownlint]\n  - [Sublime Text markdownlint for Sublime Text][sublimelinter]\n  - [coc-markdownlint extension for Vim/Neovim][coc]\n  - [flymake-markdownlint-cli2 extension for Emacs][emacs-flymake]\n- Tooling\n  - [eslint-plugin-markdownlint for the ESLint analyzer][eslint-plugin]\n  - [grunt-markdownlint for the Grunt task runner][grunt-markdownlint]\n  - [Cake.Markdownlint addin for Cake build automation system][cake]\n  - [Lombiq Node.js Extensions for MSBuild (.NET builds)][nodejs-extensions]\n- Ruby\n  - [markdownlint/mdl gem for Ruby][rubygems-mdl]\n\n[cake]: https://github.com/cake-contrib/Cake.Markdownlint\n[coc]: https://github.com/fannheyward/coc-markdownlint\n[emacs-flymake]: https://github.com/ewilderj/flymake-markdownlint-cli2\n[eslint-plugin]: https://github.com/paweldrozd/eslint-plugin-markdownlint\n[grunt-markdownlint]: https://github.com/sagiegurari/grunt-markdownlint\n[markdownlint-cli]: https://github.com/igorshubovych/markdownlint-cli\n[markdownlint-cli-precommit]: https://github.com/igorshubovych/markdownlint-cli#use-with-pre-commit\n[markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2\n[markdownlint-cli2-action]: https://github.com/marketplace/actions/markdownlint-cli2-action\n[markdownlint-cli2-precommit]: https://github.com/DavidAnson/markdownlint-cli2#pre-commit\n[markdownlint-problem-matcher]: https://github.com/xt0rted/markdownlint-problem-matcher\n[nodejs-extensions]: https://github.com/Lombiq/NodeJs-Extensions\n[rubygems-mdl]: https://rubygems.org/gems/mdl\n[sublimelinter]: https://github.com/jonlabelle/SublimeLinter-contrib-markdownlint\n[super-linter]: https://github.com/super-linter/super-linter\n[vscode-markdownlint]: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint\n\n### References\n\nThe following specifications are considered authoritative in cases of ambiguity:\n\n- [CommonMark](https://spec.commonmark.org/current/)\n- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)\n\n## Demonstration\n\n[`markdownlint` demo](https://dlaa.me/markdownlint/), an interactive, in-browser\nplayground for learning and exploring.\n\n## Rules / Aliases\n\n\u003c!-- markdownlint-disable line-length --\u003e\n\n- **[MD001](doc/md001.md)** *heading-increment* - Heading levels should only increment by one level at a time\n- **[MD003](doc/md003.md)** *heading-style* - Heading style\n- **[MD004](doc/md004.md)** *ul-style* - Unordered list style\n- **[MD005](doc/md005.md)** *list-indent* - Inconsistent indentation for list items at the same level\n- **[MD007](doc/md007.md)** *ul-indent* - Unordered list indentation\n- **[MD009](doc/md009.md)** *no-trailing-spaces* - Trailing spaces\n- **[MD010](doc/md010.md)** *no-hard-tabs* - Hard tabs\n- **[MD011](doc/md011.md)** *no-reversed-links* - Reversed link syntax\n- **[MD012](doc/md012.md)** *no-multiple-blanks* - Multiple consecutive blank lines\n- **[MD013](doc/md013.md)** *line-length* - Line length\n- **[MD014](doc/md014.md)** *commands-show-output* - Dollar signs used before commands without showing output\n- **[MD018](doc/md018.md)** *no-missing-space-atx* - No space after hash on atx style heading\n- **[MD019](doc/md019.md)** *no-multiple-space-atx* - Multiple spaces after hash on atx style heading\n- **[MD020](doc/md020.md)** *no-missing-space-closed-atx* - No space inside hashes on closed atx style heading\n- **[MD021](doc/md021.md)** *no-multiple-space-closed-atx* - Multiple spaces inside hashes on closed atx style heading\n- **[MD022](doc/md022.md)** *blanks-around-headings* - Headings should be surrounded by blank lines\n- **[MD023](doc/md023.md)** *heading-start-left* - Headings must start at the beginning of the line\n- **[MD024](doc/md024.md)** *no-duplicate-heading* - Multiple headings with the same content\n- **[MD025](doc/md025.md)** *single-title/single-h1* - Multiple top-level headings in the same document\n- **[MD026](doc/md026.md)** *no-trailing-punctuation* - Trailing punctuation in heading\n- **[MD027](doc/md027.md)** *no-multiple-space-blockquote* - Multiple spaces after blockquote symbol\n- **[MD028](doc/md028.md)** *no-blanks-blockquote* - Blank line inside blockquote\n- **[MD029](doc/md029.md)** *ol-prefix* - Ordered list item prefix\n- **[MD030](doc/md030.md)** *list-marker-space* - Spaces after list markers\n- **[MD031](doc/md031.md)** *blanks-around-fences* - Fenced code blocks should be surrounded by blank lines\n- **[MD032](doc/md032.md)** *blanks-around-lists* - Lists should be surrounded by blank lines\n- **[MD033](doc/md033.md)** *no-inline-html* - Inline HTML\n- **[MD034](doc/md034.md)** *no-bare-urls* - Bare URL used\n- **[MD035](doc/md035.md)** *hr-style* - Horizontal rule style\n- **[MD036](doc/md036.md)** *no-emphasis-as-heading* - Emphasis used instead of a heading\n- **[MD037](doc/md037.md)** *no-space-in-emphasis* - Spaces inside emphasis markers\n- **[MD038](doc/md038.md)** *no-space-in-code* - Spaces inside code span elements\n- **[MD039](doc/md039.md)** *no-space-in-links* - Spaces inside link text\n- **[MD040](doc/md040.md)** *fenced-code-language* - Fenced code blocks should have a language specified\n- **[MD041](doc/md041.md)** *first-line-heading/first-line-h1* - First line in a file should be a top-level heading\n- **[MD042](doc/md042.md)** *no-empty-links* - No empty links\n- **[MD043](doc/md043.md)** *required-headings* - Required heading structure\n- **[MD044](doc/md044.md)** *proper-names* - Proper names should have the correct capitalization\n- **[MD045](doc/md045.md)** *no-alt-text* - Images should have alternate text (alt text)\n- **[MD046](doc/md046.md)** *code-block-style* - Code block style\n- **[MD047](doc/md047.md)** *single-trailing-newline* - Files should end with a single newline character\n- **[MD048](doc/md048.md)** *code-fence-style* - Code fence style\n- **[MD049](doc/md049.md)** *emphasis-style* - Emphasis style\n- **[MD050](doc/md050.md)** *strong-style* - Strong style\n- **[MD051](doc/md051.md)** *link-fragments* - Link fragments should be valid\n- **[MD052](doc/md052.md)** *reference-links-images* - Reference links and images should use a label that is defined\n- **[MD053](doc/md053.md)** *link-image-reference-definitions* - Link and image reference definitions should be needed\n- **[MD054](doc/md054.md)** *link-image-style* - Link and image style\n- **[MD055](doc/md055.md)** *table-pipe-style* - Table pipe style\n- **[MD056](doc/md056.md)** *table-column-count* - Table column count\n- **[MD058](doc/md058.md)** *blanks-around-tables* - Tables should be surrounded by blank lines\n- **[MD059](doc/md059.md)** *descriptive-link-text* - Link text should be descriptive\n\n\u003c!-- markdownlint-restore --\u003e\n\nSee [Rules.md](doc/Rules.md) for more details.\n\n### Custom Rules\n\nIn addition to built-in rules, custom rules can be used to address\nproject-specific requirements. To find community-developed rules use\n[keyword `markdownlint-rule` on npm][markdownlint-rule].\nTo implement your own rules, refer to [CustomRules.md](doc/CustomRules.md).\n\n[markdownlint-rule]: https://www.npmjs.com/search?q=keywords:markdownlint-rule\n\n## Tags\n\nTags group related rules and can be used to enable/disable multiple\nrules at once.\n\n- **`accessibility`** - `MD045`, `MD059`\n- **`atx`** - `MD018`, `MD019`\n- **`atx_closed`** - `MD020`, `MD021`\n- **`blank_lines`** - `MD012`, `MD022`, `MD031`, `MD032`, `MD047`\n- **`blockquote`** - `MD027`, `MD028`\n- **`bullet`** - `MD004`, `MD005`, `MD007`, `MD032`\n- **`code`** - `MD014`, `MD031`, `MD038`, `MD040`, `MD046`, `MD048`\n- **`emphasis`** - `MD036`, `MD037`, `MD049`, `MD050`\n- **`hard_tab`** - `MD010`\n- **`headings`** - `MD001`, `MD003`, `MD018`, `MD019`, `MD020`, `MD021`,\n  `MD022`, `MD023`, `MD024`, `MD025`, `MD026`, `MD036`, `MD041`, `MD043`\n- **`hr`** - `MD035`\n- **`html`** - `MD033`\n- **`images`** - `MD045`, `MD052`, `MD053`, `MD054`\n- **`indentation`** - `MD005`, `MD007`, `MD027`\n- **`language`** - `MD040`\n- **`line_length`** - `MD013`\n- **`links`** - `MD011`, `MD034`, `MD039`, `MD042`, `MD051`, `MD052`, `MD053`,\n  `MD054`, `MD059`\n- **`ol`** - `MD029`, `MD030`, `MD032`\n- **`spaces`** - `MD018`, `MD019`, `MD020`, `MD021`, `MD023`\n- **`spelling`** - `MD044`\n- **`table`** - `MD055`, `MD056`, `MD058`\n- **`ul`** - `MD004`, `MD005`, `MD007`, `MD030`, `MD032`\n- **`url`** - `MD034`\n- **`whitespace`** - `MD009`, `MD010`, `MD012`, `MD027`, `MD028`, `MD030`,\n  `MD037`, `MD038`, `MD039`\n\n## Configuration\n\nText passed to `markdownlint` is parsed as Markdown, analyzed, and any\nissues reported. Two kinds of text are ignored by most rules:\n\n- [HTML comments](https://www.w3.org/TR/html5/syntax.html#comments)\n- [Front matter](https://jekyllrb.com/docs/frontmatter/) (see\n  `options.frontMatter` below)\n\nRules can be enabled, disabled, and configured via `options.config`\n(described below) to define the expected behavior for a set of inputs.\nTo enable or disable rules at a particular location within a file, add\none of these markers to the appropriate place (HTML comments don't\nappear in the final markup):\n\n- Disable all rules: `\u003c!-- markdownlint-disable --\u003e`\n- Enable all rules: `\u003c!-- markdownlint-enable --\u003e`\n- Disable all rules for the current line: `\u003c!-- markdownlint-disable-line --\u003e`\n- Disable all rules for the next line: `\u003c!-- markdownlint-disable-next-line --\u003e`\n- Disable one or more rules by name: `\u003c!-- markdownlint-disable MD001 MD005 --\u003e`\n- Enable one or more rules by name: `\u003c!-- markdownlint-enable MD001 MD005 --\u003e`\n- Disable one or more rules by name for the current line:\n  `\u003c!-- markdownlint-disable-line MD001 MD005 --\u003e`\n- Disable one or more rules by name for the next line:\n  `\u003c!-- markdownlint-disable-next-line MD001 MD005 --\u003e`\n- Capture the current rule configuration: `\u003c!-- markdownlint-capture --\u003e`\n- Restore the captured rule configuration: `\u003c!-- markdownlint-restore --\u003e`\n\nFor example:\n\n```markdown\n\u003c!-- markdownlint-disable-next-line no-space-in-emphasis --\u003e\nspace * in * emphasis\n```\n\nOr:\n\n```markdown\nspace * in * emphasis \u003c!-- markdownlint-disable-line no-space-in-emphasis --\u003e\n```\n\nOr:\n\n```markdown\n\u003c!-- markdownlint-disable no-space-in-emphasis --\u003e\nspace * in * emphasis\n\u003c!-- markdownlint-enable no-space-in-emphasis --\u003e\n```\n\nTo temporarily disable rule(s), then restore the former configuration:\n\n```markdown\n\u003c!-- markdownlint-capture --\u003e\n\u003c!-- markdownlint-disable --\u003e\nany violations you want\n\u003c!-- markdownlint-restore --\u003e\n```\n\nThe initial configuration is captured by default (as if every document\nbegan with `\u003c!-- markdownlint-capture --\u003e`), so the pattern above can\nbe expressed more simply:\n\n```markdown\n\u003c!-- markdownlint-disable --\u003e\nany violations you want\n\u003c!-- markdownlint-restore --\u003e\n```\n\nChanges take effect starting with the line a comment is on, so the following\nhas no effect:\n\n```markdown\nspace * in * emphasis \u003c!-- markdownlint-disable --\u003e \u003c!-- markdownlint-enable --\u003e\n```\n\nTo apply changes to an entire file regardless of where the comment is located,\nthe following syntax is supported:\n\n- Disable all rules: `\u003c!-- markdownlint-disable-file --\u003e`\n- Enable all rules: `\u003c!-- markdownlint-enable-file --\u003e`\n- Disable one or more rules by name: `\u003c!-- markdownlint-disable-file MD001 --\u003e`\n- Enable one or more rules by name: `\u003c!-- markdownlint-enable-file MD001 --\u003e`\n\nThis can be used to \"hide\" `markdownlint` comments at the bottom of a file.\n\nIn cases where it is desirable to change the configuration of one or\nmore rules for a file, the following more advanced syntax is supported:\n\n- Configure: `\u003c!-- markdownlint-configure-file { options.config JSON } --\u003e`\n\nFor example:\n\n```markdown\n\u003c!-- markdownlint-configure-file { \"hr-style\": { \"style\": \"---\" } } --\u003e\n```\n\nor\n\n```markdown\n\u003c!-- markdownlint-configure-file\n{\n  \"hr-style\": {\n    \"style\": \"---\"\n  },\n  \"no-trailing-spaces\": false\n}\n--\u003e\n```\n\nThese changes apply to the entire file regardless of where the comment is\nlocated. Multiple such comments (if present) are applied top-to-bottom. By\ndefault, content of `markdownlint-configure-file` is assumed to be JSON, but\n[`options.configParsers`](#optionsconfigparsers) can be used to support\nalternate formats.\n\n## API\n\n### Linting\n\nAsynchronous API via `import { lint } from \"markdownlint/async\"`:\n\n```javascript\n/**\n * Lint specified Markdown files.\n *\n * @param {Options | null} options Configuration options.\n * @param {LintCallback} callback Callback (err, result) function.\n * @returns {void}\n */\nfunction lint(options, callback) { ... }\n```\n\nSynchronous API via `import { lint } from \"markdownlint/sync\"`:\n\n```javascript\n/**\n * Lint specified Markdown files.\n *\n * @param {Options | null} options Configuration options.\n * @returns {LintResults} Results object.\n */\nfunction lint(options) { ... }\n```\n\nPromise API via `import { lint } from \"markdownlint/promise\"`:\n\n```javascript\n/**\n * Lint specified Markdown files.\n *\n * @param {Options | null} options Configuration options.\n * @returns {Promise\u003cLintResults\u003e} Results object.\n */\nfunction lint(options) { ... }\n```\n\n#### options\n\nType: `Object`\n\nConfigures the function. All properties are optional, but at least one\nof `files` or `strings` should be set to provide input.\n\n##### options.config\n\nType: `Object` mapping `String` to `Boolean | Object`\n\nConfigures the rules to use.\n\nObject keys are rule names/aliases; object values are the rule's configuration.\nThe value `false` disables a rule, `true` enables its default configuration,\nand passing an object value customizes that rule. Setting the special `default`\nrule to `true` or `false` includes/excludes all rules by default. In the absence\nof a configuration object, all rules are enabled. Enabling or disabling a tag\nname (ex: `whitespace`) affects all rules having that tag.\n\nThe `default` rule is applied first, then keys are processed in order from top\nto bottom with later values overriding earlier ones. Keys (including rule names,\naliases, tags, and `default`) are not case-sensitive.\n\nExample:\n\n```json\n{\n  \"default\": true,\n  \"MD003\": { \"style\": \"atx_closed\" },\n  \"MD007\": { \"indent\": 4 },\n  \"no-hard-tabs\": false,\n  \"whitespace\": false\n}\n```\n\nSee [.markdownlint.jsonc](schema/.markdownlint.jsonc) and/or\n[.markdownlint.yaml](schema/.markdownlint.yaml) for an example\nconfiguration object with all properties set to the default value.\n\nSets of rules (known as a \"style\") can be stored separately and loaded\nas [JSON](https://en.wikipedia.org/wiki/JSON).\n\nExample of referencing a built-in style from JavaScript:\n\n```javascript\nconst options = {\n  \"files\": [ \"...\" ],\n  \"config\": require(\"style/relaxed.json\")\n};\n```\n\nExample doing so from `.markdownlint.json` via `extends` (more on this below):\n\n```json\n{\n  \"extends\": \"markdownlint/style/relaxed\"\n}\n```\n\nSee the [style](style) directory for more samples.\n\nSee [markdownlint-config-schema.json](schema/markdownlint-config-schema.json)\nfor the [JSON Schema](https://json-schema.org/) of the `options.config`\nobject.\n\nSee [ValidatingConfiguration.md](schema/ValidatingConfiguration.md) for ways to\nuse the JSON Schema to validate configuration.\n\nFor more advanced scenarios, styles can reference and build upon other styles\nvia the `extends` keyword and a file path or (installed) package name. The\n`readConfig` function can be used to read such aggregate styles from code.\n\nFor example, assuming a `base.json` configuration file:\n\n```json\n{\n  \"default\": true\n}\n```\n\nAnd a `custom.json` configuration file:\n\n```json\n{\n  \"extends\": \"base.json\",\n  \"line-length\": false\n}\n```\n\nThen code like the following:\n\n```javascript\nconst options = {\n  \"config\": markdownlint.readConfigSync(\"./custom.json\")\n};\n```\n\nMerges `custom.json` and `base.json` and is equivalent to:\n\n```javascript\nconst options = {\n  \"config\": {\n    \"default\": true,\n    \"line-length\": false\n  }\n};\n```\n\n##### options.configParsers\n\nType: *Optional* `Array` of `Function` taking (`String`) and returning `Object`\n\nArray of functions to parse the content of `markdownlint-configure-file` blocks.\n\nAs shown in the [Configuration](#configuration) section, inline comments can be\nused to customize the [configuration object](#optionsconfig) for a document. By\ndefault, the `JSON.parse` built-in is used, but custom parsers can be specified.\nContent is passed to each parser function until one returns a value (vs.\nthrowing an exception). As such, strict parsers should come before flexible\nones.\n\nFor example:\n\n```javascript\n[ JSON.parse, require(\"toml\").parse, require(\"js-yaml\").load ]\n```\n\n##### options.customRules\n\nType: `Array` of `Object`\n\nList of custom rules to include with the default rule set for linting.\n\nEach array element should define a rule. Rules are typically exported\nby another package, but can be defined locally.\n\nExample:\n\n```javascript\nconst extraRules = require(\"extraRules\");\nconst options = {\n  \"customRules\": [ extraRules.one, extraRules.two ]\n};\n```\n\nSee [CustomRules.md](doc/CustomRules.md) for details about authoring\ncustom rules.\n\n##### options.files\n\nType: `Array` of `String`\n\nList of files to lint.\n\nEach array element should be a single file (via relative or absolute path);\n[globbing](https://en.wikipedia.org/wiki/Glob_%28programming%29) is the\ncaller's responsibility.\n\nExample: `[ \"one.md\", \"dir/two.md\" ]`\n\n##### options.frontMatter\n\nType: `RegExp`\n\nMatches any [front matter](https://jekyllrb.com/docs/frontmatter/)\nfound at the beginning of a file.\n\nSome Markdown content begins with metadata; the default `RegExp` for\nthis option ignores common forms of \"front matter\". To match differently,\nspecify a custom `RegExp` or use the value `null` to disable the feature.\n\nThe default value:\n\n```javascript\n/((^---[^\\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\n```\n\nIgnores [YAML](https://en.wikipedia.org/wiki/YAML),\n[TOML](https://en.wikipedia.org/wiki/TOML), and\n[JSON](https://en.wikipedia.org/wiki/JSON) front matter such as:\n\n```text\n---\nlayout: post\ntitle: Title\n---\n```\n\nNote: Matches must occur at the start of the file.\n\n##### options.fs\n\nType: `Object` implementing the [file system API][node-fs-api]\n\nIn advanced scenarios, it may be desirable to bypass the default file system\nAPI. If a custom file system implementation is provided, `markdownlint` will use\nthat instead of using `node:fs`.\n\nNote: The only methods called are `readFile` and `readFileSync`.\n\n[node-fs-api]: https://nodejs.org/api/fs.html\n\n##### options.handleRuleFailures\n\nType: `Boolean`\n\nCatches exceptions thrown during rule processing and reports the problem\nas a rule violation.\n\nBy default, exceptions thrown by rules (or the library itself) are unhandled\nand bubble up the stack to the caller in the conventional manner. By setting\n`handleRuleFailures` to `true`, exceptions thrown by failing rules will\nbe handled by the library and the exception message logged as a rule violation.\nThis setting can be useful in the presence of (custom) rules that encounter\nunexpected syntax and fail. By enabling this option, the linting process\nis allowed to continue and report any violations that were found.\n\n##### options.markdownItFactory\n\nType: `Function` returning an instance of a [`markdown-it` parser][markdown-it]\n\nProvides a factory function for creating instances of the `markdown-it` parser.\n\nPrevious versions of the `markdownlint` library declared `markdown-it` as a\ndirect dependency. This function makes it possible to avoid that dependency\nentirely. In cases where `markdown-it` is needed, the caller is responsible for\ndeclaring the dependency and returning an instance from this factory. If any\n[`markdown-it` plugins][markdown-it-plugin] are needed, they should be `use`d by\nthe caller before returning the `markdown-it` instance.\n\nFor compatibility with previous versions of `markdownlint`, this function should\nbe similar to:\n\n```javascript\nimport markdownIt from \"markdown-it\";\nconst markdownItFactory = () =\u003e markdownIt({ \"html\": true });\n```\n\nWhen an asynchronous implementation of `lint` is being invoked (e.g., via\n`markdownlint/async` or `markdownlint/promise`), this function can return a\n`Promise` in order to defer the import of `markdown-it`:\n\n```javascript\nconst markdownItFactory = () =\u003e import(\"markdown-it\").then((module) =\u003e module.default({ \"html\": true }));\n```\n\n\u003e Note that this function is only invoked when a `markdown-it` parser is\n\u003e needed. None of the built-in rules use the `markdown-it` parser, so it is only\n\u003e invoked when one or more [custom rules][custom-rules] are present that use the\n\u003e `markdown-it` parser.\n\n[custom-rules]: #custom-rules\n[markdown-it]: https://github.com/markdown-it/markdown-it\n[markdown-it-plugin]: https://www.npmjs.com/search?q=keywords:markdown-it-plugin\n\n##### options.noInlineConfig\n\nType: `Boolean`\n\nDisables the use of HTML comments like `\u003c!-- markdownlint-enable --\u003e` to toggle\nrules within the body of Markdown content.\n\nBy default, properly-formatted inline comments can be used to create exceptions\nfor parts of a document. Setting `noInlineConfig` to `true` ignores all such\ncomments.\n\n##### options.resultVersion\n\nType: `Number`\n\nSpecifies which version of the `result` object to return (see the \"Usage\"\nsection below for examples).\n\nPassing a `resultVersion` of `0` corresponds to the original, simple format\nwhere each error is identified by rule name and line number. *Deprecated*\n\nPassing a `resultVersion` of `1` corresponds to a detailed format where each\nerror includes information about the line number, rule name, alias, description,\nas well as any additional detail or context that is available. *Deprecated*\n\nPassing a `resultVersion` of `2` corresponds to a detailed format where each\nerror includes information about the line number, rule names, description, as\nwell as any additional detail or context that is available. *Deprecated*\n\nPassing a `resultVersion` of `3` corresponds to the detailed version `2` format\nwith additional information about how to fix automatically-fixable errors. In\nthis mode, all errors that occur on each line are reported (other versions\nreport only the first error for each rule). This is the default behavior.\n\n##### options.strings\n\nType: `Object` mapping `String` to `String`\n\nMap of identifiers to strings for linting.\n\nWhen Markdown content is not available as files, it can be passed as\nstrings. The keys of the `strings` object are used to identify each\ninput value in the `result` summary.\n\nExample:\n\n```json\n{\n  \"readme\": \"# README\\n...\",\n  \"changelog\": \"# CHANGELOG\\n...\"\n}\n```\n\n#### callback\n\nType: `Function` taking (`Error`, `Object`)\n\nStandard completion callback.\n\n#### result\n\nType: `Object`\n\nCall `result.toString()` for convenience or see below for an example of the\nstructure of the `result` object. Passing the value `true` to `toString()`\nuses rule aliases (ex: `no-hard-tabs`) instead of names (ex: `MD010`).\n\n### Config\n\nThe `options.config` configuration object is simple and can be stored in a file\nfor readability and easy reuse. The `readConfig` function loads configuration\nsettings and supports the `extends` keyword for referencing files or packages\n(see above).\n\nBy default, configuration files are parsed as JSON (and named\n`.markdownlint.json`). Custom parsers can be provided to handle other formats\nlike JSONC, YAML, and TOML.\n\nAsynchronous API via `import { readConfig } from \"markdownlint/async\"`:\n\n```javascript\n/**\n * Read specified configuration file.\n *\n * @param {string} file Configuration file name.\n * @param {ConfigurationParser[] | ReadConfigCallback} [parsers] Parsing function(s).\n * @param {Object} [fs] File system implementation.\n * @param {ReadConfigCallback} [callback] Callback (err, result) function.\n * @returns {void}\n */\nfunction readConfig(file, parsers, fs, callback) { ... }\n```\n\nSynchronous API via `import { readConfig } from \"markdownlint/sync\"`:\n\n```javascript\n/**\n * Read specified configuration file.\n *\n * @param {string} file Configuration file name.\n * @param {ConfigurationParser[]} [parsers] Parsing function(s).\n * @param {Object} [fs] File system implementation.\n * @returns {Configuration} Configuration object.\n */\nfunction readConfig(file, parsers, fs) { ... }\n```\n\nPromise API via `import { readConfig } from \"markdownlint/promise\"`:\n\n```javascript\n/**\n * Read specified configuration file.\n *\n * @param {string} file Configuration file name.\n * @param {ConfigurationParser[]} [parsers] Parsing function(s).\n * @param {Object} [fs] File system implementation.\n * @returns {Promise\u003cConfiguration\u003e} Configuration object.\n */\nfunction readConfig(file, parsers, fs) { ... }\n```\n\n#### file\n\nType: `String`\n\nLocation of configuration file to read.\n\nThe `file` is resolved relative to the current working directory. If an\n`extends` key is present once read, its value will be resolved as a path\nrelative to `file` and loaded recursively. Settings from a file referenced by\n`extends` are applied first, then those of `file` are applied on top (overriding\nany of the same keys appearing in the referenced file). If either the `file` or\n`extends` path begins with the `~` directory, it will act as a placeholder for\nthe home directory.\n\n#### parsers\n\nType: *Optional* `Array` of `Function` taking (`String`) and returning `Object`\n\nArray of functions to parse configuration files.\n\nThe contents of a configuration file are passed to each parser function until\none of them returns a value (vs. throwing an exception). Consequently, strict\nparsers should come before flexible parsers.\n\nFor example:\n\n```javascript\n[ JSON.parse, require(\"toml\").parse, require(\"js-yaml\").load ]\n```\n\n#### fs\n\nType: *Optional* `Object` implementing the [file system API][file-system-api]\n\n[file-system-api]: https://nodejs.org/api/fs.html\n\nIn advanced scenarios, it may be desirable to bypass the default file system\nAPI. If a custom file system implementation is provided, `markdownlint` will use\nthat instead of invoking `node:fs`.\n\nNote: The only methods called are `readFile`, `readFileSync`, `access`, and\n`accessSync`.\n\n#### callback\n\nType: `Function` taking (`Error`, `Object`)\n\nStandard completion callback.\n\n#### result\n\nType: `Object`\n\nConfiguration object.\n\n### Fixing\n\nRules that can be fixed automatically include a `fixInfo` property which is\noutlined in the [documentation for custom rules](doc/CustomRules.md#authoring).\nTo apply fixes consistently, the `applyFix`/`applyFixes` methods may be used via\n`import { applyFix, applyFixes } from \"markdownlint\"`:\n\n```javascript\n/**\n * Applies the specified fix to a Markdown content line.\n *\n * @param {string} line Line of Markdown content.\n * @param {RuleOnErrorFixInfo} fixInfo RuleOnErrorFixInfo instance.\n * @param {string} [lineEnding] Line ending to use.\n * @returns {string | null} Fixed content or null if deleted.\n */\nfunction applyFix(line, fixInfo, lineEnding = \"\\n\") { ... }\n\n/**\n * Applies as many of the specified fixes as possible to Markdown content.\n *\n * @param {string} input Lines of Markdown content.\n * @param {RuleOnErrorInfo[]} errors RuleOnErrorInfo instances.\n * @returns {string} Fixed content.\n */\nfunction applyFixes(input, errors) { ... }\n```\n\nInvoking `applyFixes` with the results of a call to lint can be done like so:\n\n```javascript\nimport { applyFixes } from \"markdownlint\";\nimport { lint as lintSync } from \"markdownlint/sync\";\n\nconst results = lintSync({ \"strings\": { \"content\": original } });\nconst fixed = applyFixes(original, results.content);\n```\n\n### Miscellaneous\n\nTo get the [semantic version][semver] of the library, the `getVersion` method\ncan be used:\n\n```javascript\n/**\n * Gets the (semantic) version of the library.\n *\n * @returns {string} SemVer string.\n */\nfunction getVersion() { ... }\n```\n\nInvoking `getVersion` is simple:\n\n```javascript\nimport { getVersion } from \"markdownlint\";\n\n// Displays the library version\nconsole.log(getVersion());\n```\n\n[semver]: https://semver.org\n\n## Usage\n\nInvoke `lint` and use the `result` object's `toString` method:\n\n```javascript\nimport { lint as lintAsync } from \"markdownlint/async\";\n\nconst options = {\n  \"files\": [ \"good.md\", \"bad.md\" ],\n  \"strings\": {\n    \"good.string\": \"# good.string\\n\\nThis string passes all rules.\",\n    \"bad.string\": \"#bad.string\\n\\n#This string fails\\tsome rules.\"\n  }\n};\n\nlintAsync(options, function callback(error, results) {\n  if (!error \u0026\u0026 results) {\n    console.log(results.toString());\n  }\n});\n```\n\nOutput:\n\n```text\nbad.string: 3: MD010/no-hard-tabs Hard tabs [Column: 19]\nbad.string: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: \"#bad.string\"]\nbad.string: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: \"#This string fails        some rules.\"]\nbad.string: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: \"#bad.string\"]\nbad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]\nbad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: \"#bad.md\"]\nbad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: \"#This file fails      some rules.\"]\nbad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: \"#bad.md\"]\n```\n\nOr as a synchronous call:\n\n```javascript\nimport { lint as lintSync } from \"markdownlint/sync\";\n\nconst results = lintSync(options);\nconsole.log(results.toString());\n```\n\nTo examine the `result` object directly via a `Promise`-based call:\n\n```javascript\nimport { lint as lintPromise } from \"markdownlint/promise\";\n\nconst results = await lintPromise(options);\nconsole.dir(results, { \"colors\": true, \"depth\": null });\n```\n\nOutput:\n\n```json\n{\n  \"good.md\": [],\n  \"bad.md\": [\n    { \"lineNumber\": 3,\n      \"ruleNames\": [ \"MD010\", \"no-hard-tabs\" ],\n      \"ruleDescription\": \"Hard tabs\",\n      \"ruleInformation\": \"https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md010.md\",\n      \"errorDetail\": \"Column: 17\",\n      \"errorContext\": null,\n      \"errorRange\": [ 17, 1 ] },\n    { \"lineNumber\": 1,\n      \"ruleNames\": [ \"MD018\", \"no-missing-space-atx\" ],\n      \"ruleDescription\": \"No space after hash on atx style heading\",\n      \"ruleInformation\": \"https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md018.md\",\n      \"errorDetail\": null,\n      \"errorContext\": \"#bad.md\",\n      \"errorRange\": [ 1, 2 ] },\n    { \"lineNumber\": 3,\n      \"ruleNames\": [ \"MD018\", \"no-missing-space-atx\" ],\n      \"ruleDescription\": \"No space after hash on atx style heading\",\n      \"ruleInformation\": \"https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md018.md\",\n      \"errorDetail\": null,\n      \"errorContext\": \"#This file fails\\tsome rules.\",\n      \"errorRange\": [ 1, 2 ] },\n    { \"lineNumber\": 1,\n      \"ruleNames\": [ \"MD041\", \"first-line-heading\", \"first-line-h1\" ],\n      \"ruleDescription\": \"First line in a file should be a top-level heading\",\n      \"ruleInformation\": \"https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md041.md\",\n      \"errorDetail\": null,\n      \"errorContext\": \"#bad.md\",\n      \"errorRange\": null }\n  ]\n}\n```\n\nIntegration with the [gulp](https://gulpjs.com/) build system is\nstraightforward: [`gulpfile.cjs`](example/gulpfile.cjs).\n\nIntegration with the [Grunt](https://gruntjs.com/) build system is similar:\n[`Gruntfile.cjs`](example/Gruntfile.cjs).\n\n## Browser\n\n`markdownlint` also works in the browser.\n\nGenerate normal and minified scripts with:\n\n```bash\nnpm run build-demo\n```\n\nThen reference the `markdownlint-browser` script:\n\n```html\n\u003cscript src=\"demo/markdownlint-browser.min.js\"\u003e\u003c/script\u003e\n```\n\nAnd call it like so:\n\n```javascript\nconst options = {\n  \"strings\": {\n    \"content\": \"Some Markdown to lint.\"\n  }\n};\n\nconst results = globalThis.markdownlint.lintSync(options).toString();\n```\n\n## Examples\n\nFor ideas how to integrate `markdownlint` into your workflow, refer to the\nfollowing projects or one of the tools in the [Related section](#related):\n\n- [.NET Documentation][dot-net-doc] ([Search repository][dot-net-doc-search])\n- [ally.js][ally-js] ([Search repository][ally-js-search])\n- [Apache Airflow][airflow] ([Search repository][airflow-search])\n- [Boostnote][boostnote] ([Search repository][boostnote-search])\n- [CodiMD][codimd] ([Search repository][codimd-search])\n- [Electron][electron] ([Search repository][electron-search])\n- [ESLint][eslint] ([Search repository][eslint-search])\n- [Garden React Components][garden] ([Search repository][garden-search])\n- [MDN Web Docs][mdn] ([Search repository][mdn-search])\n- [MkDocs][mkdocs] ([Search repository][mkdocs-search])\n- [Mocha][mocha] ([Search repository][mocha-search])\n- [Pi-hole documentation][pi-hole] ([Search repository][pi-hole-search])\n- [Reactable][reactable] ([Search repository][reactable-search])\n- [V8][v8] ([Search repository][v8-search])\n- [webhint][webhint] ([Search repository][webhint-search])\n- [webpack][webpack] ([Search repository][webpack-search])\n- [WordPress][wordpress] ([Search repository][wordpress-search])\n\nFor more advanced integration scenarios:\n\n- [GitHub Docs content linter][content-linter]\n- [GitHub's `markdownlint-github` repository][markdownlint-github]\n\n[ally-js]: https://allyjs.io/\n[ally-js-search]: https://github.com/medialize/ally.js/search?q=markdownlint\n[airflow]: https://airflow.apache.org\n[airflow-search]: https://github.com/apache/airflow/search?q=markdownlint\n[boostnote]: https://boostnote.io/\n[boostnote-search]: https://github.com/BoostIO/Boostnote/search?q=markdownlint\n[codimd]: https://github.com/hackmdio/codimd\n[codimd-search]: https://github.com/hackmdio/codimd/search?q=markdownlint\n[content-linter]: https://docs.github.com/en/contributing/collaborating-on-github-docs/using-the-content-linter\n[dot-net-doc]: https://docs.microsoft.com/en-us/dotnet/\n[dot-net-doc-search]: https://github.com/dotnet/docs/search?q=markdownlint\n[electron]: https://www.electronjs.org\n[electron-search]: https://github.com/electron/electron/search?q=markdownlint\n[eslint]: https://eslint.org/\n[eslint-search]: https://github.com/eslint/eslint/search?q=markdownlint\n[garden]: https://zendeskgarden.github.io/react-components/\n[garden-search]: https://github.com/zendeskgarden/react-components/search?q=markdownlint\n[markdownlint-github]: https://github.com/github/markdownlint-github\n[mdn]: https://developer.mozilla.org/\n[mdn-search]: https://github.com/mdn/content/search?q=markdownlint\n[mkdocs]: https://www.mkdocs.org/\n[mkdocs-search]: https://github.com/mkdocs/mkdocs/search?q=markdownlint\n[mocha]: https://mochajs.org/\n[mocha-search]: https://github.com/mochajs/mocha/search?q=markdownlint\n[pi-hole]: https://docs.pi-hole.net\n[pi-hole-search]: https://github.com/pi-hole/docs/search?q=markdownlint\n[reactable]: https://glittershark.github.io/reactable/\n[reactable-search]: https://github.com/glittershark/reactable/search?q=markdownlint\n[v8]: https://v8.dev/\n[v8-search]: https://github.com/v8/v8.dev/search?q=markdownlint\n[webhint]: https://webhint.io/\n[webhint-search]: https://github.com/webhintio/hint/search?q=markdownlint\n[webpack]: https://webpack.js.org/\n[webpack-search]: https://github.com/webpack/webpack.js.org/search?q=markdownlint\n[wordpress]: https://wordpress.org/gutenberg/\n[wordpress-search]: https://github.com/WordPress/gutenberg/search?q=markdownlint\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for more information.\n\n## Releasing\n\nSee [ReleaseProcess.md](doc/ReleaseProcess.md) for more information.\n\n## History\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n[npm-image]: https://img.shields.io/npm/v/markdownlint.svg\n[npm-url]: https://www.npmjs.com/package/markdownlint\n[license-image]: https://img.shields.io/npm/l/markdownlint.svg\n[license-url]: https://opensource.org/licenses/MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidanson%2Fmarkdownlint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidanson%2Fmarkdownlint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidanson%2Fmarkdownlint/lists"}