Update to version 0.38.0.

Bumps [@eslint/js](https://github.com/eslint/eslint/tree/HEAD/packages/js) from 9.25.1 to 9.26.0.
- [Release notes](https://github.com/eslint/eslint/releases)
- [Changelog](https://github.com/eslint/eslint/blob/main/CHANGELOG.md)
- [Commits](https://github.com/eslint/eslint/commits/v9.26.0/packages/js)

---
updated-dependencies:
- dependency-name: "@eslint/js"
  dependency-version: 9.26.0
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

.eslintignore

@@ -1,3 +0,0 @@
-demo/markdown-it.min.js
-demo/markdownlint-browser.js
-demo/markdownlint-browser.min.js

.eslintrc.json

@@ -1,54 +0,0 @@
-{
-  "parser": "espree",
-  "parserOptions": {
-    "ecmaVersion": 2018
-  },
-  "env": {
-    "node": true,
-    "es6": true
-  },
-  "extends": "eslint:all",
-  "rules": {
-    "array-bracket-spacing": ["error", "always"],
-    "array-element-newline": "off",
-    "capitalized-comments": "off",
-    "dot-location": ["error", "property"],
-    "func-style": ["error", "declaration"],
-    "function-paren-newline": "off",
-    "global-require": "off",
-    "id-length": "off",
-    "indent": ["error", 2, { "SwitchCase": 1 }],
-    "linebreak-style": "off",
-    "max-lines": "off",
-    "max-lines-per-function": "off",
-    "max-params": ["error", 9],
-    "max-statements": ["error", 33],
-    "multiline-comment-style": ["error", "separate-lines"],
-    "multiline-ternary": "off",
-    "newline-per-chained-call": "off",
-    "no-empty-function": "off",
-    "no-extra-parens": "off",
-    "no-implicit-coercion": "off",
-    "no-magic-numbers": "off",
-    "no-nested-ternary": "off",
-    "no-param-reassign": "off",
-    "no-plusplus": "off",
-    "no-sync": "off",
-    "no-ternary": "off",
-    "no-undefined": "off",
-    "object-curly-spacing": ["error", "always"],
-    "object-shorthand": "off",
-    "one-var": "off",
-    "operator-linebreak": ["error", "after"],
-    "padded-blocks": "off",
-    "prefer-arrow-callback": "off",
-    "prefer-destructuring": "off",
-    "prefer-named-capture-group": "off",
-    "prefer-template": "off",
-    "require-unicode-regexp": "off",
-    "sort-keys": "off",
-    "space-before-function-paren": ["error", "never"],
-    "vars-on-top": "off",
-    "wrap-regex": "off"
-  }
-}

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: DavidAnson

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/markdownlint-issue-template.md

@@ -0,0 +1,40 @@
+---
+name: markdownlint issue template
+about: This template helps report issues with the markdownlint family of tools.
+title: ''
+labels: ''
+assignees: ''
+---
+
+<!--
+
+Thank you for taking the time to report an issue!
+
+When deciding where to open an issue, please note there are multiple projects under the markdownlint umbrella:
+
+- https://github.com/DavidAnson/markdownlint : This is the core JavaScript/Node.js library and is used by other tools. Most issues with implementation and rule behavior belong here.
+- https://github.com/igorshubovych/markdownlint-cli : This is the original CLI for markdownlint. Issues specific to CLI belong here.
+- https://github.com/DavidAnson/markdownlint-cli2 : This is a newer CLI for markdownlint and is used by other tools. Issues specific to CLI2 belong here.
+- https://github.com/DavidAnson/vscode-markdownlint : This is the Visual Studio Code extension for markdownlint. Issues specific to VS Code belong here.
+- https://github.com/DavidAnson/markdownlint-cli2-action : This is a GitHub Action for markdownlint. Issues specific to the Action belong here.
+- https://github.com/markdownlint/markdownlint : This is the original markdownlint implementation for Ruby. All Ruby-related issues belong here.
+
+Before creating an issue, it's a good practice to search existing issues for something similar. If your issue has already been reported, please update the existing one with any new information. It's also good to review the documentation for any relevant details.
+
+When describing an issue, the following information is helpful:
+
+- What did you do?
+- What did you expect to happen?
+- What actually happened?
+- What messages or errors were there?
+- How can the issue be reproduced?
+- What version were you using?
+- What operating system were you using?
+
+The simplest demonstration of a problem is the most helpful. Small examples can be pasted into the issue description. (Be sure to paste as code so GitHub doesn't render the example in Markdown.) For larger examples, linking to a repository or file is more appropriate.
+
+Before proposing a new rule, please review the existing suggestions: https://github.com/DavidAnson/markdownlint/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+rule%22
+
+Thank you!
+
+-->

.github/codeql-config.yaml

@@ -0,0 +1,7 @@
+name: "CodeQL Config"
+
+queries:
+  - uses: security-and-quality
+
+paths-ignore:
+  - demo/markdownlint-browser.js

.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    target-branch: "next"
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    target-branch: "next"
+    versioning-strategy: "increase"

.github/dictionary.txt

@@ -0,0 +1,122 @@
+addin
+APIs
+async
+atx
+ATX
+atx_closed
+ATX-style
+autolink
+autolinks
+Autolinks
+axibase
+backtick
+backticks
+blockquote
+blockquotes
+Boostnote
+br
+br_spaces
+bundler
+changelog
+Changelog
+changelogs
+Changelogs
+CLI
+coc-markdownlint
+CodeQL
+CodiMD
+CommonMark
+config
+Config
+config.
+CVE-\d+-\d+
+docs-util
+ECMAScript
+ES2015
+ES6
+ESLint
+eslint-plugin-markdownlint
+first-line-h1
+flymake-markdownlint-cli2
+formatter
+fs
+GFM
+github
+globbing
+grunt-markdownlint
+h1
+h2
+html_elements
+JSDoc
+JSON
+JSONC
+kramdown
+linter
+LLMs
+Lombiq
+markdownlint
+markdownlint-cli
+markdownlint-cli2
+markdownlint-rule-helpers
+markdownlint-rule-search-replace
+matcher
+MD\d\d\d
+MD\d\d\d-MD\d\d\d
+mdl
+MDN
+minified
+MkDocs
+MSBuild
+namespace
+Neovim
+no-bare-urls
+no-blanks-blockquote
+no-inline-html
+no-missing-space-atx
+no-missing-space-closed-atx
+no-multiple-space-atx
+no-multiple-space-blockquote
+no-multiple-space-closed-atx
+non-JSON
+npm
+ol
+ol_multi
+ol-prefix
+pandoc
+Pandoc
+Params
+parsers
+pre-commit
+Reactable
+README
+reimplement
+Reimplement
+setext
+setext_with_atx
+setext_with_atx_closed
+setext-style
+single-h1
+sublist
+subpath
+Super-Linter
+TestCafe
+TOML
+trimLeft
+trimRight
+ul
+ul_single
+ul-indent
+ul-start-left
+ul-style
+unhandled
+unreferenced
+url
+v12
+V8
+vscode-markdownlint
+W3C
+webhint
+webhintio
+webpack
+whitespace
+YAML

.github/workflows/checkers.yml

@@ -0,0 +1,29 @@
+name: Checkers
+
+on:
+  pull_request:
+  push:
+    branches-ignore:
+      - 'dependabot/**'
+  workflow_dispatch:
+
+jobs:
+
+  linkcheck:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: JustinBeckwith/linkinator-action@v1.11.0
+      with:
+        linksToSkip: '^https://github.com/ ^https://opensource.org/ ^https://unix.stackexchange.com/'
+        paths: '*.md doc/*.md helpers/*.md'
+        timeout: 60000
+
+  spellcheck:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: tbroadley/spellchecker-cli-action@v1
+      with:
+        dictionaries: '.github/dictionary.txt'
+        files: '*.md doc/*.md helpers/*.md'

.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches-ignore:
+      - 'dependabot/**'
+  schedule:
+    - cron: '30 12 * * *'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-latest, windows-latest]
+        node-version: [ 20, 22, 23 ]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: Install Dependencies
+      run: npm install --no-package-lock
+    - name: Run CI Tests
+      run: npm run ci
+
+  pnpm:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use pnpm latest
+      uses: pnpm/action-setup@v4
+      with:
+        version: latest
+    - name: Use Node.js latest
+      uses: actions/setup-node@v4
+      with:
+        node-version: latest
+    - name: Install dependencies
+      run: pnpm install
+    - name: Run CI Tests
+      run: npm test

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,33 @@
+name: "CodeQL"
+
+on:
+  pull_request:
+  push:
+    branches-ignore:
+      - 'dependabot/**'
+  workflow_dispatch:
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ['javascript']
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        config-file: ./.github/codeql-config.yaml
+        languages: ${{ matrix.language }}
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3

.github/workflows/test-repos.yml

@@ -0,0 +1,31 @@
+name: TestRepos
+
+on:
+  pull_request:
+  push:
+    branches-ignore:
+      - 'dependabot/**'
+  workflow_dispatch:
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ ubuntu-latest ]
+        node-version: [ latest ]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: Install Dependencies
+      run: npm install --no-package-lock
+    - name: Clone Test Repos
+      run: npm run clone-test-repos
+    - name: Lint Test Repos
+      run: npm run lint-test-repos

.gitignore

@@ -2,8 +2,10 @@ coverage
 demo/markdown-it.min.js
 demo/markdownlint-browser.js
 demo/markdownlint-browser.min.js
-lib-es3
 node_modules
+!test/node_modules
+!test/rules/node_modules
 npm-debug.log
-.nyc_output
+test-repos
+.DS_Store
 .vscode

.markdownlint.json

@@ -1,8 +1,67 @@
 {
-  "line-length": false,
-  "no-inline-html": {
-    "allowed_elements": [
-      "a"
+  "code-block-style": {
+    "style": "fenced"
+  },
+  "code-fence-style": {
+    "style": "backtick"
+  },
+  "emphasis-style": {
+    "style": "asterisk"
+  },
+  "extended-ascii": {
+    "ascii-only": true
+  },
+  "fenced-code-language": {
+    "allowed_languages": [
+      "bash",
+      "html",
+      "javascript",
+      "json",
+      "markdown",
+      "text"
+    ],
+    "language_only": true
+  },
+  "heading-style": {
+    "style": "atx"
+  },
+  "hr-style": {
+    "style": "---"
+  },
+  "line-length": {
+    "strict": true,
+    "code_blocks": false
+  },
+  "link-image-style": {
+    "collapsed": false,
+    "shortcut": false,
+    "url_inline": false
+  },
+  "no-duplicate-heading": {
+    "siblings_only": true
+  },
+  "ol-prefix": {
+    "style": "ordered"
+  },
+  "proper-names": {
+    "code_blocks": false,
+    "names": [
+      "Cake.Markdownlint",
+      "CommonMark",
+      "JavaScript",
+      "Markdown",
+      "markdown-it",
+      "markdownlint",
+      "Node.js"
     ]
+  },
+  "reference-links-images": {
+    "shortcut_syntax": true
+  },
+  "strong-style": {
+    "style": "asterisk"
+  },
+  "ul-style": {
+    "style": "dash"
   }
 }

.npmignore

@@ -1,5 +1,15 @@
-coverage
-demo
-npm-debug.log
-test
+.eslintignore
+.github
+.markdownlint.json
+.npmrc
 .vscode
+coverage
+demo/*
+doc-build
+eslint.config.mjs
+example
+npm-debug.log
+schema/*.mjs
+scripts
+test
+test-repos

.npmrc

@@ -0,0 +1,3 @@
+engine-strict=true
+ignore-scripts=true
+package-lock=false

.travis.yml

@@ -1,12 +0,0 @@
-language: node_js
-node_js:
-  - "8"
-  - "10"
-  - "12"
-os:
-  - windows
-  - linux
-  - osx
-cache: npm
-script: "npm run-script test-cover"
-after_script: "npm install coveralls && nyc report --reporter=text-lcov | coveralls"

CHANGELOG.md

@@ -0,0 +1,505 @@
+# Changelog
+
+## 0.38.0
+
+- Add MD059/descriptive-link-text
+- Improve MD025/MD027/MD036/MD038/MD041/MD043/MD045/MD051/MD052
+- `markdown-it` parser no longer a production dependency (breaking change)
+  - Add `markdownItFactory` option, remove `markdownItPlugins` option
+- Remove support for end-of-life Node version 18
+- Improve performance
+- Update dependencies
+
+## 0.37.4
+
+- Stop using `module.createRequire`, export `resolveModule`
+
+## 0.37.3
+
+- Tweak `package.json` dependencies to work with `pnpm`
+
+## 0.37.2
+
+- Add subpath imports for overriding default bundler behavior
+- Improve MD032
+
+## 0.37.1
+
+- Add support for "browser" condition (as used by webpack)
+
+## 0.37.0
+
+- Convert module to ECMAScript (breaking change)
+  - <https://nodejs.org/docs/latest/api/esm.html>
+  - <https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c>
+- Convert module to named exports (breaking change)
+
+## 0.36.1
+
+- Fix behavior of MD054
+
+## 0.36.0
+
+- Improve MD051
+- Move `applyFix` and `applyFixes` from helpers to core
+- Make `micromark` parser available to custom rules
+- Introduce `./micromark` helpers exports
+- Update custom/rule documentation
+- Improve performance
+- Update dependencies
+
+## 0.35.0
+
+- Add MD058/blanks-around-tables
+- Use `micromark` in MD001/MD003/MD009/MD010/MD013/MD014/MD019/MD021/MD023/
+  MD024/MD025/MD039/MD042/MD043
+- Improve MD018/MD020/MD031/MD034/MD044
+- `markdown-it` parser no longer invoked by default
+- Add strict version of JSON schema
+- Improve performance
+- Update dependencies
+
+## 0.34.0
+
+- Use `micromark` in MD027/MD028/MD036/MD040/MD041/MD046/MD048
+- Improve MD013/MD034/MD049/MD050/MD051
+- Update custom rule requirements and documentation
+- Improve various TypeScript declarations
+- Update dependencies
+
+## 0.33.0
+
+- Add MD055/table-pipe-style, MD056/table-column-count
+- Improve MD005/MD007/MD024/MD026/MD038
+- Incorporate `micromark-extension-directive`
+- Improve JSON schema, document validation
+- Reduce size of browser script
+- Update dependencies
+
+## 0.32.1
+
+- Fix behavior of MD054
+
+## 0.32.0
+
+- Remove deprecated MD002/MD006
+- Remove rule aliases for "header"
+- Add MD054/link-image-style
+- Use `micromark` in MD005/MD007/MD030
+- Improve MD022/MD026/MD034/MD037/MD038/MD045/MD051
+- Improve JSON schema and related examples
+- Provide type declaration for Configuration object
+- Remove support for end-of-life Node version 16
+- Update dependencies
+
+## 0.31.1
+
+- Improve MD032/MD034
+- Update dependencies
+
+## 0.31.0
+
+- Improve MD032/MD037/MD043/MD044/MD051/MD052
+- Improve performance
+- Update dependencies
+
+## 0.30.0
+
+- Use `micromark` in MD022/MD026/MD032/MD037/MD045/MD051
+- Incorporate `micromark-extension-math` for math syntax
+- Allow custom rules to override information URL
+- Update dependencies
+
+## 0.29.0
+
+- Update `micromark` parser dependencies for better performance
+- Use `micromark` in MD049/MD050
+- Improve MD034/MD037/MD044/MD049/MD050
+- Support multiple parsers in demo page
+- Remove support for end-of-life Node version 14
+- Update dependencies
+
+## 0.28.2
+
+- Update dependencies for CVE-2023-2251
+
+## 0.28.1
+
+- Update dependencies
+
+## 0.28.0
+
+- Introduce `micromark` parser for better positional data (internal only)
+- Use `micromark` in MD013/MD033/MD034/MD035/MD038/MD044/MD052/MD053
+- Simplify file-based test cases
+- Unify browser script for demo page
+- Update dependencies
+
+## 0.27.0
+
+- Improve MD011/MD013/MD022/MD031/MD032/MD033/MD034/MD040/MD043/MD051/MD053
+- Generate/separate documentation
+- Improve documentation
+- Update dependencies
+
+## 0.26.2
+
+- Improve MD037/MD051/MD053
+
+## 0.26.1
+
+- Improve MD051
+
+## 0.26.0
+
+- Add MD051/MD052/MD053 for validating link fragments & reference
+  links/images & link/image reference definitions (MD053 auto-fixable)
+- Improve MD010/MD031/MD035/MD039/MD042/MD044/MD049/MD050
+- Add `markdownlint-disable-line` inline comment
+- Support `~` paths in `readConfig/Sync`
+- Add `configParsers` option
+- Remove support for end-of-life Node version 12
+- Default `resultVersion` to 3
+- Update browser script to use ES2015
+- Simplify JSON schema
+- Address remaining CodeQL issues
+- Improve performance
+- Update dependencies
+
+## 0.25.1
+
+- Update dependencies for CVE-2022-21670
+
+## 0.25.0
+
+- Add MD049/MD050 for consistent emphasis/strong style (both auto-fixable)
+- Improve MD007/MD010/MD032/MD033/MD035/MD037/MD039
+- Support asynchronous custom rules
+- Improve performance
+- Improve CI process
+- Reduce dependencies
+- Update dependencies
+
+## 0.24.0
+
+- Remove support for end-of-life Node version 10
+- Add support for custom file system module
+- Improve MD010/MD011/MD037/MD043/MD044
+- Improve TypeScript declaration file and JSON schema
+- Update dependencies
+
+## 0.23.1
+
+- Work around lack of webpack support for dynamic calls to `require`(`.resolve`)
+
+## 0.23.0
+
+- Add comprehensive example `.markdownlint.jsonc`/`.markdownlint.yaml` files
+- Add fix information for MD004/ul-style
+- Improve MD018/MD019/MD020/MD021/MD037/MD041
+- Improve HTML comment handling
+- Update test runner and test suite
+- Update dependencies
+
+## 0.22.0
+
+- Allow `extends` in config to reference installed packages by name
+- Add `markdownlint-disable-next-line` inline comment
+- Support JSON front matter
+- Improve MD009/MD026/MD028/MD043
+- Update dependencies (including `markdown-it` to v12)
+
+## 0.21.1
+
+- Improve MD011/MD031
+- Export `getVersion` API
+
+## 0.21.0
+
+- Lint concurrently for better performance (async only)
+- Add Promise-based APIs
+- Update TypeScript declaration file
+- Hide `toString` on `LintResults`
+- Add ability to fix in browser demo
+- Allow custom rules in `.markdownlint.json` schema
+- Improve MD042/MD044
+- Improve documentation
+- Update dependencies
+
+## 0.20.4
+
+- Fix regression in MD037
+- Improve MD034/MD044
+- Improve documentation
+
+## 0.20.3
+
+- Fix regression in MD037
+- Improve MD044
+- Add automatic regression testing
+
+## 0.20.2
+
+- Fix regression in MD037
+- Improve MD038
+
+## 0.20.1
+
+- Fix regression in MD037
+
+## 0.20.0
+
+- Add `markdownlint-configure-file` inline comment
+- Reimplement MD037
+- Improve MD005/MD007/MD013/MD018/MD029/MD031/MD034/MD038/MD039
+- Improve HTML comment handling
+- Update dependencies
+
+## 0.19.0
+
+- Remove support for end-of-life Node version 8
+- Add fix information for MD005/list-indent
+- Improve MD007/MD013/MD014
+- Deprecate MD006/ul-start-left
+- Add rationale for every rule
+- Update test runner and code coverage
+- Add more JSDoc comments
+- Update dependencies
+
+## 0.18.0
+
+- Add MD048/code-fence-style
+- Add fix information for MD007/ul-indent
+- Add `markdownlint-disable-file`/`markdownlint-enable-file` inline comments
+- Add type declaration file (.d.ts) for TypeScript dependents
+- Update schema
+- Improve MD006/MD007/MD009/MD013/MD030
+- Update dependencies
+
+## 0.17.2
+
+- Improve MD020/MD033/MD044
+
+## 0.17.1
+
+- Fix handling of front matter by fix information
+
+## 0.17.0
+
+- Add `resultVersion` 3 to support fix information for default and custom rules
+- Add fix information for 24 rules
+- Update newline handling to match latest CommonMark specification
+- Improve MD014/MD037/MD039
+- Update dependencies
+
+## 0.16.0
+
+- Add custom rule sample for linting code
+- Improve MD026/MD031/MD033/MD038
+- Update dependencies
+
+## 0.15.0
+
+- Add `markdownlint-capture`/`markdownlint-restore` inline comments
+- Improve MD009/MD013/MD026/MD033/MD036
+- Update dependencies
+
+## 0.14.2
+
+- Improve MD047
+- Add `handleRuleFailures` option
+
+## 0.14.1
+
+- Improve MD033
+
+## 0.14.0
+
+- Remove support for end-of-life Node version 6
+- Introduce `markdownlint-rule-helpers`
+- Add MD046/MD047
+- Improve MD033/MD034/MD039
+- Improve custom rule validation and in-browser demo
+- Update dependencies
+
+## 0.13.0
+
+- Improve MD013/MD022/MD025/MD029/MD031/MD032/MD037/MD041
+- Deprecate MD002
+- Improve Pandoc YAML support
+- Update dependencies
+
+## 0.12.0
+
+- Add `information` link for custom rules
+- Add `markdownItPlugins` for extensibility
+- Improve MD023/MD032/MD038
+- Update dependencies
+
+## 0.11.0
+
+- Improve MD005/MD024/MD029/MD038
+- Improve custom rule example
+- Add `CONTRIBUTING.md`
+- Update dependencies
+
+## 0.10.0
+
+- Add support for non-JSON configuration files
+- Pass file/string name to custom rules
+- Update dependencies
+
+## 0.9.0
+
+- Remove support for end-of-life Node versions 0.10/0.12/4
+- Change "header" to "heading" per spec (non-breaking)
+- Improve MD003/MD009/MD041
+- Handle uncommon line-break characters
+- Refactor for ES6
+- Update dependencies
+
+## 0.8.1
+
+- Update item loop to be iterative
+- Improve MD014
+- Update dependencies
+
+## 0.8.0
+
+- Add support for using and authoring custom rules
+- Improve MD004/MD007/MD013
+- Add `engines` to `package.json`
+- Refactor
+- Update dependencies
+
+## 0.7.0
+
+- `resultVersion` defaults to 2 (breaking change)
+- Add MD045
+- Improve MD029
+- Remove `trimLeft`/`trimRight`
+- Split rules
+- Refactor
+- Update dependencies
+
+## 0.6.4
+
+- Improve MD029/MD042
+- Update dependencies
+
+## 0.6.3
+
+- Improve highlighting for MD020
+
+## 0.6.2
+
+- Improve MD013/MD027/MD034/MD037/MD038/MD041/MD044
+- Update dependencies
+
+## 0.6.1
+
+- Update `markdown-it` versioning
+- Exclude demo/test from publishing
+
+## 0.6.0
+
+- `resultVersion` defaults to 1 (breaking change)
+- Ignore HTML comments
+- TOML front matter
+- Fixes for MD044
+- Update dependencies
+
+## 0.5.0
+
+- Add shareable configuration
+- Add `noInlineConfig` option
+- Add `README.md` links
+- Fix MD030
+- Improve MD009/MD041
+- Update dependencies
+
+## 0.4.1
+
+- Fixes for MD038/front matter
+- Improvements to MD044
+- Update dependencies
+
+## 0.4.0
+
+- Add MD044
+- Enhance MD013/MD032/MD041/MD042/MD043
+- Fix for MD038
+- Update dependencies
+
+## 0.3.1
+
+- Fix regressions in MD032/MD038
+- Update dependencies
+
+## 0.3.0
+
+- More detailed error reporting with `resultVersion`
+- Enhance MD010/MD012/MD036
+- Fixes for MD027/MD029/MD030
+- Include JSON schema dependencies
+
+## 0.2.0
+
+- Add MD042/MD043
+- Enhance MD002/MD003/MD004/MD007/MD011/MD025/MD041
+- Update dependencies
+
+## 0.1.1
+
+- Fix bug handling HTML in tables
+- Reference `markdownlint-cli`
+
+## 0.1.0
+
+- Add aliases
+- Exceptions for MD033
+- Exclusions for MD013
+- Update dependencies
+
+## 0.0.8
+
+- Support disabling/enabling rules inline
+- Improve code fence
+- Update dependencies
+
+## 0.0.7
+
+- Add MD041
+- Improve MD003
+- Ignore front matter
+- Update dependencies
+
+## 0.0.6
+
+- Improve performance
+- Simplify in-browser
+- Update dependencies
+
+## 0.0.5
+
+- Add `strings` option to enable file-less scenarios
+- Add in-browser demo
+
+## 0.0.4
+
+- Add tests MD033-MD040
+- Update dependencies
+
+## 0.0.3
+
+- Add synchronous API
+- Improve documentation and code
+
+## 0.0.2
+
+- Improve documentation, tests, and code
+
+## 0.0.1
+
+- Initial release
+- Includes tests MD001-MD032

CONTRIBUTING.md

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

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2019 David Anson
+Copyright (c) David Anson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

demo/Web.config

@@ -1,24 +0,0 @@
-<?xml version="1.0"?>
-<configuration>
-  <!-- Standard ASP.NET configuration; see https://go.microsoft.com/fwlink/?LinkId=169433 -->
-  <system.web>
-    <compilation debug="false" targetFramework="4.0"/>
-  </system.web>
-
-  <!-- Register MIME type for cache manifest -->
-  <system.webServer>
-    <staticContent>
-      <remove fileExtension=".appcache"/>
-      <mimeMap fileExtension=".appcache" mimeType="text/cache-manifest"/>
-    </staticContent>
-  </system.webServer>
-
-  <!-- Disable caching for cache manifest file -->
-  <location path="offline.appcache">
-    <system.webServer>
-      <staticContent>
-        <clientCache cacheControlMode="DisableCache"/>
-      </staticContent>
-    </system.webServer>
-  </location>
-</configuration>

demo/browser-exports.mjs

@@ -0,0 +1,10 @@
+// @ts-check
+
+export { applyFixes, getVersion } from "markdownlint";
+export { lint as lintSync } from "markdownlint/sync";
+export { compile, parse, postprocess, preprocess } from "micromark";
+export { directive, directiveHtml } from "micromark-extension-directive";
+export { gfmAutolinkLiteral, gfmAutolinkLiteralHtml } from "micromark-extension-gfm-autolink-literal";
+export { gfmFootnote, gfmFootnoteHtml } from "micromark-extension-gfm-footnote";
+export { gfmTable, gfmTableHtml } from "micromark-extension-gfm-table";
+export { math, mathHtml } from "micromark-extension-math";

demo/default.htm

@@ -1,9 +1,9 @@
 <!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml" manifest="offline.appcache">
+<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
   <meta charset="utf-8"/>
   <link href="default.css" rel="stylesheet" type="text/css"/>
-  <link rel="shortcut icon" href="favicon.ico"/>
+  <link href="favicon.svg" rel="icon" type="image/svg+xml"/>
   <meta name="description" content="Demo for markdownlint, a Node.js style checker and lint tool for Markdown/CommonMark files."/>
   <title>markdownlint demo</title>
   <base target="_blank"/>
@@ -11,7 +11,7 @@
 <body>
   <div class="flex-rows">
     <div class="flex-columns inset">
-      <header>markdownlint demo</header>
+      <header>markdownlint demo <span id="version" class="detail"></span></header>
       <div class="flex-fill"></div>
       <form>
         <input id="openFile" type="file"/>
@@ -30,7 +30,7 @@
       <div class="flex-fill"></div>
       <footer><a href="#" id="copyLink">Copy Link</a></footer>
       <div class="flex-fill"></div>
-      <footer>Copyright &copy; 2015-2019 by <a href="https://dlaa.me/">David Anson</a></footer>
+      <footer>Copyright &copy; <a href="https://dlaa.me/">David Anson</a></footer>
     </div>
   </div>
   <script src="markdown-it.min.js"></script>

demo/default.js

@@ -1,6 +1,11 @@
 "use strict";
 
 (function main() {
+  // Dependencies
+  var markdownit = globalThis.markdownit;
+  var markdownlint = globalThis.markdownlint;
+  var micromark = markdownlint;
+
   // DOM elements
   var markdown = document.getElementById("markdown");
   var markup = document.getElementById("markup");
@@ -11,11 +16,9 @@
   var copyLink = document.getElementById("copyLink");
 
   // Variables
-  var markdownit = window.markdownit({ "html": true });
   var newLineRe = /\r\n|\r|\n/;
   var hashPrefix = "%m";
-  var rulesMd = "https://github.com/DavidAnson/markdownlint" +
-    "/blob/master/doc/Rules.md";
+  var allLintErrors = [];
 
   // Do-nothing function
   function noop() {}
@@ -28,12 +31,66 @@
       .replace(/>/g, ">");
   }
 
+  // Renders directive metadata
+  function handleDirective(directive) {
+    const content = directive.content;
+    delete directive.content;
+    if (content) {
+      this.tag("<blockquote>");
+    }
+    this.tag("<code>");
+    this.raw(this.encode(JSON.stringify(directive)));
+    this.tag("</code>");
+    this.raw(content);
+    if (content) {
+      this.tag("</blockquote>");
+    }
+  }
+
+  // Renders Markdown to HTML
+  function render(markdown) {
+    const match = /^\?renderer=([a-z-]+)$/.exec(globalThis.location.search);
+    const renderer = match ? match[1] : "micromark";
+    if (renderer === "markdown-it") {
+      return markdownit({ "html": true }).render(markdown);
+    } else if (renderer === "micromark") {
+      const parseOptions = {
+        "extensions": [
+          micromark.directive(),
+          micromark.gfmAutolinkLiteral(),
+          micromark.gfmFootnote(),
+          micromark.gfmTable(),
+          micromark.math()
+        ]
+      };
+      const context = micromark.parse(parseOptions);
+      const chunks = micromark.preprocess()(markdown, undefined, true);
+      const events = micromark.postprocess(context.document().write(chunks));
+      const compileOptions = {
+        "allowDangerousHtml": true,
+        "htmlExtensions": [
+          micromark.directiveHtml({ "*": handleDirective }),
+          micromark.gfmAutolinkLiteralHtml(),
+          micromark.gfmFootnoteHtml(),
+          micromark.gfmTableHtml(),
+          micromark.mathHtml()
+        ]
+      };
+      try {
+        return micromark.compile(compileOptions)(events);
+      } catch (error) {
+        return `[Exception: "${error}"]`;
+      }
+    }
+    return `[Unsupported renderer "${renderer}"]`;
+  }
+
   // Handle input
   function onMarkdownInput() {
     // Markdown
     var content = markdown.value;
     // Markup
-    markup.innerHTML = markdownit.render(content);
+    markup.innerHTML = render(content);
     // Numbered
     var lines = content.split(newLineRe);
     var padding = lines.length.toString().replace(/\d/g, " ");
@@ -52,17 +109,15 @@
       },
       "config": {
         "MD013": false
-      }
+      },
+      "handleRuleFailures": true
     };
-    var results = window.markdownlint.sync(options);
-    violations.innerHTML = results.content.map(function mapResult(result) {
-      var ruleName = result.ruleNames[0];
-      var ruleRef = rulesMd + "#" + ruleName.toLowerCase() + "---" +
-        result.ruleDescription.toLowerCase()
-          .replace(/ /g, "-")
-          .replace(/[()]/g, "");
-      return "<a href='#" + result.lineNumber + "'><em>" + result.lineNumber +
-        "</em></a> - <a href='" + ruleRef + "'>" + ruleName + "</a> " +
+    allLintErrors = markdownlint.lintSync(options).content;
+    violations.innerHTML = allLintErrors.map(function mapResult(result) {
+      var ruleName = result.ruleNames.slice(0, 2).join(" / ");
+      return "<em><a href='#line' target='" + result.lineNumber + "'>" +
+        result.lineNumber + "</a></em> - <a href='" + result.ruleInformation +
+        "'>" + ruleName + "</a> " +
         result.ruleDescription +
         (result.errorDetail ?
           " [<span class='detail'>" +
@@ -73,13 +128,12 @@
           " [<span class='detail'>Context: \"" +
             sanitize(result.errorContext) +
             "\"</span>]" :
+          "") +
+        (result.fixInfo ?
+          " [<a href='#fix' target=\"" +
+            encodeURIComponent(JSON.stringify(result)) +
+            "\" class='detail'>Fix</a>]" :
           "");
-      // + (result.errorRange ?
-      //     " <u style='white-space: pre-wrap'>" +
-      //       lines[result.lineNumber - 1].substr(
-      //         result.errorRange[0] - 1, result.errorRange[1]) +
-      //     "</u>" :
-      //     "");
     }).join("<br/>");
   }
 
@@ -93,12 +147,10 @@
       onMarkdownInput();
     } else {
       // Update from File object
-      var reader = new FileReader();
-      reader.onload = function onload(e) {
-        markdown.value = e.target.result;
+      source.text().then((text) => {
+        markdown.value = text;
         onMarkdownInput();
-      };
-      reader.readAsText(source);
+      });
     }
   }
 
@@ -124,37 +176,61 @@
   }
 
   // Handle violation navigation
-  function onLineNumberClick(e) {
-    var line = document.getElementById("l" + e.target.textContent);
-    if (line) {
-      var highlighted = document.getElementsByClassName("highlight");
-      Array.prototype.forEach.call(highlighted, function forElement(element) {
-        element.classList.remove("highlight");
-      });
-      line.classList.add("highlight");
-      line.scrollIntoView();
-      e.preventDefault();
+  function onViolationClick(e) {
+    switch (e.target.hash) {
+      case "#fix":
+        var errors = e.shiftKey ?
+          allLintErrors :
+          [ JSON.parse(decodeURIComponent(e.target.target)) ];
+        var fixed = markdownlint.applyFixes(markdown.value, errors);
+        markdown.value = fixed;
+        onMarkdownInput();
+        e.preventDefault();
+        break;
+      case "#line":
+        var line = document.getElementById("l" + e.target.target);
+        if (line) {
+          var highlighted = document.getElementsByClassName("highlight");
+          Array.prototype.forEach.call(
+            highlighted,
+            function forElement(element) {
+              element.classList.remove("highlight");
+            }
+          );
+          line.classList.add("highlight");
+          line.scrollIntoView();
+        }
+        e.preventDefault();
+        break;
+      default:
+        break;
     }
   }
 
   // Updates the URL hash and copies the URL to the clipboard
   function onCopyLinkClick(e) {
-    window.location.hash = encodeURIComponent(hashPrefix + markdown.value);
-    /* eslint-disable-next-line no-unused-expressions */
-    navigator.clipboard && navigator.clipboard.writeText &&
-      navigator.clipboard.writeText(window.location).then(noop, noop);
+    globalThis.location.hash = encodeURIComponent(hashPrefix + markdown.value);
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(globalThis.location).then(noop, noop);
+    } else {
+      /* eslint-disable-next-line no-alert */
+      alert("Document URL updated, select and copy it now.");
+    }
     e.preventDefault();
   }
 
+  // Show library version
+  var version = markdownlint.getVersion();
+  document.getElementById("version").textContent = "(v" + version + ")";
+
   // Add event listeners
   document.body.addEventListener("dragover", onDragOver);
   document.body.addEventListener("drop", onDrop);
   openFile.addEventListener("change", onOpenFileChange);
   markdown.addEventListener("input", onMarkdownInput);
-  violations.addEventListener("click", onLineNumberClick, true);
+  violations.addEventListener("click", onViolationClick, true);
   copyLink.addEventListener("click", onCopyLinkClick);
 
-  /* eslint-disable max-len */
   markdown.value = [
     "## Introduction",
     "",
@@ -167,7 +243,7 @@
     "Content gets parsed and displayed in the upper-right box; rule violations (if any) show up in the lower-right box.",
     "Click a violation for information about it or click its line number to highlighted it in the lower-left box.",
     "",
-    "> *Note*: [All rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md) are enabled except [MD013/line-length](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md013) and [MD002/first-heading-h1](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md002) (deprecated). ",
+    "> *Note*: [All rules](https://github.com/DavidAnson/markdownlint/blob/v" + version + "/doc/Rules.md) are enabled except [MD013/line-length](https://github.com/DavidAnson/markdownlint/blob/v" + version + "/doc/md013.md).",
     "",
     "",
     "#### Resources",
@@ -181,16 +257,15 @@
     "[`markdownlint/Ruby`](https://github.com/markdownlint/markdownlint) for the inspiration and [`markdown-it`](https://github.com/markdown-it/markdown-it) for the parser and interactive demo idea!",
     ""
   ].join("\n");
-  /* eslint-enable max-len */
 
   // Update Markdown from hash (if present)
-  if (window.location.hash) {
+  if (globalThis.location.hash) {
     try {
-      const decodedHash = decodeURIComponent(window.location.hash.substring(1));
+      var decodedHash = decodeURIComponent(globalThis.location.hash.substring(1));
       if (hashPrefix === decodedHash.substring(0, hashPrefix.length)) {
         markdown.value = decodedHash.substring(hashPrefix.length);
       }
-    } catch (ex) {
+    } catch {
       // Invalid
     }
   }
@@ -198,8 +273,8 @@
   // Detect legacy browsers
   try {
     /* eslint-disable-next-line no-new */
-    new URL(rulesMd);
-  } catch (ex) {
+    new URL("https://example.com/");
+  } catch {
     markdown.value = [
       "# Sorry",
       "",

demo/favicon.svg

@@ -0,0 +1,13 @@
+<svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    rect { stroke: black; stroke-width: 1; fill: white }
+    path { stroke: black; stroke-linecap: round; stroke-linejoin: round; fill: none }
+  </style>
+  <rect x="0.5" y="0.5" width="15" height="15" rx= "1" ry="1"/>
+  <path d="M 10.5,2.5 L 11.5,2.5 L 11.5,5.5 L 13,5.5 L 11,7.5 L 9,5.5 L 10.5,5.5 Z" style="fill:black"/>
+  <path d="M 2.5 7.5 L 2.5 3 L 4.5 5 L 6.5 3 L 6.5 7.5"/>
+  <path d="M 2.5,9.5 L 2.5,13.5 L 4,13.5"/>
+  <path d="M 5.5,10 L 5.5,10 M 5.5,11.5 L 5.5,13.5"/>
+  <path d="M 7.5,13.5 L 7.5,12 L 8 11.5 L 9 11.5 L 9.5,12 L 9.5,13.5"/>
+  <path d="M 12,13.5 L 12,10 M 11,11.5 L 13,11.5"/>
+</svg>

demo/file-header.js

@@ -1,2 +0,0 @@
-/* markdownlint - https://github.com/DavidAnson/markdownlint - @license MIT */
-

demo/markdown-it-stub.js

@@ -1,13 +0,0 @@
-"use strict";
-
-// Alias "markdown-it" (expected) to "markdownit" (exported)
-module.exports = window.markdownit;
-if (!module.exports) {
-  console.error("markdown-it must be loaded before markdownlint.");
-}
-
-// Use browser's URL implementation if not available on url module
-var url = require("url");
-if (!url.URL) {
-  url.URL = URL;
-}

demo/offline.appcache

@@ -1,10 +0,0 @@
-CACHE MANIFEST
-# 2019-05-07
-default.css
-default.htm
-default.js
-favicon.ico
-markdown-it.min.js
-markdownlint-browser.min.js
-NETWORK:
-*

demo/webpack.config.mjs

@@ -0,0 +1,81 @@
+// @ts-check
+
+import webpack from "webpack";
+import TerserPlugin from "terser-webpack-plugin";
+import { __dirname, importWithTypeJson } from "../test/esm-helpers.mjs";
+const libraryPackageJson = await importWithTypeJson(import.meta, "../package.json");
+
+// eslint-disable-next-line jsdoc/require-jsdoc
+function config(options) {
+  const { entry, filename, mode, optimization, packageJson } = options;
+  const { name, version, homepage, license } = packageJson;
+  return {
+    "devtool": false,
+    "entry": entry,
+    "externals": {
+      "markdown-it": "markdownit"
+    },
+    "mode": mode,
+    "name": name,
+    "optimization": optimization,
+    "output": {
+      "filename": filename,
+      "library": {
+        "name": name.replace(/(-\w)/g, (m) => m.slice(1).toUpperCase()),
+        "type": "var"
+      },
+      "path": __dirname(import.meta)
+    },
+    "plugins": [
+      new webpack.BannerPlugin({
+        "banner": `${name} ${version} ${homepage} @license ${license}`
+      })
+    ],
+    "ignoreWarnings": [
+      {
+        "message": /(asset|entrypoint) size limit/
+      },
+      {
+        "message": /dependencies cannot be statically extracted/
+      },
+      {
+        "message": /lazy load some parts of your application/
+      }
+    ]
+  };
+}
+
+const modeDevelopment = {
+  "mode": "development"
+};
+const modeProduction = {
+  "mode": "production",
+  "optimization": {
+    "minimizer": [
+      new TerserPlugin({
+        "extractComments": false,
+        "terserOptions": {
+          "compress": {
+            "passes": 2
+          }
+        }
+      })
+    ]
+  }
+};
+const entryLibrary = {
+  "entry": "./browser-exports.mjs",
+  "packageJson": libraryPackageJson
+};
+export default [
+  config({
+    ...entryLibrary,
+    ...modeDevelopment,
+    "filename": "markdownlint-browser.js"
+  }),
+  config({
+    ...entryLibrary,
+    ...modeProduction,
+    "filename": "markdownlint-browser.min.js"
+  })
+];

doc-build/.markdownlint.jsonc

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

doc-build/build-rules.mjs

@@ -0,0 +1,117 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { EOL } from "node:os";
+import rules from "../lib/rules.mjs";
+import { newLineRe } from "../helpers/helpers.cjs";
+import { deprecatedRuleNames, fixableRuleNames } from "../lib/constants.mjs";
+
+const maxLineLength = 80;
+
+const pathFor = (relativePath) => new URL(relativePath, import.meta.url);
+const inCode = (items) => items.map((item) => `\`${item}\``);
+const sortedComma = (items) => items.sort().join(", ");
+const linesFrom = (text) => text.split(newLineRe);
+const wrapListItem = (line) => {
+  const wrappedLines = [];
+  let remainingLine = line;
+  while (remainingLine.length > maxLineLength) {
+    let index = maxLineLength - 1;
+    while (remainingLine[index] !== " ") {
+      index--;
+    }
+    wrappedLines.push(remainingLine.slice(0, index + 1).trimEnd());
+    remainingLine = "  " + remainingLine.slice(index + 1).trimStart();
+  }
+  wrappedLines.push(remainingLine);
+  return wrappedLines;
+};
+
+// import { default as schema } from "file.json" assert { type: "json" };
+const importJson =
+  async(file) => JSON.parse(await readFile(pathFor(file)));
+const schema = await importJson("../schema/markdownlint-config-schema.json");
+
+const lines = [];
+
+const heading = await readFile(pathFor("./heading.md"), "utf8");
+lines.push(...linesFrom(heading));
+
+for (const rule of rules) {
+  const name = rule.names[0];
+  const deprecated = deprecatedRuleNames.includes(name);
+  const decorator = deprecated ? "~~" : "";
+  lines.push(
+    `<a name="${name.toLowerCase()}"></a>`,
+    ""
+  );
+  const section = [];
+  section.push(
+    `## ${decorator}\`${name}\` - ${rule.description}${decorator}`,
+    ""
+  );
+  if (deprecated) {
+    section.push(
+      "> This rule is deprecated and provided for backward-compatibility",
+      ""
+    );
+  }
+  section.push(
+    `Tags: ${sortedComma(inCode(rule.tags))}`,
+    "",
+    `Aliases: ${sortedComma(inCode(rule.names.slice(1)))}`,
+    ""
+  );
+  const ruleData = schema.properties[name];
+  if (ruleData.properties) {
+    section.push(
+      "Parameters:",
+      ""
+    );
+    for (const property of Object.keys(ruleData.properties).sort()) {
+      const propData = ruleData.properties[property];
+      const propType = [ propData.type ]
+        .flat()
+        .map((type) => ((type === "array") ? `${propData.items.type}[]` : type))
+        .join("|");
+      const defaultValue = Array.isArray(propData.default) ?
+        JSON.stringify(propData.default) :
+        propData.default;
+      const allValues = propData.enum?.sort();
+      const listItem = `- \`${property}\`: ${propData.description} (` +
+        `\`${propType}\`, default \`${defaultValue}\`` +
+        (propData.enum ?
+          `, values ${allValues.map((value) => `\`${value}\``).join(" / ")}` :
+          ""
+        ) +
+        ")";
+      section.push(...wrapListItem(listItem));
+    }
+    section.push(
+      ""
+    );
+  }
+  if (fixableRuleNames.includes(name)) {
+    section.push(
+      "Fixable: Some violations can be fixed by tooling",
+      ""
+    );
+  }
+  const contents =
+    // eslint-disable-next-line no-await-in-loop
+    await readFile(pathFor(`./${name.toLowerCase()}.md`), "utf8");
+  section.push(...linesFrom(contents));
+
+  // eslint-disable-next-line no-await-in-loop
+  await writeFile(
+    pathFor(`../doc/${name.toLowerCase()}.md`),
+    section.join(EOL).slice(1),
+    "utf8"
+  );
+
+  lines.push(...section);
+}
+
+const footing = await readFile(pathFor("./footing.md"), "utf8");
+lines.push(...linesFrom(footing));
+
+const content = lines.join(EOL);
+await writeFile(pathFor("../doc/Rules.md"), content, "utf8");

doc-build/footing.md

@@ -0,0 +1,7 @@
+<!-- markdownlint-configure-file {
+  "no-inline-html": {
+    "allowed_elements": [
+      "a"
+    ]
+  }
+} -->

doc-build/heading.md

@@ -0,0 +1,5 @@
+# Rules
+
+This document contains a description of all rules, what they are checking for,
+as well as examples of documents that break the rule and corrected
+versions of the examples.

doc-build/md001.md

@@ -0,0 +1,31 @@
+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
+```
+
+Rationale: Headings represent the structure of a document and can be confusing
+when skipped - especially for accessibility scenarios. More information:
+<https://www.w3.org/WAI/tutorials/page-structure/headings/>.

doc-build/md003.md

@@ -0,0 +1,47 @@
+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.

doc-build/md004.md

@@ -0,0 +1,37 @@
+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.

doc-build/md005.md

@@ -0,0 +1,45 @@
+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.

doc-build/md007.md

@@ -0,0 +1,36 @@
+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

doc-build/md009.md

@@ -0,0 +1,36 @@
+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.
+
+Note: Trailing space is allowed in indented and fenced code blocks because some
+languages require it.
+
+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 (\<br> element).
+
+Note: 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, 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 as well, 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.

doc-build/md010.md

@@ -0,0 +1,41 @@
+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:
+
+<!-- markdownlint-disable no-hard-tabs -->
+
+```markdown
+Some text
+
+	* hard tab character used to indent the list item
+```
+
+<!-- markdownlint-restore -->
+
+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.

doc-build/md011.md

@@ -0,0 +1,22 @@
+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://en.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.

doc-build/md012.md

@@ -0,0 +1,26 @@
+This rule is triggered when there are multiple consecutive blank lines in the
+document:
+
+```markdown
+Some text here
+
+
+Some more text here
+```
+
+To fix this, delete the offending lines:
+
+```markdown
+Some text here
+
+Some more text here
+```
+
+Note: this rule will not be triggered if there are multiple consecutive blank
+lines inside code blocks.
+
+Note: The `maximum` parameter can be used to configure the maximum number of
+consecutive blank lines.
+
+Rationale: Except in a code block, blank lines serve no purpose and do not
+affect the rendering of content.

doc-build/md013.md

@@ -0,0 +1,39 @@
+This rule is triggered when there are lines that are longer than the
+configured `line_length` (default: 80 characters). To fix this, split the line
+up into multiple lines. To set a different maximum length for headings, use
+`heading_line_length`. To set a different maximum length for code blocks, use
+`code_block_line_length`
+
+This rule has an exception when there is no whitespace beyond the configured
+line length. This allows you to include items such as long URLs without being
+forced to break them in the middle. To disable this exception, set the `strict`
+parameter to `true` and an issue will be reported when any line is too long. To
+warn for lines that are too long and could be fixed but allow long lines
+without spaces, set the `stern` parameter to `true`.
+
+For example (assuming normal behavior):
+
+```markdown
+IF THIS LINE IS THE MAXIMUM LENGTH
+This line is okay because there are-no-spaces-beyond-that-length
+This line is a violation because there are spaces beyond that length
+This-line-is-okay-because-there-are-no-spaces-anywhere-within
+```
+
+In `strict` mode, the last three lines above are all violations. In `stern`
+mode, the middle two lines above are both violations, but the last is okay.
+
+You have the option to exclude this rule for code blocks, tables, or headings.
+To do so, set the `code_blocks`, `tables`, or `headings` parameter(s) to false.
+
+Code blocks are included in this rule by default since it is often a
+requirement for document readability, and tentatively compatible with code
+rules. Still, some languages do not lend themselves to short lines.
+
+Lines with link/image reference definitions and standalone lines (i.e., not part
+of a paragraph) with only a link/image (possibly using (strong) emphasis) are
+always exempted from this rule (even in `strict` mode) because there is often no
+way to split such lines without breaking the URL.
+
+Rationale: Extremely long lines can be difficult to work with in some editors.
+More information: <https://cirosantilli.com/markdown-style-guide#line-wrapping>.

doc-build/md014.md

@@ -0,0 +1,46 @@
+This rule is triggered when there are code blocks showing shell commands to be
+typed, and *all* of the shell commands are preceded by dollar signs ($):
+
+<!-- markdownlint-disable commands-show-output -->
+
+```markdown
+$ ls
+$ cat foo
+$ less bar
+```
+
+<!-- markdownlint-restore -->
+
+The dollar signs are unnecessary in this situation, and should not be
+included:
+
+```markdown
+ls
+cat foo
+less bar
+```
+
+Showing output for commands preceded by dollar signs does not trigger this rule:
+
+```markdown
+$ ls
+foo bar
+$ cat foo
+Hello world
+$ cat bar
+baz
+```
+
+Because some commands do not produce output, it is not a violation if *some*
+commands do not have output:
+
+```markdown
+$ mkdir test
+mkdir: created directory 'test'
+$ ls test
+```
+
+Rationale: It is easier to copy/paste and less noisy if the dollar signs
+are omitted when they are not needed. See
+<https://cirosantilli.com/markdown-style-guide#dollar-signs-in-shell-code>
+for more information.

doc-build/md018.md

@@ -0,0 +1,19 @@
+This rule is triggered when spaces are missing after the hash characters
+in an atx style heading:
+
+```markdown
+#Heading 1
+
+##Heading 2
+```
+
+To fix this, separate the heading text from the hash character by a single
+space:
+
+```markdown
+# Heading 1
+
+## Heading 2
+```
+
+Rationale: Violations of this rule can lead to improperly rendered content.

doc-build/md019.md

@@ -0,0 +1,20 @@
+This rule is triggered when more than one space is used to separate the
+heading text from the hash characters in an atx style heading:
+
+```markdown
+#  Heading 1
+
+##  Heading 2
+```
+
+To fix this, separate the heading text from the hash character by a single
+space:
+
+```markdown
+# Heading 1
+
+## Heading 2
+```
+
+Rationale: Extra space has no purpose and does not affect the rendering of
+content.

doc-build/md020.md

@@ -0,0 +1,21 @@
+This rule is triggered when spaces are missing inside the hash characters
+in a closed atx style heading:
+
+```markdown
+#Heading 1#
+
+##Heading 2##
+```
+
+To fix this, separate the heading text from the hash character by a single
+space:
+
+```markdown
+# Heading 1 #
+
+## Heading 2 ##
+```
+
+Note: this rule will fire if either side of the heading is missing spaces.
+
+Rationale: Violations of this rule can lead to improperly rendered content.

doc-build/md021.md

@@ -0,0 +1,23 @@
+This rule is triggered when more than one space is used to separate the
+heading text from the hash characters in a closed atx style heading:
+
+```markdown
+#  Heading 1  #
+
+##  Heading 2  ##
+```
+
+To fix this, separate the heading text from the hash character by a single
+space:
+
+```markdown
+# Heading 1 #
+
+## Heading 2 ##
+```
+
+Note: this rule will fire if either side of the heading contains multiple
+spaces.
+
+Rationale: Extra space has no purpose and does not affect the rendering of
+content.

doc-build/md022.md

@@ -0,0 +1,39 @@
+This rule is triggered when headings (any style) are either not preceded or not
+followed by at least one blank line:
+
+```markdown
+# Heading 1
+Some text
+
+Some more text
+## Heading 2
+```
+
+To fix this, ensure that all headings have a blank line both before and after
+(except where the heading is at the beginning or end of the document):
+
+```markdown
+# Heading 1
+
+Some text
+
+Some more text
+
+## Heading 2
+```
+
+The `lines_above` and `lines_below` parameters can be used to specify a
+different number of blank lines (including `0`) above or below each heading.
+If the value `-1` is used for either parameter, any number of blank lines is
+allowed. To customize the number of lines above or below each heading level
+individually, specify a `number[]` where values correspond to heading levels
+1-6 (in order).
+
+Notes: If `lines_above` or `lines_below` are configured to require more than one
+blank line, [MD012/no-multiple-blanks](md012.md) should also be customized. This
+rule checks for *at least* as many blank lines as specified; any extra blank
+lines are ignored.
+
+Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`,
+will not parse headings that don't have a blank line before, and will parse them
+as regular text.

doc-build/md023.md

@@ -0,0 +1,25 @@
+This rule is triggered when a heading is indented by one or more spaces:
+
+```markdown
+Some text
+
+  # Indented heading
+```
+
+To fix this, ensure that all headings start at the beginning of the line:
+
+```markdown
+Some text
+
+# Heading
+```
+
+Note that scenarios like block quotes "indent" the start of the line, so the
+following is also correct:
+
+```markdown
+> # Heading in Block Quote
+```
+
+Rationale: Headings that don't start at the beginning of the line will not be
+parsed as headings, and will instead appear as regular text.

doc-build/md024.md

@@ -0,0 +1,34 @@
+This rule is triggered if there are multiple headings in the document that have
+the same text:
+
+```markdown
+# Some text
+
+## Some text
+```
+
+To fix this, ensure that the content of each heading is different:
+
+```markdown
+# Some text
+
+## Some more text
+```
+
+If the parameter `siblings_only` is set to `true`, duplication is allowed for
+headings with different parents (as is common in changelogs):
+
+```markdown
+# Change log
+
+## 1.0.0
+
+### Features
+
+## 2.0.0
+
+### Features
+```
+
+Rationale: Some Markdown parsers generate anchors for headings based on the
+heading name; headings with the same content can cause problems with that.

doc-build/md025.md

@@ -0,0 +1,37 @@
+This rule is triggered when a top-level heading is in use (the first line of
+the file is an h1 heading), and more than one h1 heading is in use in the
+document:
+
+```markdown
+# Top level heading
+
+# Another top-level heading
+```
+
+To fix, structure your document so there is a single h1 heading that is
+the title for the document. Subsequent headings must be
+lower-level headings (h2, h3, etc.):
+
+```markdown
+# Title
+
+## Heading
+
+## Another heading
+```
+
+Note: The `level` parameter can be used to change the top-level (ex: to h2) in
+cases where an h1 is added externally.
+
+If [YAML](https://en.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 for any subsequent
+top-level headings. 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`.
+
+Rationale: A top-level heading is an h1 on the first line of the file, and
+serves as the title for the document. If this convention is in use, then there
+can not be more than one title for the document, and the entire document should
+be contained within this heading.

doc-build/md026.md

@@ -0,0 +1,28 @@
+This rule is triggered on any heading that has one of the specified normal or
+full-width punctuation characters as the last character in the line:
+
+```markdown
+# This is a heading.
+```
+
+To fix this, remove the trailing punctuation:
+
+```markdown
+# This is a heading
+```
+
+Note: The `punctuation` parameter can be used to specify what characters count
+as punctuation at the end of a heading. For example, you can change it to
+`".,;:"` to allow headings that end with an exclamation point. `?` is
+allowed by default because of how common it is in headings of FAQ-style
+documents. Setting the `punctuation` parameter to `""` allows all characters -
+and is equivalent to disabling the rule.
+
+Note: The trailing semicolon of [HTML entity references][html-entity-references]
+like `©`, `©`, and `©` is ignored by this rule.
+
+Rationale: Headings are not meant to be full sentences. More information:
+[Punctuation at the end of headers][end-punctuation].
+
+[end-punctuation]: https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers
+[html-entity-references]: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

doc-build/md027.md

@@ -0,0 +1,20 @@
+This rule is triggered when blockquotes have more than one space after the
+blockquote (`>`) symbol:
+
+```markdown
+>  This is a blockquote with bad indentation
+>  there should only be one.
+```
+
+To fix, remove any extraneous space:
+
+```markdown
+> This is a blockquote with correct
+> indentation.
+```
+
+Inferring intended list indentation within a blockquote can be challenging;
+setting the `list_items` parameter to `false` disables this rule for ordered
+and unordered list items.
+
+Rationale: Consistent formatting makes it easier to understand a document.

doc-build/md028.md

@@ -0,0 +1,34 @@
+This rule is triggered when two blockquote blocks are separated by nothing
+except for a blank line:
+
+```markdown
+> This is a blockquote
+> which is immediately followed by
+
+> this blockquote. Unfortunately
+> In some parsers, these are treated as the same blockquote.
+```
+
+To fix this, ensure that any blockquotes that are right next to each other
+have some text in between:
+
+```markdown
+> This is a blockquote.
+
+And Jimmy also said:
+
+> This too is a blockquote.
+```
+
+Alternatively, if they are supposed to be the same quote, then add the
+blockquote symbol at the beginning of the blank line:
+
+```markdown
+> This is a blockquote.
+>
+> This is the same blockquote.
+```
+
+Rationale: Some Markdown parsers will treat two blockquotes separated by one
+or more blank lines as the same blockquote, while others will treat them as
+separate blockquotes.

doc-build/md029.md

@@ -0,0 +1,87 @@
+This rule is triggered for ordered lists that do not either start with '1.' or
+do not have a prefix that increases in numerical order (depending on the
+configured style). The less-common pattern of using '0.' as a first prefix or
+for all prefixes is also supported.
+
+Example valid list if the style is configured as 'one':
+
+```markdown
+1. Do this.
+1. Do that.
+1. Done.
+```
+
+Examples of valid lists if the style is configured as 'ordered':
+
+```markdown
+1. Do this.
+2. Do that.
+3. Done.
+```
+
+```markdown
+0. Do this.
+1. Do that.
+2. Done.
+```
+
+All three examples are valid when the style is configured as 'one_or_ordered'.
+
+Example valid list if the style is configured as 'zero':
+
+```markdown
+0. Do this.
+0. Do that.
+0. Done.
+```
+
+Example invalid list for all styles:
+
+```markdown
+1. Do this.
+3. Done.
+```
+
+This rule supports 0-prefixing ordered list items for uniform indentation:
+
+```markdown
+...
+08. Item
+09. Item
+10. Item
+11. Item
+...
+```
+
+Note: This rule will report violations for cases like the following where an
+improperly-indented code block (or similar) appears between two list items and
+"breaks" the list in two:
+
+<!-- markdownlint-disable code-fence-style -->
+
+~~~markdown
+1. First list
+
+```text
+Code block
+```
+
+1. Second list
+~~~
+
+The fix is to indent the code block so it becomes part of the preceding list
+item as intended:
+
+~~~markdown
+1. First list
+
+   ```text
+   Code block
+   ```
+
+2. Still first list
+~~~
+
+<!-- markdownlint-restore -->
+
+Rationale: Consistent formatting makes it easier to understand a document.

doc-build/md030.md

@@ -0,0 +1,64 @@
+This rule checks for the number of spaces between a list marker (e.g. '`-`',
+'`*`', '`+`' or '`1.`') and the text of the list item.
+
+The number of spaces checked for depends on the document style in use, but the
+default is 1 space after any list marker:
+
+```markdown
+* Foo
+* Bar
+* Baz
+
+1. Foo
+1. Bar
+1. Baz
+
+1. Foo
+   * Bar
+1. Baz
+```
+
+A document style may change the number of spaces after unordered list items
+and ordered list items independently, as well as based on whether the content
+of every item in the list consists of a single paragraph or multiple
+paragraphs (including sub-lists and code blocks).
+
+For example, the style guide at
+<https://cirosantilli.com/markdown-style-guide#spaces-after-list-marker>
+specifies that 1 space after the list marker should be used if every item in
+the list fits within a single paragraph, but to use 2 or 3 spaces (for ordered
+and unordered lists respectively) if there are multiple paragraphs of content
+inside the list:
+
+```markdown
+* Foo
+* Bar
+* Baz
+```
+
+vs.
+
+```markdown
+*   Foo
+
+    Second paragraph
+
+*   Bar
+```
+
+or
+
+```markdown
+1.  Foo
+
+    Second paragraph
+
+1.  Bar
+```
+
+To fix this, ensure the correct number of spaces are used after the list marker
+for your selected document style.
+
+Rationale: Violations of this rule can lead to improperly rendered content.
+
+Note: See [Prettier.md](Prettier.md) for compatibility information.

doc-build/md031.md

@@ -0,0 +1,38 @@
+This rule is triggered when fenced code blocks are either not preceded or not
+followed by a blank line:
+
+````markdown
+Some text
+```
+Code block
+```
+
+```
+Another code block
+```
+Some more text
+````
+
+To fix this, ensure that all fenced code blocks have a blank line both before
+and after (except where the block is at the beginning or end of the document):
+
+````markdown
+Some text
+
+```
+Code block
+```
+
+```
+Another code block
+```
+
+Some more text
+````
+
+Set the `list_items` parameter to `false` to disable this rule for list items.
+Disabling this behavior for lists can be useful if it is necessary to create a
+[tight](https://spec.commonmark.org/0.29/#tight) list containing a code fence.
+
+Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
+not parse fenced code blocks that don't have blank lines before and after them.

doc-build/md032.md

@@ -0,0 +1,47 @@
+This rule is triggered when lists (of any kind) are either not preceded or not
+followed by a blank line:
+
+```markdown
+Some text
+* List item
+* List item
+
+1. List item
+2. List item
+***
+```
+
+In the first case above, text immediately precedes the unordered list. In the
+second case above, a thematic break immediately follows the ordered list. To fix
+violations of this rule, ensure that all lists have a blank line both before and
+after (except when the list is at the very beginning or end of the document):
+
+```markdown
+Some text
+
+* List item
+* List item
+
+1. List item
+2. List item
+
+***
+```
+
+Note that the following case is **not** a violation of this rule:
+
+```markdown
+1. List item
+   More item 1
+2. List item
+More item 2
+```
+
+Although it is not indented, the text "More item 2" is referred to as a
+[lazy continuation line][lazy-continuation] and considered part of the second
+list item.
+
+Rationale: In addition to aesthetic reasons, some parsers, including kramdown,
+will not parse lists that don't have blank lines before and after them.
+
+[lazy-continuation]: https://spec.commonmark.org/0.30/#lazy-continuation-line

doc-build/md033.md

@@ -0,0 +1,17 @@
+This rule is triggered whenever raw HTML is used in a Markdown document:
+
+```markdown
+<h1>Inline HTML heading</h1>
+```
+
+To fix this, use 'pure' Markdown instead of including raw HTML:
+
+```markdown
+# Markdown heading
+```
+
+Note: To allow specific HTML elements, use the `allowed_elements` parameter.
+
+Rationale: Raw HTML is allowed in Markdown, but this rule is included for
+those who want their documents to only include "pure" Markdown, or for those
+who are rendering Markdown documents into something other than HTML.

doc-build/md034.md

@@ -0,0 +1,47 @@
+This rule is triggered whenever a URL or email address appears without
+surrounding angle brackets:
+
+```markdown
+For more info, visit https://www.example.com/ or email user@example.com.
+```
+
+To fix this, add angle brackets around the URL or email address:
+
+```markdown
+For more info, visit <https://www.example.com/> or email <user@example.com>.
+```
+
+If a URL or email address contains non-ASCII characters, it may be not be
+handled as intended even when angle brackets are present. In such cases,
+[percent-encoding](https://en.m.wikipedia.org/wiki/Percent-encoding) can be used
+to comply with the required syntax for URL and email.
+
+Note: To include a bare URL or email without it being converted into a link,
+wrap it in a code span:
+
+```markdown
+Not a clickable link: `https://www.example.com`
+```
+
+Note: The following scenario does not trigger this rule because it could be a
+shortcut link:
+
+```markdown
+[https://www.example.com]
+```
+
+Note: The following syntax triggers this rule because the nested link could be
+a shortcut link (which takes precedence):
+
+```markdown
+[text [shortcut] text](https://example.com)
+```
+
+To avoid this, escape both inner brackets:
+
+```markdown
+[link \[text\] link](https://example.com)
+```
+
+Rationale: Without angle brackets, a bare URL or email isn't converted into a
+link by some Markdown parsers.

doc-build/md035.md

@@ -0,0 +1,27 @@
+This rule is triggered when inconsistent styles of horizontal rules are used
+in the document:
+
+```markdown
+---
+
+- - -
+
+***
+
+* * *
+
+****
+```
+
+To fix this, use the same horizontal rule everywhere:
+
+```markdown
+---
+
+---
+```
+
+The configured style can ensure all horizontal rules use a specific string or it
+can ensure all horizontal rules match the first horizontal rule (`consistent`).
+
+Rationale: Consistent formatting makes it easier to understand a document.

doc-build/md036.md

@@ -0,0 +1,35 @@
+This check looks for instances where emphasized (i.e. bold or italic) text is
+used to separate sections, where a heading should be used instead:
+
+```markdown
+**My document**
+
+Lorem ipsum dolor sit amet...
+
+_Another section_
+
+Consectetur adipiscing elit, sed do eiusmod.
+```
+
+To fix this, use Markdown headings instead of emphasized text to denote
+sections:
+
+```markdown
+# My document
+
+Lorem ipsum dolor sit amet...
+
+## Another section
+
+Consectetur adipiscing elit, sed do eiusmod.
+```
+
+Note: This rule looks for single-line paragraphs that consist entirely
+of emphasized text. It won't fire on emphasis used within regular text,
+multi-line emphasized paragraphs, or paragraphs ending in punctuation
+(normal or full-width). Similarly to rule MD026, you can configure what
+characters are recognized as punctuation.
+
+Rationale: Using emphasis instead of a heading prevents tools from inferring
+the structure of a document. More information:
+<https://cirosantilli.com/markdown-style-guide#emphasis-vs-headers>.

doc-build/md037.md

@@ -0,0 +1,29 @@
+This rule is triggered when emphasis markers (bold, italic) are used, but they
+have spaces between the markers and the text:
+
+```markdown
+Here is some ** bold ** text.
+
+Here is some * italic * text.
+
+Here is some more __ bold __ text.
+
+Here is some more _ italic _ text.
+```
+
+To fix this, remove the spaces around the emphasis markers:
+
+```markdown
+Here is some **bold** text.
+
+Here is some *italic* text.
+
+Here is some more __bold__ text.
+
+Here is some more _italic_ text.
+```
+
+Rationale: Emphasis is only parsed as such when the asterisks/underscores
+aren't surrounded by spaces. This rule attempts to detect where
+they were surrounded by spaces, but it appears that emphasized text was
+intended by the author.

doc-build/md038.md

@@ -0,0 +1,44 @@
+This rule is triggered for code spans containing content with unnecessary space
+next to the beginning or ending backticks:
+
+```markdown
+`some text `
+
+` some text`
+
+`   some text   `
+```
+
+To fix this, remove the extra space characters from the beginning and ending:
+
+```markdown
+`some text`
+```
+
+Note: A single leading *and* trailing space is allowed by the specification and
+trimmed by the parser to support code spans that begin or end with a backtick:
+
+```markdown
+`` `backticks` ``
+
+`` backtick` ``
+```
+
+Note: When single-space padding is present in the input, it will be preserved
+(even if unnecessary):
+
+```markdown
+` code `
+```
+
+Note: Code spans containing only spaces are allowed by the specification and are
+also preserved:
+
+```markdown
+` `
+
+`   `
+```
+
+Rationale: Violations of this rule are usually unintentional and can lead to
+improperly-rendered content.

doc-build/md039.md

@@ -0,0 +1,13 @@
+This rule is triggered on links that have spaces surrounding the link text:
+
+```markdown
+[ a link ](https://www.example.com/)
+```
+
+To fix this, remove the spaces surrounding the link text:
+
+```markdown
+[a link](https://www.example.com/)
+```
+
+Rationale: Consistent formatting makes it easier to understand a document.

doc-build/md040.md

@@ -0,0 +1,41 @@
+This rule is triggered when fenced code blocks are used, but a language isn't
+specified:
+
+````markdown
+```
+#!/bin/bash
+echo Hello world
+```
+````
+
+To fix this, add a language specifier to the code block:
+
+````markdown
+```bash
+#!/bin/bash
+echo Hello world
+```
+````
+
+To display a code block without syntax highlighting, use:
+
+````markdown
+```text
+Plain text in a code block
+```
+````
+
+You can configure the `allowed_languages` parameter to specify a list of
+languages code blocks could use. Languages are case sensitive. The default value
+is `[]` which means any language specifier is valid.
+
+You can prevent extra data from being present in the info string of fenced code
+blocks. To do so, set the `language_only` parameter to `true`.
+
+<!-- markdownlint-disable-next-line no-space-in-code -->
+Info strings with leading/trailing whitespace (ex: `js `) or other content (ex:
+`ruby startline=3`) will trigger this rule.
+
+Rationale: Specifying a language improves content rendering by using the
+correct syntax highlighting for code. More information:
+<https://cirosantilli.com/markdown-style-guide#option-code-fenced>.

doc-build/md041.md

@@ -0,0 +1,50 @@
+This rule is intended to ensure documents have a title and is triggered when
+the first line in a document is not a top-level ([HTML][HTML] `h1`) heading:
+
+```markdown
+This is a document without a heading
+```
+
+To fix this, add a top-level heading to the beginning of the document:
+
+```markdown
+# Document Heading
+
+This is a document with a top-level heading
+```
+
+Because it is common for projects on GitHub to use an image for the heading of
+`README.md` and that pattern is not well-supported by Markdown, HTML headings
+are also permitted by this rule. For example:
+
+```markdown
+<h1 align="center"><img src="https://placekitten.com/300/150"/></h1>
+
+This is a document with a top-level HTML heading
+```
+
+In some cases, a document's title heading may be preceded by text like a table
+of contents. This is not ideal for accessibility, but can be allowed by setting
+the `allow_preamble` parameter to `true`.
+
+```markdown
+This is a document with preamble text
+
+# Document Heading
+```
+
+If [YAML][YAML] front matter is present and contains a `title` property
+(commonly used with blog posts), this rule will not report a violation. To use a
+different property name in the front matter, specify the text of a [regular
+expression][RegExp] via the `front_matter_title` parameter. To disable the use
+of front matter by this rule, specify `""` for `front_matter_title`.
+
+The `level` parameter can be used to change the top-level heading (ex: to `h2`)
+in cases where an `h1` is added externally.
+
+Rationale: The top-level heading often acts as the title of a document. More
+information: <https://cirosantilli.com/markdown-style-guide#top-level-header>.
+
+[HTML]: https://en.wikipedia.org/wiki/HTML
+[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions
+[YAML]: https://en.wikipedia.org/wiki/YAML

doc-build/md042.md

@@ -0,0 +1,26 @@
+This rule is triggered when an empty link is encountered:
+
+```markdown
+[an empty link]()
+```
+
+To fix the violation, provide a destination for the link:
+
+```markdown
+[a valid link](https://example.com/)
+```
+
+Empty fragments will trigger this rule:
+
+```markdown
+[an empty fragment](#)
+```
+
+But non-empty fragments will not:
+
+```markdown
+[a valid fragment](#fragment)
+```
+
+Rationale: Empty links do not lead anywhere and therefore don't function as
+links.

doc-build/md043.md

@@ -0,0 +1,76 @@
+This rule is triggered when the headings in a file do not match the array of
+headings passed to the rule. It can be used to enforce a standard heading
+structure for a set of files.
+
+To require exactly the following structure:
+
+```markdown
+# Heading
+## Item
+### Detail
+```
+
+Set the `headings` parameter to:
+
+```json
+[
+    "# Heading",
+    "## Item",
+    "### Detail"
+]
+```
+
+To allow optional headings as with the following structure:
+
+```markdown
+# Heading
+## Item
+### Detail (optional)
+## Foot
+### Notes (optional)
+```
+
+Use the special value `"*"` meaning "zero or more unspecified headings" or the
+special value `"+"` meaning "one or more unspecified headings" and set the
+`headings` parameter to:
+
+```json
+[
+    "# Heading",
+    "## Item",
+    "*",
+    "## Foot",
+    "*"
+]
+```
+
+To allow a single required heading to vary as with a project name:
+
+```markdown
+# Project Name
+## Description
+## Examples
+```
+
+Use the special value `"?"` meaning "exactly one unspecified heading":
+
+```json
+[
+    "?",
+    "## Description",
+    "## Examples"
+]
+```
+
+When an error is detected, this rule outputs the line number of the first
+problematic heading (otherwise, it outputs the last line number of the file).
+
+Note that while the `headings` parameter uses the "## Text" ATX heading style
+for simplicity, a file may use any supported heading style.
+
+By default, the case of headings in the document is not required to match that
+of `headings`. To require that case match exactly, set the `match_case`
+parameter to `true`.
+
+Rationale: Projects may wish to enforce a consistent document structure across
+a set of similar content.

doc-build/md044.md

@@ -0,0 +1,31 @@
+This rule is triggered when any of the strings in the `names` array do not have
+the specified capitalization. It can be used to enforce a standard letter case
+for the names of projects and products.
+
+For example, the language "JavaScript" is usually written with both the 'J' and
+'S' capitalized - though sometimes the 's' or 'j' appear in lower-case. To
+enforce the proper capitalization, specify the desired letter case in the
+`names` array:
+
+```json
+[
+    "JavaScript"
+]
+```
+
+Sometimes a proper name is capitalized differently in certain contexts. In such
+cases, add both forms to the `names` array:
+
+```json
+[
+    "GitHub",
+    "github.com"
+]
+```
+
+Set the `code_blocks` parameter to `false` to disable this rule for code blocks
+and spans. Set the `html_elements` parameter to `false` to disable this rule
+for HTML elements and attributes (such as when using a proper name as part of
+a path for `a`/`href` or `img`/`src`).
+
+Rationale: Incorrect capitalization of proper names is usually a mistake.

doc-build/md045.md

@@ -0,0 +1,42 @@
+This rule reports a violation when an image is missing alternate text (alt text)
+information.
+
+Alternate text is commonly specified inline as:
+
+```markdown
+![Alternate text](image.jpg)
+```
+
+Or with reference syntax as:
+
+```markdown
+![Alternate text][ref]
+
+...
+
+[ref]: image.jpg "Optional title"
+```
+
+Or with HTML as:
+
+```html
+<img src="image.jpg" alt="Alternate text" />
+```
+
+Note: If the [HTML `aria-hidden` attribute][aria-hidden] is used to hide the
+image from assistive technology, this rule does not report a violation:
+
+```html
+<img src="image.jpg" aria-hidden="true" />
+```
+
+Guidance for writing alternate text is available from the [W3C][w3c],
+[Wikipedia][wikipedia], and [other locations][phase2technology].
+
+Rationale: Alternate text is important for accessibility and describes the
+content of an image for people who may not be able to see it.
+
+[aria-hidden]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden
+[phase2technology]: https://www.phase2technology.com/blog/no-more-excuses
+[w3c]: https://www.w3.org/WAI/alt/
+[wikipedia]: https://en.wikipedia.org/wiki/Alt_attribute

doc-build/md046.md

@@ -0,0 +1,29 @@
+This rule is triggered when unwanted or different code block styles are used in
+the same document.
+
+In the default configuration this rule reports a violation for the following
+document:
+
+<!-- markdownlint-disable code-block-style -->
+
+    Some text.
+
+        # Indented code
+
+    More text.
+
+    ```ruby
+    # Fenced code
+    ```
+
+    More text.
+
+<!-- markdownlint-restore -->
+
+To fix violations of this rule, use a consistent style (either indenting or code
+fences).
+
+The configured code block style can be specific (`fenced`, `indented`) or can
+require all code blocks match the first code block (`consistent`).
+
+Rationale: Consistent formatting makes it easier to understand a document.

doc-build/md047.md

@@ -0,0 +1,26 @@
+This rule is triggered when there is not a single newline character at the end
+of a file.
+
+An example that triggers the rule:
+
+```markdown
+# Heading
+
+This file ends without a newline.[EOF]
+```
+
+To fix the violation, add a newline character to the end of the file:
+
+```markdown
+# Heading
+
+This file ends with a newline.
+[EOF]
+```
+
+Rationale: Some programs have trouble with files that do not end with a newline.
+
+More information: [What's the point in adding a new line to the end of a
+file?][stack-exchange]
+
+[stack-exchange]: https://unix.stackexchange.com/questions/18743/whats-the-point-in-adding-a-new-line-to-the-end-of-a-file

doc-build/md048.md

@@ -0,0 +1,31 @@
+This rule is triggered when the symbols used in the document for fenced code
+blocks do not match the configured code fence style:
+
+````markdown
+```ruby
+# Fenced code
+```
+
+~~~ruby
+# Fenced code
+~~~
+````
+
+To fix this issue, use the configured code fence style throughout the
+document:
+
+````markdown
+```ruby
+# Fenced code
+```
+
+```ruby
+# Fenced code
+```
+````
+
+The configured code fence style can be a specific symbol to use (`backtick`,
+`tilde`) or it can require all code fences match the first code fence
+(`consistent`).
+
+Rationale: Consistent formatting makes it easier to understand a document.

doc-build/md049.md

@@ -0,0 +1,23 @@
+This rule is triggered when the symbols used in the document for emphasis do not
+match the configured emphasis style:
+
+```markdown
+*Text*
+_Text_
+```
+
+To fix this issue, use the configured emphasis style throughout the document:
+
+```markdown
+*Text*
+*Text*
+```
+
+The configured emphasis style can be a specific symbol to use (`asterisk`,
+`underscore`) or can require all emphasis matches the first emphasis
+(`consistent`).
+
+Note: Emphasis within a word is restricted to `asterisk` in order to avoid
+unwanted emphasis for words containing internal underscores like_this_one.
+
+Rationale: Consistent formatting makes it easier to understand a document.

doc-build/md050.md

@@ -0,0 +1,22 @@
+This rule is triggered when the symbols used in the document for strong do not
+match the configured strong style:
+
+```markdown
+**Text**
+__Text__
+```
+
+To fix this issue, use the configured strong style throughout the document:
+
+```markdown
+**Text**
+**Text**
+```
+
+The configured strong style can be a specific symbol to use (`asterisk`,
+`underscore`) or can require all strong matches the first strong (`consistent`).
+
+Note: Emphasis within a word is restricted to `asterisk` in order to avoid
+unwanted emphasis for words containing internal underscores like__this__one.
+
+Rationale: Consistent formatting makes it easier to understand a document.

doc-build/md051.md

@@ -0,0 +1,98 @@
+This rule is triggered when a link fragment does not match any of the fragments
+that are automatically generated for headings in a document:
+
+```markdown
+# Heading Name
+
+[Link](#fragment)
+```
+
+To fix this issue, change the link fragment to reference an existing heading's
+generated name (see below):
+
+```markdown
+# Heading Name
+
+[Link](#heading-name)
+```
+
+For consistency, this rule requires fragments to exactly match the [GitHub
+heading algorithm][github-heading-algorithm] which converts letters to
+lowercase. Therefore, the following example is reported as a violation:
+
+```markdown
+# Heading Name
+
+[Link](#Heading-Name)
+```
+
+To ignore case when comparing fragments with heading names, the `ignore_case`
+parameter can be set to `true`. In this configuration, the previous example is
+not reported as a violation.
+
+Alternatively, some platforms allow the syntax `{#named-anchor}` to be used
+within a heading to provide a specific name (consisting of only lower-case
+letters, numbers, `-`, and `_`):
+
+```markdown
+# Heading Name {#custom-name}
+
+[Link](#custom-name)
+```
+
+Alternatively, any HTML tag with an `id` attribute or an `a` tag with a `name`
+attribute can be used to define a fragment:
+
+```markdown
+<a id="bookmark"></a>
+
+[Link](#bookmark)
+```
+
+An `a` tag can be useful in scenarios where a heading is not appropriate or for
+control over the text of the fragment identifier.
+
+[HTML links to `#top` scroll to the top of a document][html-top-fragment]. This
+rule allows that syntax (using lower-case for consistency):
+
+```markdown
+[Link](#top)
+```
+
+This rule also recognizes the custom fragment syntax used by GitHub to highlight
+[specific content in a document][github-linking-to-content].
+
+For example, this link to line 20:
+
+```markdown
+[Link](#L20)
+```
+
+And this link to content starting within line 19 running into line 21:
+
+```markdown
+[Link](#L19C5-L21C11)
+```
+
+Some Markdown generators dynamically create and insert headings when building
+documents, for example by combining a fixed prefix like `figure-` and an
+incrementing numeric counter. To ignore such generated fragments, set the
+`ignored_pattern` [regular expression][RegEx] parameter to a pattern that
+matches (e.g., `^figure-`).
+
+Rationale: [GitHub section links][github-section-links] are created
+automatically for every heading when Markdown content is displayed on GitHub.
+This makes it easy to link directly to different sections within a document.
+However, section links change if headings are renamed or removed. This rule
+helps identify broken section links within a document.
+
+Section links are **not** part of the CommonMark specification. This rule
+enforces the [GitHub heading algorithm][github-heading-algorithm] which is:
+convert heading to lowercase, remove punctuation, convert spaces to dashes,
+append an incrementing integer as needed for uniqueness.
+
+[github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
+[github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/f13a1534cb650ba17af400d1acd3a22c28004c09/lib/html/pipeline/toc_filter.rb
+[github-linking-to-content]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet#linking-to-markdown#linking-to-markdown
+[html-top-fragment]: https://html.spec.whatwg.org/multipage/browsing-the-web.html#scrolling-to-a-fragment
+[RegEx]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions

doc-build/md052.md

@@ -0,0 +1,41 @@
+Links and images in Markdown can provide the link destination or image source
+at the time of use or can define it elsewhere and use a label for reference.
+The reference format is convenient for keeping paragraph text clutter-free
+and makes it easy to reuse the same URL in multiple places.
+
+There are three kinds of reference links and images:
+
+```markdown
+Full: [text][label]
+Collapsed: [label][]
+Shortcut: [label]
+
+Full: ![text][image]
+Collapsed: ![image][]
+Shortcut: ![image]
+
+[label]: https://example.com/label
+[image]: https://example.com/image
+```
+
+A link or image renders correctly when the corresponding label is defined, but
+displays as text with brackets when the label is not present. By default, this
+rule warns of undefined labels for "full" and "collapsed" reference syntax but
+not for "shortcut" syntax because it is ambiguous.
+
+The text `[example]` could be a shortcut link or the text "example" in brackets,
+so "shortcut" syntax is ignored by default. To include "shortcut" syntax, set
+the `include_shortcut` parameter to `true`. Note that doing so produces warnings
+for *all* text in the document that *could* be a shortcut. If bracketed text is
+intentional, brackets can be escaped with the `\` character: `\[example\]`.
+
+If there are link labels that are deliberately unreferenced, they can be ignored
+by setting the `ignored_labels` parameter to the list of strings to ignore. The
+default value of this parameter ignores the checkbox syntax used by
+[GitHub Flavored Markdown task list items][gfm-tasklist]:
+
+```markdown
+- [x] Checked task list item
+```
+
+[gfm-tasklist]: https://github.github.com/gfm/#task-list-items-extension-

doc-build/md053.md

@@ -0,0 +1,26 @@
+Links and images in Markdown can provide the link destination or image source
+at the time of use or can use a label to reference a definition elsewhere in
+the document. The latter reference format is convenient for keeping paragraph
+text clutter-free and makes it easy to reuse the same URL in multiple places.
+
+Because link and image reference definitions are located separately from
+where they are used, there are two scenarios where a definition can be
+unnecessary:
+
+1. If a label is not referenced by any link or image in a document, that
+   definition is unused and can be deleted.
+2. If a label is defined multiple times in a document, the first definition is
+   used and the others can be deleted.
+
+This rule considers a reference definition to be used if any link or image
+reference has the corresponding label. The "full", "collapsed", and "shortcut"
+formats are all supported.
+
+If there are reference definitions that are deliberately unreferenced, they can
+be ignored by setting the `ignored_definitions` parameter to the list of strings
+to ignore. The default value of this parameter ignores the following convention
+for adding non-HTML comments to Markdown:
+
+```markdown
+[//]: # (This behaves like a comment)
+```

doc-build/md054.md

@@ -0,0 +1,81 @@
+Links and images in Markdown can provide the link destination or image source at
+the time of use or can use a label to reference a definition elsewhere in the
+document. The three reference formats are convenient for keeping paragraph text
+clutter-free and make it easy to reuse the same URL in multiple places.
+
+By default, this rule allows all link/image styles.
+
+Setting the `autolink` parameter to `false` disables autolinks:
+
+```markdown
+<https://example.com>
+```
+
+Setting the `inline` parameter to `false` disables inline links and images:
+
+```markdown
+[link](https://example.com)
+
+![image](https://example.com)
+```
+
+Setting the `full` parameter to `false` disables full reference links and
+images:
+
+```markdown
+[link][url]
+
+![image][url]
+
+[url]: https://example.com
+```
+
+Setting the `collapsed` parameter to `false` disables collapsed reference links
+and images:
+
+```markdown
+[url][]
+
+![url][]
+
+[url]: https://example.com
+```
+
+Setting the `shortcut` parameter to `false` disables shortcut reference links
+and images:
+
+```markdown
+[url]
+
+![url]
+
+[url]: https://example.com
+```
+
+To fix violations of this rule, change the link or image to use an allowed
+style. This rule can automatically fix violations when a link or image can be
+converted to the `inline` style (preferred) or a link can be converted to the
+`autolink` style (which does not support images and must be an absolute URL).
+This rule does *not* fix scenarios that require converting a link or image to
+the `full`, `collapsed`, or `shortcut` reference styles because that involves
+naming the reference and determining where to insert it in the document.
+
+Setting the `url_inline` parameter to `false` prevents the use of inline links
+with the same absolute URL text/destination and no title because such links can
+be converted to autolinks:
+
+```markdown
+[https://example.com](https://example.com)
+```
+
+To fix `url_inline` violations, use the simpler autolink syntax instead:
+
+```markdown
+<https://example.com>
+```
+
+Rationale: Consistent formatting makes it easier to understand a document.
+Autolinks are concise, but appear as URLs which can be long and confusing.
+Inline links and images can include descriptive text, but take up more space in
+Markdown form. Reference links and images can be easier to read and manipulate
+in Markdown form, but require a separate link reference definition.

doc-build/md055.md

@@ -0,0 +1,43 @@
+This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-055]
+is inconsistent about its use of leading and trailing pipe characters (`|`).
+
+By default (`consistent` style), the header row of the first table in a document
+is used to determine the style that is enforced for every table in the document.
+A specific style can be used instead (`leading_and_trailing`, `leading_only`,
+`no_leading_or_trailing`, `trailing_only`).
+
+This table's header row has leading and trailing pipes, but its delimiter row is
+missing the trailing pipe and its first row of cells is missing the leading
+pipe:
+
+```markdown
+| Header | Header |
+| ------ | ------
+  Cell   | Cell   |
+```
+
+To fix these issues, make sure there is a pipe character at the beginning and
+end of every row:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+```
+
+Note that text immediately following a table (i.e., not separated by an empty
+line) is treated as part of the table (per the specification) and may also
+trigger this rule:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+This text is part of the table
+```
+
+Rationale: Some parsers have difficulty with tables that are missing their
+leading or trailing pipe characters. The use of leading/trailing pipes can also
+help provide visual clarity.
+
+[gfm-table-055]: https://github.github.com/gfm/#tables-extension-

doc-build/md056.md

@@ -0,0 +1,31 @@
+This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-056]
+does not have the same number of cells in every row.
+
+This table's second data row has too few cells and its third data row has too
+many cells:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+| Cell   |
+| Cell   | Cell   | Cell   |
+```
+
+To fix these issues, ensure every row has the same number of cells:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+| Cell   | Cell   |
+| Cell   | Cell   |
+```
+
+Note that a table's header row and its delimiter row must have the same number
+of cells or it will not be recognized as a table (per specification).
+
+Rationale: Extra cells in a row are usually not shown, so their data is lost.
+Missing cells in a row create holes in the table and suggest an omission.
+
+[gfm-table-056]: https://github.github.com/gfm/#tables-extension-

doc-build/md058.md

@@ -0,0 +1,40 @@
+This rule is triggered when tables are either not preceded or not followed by a
+blank line:
+
+```markdown
+Some text
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+> Blockquote
+```
+
+To fix violations of this rule, ensure that all tables have a blank line both
+before and after (except when the table is at the very beginning or end of the
+document):
+
+```markdown
+Some text
+
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+
+> Blockquote
+```
+
+Note that text immediately following a table (i.e., not separated by an empty
+line) is treated as part of the table (per the specification) and will not
+trigger this rule:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+This text is part of the table and the next line is blank
+
+Some text
+```
+
+Rationale: In addition to aesthetic reasons, some parsers will incorrectly parse
+tables that don't have blank lines before and after them.

doc-build/md059.md

@@ -0,0 +1,19 @@
+This rule is triggered when a link has generic text like `[click here](...)` or
+`[link](...)`.
+
+Link text should be descriptive and communicate the purpose of the link (e.g.,
+`[Download the budget document](...)` or `[CommonMark Specification](...)`).
+This is especially important for screen readers which sometimes present links
+without context.
+
+By default, this rule prohibits a small number of common English words/phrases.
+To customize that list of words/phrases, set the `prohibited_texts` parameter to
+an `Array` of `string`s.
+
+Note: For languages other than English, use the `prohibited_texts` parameter to
+customize the list for that language. It is *not* a goal for this rule to have
+translations for every language.
+
+Note: This rule checks Markdown links; HTML links are ignored.
+
+More information: <https://webaim.org/techniques/hypertext/>

doc/CustomRules.md

@@ -1,304 +1,194 @@
 # Custom Rules
 
-In addition to its built-in rules, `markdownlint` lets you enhance the linting experience by passing a list of custom rules using the [`options.customRules` property](../README.md#optionscustomrules).
-Custom rules can do everything the built-in rules can and are defined inline or imported from another package ([keyword `markdownlint-rule` on npm](https://www.npmjs.com/search?q=keywords:markdownlint-rule)).
-Custom rules can be disabled, enabled, and customized using the same syntax as built-in 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.
+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.
 
-A simple rule implementation looks like:
+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`.
 
-```js
-const { URL } = require("url");
+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" ],
+  "names": [ "any-blockquote-micromark" ],
   "description": "Rule that reports an error for any blockquote",
   "information": new URL("https://example.com/rules/any-blockquote"),
   "tags": [ "test" ],
-  "function": function rule(params, onError) {
-    params.tokens.filter(function filterToken(token) {
-      return token.type === "blockquote_open";
-    }).forEach(function forToken(blockquote) {
-      var lines = blockquote.map[1] - blockquote.map[0];
+  "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.lineNumber,
+        "lineNumber": blockquote.startLine,
         "detail": "Blockquote spans " + lines + " line(s).",
-        "context": blockquote.line.substr(0, 7)
+        "context": params.lines[blockquote.startLine - 1]
       });
-    });
-  }
-};
-```
-
-A rule is implemented as an `Object` with four required properties:
-
-- `names` is an `Array` of `String` values that identify the rule in output messages and config.
-- `description` is a `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 an `Array` of `String` values that groups related rules for easier customization.
-- `function` is a synchronous `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.
-    - `tokens` is an `Array` of [`markdown-it` `Token` objects](https://markdown-it.github.io/markdown-it/#Token) with added `line` and `lineNumber` properties.
-    - `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).
-  - `onError` is a function that takes a single `Object` parameter with one required and three optional properties:
-    - `lineNumber` is a required `Number` specifying the 1-based line number of the error.
-    - `details` is an optional `String` with information about what caused the error.
-    - `context` is an optional `String` with relevant text surrounding the error location.
-    - `range` is an optional `Array` with two `Number` values identifying the 1-based column and length of the error.
-
-The collection of helper functions shared by the built-in rules is available for use by custom rules in the [markdownlint-rule-helpers package](https://www.npmjs.com/package/markdownlint-rule-helpers).
-
-## Examples
-
-- [Simple rules used by the project's test cases](../test/rules)
-- [Code for all `markdownlint` built-in rules](../lib)
-- [Package configuration for publishing to npm](../test/rules/npm)
-  - Packages should export a single rule object or an `Array` of rule objects
-- [Custom rules from the Microsoft/vscode-docs-authoring repository](https://github.com/Microsoft/vscode-docs-authoring/tree/master/docs-markdown/markdownlint-custom-rules)
-- [Custom rules from the axibase/docs-util repository](https://github.com/axibase/docs-util/tree/master/linting-rules)
-- [Custom rules from the webhintio/hint repository](https://github.com/webhintio/hint/blob/master/scripts/lint-markdown.js)
-
-## References
-
-- [CommonMark documentation and specification](https://commonmark.org/)
-- [`markdown-it` Markdown parser project page](https://github.com/markdown-it/markdown-it)
-
-## Params
-
-The Markdown document:
-
-```markdown
-# Title
-
-Text *text* text.
-```
-
-Yields the `params` object:
-
-```json
-{
-  "name": "doc/example.md",
-  "tokens": [
-    {
-      "type": "heading_open",
-      "tag": "h1",
-      "attrs": null,
-      "map": [ 0, 1 ],
-      "nesting": 1,
-      "level": 0,
-      "children": null,
-      "content": "",
-      "markup": "#",
-      "info": "",
-      "meta": null,
-      "block": true,
-      "hidden": false,
-      "line": "# Title",
-      "lineNumber": 1
-    },
-    {
-      "type": "inline",
-      "tag": "",
-      "attrs": null,
-      "map": [ 0, 1 ],
-      "nesting": 0,
-      "level": 1,
-      "children": [
-        {
-          "type": "text",
-          "tag": "",
-          "attrs": null,
-          "map": null,
-          "nesting": 0,
-          "level": 0,
-          "children": null,
-          "content": "Title",
-          "markup": "",
-          "info": "",
-          "meta": null,
-          "block": false,
-          "hidden": false,
-          "lineNumber": 1,
-          "line": "# Title"
-        }
-      ],
-      "content": "Title",
-      "markup": "",
-      "info": "",
-      "meta": null,
-      "block": true,
-      "hidden": false,
-      "line": "# Title",
-      "lineNumber": 1
-    },
-    {
-      "type": "heading_close",
-      "tag": "h1",
-      "attrs": null,
-      "map": null,
-      "nesting": -1,
-      "level": 0,
-      "children": null,
-      "content": "",
-      "markup": "#",
-      "info": "",
-      "meta": null,
-      "block": true,
-      "hidden": false
-    },
-    {
-      "type": "paragraph_open",
-      "tag": "p",
-      "attrs": null,
-      "map": [ 2, 3 ],
-      "nesting": 1,
-      "level": 0,
-      "children": null,
-      "content": "",
-      "markup": "",
-      "info": "",
-      "meta": null,
-      "block": true,
-      "hidden": false,
-      "line": "Text *text* text.",
-      "lineNumber": 3
-    },
-    {
-      "type": "inline",
-      "tag": "",
-      "attrs": null,
-      "map": [ 2, 3 ],
-      "nesting": 0,
-      "level": 1,
-      "children": [
-        {
-          "type": "text",
-          "tag": "",
-          "attrs": null,
-          "map": null,
-          "nesting": 0,
-          "level": 0,
-          "children": null,
-          "content": "Text ",
-          "markup": "",
-          "info": "",
-          "meta": null,
-          "block": false,
-          "hidden": false,
-          "lineNumber": 3,
-          "line": "Text *text* text."
-        },
-        {
-          "type": "em_open",
-          "tag": "em",
-          "attrs": null,
-          "map": null,
-          "nesting": 1,
-          "level": 1,
-          "children": null,
-          "content": "",
-          "markup": "*",
-          "info": "",
-          "meta": null,
-          "block": false,
-          "hidden": false,
-          "lineNumber": 3,
-          "line": "Text *text* text."
-        },
-        {
-          "type": "text",
-          "tag": "",
-          "attrs": null,
-          "map": null,
-          "nesting": 0,
-          "level": 1,
-          "children": null,
-          "content": "text",
-          "markup": "",
-          "info": "",
-          "meta": null,
-          "block": false,
-          "hidden": false,
-          "lineNumber": 3,
-          "line": "Text *text* text."
-        },
-        {
-          "type": "em_close",
-          "tag": "em",
-          "attrs": null,
-          "map": null,
-          "nesting": -1,
-          "level": 0,
-          "children": null,
-          "content": "",
-          "markup": "*",
-          "info": "",
-          "meta": null,
-          "block": false,
-          "hidden": false,
-          "lineNumber": 3,
-          "line": "Text *text* text."
-        },
-        {
-          "type": "text",
-          "tag": "",
-          "attrs": null,
-          "map": null,
-          "nesting": 0,
-          "level": 0,
-          "children": null,
-          "content": " text.",
-          "markup": "",
-          "info": "",
-          "meta": null,
-          "block": false,
-          "hidden": false,
-          "lineNumber": 3,
-          "line": "Text *text* text."
-        }
-      ],
-      "content": "Text *text* text.",
-      "markup": "",
-      "info": "",
-      "meta": null,
-      "block": true,
-      "hidden": false,
-      "line": "Text *text* text.",
-      "lineNumber": 3
-    },
-    {
-      "type": "paragraph_close",
-      "tag": "p",
-      "attrs": null,
-      "map": null,
-      "nesting": -1,
-      "level": 0,
-      "children": null,
-      "content": "",
-      "markup": "",
-      "info": "",
-      "meta": null,
-      "block": true,
-      "hidden": false
     }
-  ],
-  "lines": [
-    "# Title",
-    "",
-    "Text *text* text.",
-    ""
-  ],
-  "frontMatterLines": [],
-  "config": {
-    "customValue1": "abc",
-    "customValue2": 123
   }
 }
 ```
+
+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/snapshots/markdownlint-test-custom-rules.mjs.md

doc/Prettier.md

@@ -0,0 +1,27 @@
+# Using `markdownlint` with Prettier
+
+[`Prettier`](https://prettier.io) is a popular code formatter.
+For the most part, Prettier works seamlessly with `markdownlint`.
+
+You can `extend` the [`prettier.json`](../style/prettier.json) style to disable
+all `markdownlint` rules that overlap with Prettier.
+
+Other scenarios are documented below.
+
+## List item indentation
+
+The default settings of `markdownlint` and `Prettier` are compatible and don't
+result in any linting violations. If `Prettier` is used with `--tab-width` set
+to `4` (vs. `2`), the following `markdownlint` configuration can be used:
+
+```json
+{
+  "list-marker-space": {
+    "ul_multi": 3,
+    "ul_single": 3
+  },
+  "ul-indent": {
+    "indent": 4
+  }
+}
+```

doc/ReleaseProcess.md

@@ -0,0 +1,20 @@
+# Release Process
+
+The `markdownlint` library has some related dependencies that are updated along
+with it. To prevent possible regressions from having a widespread impact, these
+releases are separated by a few days to provide an opportunity to find issues.
+
+1. [`markdownlint`][markdownlint]
+2. [`markdownlint-cli2`][markdownlint-cli2]
+3. [`markdownlint-cli2-action`][markdownlint-cli2-action]
+4. [`vscode-markdownlint`][vscode-markdownlint]
+5. [`markdownlint-cli`][markdownlint-cli]
+
+This sequence is not strict and may be adjusted based on the content of the
+release and the scope of feature work in each dependency.
+
+[markdownlint]: https://github.com/DavidAnson/markdownlint
+[markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2
+[markdownlint-cli2-action]: https://github.com/marketplace/actions/markdownlint-cli2-action
+[vscode-markdownlint]: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
+[markdownlint-cli]: https://github.com/igorshubovych/markdownlint-cli

doc/md001.md

@@ -0,0 +1,37 @@
+# `MD001` - Heading levels should only increment by one level at a time
+
+Tags: `headings`
+
+Aliases: `heading-increment`
+
+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
+```
+
+Rationale: Headings represent the structure of a document and can be confusing
+when skipped - especially for accessibility scenarios. More information:
+<https://www.w3.org/WAI/tutorials/page-structure/headings/>.

doc/md003.md

@@ -0,0 +1,59 @@
+# `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.

doc/md004.md

@@ -0,0 +1,50 @@
+# `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.

doc/md005.md

@@ -0,0 +1,53 @@
+# `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.

doc/md007.md

@@ -0,0 +1,52 @@
+# `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

doc/md009.md

@@ -0,0 +1,51 @@
+# `MD009` - Trailing spaces
+
+Tags: `whitespace`
+
+Aliases: `no-trailing-spaces`
+
+Parameters:
+
+- `br_spaces`: Spaces for line break (`integer`, default `2`)
+- `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.
+
+Note: Trailing space is allowed in indented and fenced code blocks because some
+languages require it.
+
+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 (\<br> element).
+
+Note: 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, 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 as well, 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.

doc/md010.md

@@ -0,0 +1,56 @@
+# `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:
+
+<!-- markdownlint-disable no-hard-tabs -->
+
+```markdown
+Some text
+
+	* hard tab character used to indent the list item
+```
+
+<!-- markdownlint-restore -->
+
+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.

doc/md011.md

@@ -0,0 +1,30 @@
+# `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://en.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.

doc/md012.md

@@ -0,0 +1,38 @@
+# `MD012` - Multiple consecutive blank lines
+
+Tags: `blank_lines`, `whitespace`
+
+Aliases: `no-multiple-blanks`
+
+Parameters:
+
+- `maximum`: Consecutive blank lines (`integer`, default `1`)
+
+Fixable: Some violations can be fixed by tooling
+
+This rule is triggered when there are multiple consecutive blank lines in the
+document:
+
+```markdown
+Some text here
+
+
+Some more text here
+```
+
+To fix this, delete the offending lines:
+
+```markdown
+Some text here
+
+Some more text here
+```
+
+Note: this rule will not be triggered if there are multiple consecutive blank
+lines inside code blocks.
+
+Note: The `maximum` parameter can be used to configure the maximum number of
+consecutive blank lines.
+
+Rationale: Except in a code block, blank lines serve no purpose and do not
+affect the rendering of content.

doc/md013.md

@@ -0,0 +1,58 @@
+# `MD013` - Line length
+
+Tags: `line_length`
+
+Aliases: `line-length`
+
+Parameters:
+
+- `code_block_line_length`: Number of characters for code blocks (`integer`,
+  default `80`)
+- `code_blocks`: Include code blocks (`boolean`, default `true`)
+- `heading_line_length`: Number of characters for headings (`integer`, default
+  `80`)
+- `headings`: Include headings (`boolean`, default `true`)
+- `line_length`: Number of characters (`integer`, default `80`)
+- `stern`: Stern length checking (`boolean`, default `false`)
+- `strict`: Strict length checking (`boolean`, default `false`)
+- `tables`: Include tables (`boolean`, default `true`)
+
+This rule is triggered when there are lines that are longer than the
+configured `line_length` (default: 80 characters). To fix this, split the line
+up into multiple lines. To set a different maximum length for headings, use
+`heading_line_length`. To set a different maximum length for code blocks, use
+`code_block_line_length`
+
+This rule has an exception when there is no whitespace beyond the configured
+line length. This allows you to include items such as long URLs without being
+forced to break them in the middle. To disable this exception, set the `strict`
+parameter to `true` and an issue will be reported when any line is too long. To
+warn for lines that are too long and could be fixed but allow long lines
+without spaces, set the `stern` parameter to `true`.
+
+For example (assuming normal behavior):
+
+```markdown
+IF THIS LINE IS THE MAXIMUM LENGTH
+This line is okay because there are-no-spaces-beyond-that-length
+This line is a violation because there are spaces beyond that length
+This-line-is-okay-because-there-are-no-spaces-anywhere-within
+```
+
+In `strict` mode, the last three lines above are all violations. In `stern`
+mode, the middle two lines above are both violations, but the last is okay.
+
+You have the option to exclude this rule for code blocks, tables, or headings.
+To do so, set the `code_blocks`, `tables`, or `headings` parameter(s) to false.
+
+Code blocks are included in this rule by default since it is often a
+requirement for document readability, and tentatively compatible with code
+rules. Still, some languages do not lend themselves to short lines.
+
+Lines with link/image reference definitions and standalone lines (i.e., not part
+of a paragraph) with only a link/image (possibly using (strong) emphasis) are
+always exempted from this rule (even in `strict` mode) because there is often no
+way to split such lines without breaking the URL.
+
+Rationale: Extremely long lines can be difficult to work with in some editors.
+More information: <https://cirosantilli.com/markdown-style-guide#line-wrapping>.