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>

.eslintrc.json

@@ -1,232 +0,0 @@
-{
-  "env": {
-    "node": true,
-    "es6": true
-  },
-  "extends": [
-    "eslint:all",
-    "plugin:jsdoc/recommended",
-    "plugin:n/recommended",
-    "plugin:regexp/recommended",
-    "plugin:unicorn/all"
-  ],
-  "ignorePatterns": [
-    "demo/markdown-it.min.js",
-    "demo/markdownlint-browser.js",
-    "demo/markdownlint-browser.min.js",
-    "demo/micromark-browser.js",
-    "example/typescript/type-check.js",
-    "micromark/micromark.cjs",
-    "micromark/micromark.dev.cjs",
-    "micromark/micromark-browser.js",
-    "micromark/micromark-browser.dev.js",
-    "test-repos/"
-  ],
-  "overrides": [
-    {
-      "files": [
-        "demo/*.js"
-      ],
-      "env": {
-        "browser": true
-      },
-      "rules": {
-        "jsdoc/require-jsdoc": "off",
-        "unicorn/prefer-query-selector": "off",
-        "unicorn/prefer-add-event-listener": "off",
-        "no-console": "off",
-        "no-shadow": "off",
-        "no-var": "off"
-      }
-    },
-    {
-      "files": [
-        "example/*.js"
-      ],
-      "rules": {
-        "n/no-extraneous-require": "off",
-        "n/no-missing-require": "off",
-        "no-console": "off",
-        "no-invalid-this": "off",
-        "no-shadow": "off",
-        "object-property-newline": "off"
-      }
-    },
-    {
-      "files": [
-        "**/*.mjs"
-      ],
-      "parserOptions": {
-        "ecmaVersion": 2022,
-        "sourceType": "module"
-      }
-    }
-  ],
-  "parserOptions": {
-    "ecmaVersion": 2021,
-    "sourceType": "script"
-  },
-  "plugins": [
-    "es",
-    "jsdoc",
-    "n",
-    "unicorn"
-  ],
-  "reportUnusedDisableDirectives": true,
-  "rules": {
-    "array-bracket-spacing": ["error", "always"],
-    "array-element-newline": "off",
-    "capitalized-comments": "off",
-    "complexity": "off",
-    "dot-location": ["error", "property"],
-    "func-style": "off",
-    "function-call-argument-newline": "off",
-    "function-paren-newline": "off",
-    "global-require": "off",
-    "id-length": "off",
-    "indent": ["error", 2, { "SwitchCase": 1 }],
-    "linebreak-style": "off",
-    "logical-assignment-operators": "off",
-    "max-depth": "off",
-    "max-lines": "off",
-    "max-lines-per-function": "off",
-    "max-params": ["off"],
-    "max-statements": "off",
-    "multiline-comment-style": ["error", "separate-lines"],
-    "multiline-ternary": "off",
-    "newline-per-chained-call": "off",
-    "no-continue": "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-imports": "off",
-    "sort-keys": "off",
-    "space-before-function-paren": ["error", "never"],
-    "vars-on-top": "off",
-    "wrap-regex": "off",
-
-    "es/no-regexp-lookbehind-assertions": "error",
-
-    "jsdoc/check-access": "error",
-    "jsdoc/check-alignment": "error",
-    "jsdoc/check-examples": "off",
-    "jsdoc/check-indentation": "error",
-    "jsdoc/check-line-alignment": "error",
-    "jsdoc/check-param-names": "error",
-    "jsdoc/check-property-names": "error",
-    "jsdoc/check-syntax": "error",
-    "jsdoc/check-tag-names": "error",
-    "jsdoc/check-types": "error",
-    "jsdoc/check-values": "error",
-    "jsdoc/empty-tags": "error",
-    "jsdoc/implements-on-classes": "error",
-    "jsdoc/match-description": "error",
-    "jsdoc/multiline-blocks": "error",
-    "jsdoc/newline-after-description": "error",
-    "jsdoc/no-bad-blocks": "error",
-    "jsdoc/no-defaults": "error",
-    "jsdoc/no-multi-asterisks": "error",
-    "jsdoc/no-undefined-types": "error",
-    "jsdoc/require-asterisk-prefix": "error",
-    "jsdoc/require-description": "error",
-    "jsdoc/require-description-complete-sentence": "error",
-    "jsdoc/require-jsdoc": "error",
-    "jsdoc/require-param": "error",
-    "jsdoc/require-param-description": "error",
-    "jsdoc/require-param-name": "error",
-    "jsdoc/require-param-type": "error",
-    "jsdoc/require-property": "error",
-    "jsdoc/require-property-description": "error",
-    "jsdoc/require-property-name": "error",
-    "jsdoc/require-property-type": "error",
-    "jsdoc/require-returns": "error",
-    "jsdoc/require-returns-check": "error",
-    "jsdoc/require-returns-description": "error",
-    "jsdoc/require-returns-type": "error",
-    "jsdoc/require-throws": "error",
-    "jsdoc/require-yields": "error",
-    "jsdoc/require-yields-check": "error",
-    "jsdoc/tag-lines": "error",
-    "jsdoc/valid-types": "error",
-
-    "n/handle-callback-err": "error",
-    "n/no-callback-literal": "error",
-    "n/no-exports-assign": "error",
-    "n/no-extraneous-import": "error",
-    "n/no-extraneous-require": "error",
-    "n/no-missing-import": "error",
-    "n/no-missing-require": "error",
-    "n/no-new-require": "error",
-    "n/no-path-concat": "error",
-    "n/no-process-exit": "error",
-    "n/no-unpublished-bin": "error",
-    "n/no-unpublished-import": "error",
-    "n/no-unpublished-require": "error",
-    "n/no-unsupported-features/es-builtins": "error",
-    "n/no-unsupported-features/es-syntax": "error",
-    "n/no-unsupported-features/node-builtins": "error",
-    "n/process-exit-as-throw": "error",
-    "n/shebang": "error",
-    "n/no-deprecated-api": "error",
-    "n/callback-return": "error",
-    "n/exports-style": "error",
-    "n/file-extension-in-import": "error",
-    "n/global-require": "off",
-    "n/no-mixed-requires": "error",
-    "n/no-process-env": "error",
-    "n/no-restricted-import": "error",
-    "n/no-restricted-require": "error",
-    "n/no-sync": "off",
-    "n/prefer-global/buffer": "error",
-    "n/prefer-global/console": "error",
-    "n/prefer-global/process": "error",
-    "n/prefer-global/text-decoder": "error",
-    "n/prefer-global/text-encoder": "error",
-    "n/prefer-global/url-search-params": "error",
-    "n/prefer-global/url": "error",
-    "n/prefer-promises/dns": "error",
-    "n/prefer-promises/fs": "error",
-
-    "regexp/no-super-linear-backtracking": "off",
-
-    "unicorn/better-regex": "off",
-    "unicorn/consistent-function-scoping": "off",
-    "unicorn/filename-case": "off",
-    "unicorn/no-array-callback-reference": "off",
-    "unicorn/no-keyword-prefix": "off",
-    "unicorn/no-new-array": "off",
-    "unicorn/no-null": "off",
-    "unicorn/no-unsafe-regex": "off",
-    "unicorn/prefer-at": "off",
-    "unicorn/prefer-module": "off",
-    "unicorn/prefer-string-replace-all": "off",
-    "unicorn/prefer-string-slice": "off",
-    "unicorn/prefer-switch": "off",
-    "unicorn/prevent-abbreviations": "off",
-    "unicorn/switch-case-braces": ["error", "avoid"]
-  },
-  "settings": {
-    "jsdoc": {
-      "preferredTypes": {
-        "object": "Object"
-      }
-    }
-  }
-}

.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/dictionary.txt

@@ -5,6 +5,9 @@ atx
 ATX
 atx_closed
 ATX-style
+autolink
+autolinks
+Autolinks
 axibase
 backtick
 backticks
@@ -13,29 +16,32 @@ blockquotes
 Boostnote
 br
 br_spaces
-Changelog
-Changelogs
+bundler
 changelog
+Changelog
 changelogs
+Changelogs
 CLI
 coc-markdownlint
 CodeQL
 CodiMD
 CommonMark
 config
-config.
 Config
-CVE-2022-21670
+config.
+CVE-\d+-\d+
 docs-util
+ECMAScript
 ES2015
 ES6
 ESLint
 eslint-plugin-markdownlint
-first-header-h1
-first-heading-h1
 first-line-h1
+flymake-markdownlint-cli2
 formatter
 fs
+GFM
+github
 globbing
 grunt-markdownlint
 h1
@@ -46,6 +52,7 @@ JSON
 JSONC
 kramdown
 linter
+LLMs
 Lombiq
 markdownlint
 markdownlint-cli
@@ -75,29 +82,30 @@ npm
 ol
 ol_multi
 ol-prefix
-Pandoc
 pandoc
+Pandoc
 Params
 parsers
 pre-commit
 Reactable
 README
-Reimplement
 reimplement
+Reimplement
 setext
-setext-style
 setext_with_atx
 setext_with_atx_closed
+setext-style
 single-h1
 sublist
+subpath
 Super-Linter
 TestCafe
 TOML
 trimLeft
 trimRight
 ul
-ul-indent
 ul_single
+ul-indent
 ul-start-left
 ul-style
 unhandled

.github/workflows/checkers.yml

@@ -3,6 +3,8 @@ name: Checkers
 on:
   pull_request:
   push:
+    branches-ignore:
+      - 'dependabot/**'
   workflow_dispatch:
 
 jobs:
@@ -10,17 +12,17 @@ jobs:
   linkcheck:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    - uses: JustinBeckwith/linkinator-action@v1.10.4
+    - uses: actions/checkout@v4
+    - uses: JustinBeckwith/linkinator-action@v1.11.0
       with:
-        linksToSkip: '^https://github.com/.*/search\?q= ^https://opensource.org/'
+        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@v3
+    - uses: actions/checkout@v4
     - uses: tbroadley/spellchecker-cli-action@v1
       with:
         dictionaries: '.github/dictionary.txt'

.github/workflows/ci.yml

@@ -3,35 +3,47 @@ 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: [ 14, 16, 18 ]
+        node-version: [ 20, 22, 23 ]
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Edit .npmrc to avoid setup-node issue with Node 14
-      if: ${{ matrix.node-version == '14' }}
-      run: perl -i -p -e 's/(ignore-scripts=true)/# $1/' .npmrc && git add .npmrc
+    - uses: actions/checkout@v4
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v3
+      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
-    - name: Install markdownlint-micromark Dependencies
-      run: cd micromark && npm install --no-package-lock
-    - name: Build markdownlint-micromark
-      run: npm run build-micromark
+
+  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

@@ -3,6 +3,8 @@ name: "CodeQL"
 on:
   pull_request:
   push:
+    branches-ignore:
+      - 'dependabot/**'
   workflow_dispatch:
 
 jobs:
@@ -19,13 +21,13 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      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@v2
+      uses: github/codeql-action/analyze@v3

.github/workflows/test-repos.yml

@@ -3,6 +3,8 @@ name: TestRepos
 on:
   pull_request:
   push:
+    branches-ignore:
+      - 'dependabot/**'
   workflow_dispatch:
 
 jobs:
@@ -13,12 +15,12 @@ jobs:
     strategy:
       matrix:
         os: [ ubuntu-latest ]
-        node-version: [16.x]
+        node-version: [ latest ]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v3
+      uses: actions/setup-node@v4
       with:
         node-version: ${{ matrix.node-version }}
     - name: Install Dependencies

.gitignore

@@ -1,13 +1,10 @@
 coverage
 demo/markdown-it.min.js
+demo/markdownlint-browser.js
 demo/markdownlint-browser.min.js
-demo/micromark-browser.js
-micromark/micromark.cjs
-micromark/micromark.dev.cjs
-micromark/micromark-browser.js
-micromark/micromark-browser.dev.js
 node_modules
 !test/node_modules
+!test/rules/node_modules
 npm-debug.log
 test-repos
 .DS_Store

.markdownlint.json

@@ -8,6 +8,9 @@
   "emphasis-style": {
     "style": "asterisk"
   },
+  "extended-ascii": {
+    "ascii-only": true
+  },
   "fenced-code-language": {
     "allowed_languages": [
       "bash",
@@ -29,6 +32,11 @@
     "strict": true,
     "code_blocks": false
   },
+  "link-image-style": {
+    "collapsed": false,
+    "shortcut": false,
+    "url_inline": false
+  },
   "no-duplicate-heading": {
     "siblings_only": true
   },
@@ -47,6 +55,9 @@
       "Node.js"
     ]
   },
+  "reference-links-images": {
+    "shortcut_syntax": true
+  },
   "strong-style": {
     "style": "asterisk"
   },

.npmignore

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

.npmrc

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

CHANGELOG.md

@@ -1,11 +1,138 @@
 # 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
+- Unify browser script for demo page
 - Update dependencies
 
 ## 0.27.0

CONTRIBUTING.md

@@ -14,8 +14,14 @@ 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`][dependencies]. The Markdown
-parsers [`markdown-it`][markdown-it] and [`micromark`][micromark] are the
-project's only dependencies.
+parser [`micromark`][micromark] (and its extensions) is this project's only
+dependency.
+
+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.)
 
 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
@@ -68,8 +74,8 @@ 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 that generate code from other projects is not
-allowed.
+tools such as GitHub Copilot, ChatGPT, LLMs (large language models), etc. that
+incorporate code from other projects is not allowed.
 
 Thank you!
 
@@ -79,8 +85,8 @@ Thank you!
 [custom-rules]: doc/CustomRules.md
 [dependencies]: https://docs.npmjs.com/files/package.json#dependencies
 [example-com]: https://en.wikipedia.org/wiki/Example.com
-[markdown-it]: https://www.npmjs.com/package/markdown-it
 [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

README.md

@@ -13,22 +13,31 @@ npm install markdownlint --save-dev
 
 ## Overview
 
-The [Markdown](https://en.wikipedia.org/wiki/Markdown) markup language
-is designed to be easy to read, write, and understand. It succeeds -
-and its flexibility is both a benefit and a drawback. Many styles are
-possible, so formatting can be inconsistent. Some constructs don't
-work well in all parsers and should be avoided. The
-[CommonMark](https://commonmark.org/) specification standardizes
-parsers - but not authors.
+The [Markdown][markdown] markup language is designed to be easy to read, write,
+and understand. It succeeds - and its flexibility is both a benefit and a
+drawback. Many styles are possible, so formatting can be inconsistent; some
+constructs don't work well in all parsers and should be avoided.
 
-`markdownlint` is a
-[static analysis](https://en.wikipedia.org/wiki/Static_program_analysis)
-tool for [Node.js](https://nodejs.org/) with a library of rules
-to enforce standards and consistency for Markdown files. It was
-inspired by - and heavily influenced by - Mark Harrison's
-[markdownlint](https://github.com/markdownlint/markdownlint) for
-[Ruby](https://www.ruby-lang.org/). The initial rules, rule documentation,
-and test cases came directly from that project.
+`markdownlint` is a [static analysis][static-analysis] tool for
+[Node.js][nodejs] with a library of rules to enforce standards and consistency
+for Markdown files. It was inspired by - and heavily influenced by - Mark
+Harrison's [markdownlint][markdownlint-ruby] for Ruby. The initial rules, rule
+documentation, and test cases came from that project.
+
+`markdownlint` uses the [`micromark` parser][micromark] and honors the
+[CommonMark][commonmark] specification for Markdown. It additionally supports
+popular [GitHub Flavored Markdown (GFM)][gfm] syntax like autolinks and tables
+as well as directives, footnotes, and math syntax - all implemented by
+[`micromark` extensions][micromark-extensions].
+
+[commonmark]: https://commonmark.org/
+[gfm]: https://github.github.com/gfm/
+[markdown]: https://en.wikipedia.org/wiki/Markdown
+[markdownlint-ruby]: https://github.com/markdownlint/markdownlint
+[micromark]: https://github.com/micromark/micromark
+[micromark-extensions]: https://github.com/micromark/micromark?tab=readme-ov-file#list-of-extensions
+[nodejs]: https://nodejs.org/
+[static-analysis]: https://en.wikipedia.org/wiki/Static_program_analysis
 
 ### Related
 
@@ -46,6 +55,7 @@ and test cases came directly from that project.
   - [vscode-markdownlint extension for VS Code][vscode-markdownlint]
   - [Sublime Text markdownlint for Sublime Text][sublimelinter]
   - [coc-markdownlint extension for Vim/Neovim][coc]
+  - [flymake-markdownlint-cli2 extension for Emacs][emacs-flymake]
 - Tooling
   - [eslint-plugin-markdownlint for the ESLint analyzer][eslint-plugin]
   - [grunt-markdownlint for the Grunt task runner][grunt-markdownlint]
@@ -56,6 +66,7 @@ and test cases came directly from that project.
 
 [cake]: https://github.com/cake-contrib/Cake.Markdownlint
 [coc]: https://github.com/fannheyward/coc-markdownlint
+[emacs-flymake]: https://github.com/ewilderj/flymake-markdownlint-cli2
 [eslint-plugin]: https://github.com/paweldrozd/eslint-plugin-markdownlint
 [grunt-markdownlint]: https://github.com/sagiegurari/grunt-markdownlint
 [markdownlint-cli]: https://github.com/igorshubovych/markdownlint-cli
@@ -66,10 +77,17 @@ and test cases came directly from that project.
 [markdownlint-problem-matcher]: https://github.com/xt0rted/markdownlint-problem-matcher
 [nodejs-extensions]: https://github.com/Lombiq/NodeJs-Extensions
 [rubygems-mdl]: https://rubygems.org/gems/mdl
-[sublimelinter]: https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint
-[super-linter]: https://github.com/github/super-linter
+[sublimelinter]: https://github.com/jonlabelle/SublimeLinter-contrib-markdownlint
+[super-linter]: https://github.com/super-linter/super-linter
 [vscode-markdownlint]: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
 
+### References
+
+The following specifications are considered authoritative in cases of ambiguity:
+
+- [CommonMark](https://spec.commonmark.org/current/)
+- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
+
 ## Demonstration
 
 [`markdownlint` demo](https://dlaa.me/markdownlint/), an interactive, in-browser
@@ -79,12 +97,10 @@ playground for learning and exploring.
 
 <!-- markdownlint-disable line-length -->
 
-- **[MD001](doc/md001.md)** *heading-increment/header-increment* - Heading levels should only increment by one level at a time
-- ~~**[MD002](doc/md002.md)** *first-heading-h1/first-header-h1* - First heading should be a top-level heading~~
-- **[MD003](doc/md003.md)** *heading-style/header-style* - Heading style
+- **[MD001](doc/md001.md)** *heading-increment* - Heading levels should only increment by one level at a time
+- **[MD003](doc/md003.md)** *heading-style* - Heading style
 - **[MD004](doc/md004.md)** *ul-style* - Unordered list style
 - **[MD005](doc/md005.md)** *list-indent* - Inconsistent indentation for list items at the same level
-- ~~**[MD006](doc/md006.md)** *ul-start-left* - Consider starting bulleted lists at the beginning of the line~~
 - **[MD007](doc/md007.md)** *ul-indent* - Unordered list indentation
 - **[MD009](doc/md009.md)** *no-trailing-spaces* - Trailing spaces
 - **[MD010](doc/md010.md)** *no-hard-tabs* - Hard tabs
@@ -96,9 +112,9 @@ playground for learning and exploring.
 - **[MD019](doc/md019.md)** *no-multiple-space-atx* - Multiple spaces after hash on atx style heading
 - **[MD020](doc/md020.md)** *no-missing-space-closed-atx* - No space inside hashes on closed atx style heading
 - **[MD021](doc/md021.md)** *no-multiple-space-closed-atx* - Multiple spaces inside hashes on closed atx style heading
-- **[MD022](doc/md022.md)** *blanks-around-headings/blanks-around-headers* - Headings should be surrounded by blank lines
-- **[MD023](doc/md023.md)** *heading-start-left/header-start-left* - Headings must start at the beginning of the line
-- **[MD024](doc/md024.md)** *no-duplicate-heading/no-duplicate-header* - Multiple headings with the same content
+- **[MD022](doc/md022.md)** *blanks-around-headings* - Headings should be surrounded by blank lines
+- **[MD023](doc/md023.md)** *heading-start-left* - Headings must start at the beginning of the line
+- **[MD024](doc/md024.md)** *no-duplicate-heading* - Multiple headings with the same content
 - **[MD025](doc/md025.md)** *single-title/single-h1* - Multiple top-level headings in the same document
 - **[MD026](doc/md026.md)** *no-trailing-punctuation* - Trailing punctuation in heading
 - **[MD027](doc/md027.md)** *no-multiple-space-blockquote* - Multiple spaces after blockquote symbol
@@ -110,35 +126,34 @@ playground for learning and exploring.
 - **[MD033](doc/md033.md)** *no-inline-html* - Inline HTML
 - **[MD034](doc/md034.md)** *no-bare-urls* - Bare URL used
 - **[MD035](doc/md035.md)** *hr-style* - Horizontal rule style
-- **[MD036](doc/md036.md)** *no-emphasis-as-heading/no-emphasis-as-header* - Emphasis used instead of a heading
+- **[MD036](doc/md036.md)** *no-emphasis-as-heading* - Emphasis used instead of a heading
 - **[MD037](doc/md037.md)** *no-space-in-emphasis* - Spaces inside emphasis markers
 - **[MD038](doc/md038.md)** *no-space-in-code* - Spaces inside code span elements
 - **[MD039](doc/md039.md)** *no-space-in-links* - Spaces inside link text
 - **[MD040](doc/md040.md)** *fenced-code-language* - Fenced code blocks should have a language specified
 - **[MD041](doc/md041.md)** *first-line-heading/first-line-h1* - First line in a file should be a top-level heading
 - **[MD042](doc/md042.md)** *no-empty-links* - No empty links
-- **[MD043](doc/md043.md)** *required-headings/required-headers* - Required heading structure
+- **[MD043](doc/md043.md)** *required-headings* - Required heading structure
 - **[MD044](doc/md044.md)** *proper-names* - Proper names should have the correct capitalization
 - **[MD045](doc/md045.md)** *no-alt-text* - Images should have alternate text (alt text)
 - **[MD046](doc/md046.md)** *code-block-style* - Code block style
 - **[MD047](doc/md047.md)** *single-trailing-newline* - Files should end with a single newline character
 - **[MD048](doc/md048.md)** *code-fence-style* - Code fence style
-- **[MD049](doc/md049.md)** *emphasis-style* - Emphasis style should be consistent
-- **[MD050](doc/md050.md)** *strong-style* - Strong style should be consistent
+- **[MD049](doc/md049.md)** *emphasis-style* - Emphasis style
+- **[MD050](doc/md050.md)** *strong-style* - Strong style
 - **[MD051](doc/md051.md)** *link-fragments* - Link fragments should be valid
 - **[MD052](doc/md052.md)** *reference-links-images* - Reference links and images should use a label that is defined
 - **[MD053](doc/md053.md)** *link-image-reference-definitions* - Link and image reference definitions should be needed
+- **[MD054](doc/md054.md)** *link-image-style* - Link and image style
+- **[MD055](doc/md055.md)** *table-pipe-style* - Table pipe style
+- **[MD056](doc/md056.md)** *table-column-count* - Table column count
+- **[MD058](doc/md058.md)** *blanks-around-tables* - Tables should be surrounded by blank lines
+- **[MD059](doc/md059.md)** *descriptive-link-text* - Link text should be descriptive
 
 <!-- markdownlint-restore -->
 
 See [Rules.md](doc/Rules.md) for more details.
 
-~~Struck through~~ rules are deprecated and provided for backward-compatibility.
-
-> All rules with `heading` as part of their name are also available as `header`
-> aliases (e.g. `heading-increment` is also available as `header-increment`).
-> The use of `header` is deprecated and provided for backward-compatibility.
-
 ### Custom Rules
 
 In addition to built-in rules, custom rules can be used to address
@@ -153,31 +168,30 @@ To implement your own rules, refer to [CustomRules.md](doc/CustomRules.md).
 Tags group related rules and can be used to enable/disable multiple
 rules at once.
 
-- **`accessibility`** - `MD045`
+- **`accessibility`** - `MD045`, `MD059`
 - **`atx`** - `MD018`, `MD019`
 - **`atx_closed`** - `MD020`, `MD021`
 - **`blank_lines`** - `MD012`, `MD022`, `MD031`, `MD032`, `MD047`
 - **`blockquote`** - `MD027`, `MD028`
-- **`bullet`** - `MD004`, `MD005`, `MD006`, `MD007`, `MD032`
+- **`bullet`** - `MD004`, `MD005`, `MD007`, `MD032`
 - **`code`** - `MD014`, `MD031`, `MD038`, `MD040`, `MD046`, `MD048`
 - **`emphasis`** - `MD036`, `MD037`, `MD049`, `MD050`
 - **`hard_tab`** - `MD010`
-- **`headers`** - `MD001`, `MD002`, `MD003`, `MD018`, `MD019`, `MD020`, `MD021`,
+- **`headings`** - `MD001`, `MD003`, `MD018`, `MD019`, `MD020`, `MD021`,
   `MD022`, `MD023`, `MD024`, `MD025`, `MD026`, `MD036`, `MD041`, `MD043`
-- **`headings`** - `MD001`, `MD002`, `MD003`, `MD018`, `MD019`, `MD020`,
-  `MD021`, `MD022`, `MD023`, `MD024`, `MD025`, `MD026`, `MD036`, `MD041`,
-  `MD043`
 - **`hr`** - `MD035`
 - **`html`** - `MD033`
-- **`images`** - `MD045`, `MD052`, `MD053`
-- **`indentation`** - `MD005`, `MD006`, `MD007`, `MD027`
+- **`images`** - `MD045`, `MD052`, `MD053`, `MD054`
+- **`indentation`** - `MD005`, `MD007`, `MD027`
 - **`language`** - `MD040`
 - **`line_length`** - `MD013`
-- **`links`** - `MD011`, `MD034`, `MD039`, `MD042`, `MD051`, `MD052`, `MD053`
+- **`links`** - `MD011`, `MD034`, `MD039`, `MD042`, `MD051`, `MD052`, `MD053`,
+  `MD054`, `MD059`
 - **`ol`** - `MD029`, `MD030`, `MD032`
 - **`spaces`** - `MD018`, `MD019`, `MD020`, `MD021`, `MD023`
 - **`spelling`** - `MD044`
-- **`ul`** - `MD004`, `MD005`, `MD006`, `MD007`, `MD030`, `MD032`
+- **`table`** - `MD055`, `MD056`, `MD058`
+- **`ul`** - `MD004`, `MD005`, `MD007`, `MD030`, `MD032`
 - **`url`** - `MD034`
 - **`whitespace`** - `MD009`, `MD010`, `MD012`, `MD027`, `MD028`, `MD030`,
   `MD037`, `MD038`, `MD039`
@@ -185,7 +199,7 @@ rules at once.
 ## Configuration
 
 Text passed to `markdownlint` is parsed as Markdown, analyzed, and any
-issues reported. Two kinds of text are ignored:
+issues reported. Two kinds of text are ignored by most rules:
 
 - [HTML comments](https://www.w3.org/TR/html5/syntax.html#comments)
 - [Front matter](https://jekyllrb.com/docs/frontmatter/) (see
@@ -301,42 +315,41 @@ alternate formats.
 
 ### Linting
 
-Standard asynchronous API:
+Asynchronous API via `import { lint } from "markdownlint/async"`:
 
 ```javascript
 /**
  * Lint specified Markdown files.
  *
- * @param {Options} options Configuration options.
+ * @param {Options | null} options Configuration options.
  * @param {LintCallback} callback Callback (err, result) function.
  * @returns {void}
  */
-function markdownlint(options, callback) { ... }
+function lint(options, callback) { ... }
 ```
 
-Synchronous API (for build scripts, etc.):
-
-```javascript
-/**
- * Lint specified Markdown files synchronously.
- *
- * @param {Options} options Configuration options.
- * @returns {LintResults} Results object.
- */
-function markdownlint.sync(options) { ... }
-```
-
-Promise API (in the `promises` namespace like Node.js's
-[`fs` Promises API](https://nodejs.org/api/fs.html#fs_fs_promises_api)):
+Synchronous API via `import { lint } from "markdownlint/sync"`:
 
 ```javascript
 /**
  * Lint specified Markdown files.
  *
- * @param {Options} options Configuration options.
+ * @param {Options | null} options Configuration options.
+ * @returns {LintResults} Results object.
+ */
+function lint(options) { ... }
+```
+
+Promise API via `import { lint } from "markdownlint/promise"`:
+
+```javascript
+/**
+ * Lint specified Markdown files.
+ *
+ * @param {Options | null} options Configuration options.
  * @returns {Promise<LintResults>} Results object.
  */
-function markdownlint(options) { ... }
+function lint(options) { ... }
 ```
 
 #### options
@@ -352,16 +365,16 @@ Type: `Object` mapping `String` to `Boolean | Object`
 
 Configures the rules to use.
 
-Object keys are rule names or aliases and values are the rule's configuration.
+Object keys are rule names/aliases; object values are the rule's configuration.
 The value `false` disables a rule, `true` enables its default configuration,
-and passing an object customizes its settings. Setting the special `default`
-rule to `true` or `false` includes/excludes all rules by default. Enabling
-or disabling a tag name (ex: `whitespace`) affects all rules having that
-tag.
+and passing an object value customizes that rule. Setting the special `default`
+rule to `true` or `false` includes/excludes all rules by default. In the absence
+of a configuration object, all rules are enabled. Enabling or disabling a tag
+name (ex: `whitespace`) affects all rules having that tag.
 
-The `default` rule is applied first, then keys are processed in order
-from top to bottom with later values overriding earlier ones. Keys
-(including rule names, aliases, tags, and `default`) are not case-sensitive.
+The `default` rule is applied first, then keys are processed in order from top
+to bottom with later values overriding earlier ones. Keys (including rule names,
+aliases, tags, and `default`) are not case-sensitive.
 
 Example:
 
@@ -405,9 +418,12 @@ See [markdownlint-config-schema.json](schema/markdownlint-config-schema.json)
 for the [JSON Schema](https://json-schema.org/) of the `options.config`
 object.
 
-For more advanced scenarios, styles can reference and extend other styles.
-The `readConfig` and `readConfigSync` functions can be used to read such
-styles.
+See [ValidatingConfiguration.md](schema/ValidatingConfiguration.md) for ways to
+use the JSON Schema to validate configuration.
+
+For more advanced scenarios, styles can reference and build upon other styles
+via the `extends` keyword and a file path or (installed) package name. The
+`readConfig` function can be used to read such aggregate styles from code.
 
 For example, assuming a `base.json` configuration file:
 
@@ -511,7 +527,7 @@ specify a custom `RegExp` or use the value `null` to disable the feature.
 The default value:
 
 ```javascript
-/((^---\s*$[\s\S]*?^---\s*)|(^\+\+\+\s*$[\s\S]*?^(\+\+\+|\.\.\.)\s*)|(^\{\s*$[\s\S]*?^\}\s*))(\r\n|\r|\n|$)/m
+/((^---[^\S\r\n\u2028\u2029]*$[\s\S]+?^---\s*)|(^\+\+\+[^\S\r\n\u2028\u2029]*$[\s\S]+?^(\+\+\+|\.\.\.)\s*)|(^\{[^\S\r\n\u2028\u2029]*$[\s\S]+?^\}\s*))(\r\n|\r|\n|$)/m
 ```
 
 Ignores [YAML](https://en.wikipedia.org/wiki/YAML),
@@ -533,7 +549,7 @@ Type: `Object` implementing the [file system API][node-fs-api]
 
 In advanced scenarios, it may be desirable to bypass the default file system
 API. If a custom file system implementation is provided, `markdownlint` will use
-that instead of invoking `require("fs")`.
+that instead of using `node:fs`.
 
 Note: The only methods called are `readFile` and `readFileSync`.
 
@@ -554,22 +570,44 @@ This setting can be useful in the presence of (custom) rules that encounter
 unexpected syntax and fail. By enabling this option, the linting process
 is allowed to continue and report any violations that were found.
 
-##### options.markdownItPlugins
+##### options.markdownItFactory
 
-Type: `Array` of `Array` of `Function` and plugin parameters
+Type: `Function` returning an instance of a [`markdown-it` parser][markdown-it]
 
-Specifies additional [markdown-it plugins][markdown-it-plugin] to use when
-parsing input. Plugins can be used to support additional syntax and features for
-advanced scenarios.
+Provides a factory function for creating instances of the `markdown-it` parser.
 
-[markdown-it-plugin]: https://www.npmjs.com/search?q=keywords:markdown-it-plugin
+Previous versions of the `markdownlint` library declared `markdown-it` as a
+direct dependency. This function makes it possible to avoid that dependency
+entirely. In cases where `markdown-it` is needed, the caller is responsible for
+declaring the dependency and returning an instance from this factory. If any
+[`markdown-it` plugins][markdown-it-plugin] are needed, they should be `use`d by
+the caller before returning the `markdown-it` instance.
 
-Each item in the top-level `Array` should be of the form:
+For compatibility with previous versions of `markdownlint`, this function should
+be similar to:
 
 ```javascript
-[ require("markdown-it-plugin"), plugin_param_0, plugin_param_1, ... ]
+import markdownIt from "markdown-it";
+const markdownItFactory = () => markdownIt({ "html": true });
 ```
 
+When an asynchronous implementation of `lint` is being invoked (e.g., via
+`markdownlint/async` or `markdownlint/promise`), this function can return a
+`Promise` in order to defer the import of `markdown-it`:
+
+```javascript
+const markdownItFactory = () => import("markdown-it").then((module) => module.default({ "html": true }));
+```
+
+> Note that this function is only invoked when a `markdown-it` parser is
+> needed. None of the built-in rules use the `markdown-it` parser, so it is only
+> invoked when one or more [custom rules][custom-rules] are present that use the
+> `markdown-it` parser.
+
+[custom-rules]: #custom-rules
+[markdown-it]: https://github.com/markdown-it/markdown-it
+[markdown-it-plugin]: https://www.npmjs.com/search?q=keywords:markdown-it-plugin
+
 ##### options.noInlineConfig
 
 Type: `Boolean`
@@ -589,23 +627,20 @@ Specifies which version of the `result` object to return (see the "Usage"
 section below for examples).
 
 Passing a `resultVersion` of `0` corresponds to the original, simple format
-where each error is identified by rule name and line number. *This is
-deprecated.*
+where each error is identified by rule name and line number. *Deprecated*
 
 Passing a `resultVersion` of `1` corresponds to a detailed format where each
 error includes information about the line number, rule name, alias, description,
-as well as any additional detail or context that is available. *This is
-deprecated.*
+as well as any additional detail or context that is available. *Deprecated*
 
 Passing a `resultVersion` of `2` corresponds to a detailed format where each
 error includes information about the line number, rule names, description, as
-well as any additional detail or context that is available. *This is
-deprecated.*
+well as any additional detail or context that is available. *Deprecated*
 
 Passing a `resultVersion` of `3` corresponds to the detailed version `2` format
 with additional information about how to fix automatically-fixable errors. In
 this mode, all errors that occur on each line are reported (other versions
-report only the first error for each rule). *This is the default.*
+report only the first error for each rule). This is the default behavior.
 
 ##### options.strings
 
@@ -643,22 +678,22 @@ uses rule aliases (ex: `no-hard-tabs`) instead of names (ex: `MD010`).
 ### Config
 
 The `options.config` configuration object is simple and can be stored in a file
-for readability and easy reuse. The `readConfig` and `readConfigSync` functions
-load configuration settings and support the `extends` keyword for referencing
-other files (see above).
+for readability and easy reuse. The `readConfig` function loads configuration
+settings and supports the `extends` keyword for referencing files or packages
+(see above).
 
 By default, configuration files are parsed as JSON (and named
 `.markdownlint.json`). Custom parsers can be provided to handle other formats
 like JSONC, YAML, and TOML.
 
-Asynchronous API:
+Asynchronous API via `import { readConfig } from "markdownlint/async"`:
 
 ```javascript
 /**
  * Read specified configuration file.
  *
  * @param {string} file Configuration file name.
- * @param {ConfigurationParser[] | ReadConfigCallback} parsers Parsing function.
+ * @param {ConfigurationParser[] | ReadConfigCallback} [parsers] Parsing function(s).
  * @param {Object} [fs] File system implementation.
  * @param {ReadConfigCallback} [callback] Callback (err, result) function.
  * @returns {void}
@@ -666,22 +701,21 @@ Asynchronous API:
 function readConfig(file, parsers, fs, callback) { ... }
 ```
 
-Synchronous API:
+Synchronous API via `import { readConfig } from "markdownlint/sync"`:
 
 ```javascript
 /**
- * Read specified configuration file synchronously.
+ * Read specified configuration file.
  *
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[]} [parsers] Parsing function(s).
  * @param {Object} [fs] File system implementation.
  * @returns {Configuration} Configuration object.
  */
-function readConfigSync(file, parsers, fs) { ... }
+function readConfig(file, parsers, fs) { ... }
 ```
 
-Promise API (in the `promises` namespace like Node.js's
-[`fs` Promises API](https://nodejs.org/api/fs.html#fs_promises_api)):
+Promise API via `import { readConfig } from "markdownlint/promise"`:
 
 ```javascript
 /**
@@ -733,7 +767,7 @@ Type: *Optional* `Object` implementing the [file system API][file-system-api]
 
 In advanced scenarios, it may be desirable to bypass the default file system
 API. If a custom file system implementation is provided, `markdownlint` will use
-that instead of invoking `require("fs")`.
+that instead of invoking `node:fs`.
 
 Note: The only methods called are `readFile`, `readFileSync`, `access`, and
 `accessSync`.
@@ -750,12 +784,75 @@ Type: `Object`
 
 Configuration object.
 
-## Usage
+### Fixing
 
-Invoke `markdownlint` and use the `result` object's `toString` method:
+Rules that can be fixed automatically include a `fixInfo` property which is
+outlined in the [documentation for custom rules](doc/CustomRules.md#authoring).
+To apply fixes consistently, the `applyFix`/`applyFixes` methods may be used via
+`import { applyFix, applyFixes } from "markdownlint"`:
 
 ```javascript
-const markdownlint = require("markdownlint");
+/**
+ * Applies the specified fix to a Markdown content line.
+ *
+ * @param {string} line Line of Markdown content.
+ * @param {RuleOnErrorFixInfo} fixInfo RuleOnErrorFixInfo instance.
+ * @param {string} [lineEnding] Line ending to use.
+ * @returns {string | null} Fixed content or null if deleted.
+ */
+function applyFix(line, fixInfo, lineEnding = "\n") { ... }
+
+/**
+ * Applies as many of the specified fixes as possible to Markdown content.
+ *
+ * @param {string} input Lines of Markdown content.
+ * @param {RuleOnErrorInfo[]} errors RuleOnErrorInfo instances.
+ * @returns {string} Fixed content.
+ */
+function applyFixes(input, errors) { ... }
+```
+
+Invoking `applyFixes` with the results of a call to lint can be done like so:
+
+```javascript
+import { applyFixes } from "markdownlint";
+import { lint as lintSync } from "markdownlint/sync";
+
+const results = lintSync({ "strings": { "content": original } });
+const fixed = applyFixes(original, results.content);
+```
+
+### Miscellaneous
+
+To get the [semantic version][semver] of the library, the `getVersion` method
+can be used:
+
+```javascript
+/**
+ * Gets the (semantic) version of the library.
+ *
+ * @returns {string} SemVer string.
+ */
+function getVersion() { ... }
+```
+
+Invoking `getVersion` is simple:
+
+```javascript
+import { getVersion } from "markdownlint";
+
+// Displays the library version
+console.log(getVersion());
+```
+
+[semver]: https://semver.org
+
+## Usage
+
+Invoke `lint` and use the `result` object's `toString` method:
+
+```javascript
+import { lint as lintAsync } from "markdownlint/async";
 
 const options = {
   "files": [ "good.md", "bad.md" ],
@@ -765,9 +862,9 @@ const options = {
   }
 };
 
-markdownlint(options, function callback(err, result) {
-  if (!err) {
-    console.log(result.toString());
+lintAsync(options, function callback(error, results) {
+  if (!error && results) {
+    console.log(results.toString());
   }
 });
 ```
@@ -785,21 +882,22 @@ bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [
 bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "#bad.md"]
 ```
 
-Or invoke `markdownlint.sync` for a synchronous call:
+Or as a synchronous call:
 
 ```javascript
-const result = markdownlint.sync(options);
-console.log(result.toString());
+import { lint as lintSync } from "markdownlint/sync";
+
+const results = lintSync(options);
+console.log(results.toString());
 ```
 
-To examine the `result` object directly:
+To examine the `result` object directly via a `Promise`-based call:
 
 ```javascript
-markdownlint(options, function callback(err, result) {
-  if (!err) {
-    console.dir(result, { "colors": true, "depth": null });
-  }
-});
+import { lint as lintPromise } from "markdownlint/promise";
+
+const results = await lintPromise(options);
+console.dir(results, { "colors": true, "depth": null });
 ```
 
 Output:
@@ -841,88 +939,10 @@ Output:
 ```
 
 Integration with the [gulp](https://gulpjs.com/) build system is
-straightforward:
-
-```javascript
-const gulp = require("gulp");
-const through2 = require("through2");
-const markdownlint = require("markdownlint");
-
-gulp.task("markdownlint", function task() {
-  return gulp.src("*.md", { "read": false })
-    .pipe(through2.obj(function obj(file, enc, next) {
-      markdownlint(
-        { "files": [ file.relative ] },
-        function callback(err, result) {
-          const resultString = (result || "").toString();
-          if (resultString) {
-            console.log(resultString);
-          }
-          next(err, file);
-        });
-    }));
-});
-```
-
-Output:
-
-```text
-[00:00:00] Starting 'markdownlint'...
-bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
-bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
-bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails      some rules."]
-bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "#bad.md"]
-[00:00:00] Finished 'markdownlint' after 10 ms
-```
+straightforward: [`gulpfile.cjs`](example/gulpfile.cjs).
 
 Integration with the [Grunt](https://gruntjs.com/) build system is similar:
-
-```javascript
-const markdownlint = require("markdownlint");
-
-module.exports = function wrapper(grunt) {
-  grunt.initConfig({
-    "markdownlint": {
-      "example": {
-        "src": [ "*.md" ]
-      }
-    }
-  });
-
-  grunt.registerMultiTask("markdownlint", function task() {
-    const done = this.async();
-    markdownlint(
-      { "files": this.filesSrc },
-      function callback(err, result) {
-        const resultString = err || ((result || "").toString());
-        if (resultString) {
-          grunt.fail.warn("\n" + resultString + "\n");
-        }
-        done(!err || !resultString);
-      });
-  });
-};
-```
-
-Output:
-
-```text
-Running "markdownlint:example" (markdownlint) task
-Warning:
-bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
-bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
-bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails      some rules."]
-bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "#bad.md"]
- Use --force to continue.
-```
-
-### Fixing
-
-Rules that can be fixed automatically include a `fixInfo` property which is
-outlined in the [documentation for custom rules](doc/CustomRules.md#authoring).
-To apply those fixes more easily, the `applyFixes` method in
-[markdownlint-rule-helpers](helpers/README.md#applying-recommended-fixes) may
-be used.
+[`Gruntfile.cjs`](example/Gruntfile.cjs).
 
 ## Browser
 
@@ -934,10 +954,9 @@ Generate normal and minified scripts with:
 npm run build-demo
 ```
 
-Then reference `markdown-it` and `markdownlint`:
+Then reference the `markdownlint-browser` script:
 
 ```html
-<script src="demo/markdown-it.min.js"></script>
 <script src="demo/markdownlint-browser.min.js"></script>
 ```
 
@@ -949,7 +968,8 @@ const options = {
     "content": "Some Markdown to lint."
   }
 };
-const results = window.markdownlint.sync(options).toString();
+
+const results = globalThis.markdownlint.lintSync(options).toString();
 ```
 
 ## Examples
@@ -975,6 +995,11 @@ following projects or one of the tools in the [Related section](#related):
 - [webpack][webpack] ([Search repository][webpack-search])
 - [WordPress][wordpress] ([Search repository][wordpress-search])
 
+For more advanced integration scenarios:
+
+- [GitHub Docs content linter][content-linter]
+- [GitHub's `markdownlint-github` repository][markdownlint-github]
+
 [ally-js]: https://allyjs.io/
 [ally-js-search]: https://github.com/medialize/ally.js/search?q=markdownlint
 [airflow]: https://airflow.apache.org
@@ -983,6 +1008,7 @@ following projects or one of the tools in the [Related section](#related):
 [boostnote-search]: https://github.com/BoostIO/Boostnote/search?q=markdownlint
 [codimd]: https://github.com/hackmdio/codimd
 [codimd-search]: https://github.com/hackmdio/codimd/search?q=markdownlint
+[content-linter]: https://docs.github.com/en/contributing/collaborating-on-github-docs/using-the-content-linter
 [dot-net-doc]: https://docs.microsoft.com/en-us/dotnet/
 [dot-net-doc-search]: https://github.com/dotnet/docs/search?q=markdownlint
 [electron]: https://www.electronjs.org
@@ -991,6 +1017,7 @@ following projects or one of the tools in the [Related section](#related):
 [eslint-search]: https://github.com/eslint/eslint/search?q=markdownlint
 [garden]: https://zendeskgarden.github.io/react-components/
 [garden-search]: https://github.com/zendeskgarden/react-components/search?q=markdownlint
+[markdownlint-github]: https://github.com/github/markdownlint-github
 [mdn]: https://developer.mozilla.org/
 [mdn-search]: https://github.com/mdn/content/search?q=markdownlint
 [mkdocs]: https://www.mkdocs.org/

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

@@ -34,7 +34,6 @@
     </div>
   </div>
   <script src="markdown-it.min.js"></script>
-  <script src="micromark-browser.js"></script>
   <script src="markdownlint-browser.min.js"></script>
   <script src="default.js"></script>
 </body>

demo/default.js

@@ -2,9 +2,9 @@
 
 (function main() {
   // Dependencies
-  var markdownit = window.markdownit({ "html": true });
-  var markdownlint = window.markdownlint.library;
-  var helpers = window.markdownlint.helpers;
+  var markdownit = globalThis.markdownit;
+  var markdownlint = globalThis.markdownlint;
+  var micromark = markdownlint;
 
   // DOM elements
   var markdown = document.getElementById("markdown");
@@ -31,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, " ");
@@ -58,7 +112,7 @@
       },
       "handleRuleFailures": true
     };
-    allLintErrors = markdownlint.sync(options).content;
+    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 + "'>" +
@@ -76,9 +130,9 @@
             "\"</span>]" :
           "") +
         (result.fixInfo ?
-          " [<a href='#fix' target='" +
+          " [<a href='#fix' target=\"" +
             encodeURIComponent(JSON.stringify(result)) +
-            "' class='detail'>Fix</a>]" :
+            "\" class='detail'>Fix</a>]" :
           "");
     }).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);
+      });
     }
   }
 
@@ -130,7 +182,7 @@
         var errors = e.shiftKey ?
           allLintErrors :
           [ JSON.parse(decodeURIComponent(e.target.target)) ];
-        var fixed = helpers.applyFixes(markdown.value, errors);
+        var fixed = markdownlint.applyFixes(markdown.value, errors);
         markdown.value = fixed;
         onMarkdownInput();
         e.preventDefault();
@@ -157,9 +209,9 @@
 
   // Updates the URL hash and copies the URL to the clipboard
   function onCopyLinkClick(e) {
-    window.location.hash = encodeURIComponent(hashPrefix + markdown.value);
+    globalThis.location.hash = encodeURIComponent(hashPrefix + markdown.value);
     if (navigator.clipboard && navigator.clipboard.writeText) {
-      navigator.clipboard.writeText(window.location).then(noop, noop);
+      navigator.clipboard.writeText(globalThis.location).then(noop, noop);
     } else {
       /* eslint-disable-next-line no-alert */
       alert("Document URL updated, select and copy it now.");
@@ -168,8 +220,8 @@
   }
 
   // Show library version
-  document.getElementById("version").textContent =
-    "(v" + markdownlint.getVersion() + ")";
+  var version = markdownlint.getVersion();
+  document.getElementById("version").textContent = "(v" + version + ")";
 
   // Add event listeners
   document.body.addEventListener("dragover", onDragOver);
@@ -179,7 +231,6 @@
   violations.addEventListener("click", onViolationClick, true);
   copyLink.addEventListener("click", onCopyLinkClick);
 
-  /* eslint-disable max-len */
   markdown.value = [
     "## Introduction",
     "",
@@ -192,8 +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/main/doc/Rules.md) are enabled except [MD013/line-length](https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md).",
-    "> ([MD002/first-heading-h1](https://github.com/DavidAnson/markdownlint/blob/main/doc/md002.md) and [MD006/ul-start-left](https://github.com/DavidAnson/markdownlint/blob/main/doc/md006.md) are 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",
@@ -207,17 +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 {
-      var 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);
       }
-      /* eslint-disable-next-line unicorn/prefer-optional-catch-binding */
-    } catch (error) {
+    } catch {
       // Invalid
     }
   }
@@ -226,8 +274,7 @@
   try {
     /* eslint-disable-next-line no-new */
     new URL("https://example.com/");
-    /* eslint-disable-next-line unicorn/prefer-optional-catch-binding */
-  } catch (error) {
+  } catch {
     markdown.value = [
       "# Sorry",
       "",

demo/markdownlint-exports.js

@@ -1,8 +0,0 @@
-// @ts-check
-
-"use strict";
-
-module.exports = {
-  "library": require(".."),
-  "helpers": require("../helpers")
-};

demo/webpack.config.js

@@ -1,114 +0,0 @@
-// @ts-check
-
-"use strict";
-
-const webpack = require("webpack");
-const TerserPlugin = require("terser-webpack-plugin");
-const nodeModulePrefixRe = /^node:/u;
-
-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",
-      "markdownlint-micromark": "micromarkBrowser"
-    },
-    "mode": mode,
-    "module": {
-      "rules": [
-        {
-          "test": /\.[cm]?js$/,
-          "exclude": /node_modules/,
-          "use": {
-            "loader": "babel-loader",
-            "options": {
-              "presets": [ "@babel/preset-env" ]
-            }
-          }
-        }
-      ]
-    },
-    "name": name,
-    "optimization": optimization,
-    "output": {
-      "filename": filename,
-      "library": {
-        "name": name.replace(/(-\w)/g, (m) => m.slice(1).toUpperCase()),
-        "type": "var"
-      },
-      "path": __dirname
-    },
-    "plugins": [
-      new webpack.NormalModuleReplacementPlugin(
-        nodeModulePrefixRe,
-        (resource) => {
-          const module = resource.request.replace(nodeModulePrefixRe, "");
-          resource.request = module;
-        }
-      ),
-      new webpack.BannerPlugin({
-        "banner": `${name} ${version} ${homepage} @license ${license}`
-      })
-    ],
-    "resolve": {
-      "fallback": {
-        "fs": false,
-        "os": false,
-        "path": false,
-        "util": false
-      }
-    }
-  };
-}
-
-const modeDevelopment = {
-  "mode": "development"
-};
-const modeProduction = {
-  "mode": "production",
-  "optimization": {
-    "minimizer": [
-      new TerserPlugin({
-        "extractComments": false,
-        "terserOptions": {
-          "compress": {
-            "passes": 2
-          }
-        }
-      })
-    ]
-  }
-};
-const entryLibrary = {
-  "entry": "./markdownlint-exports.js",
-  "packageJson": require("../package.json")
-};
-// const entryHelpers = {
-//   "entry": "../helpers/helpers.js",
-//   "packageJson": require("../helpers/package.json")
-// };
-module.exports = [
-  config({
-    ...entryLibrary,
-    ...modeDevelopment,
-    "filename": "markdownlint-browser.js"
-  }),
-  config({
-    ...entryLibrary,
-    ...modeProduction,
-    "filename": "markdownlint-browser.min.js"
-  })
-  // config({
-  //   ...entryHelpers,
-  //   ...modeDevelopment,
-  //   "filename": "markdownlint-rule-helpers-browser.js"
-  // }),
-  // config({
-  //   ...entryHelpers,
-  //   ...modeProduction,
-  //   "filename": "markdownlint-rule-helpers-browser.min.js"
-  // })
-];

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/build-rules.mjs

@@ -1,8 +1,8 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { EOL } from "node:os";
-import { default as rules } from "../lib/rules.js";
-import { newLineRe } from "../helpers/helpers.js";
-import { deprecatedRuleNames, fixableRuleNames } from "../lib/constants.js";
+import rules from "../lib/rules.mjs";
+import { newLineRe } from "../helpers/helpers.cjs";
+import { deprecatedRuleNames, fixableRuleNames } from "../lib/constants.mjs";
 
 const maxLineLength = 80;
 
@@ -68,9 +68,10 @@ for (const rule of rules) {
     );
     for (const property of Object.keys(ruleData.properties).sort()) {
       const propData = ruleData.properties[property];
-      const propType = (propData.type === "array") ?
-        `${propData.items.type}[]` :
-        propData.type;
+      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;

doc-build/heading.md

@@ -2,5 +2,4 @@
 
 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. Any rule whose heading is ~~struck through~~ is
-deprecated, but still provided for backward-compatibility.
+versions of the examples.

doc-build/md002.md

@@ -1,25 +0,0 @@
-> Note: *MD002 has been deprecated and is disabled by default.*
-> [MD041/first-line-heading](md041.md) offers an improved implementation.
-
-This rule is intended to ensure document headings start at the top level and
-is triggered when the first heading in the document isn't an h1 heading:
-
-```markdown
-## This isn't an H1 heading
-
-### Another heading
-```
-
-The first heading in the document should be an h1 heading:
-
-```markdown
-# Start with an H1 heading
-
-## Then use an H2 for subsections
-```
-
-Note: The `level` parameter can be used to change the top-level (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>.

doc-build/md003.md

@@ -33,8 +33,8 @@ Setext style H2
 ```
 
 Note: The configured heading style can be a specific style to require (`atx`,
-`atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or may
-just require that usage is consistent within the document via `consistent`.
+`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:

doc-build/md004.md

@@ -16,9 +16,10 @@ document:
 * Item 3
 ```
 
-The configured list style can be a specific symbol to use (asterisk, plus,
-dash), to ensure that all list styling is consistent, or to ensure that each
-sublist has a consistent symbol that differs from its parent list.
+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

doc-build/md006.md

@@ -1,36 +0,0 @@
-This rule is triggered when top-level lists don't start at the beginning of a
-line:
-
-```markdown
-Some text
-
-  * List item
-  * List item
-```
-
-To fix, ensure that top-level list items are not indented:
-
-```markdown
-Some test
-
-* List item
-* List item
-```
-
-Note: This rule is triggered for the following scenario because the unordered
-sublist is not recognized as such by the parser. Not being nested 3 characters
-as required by the outer ordered list, it creates a top-level unordered list
-instead.
-
-```markdown
-1. List item
-  - List item
-  - List item
-1. List item
-```
-
-Rationale: Starting lists at the beginning of the line means that nested list
-items can all be indented by the same amount when an editor's indent function
-or the tab key is used to indent. Starting a list 1 space in means that the
-indent of the first nested list is less than the indent of the second level (3
-characters if you use 4 space tabs, or 1 character if you use 2 space tabs).

doc-build/md007.md

@@ -20,20 +20,17 @@ 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 inverse of
-MD006). 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).
+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] and [Marked app\
-support][marked-app-support].
+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
-[marked-app-support]: http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting

doc-build/md013.md

@@ -1,5 +1,3 @@
-> If `headings` is not provided, `headers` (deprecated) will be used.
-
 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
@@ -18,12 +16,12 @@ 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
-And this line is a violation because there are
-This-line-is-also-okay-because-there-are-no-spaces
+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` or `stern` modes, the two middle lines above are a violation. The
-third line is a violation in `strict` mode but allowed in `stern` mode.
+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.
@@ -32,9 +30,10 @@ 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 are always exempted from this rule
-(even in `strict` mode) because there is generally no way to split such lines
-without breaking the URL.
+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/md022.md

@@ -23,10 +23,16 @@ Some more text
 ```
 
 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.
+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).
 
-Note: If `lines_above` or `lines_below` are configured to require more than one
-blank line, [MD012/no-multiple-blanks](md012.md) should also be customized.
+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

doc-build/md023.md

@@ -14,5 +14,12 @@ 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

@@ -15,9 +15,8 @@ To fix this, ensure that the content of each heading is different:
 ## Some more text
 ```
 
-If the parameter `siblings_only` (alternatively `allow_different_nesting`) is
-set to `true`, heading duplication is allowed for non-sibling headings (common
-in changelogs):
+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

doc-build/md027.md

@@ -13,4 +13,8 @@ To fix, remove any extraneous space:
 > 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/md032.md

@@ -3,28 +3,45 @@ followed by a blank line:
 
 ```markdown
 Some text
-* Some
-* List
+* List item
+* List item
 
-1. Some
-2. List
-Some text
+1. List item
+2. List item
+***
 ```
 
-To fix this, ensure that all lists have a blank line both before and after
-(except where the block is at the beginning or end of the document):
+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
 
-* Some
-* List
+* List item
+* List item
 
-1. Some
-2. List
+1. List item
+2. List item
 
-Some text
+***
 ```
 
-Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
-not parse lists that don't have blank lines before and after them.
+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/md034.md

@@ -11,6 +11,11 @@ To fix this, add angle brackets around the URL or email address:
 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:
 

doc-build/md035.md

@@ -13,8 +13,7 @@ in the document:
 ****
 ```
 
-To fix this, ensure any horizontal rules used in the document are consistent,
-or match the given style if the rule is so configured:
+To fix this, use the same horizontal rule everywhere:
 
 ```markdown
 ---
@@ -22,11 +21,7 @@ or match the given style if the rule is so configured:
 ---
 ```
 
-Note: by default, this rule is configured to just require that all horizontal
-rules in the document are the same and will trigger if any of the horizontal
-rules are different than the first one encountered in the document. If you
-want to configure the rule to match a specific style, the parameter given to
-the 'style' option is a string containing the exact horizontal rule text that
-is allowed.
+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/md038.md

@@ -1,32 +1,44 @@
-This rule is triggered for code span elements that have spaces adjacent to the
-backticks:
+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 any spaces adjacent to the backticks:
+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
-automatically trimmed (in order to allow for code spans that embed backticks):
+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: A single leading or trailing space is allowed if used to separate code
-span markers from an embedded backtick (though the space is not trimmed):
+Note: When single-space padding is present in the input, it will be preserved
+(even if unnecessary):
 
 ```markdown
-`` ` embedded backtick``
+` code `
 ```
 
-Rationale: Violations of this rule are usually unintentional and may lead to
-improperly-rendered content. If spaces beside backticks are intentional, this
-rule can be disabled for that line or file.
+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/md041.md

@@ -1,37 +1,50 @@
 This rule is intended to ensure documents have a title and is triggered when
-the first line in the file isn't a top-level (h1) heading:
+the first line in a document is not a top-level ([HTML][HTML] `h1`) heading:
 
 ```markdown
-This is a file without a heading
+This is a document without a heading
 ```
 
-To fix this, add a top-level heading to the beginning of the file:
+To fix this, add a top-level heading to the beginning of the document:
 
 ```markdown
-# File with heading
+# Document Heading
 
-This is a file with a top-level 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 is not well-supported by Markdown, HTML headings are also
-permitted by this rule. For example:
+`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 file with a top-level HTML heading
+This is a document with a top-level HTML heading
 ```
 
-Note: The `level` parameter can be used to change the top-level (ex: to h2) in
-cases where an h1 is added externally.
+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`.
 
-If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
-contains a `title` property (commonly used with blog posts), this rule will not
-report a violation. To use a different property name in the front matter,
-specify the text of a regular expression via the `front_matter_title` parameter.
-To disable the use of front matter by this rule, specify `""` for
-`front_matter_title`.
+```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/md043.md

@@ -1,5 +1,3 @@
-> If `headings` is not provided, `headers` (deprecated) will be used.
-
 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.
@@ -7,7 +5,7 @@ structure for a set of files.
 To require exactly the following structure:
 
 ```markdown
-# Head
+# Heading
 ## Item
 ### Detail
 ```
@@ -16,7 +14,7 @@ Set the `headings` parameter to:
 
 ```json
 [
-    "# Head",
+    "# Heading",
     "## Item",
     "### Detail"
 ]
@@ -25,7 +23,7 @@ Set the `headings` parameter to:
 To allow optional headings as with the following structure:
 
 ```markdown
-# Head
+# Heading
 ## Item
 ### Detail (optional)
 ## Foot
@@ -38,7 +36,7 @@ special value `"+"` meaning "one or more unspecified headings" and set the
 
 ```json
 [
-    "# Head",
+    "# Heading",
     "## Item",
     "*",
     "## Foot",
@@ -46,6 +44,24 @@ special value `"+"` meaning "one or more unspecified headings" and set the
 ]
 ```
 
+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).
 

doc-build/md044.md

@@ -13,6 +13,16 @@ enforce the proper capitalization, specify the desired letter case in the
 ]
 ```
 
+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

doc-build/md045.md

@@ -1,4 +1,4 @@
-This rule is triggered when an image is missing alternate text (alt text)
+This rule reports a violation when an image is missing alternate text (alt text)
 information.
 
 Alternate text is commonly specified inline as:
@@ -17,12 +17,26 @@ Or with reference syntax as:
 [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

@@ -23,7 +23,7 @@ document:
 To fix violations of this rule, use a consistent style (either indenting or code
 fences).
 
-The specified style can be specific (`fenced`, `indented`) or simply require
-that usage be consistent within the document (`consistent`).
+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/md048.md

@@ -24,7 +24,8 @@ document:
 ```
 ````
 
-The configured list style can be a specific symbol to use (backtick, tilde), or
-can require that usage be consistent within the document.
+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

@@ -13,7 +13,11 @@ To fix this issue, use the configured emphasis style throughout the document:
 *Text*
 ```
 
-The configured emphasis style can be a specific symbol to use ("asterisk",
-"underscore"), or can require that usage be consistent within the document.
+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

@@ -13,7 +13,10 @@ To fix this issue, use the configured strong style throughout the document:
 **Text**
 ```
 
-The configured strong style can be a specific symbol to use ("asterisk",
-"underscore"), or can require that usage be consistent within the document.
+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

@@ -2,21 +2,46 @@ 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
-# Title
+# Heading Name
 
 [Link](#fragment)
 ```
 
-To fix this issue, change the link fragment to reference an existing heading:
+To fix this issue, change the link fragment to reference an existing heading's
+generated name (see below):
 
 ```markdown
-# Title
+# Heading Name
 
-[Link](#title)
+[Link](#heading-name)
 ```
 
-Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to
-define a fragment:
+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>
@@ -27,6 +52,34 @@ define a fragment:
 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.
@@ -40,3 +93,6 @@ 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

@@ -18,10 +18,24 @@ Shortcut: ![image]
 [image]: https://example.com/image
 ```
 
-A link or image renders correctly when a corresponding label is defined, but
-the text displays with brackets if the label is not present. This rule warns
-of undefined labels for "full" and "collapsed" reference syntax.
+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.
 
-> "Shortcut" syntax is ambiguous and a missing label will not generate an
-  error. For example, `[shortcut]` could be a shortcut link or the text
-  "shortcut" in brackets.
+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

@@ -1,7 +1,7 @@
 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.
+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
@@ -17,9 +17,9 @@ 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. The default value of
-this parameter ignores the following convention for adding non-HTML comments to
-Markdown:
+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,20 +1,21 @@
 # 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`
+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]). Custom rules can be disabled,
-enabled, and customized using the same syntax as built-in rules.
+`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 in
-JSON without needing to write any code.
+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
 
@@ -25,31 +26,65 @@ 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`.
+
+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.parsers.markdownit.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.startLine,
+        "detail": "Blockquote spans " + lines + " line(s).",
+        "context": params.lines[blockquote.startLine - 1]
+      });
+    }
+  }
+}
+```
+
+That same rule implemented using the `markdown-it` parser might look like:
+
+```javascript
+/** @type {import("markdownlint").Rule} */
+module.exports = {
+  "names": [ "any-blockquote-markdown-it" ],
+  "description": "Rule that reports an error for any blockquote",
+  "information": new URL("https://example.com/rules/any-blockquote"),
+  "tags": [ "test" ],
+  "parser": "markdownit",
+  "function": (params, onError) => {
+    const blockquotes = params.parsers.markdownit.tokens
+      .filter((token) => token.type === "blockquote_open");
+    for (const blockquote of blockquotes) {
+      const [ startIndex, endIndex ] = blockquote.map;
+      const lines = endIndex - startIndex;
       onError({
         "lineNumber": blockquote.lineNumber,
         "detail": "Blockquote spans " + lines + " line(s).",
-        "context": blockquote.line.substr(0, 7)
-      });
+        "context": blockquote.line
       });
     }
-};
+  }
+}
 ```
 
-A rule is implemented as an `Object` with one optional and four required
-properties:
+A rule is implemented as an `Object`:
 
 - `names` is a required `Array` of `String` values that identify the rule in
   output messages and config.
@@ -59,6 +94,8 @@ properties:
   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
@@ -66,14 +103,24 @@ properties:
   - `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`s][markdown-it-token] with
-      added `line` and `lineNumber` properties.
+    - `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
@@ -82,6 +129,8 @@ properties:
       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
@@ -111,16 +160,16 @@ implementation that is resolved when the rule completes. (The value passed to
 reported via the `onError` function just like for synchronous rules.
 
 **Note**: Asynchronous rules cannot be referenced in a synchronous calling
-context (i.e., `markdownlint.sync(...)`). Attempting to do so throws an
-exception.
+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]
-- [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 axibase/docs-util repository][docs-util]
+- [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
@@ -128,247 +177,18 @@ exception.
 - [CommonMark documentation and specification][commonmark]
 - [`markdown-it` Markdown parser project page][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
-  }
-}
-```
-
 [commonmark]: https://commonmark.org/
-[docs-util]: https://github.com/axibase/docs-util/tree/master/linting-rules
+[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
-[test-rules-npm]: ../test/rules/npm
+[tokens]: ../test/snapshots/markdownlint-test-custom-rules.mjs.md

doc/md001.md

@@ -1,8 +1,8 @@
 # `MD001` - Heading levels should only increment by one level at a time
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
-Aliases: `header-increment`, `heading-increment`
+Aliases: `heading-increment`
 
 This rule is triggered when you skip heading levels in a Markdown document, for
 example:

doc/md002.md

@@ -1,37 +0,0 @@
-# ~~`MD002` - First heading should be a top-level heading~~
-
-> This rule is deprecated and provided for backward-compatibility
-
-Tags: `headers`, `headings`
-
-Aliases: `first-header-h1`, `first-heading-h1`
-
-Parameters:
-
-- `level`: Heading level (`integer`, default `1`)
-
-> Note: *MD002 has been deprecated and is disabled by default.*
-> [MD041/first-line-heading](md041.md) offers an improved implementation.
-
-This rule is intended to ensure document headings start at the top level and
-is triggered when the first heading in the document isn't an h1 heading:
-
-```markdown
-## This isn't an H1 heading
-
-### Another heading
-```
-
-The first heading in the document should be an h1 heading:
-
-```markdown
-# Start with an H1 heading
-
-## Then use an H2 for subsections
-```
-
-Note: The `level` parameter can be used to change the top-level (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>.

doc/md003.md

@@ -1,8 +1,8 @@
 # `MD003` - Heading style
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
-Aliases: `header-style`, `heading-style`
+Aliases: `heading-style`
 
 Parameters:
 
@@ -45,8 +45,8 @@ Setext style H2
 ```
 
 Note: The configured heading style can be a specific style to require (`atx`,
-`atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or may
-just require that usage is consistent within the document via `consistent`.
+`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:

doc/md004.md

@@ -29,9 +29,10 @@ document:
 * Item 3
 ```
 
-The configured list style can be a specific symbol to use (asterisk, plus,
-dash), to ensure that all list styling is consistent, or to ensure that each
-sublist has a consistent symbol that differs from its parent list.
+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

doc/md006.md

@@ -1,46 +0,0 @@
-# ~~`MD006` - Consider starting bulleted lists at the beginning of the line~~
-
-> This rule is deprecated and provided for backward-compatibility
-
-Tags: `bullet`, `indentation`, `ul`
-
-Aliases: `ul-start-left`
-
-Fixable: Some violations can be fixed by tooling
-
-This rule is triggered when top-level lists don't start at the beginning of a
-line:
-
-```markdown
-Some text
-
-  * List item
-  * List item
-```
-
-To fix, ensure that top-level list items are not indented:
-
-```markdown
-Some test
-
-* List item
-* List item
-```
-
-Note: This rule is triggered for the following scenario because the unordered
-sublist is not recognized as such by the parser. Not being nested 3 characters
-as required by the outer ordered list, it creates a top-level unordered list
-instead.
-
-```markdown
-1. List item
-  - List item
-  - List item
-1. List item
-```
-
-Rationale: Starting lists at the beginning of the line means that nested list
-items can all be indented by the same amount when an editor's indent function
-or the tab key is used to indent. Starting a list 1 space in means that the
-indent of the first nested list is less than the indent of the second level (3
-characters if you use 4 space tabs, or 1 character if you use 2 space tabs).

doc/md007.md

@@ -36,20 +36,17 @@ 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 inverse of
-MD006). 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).
+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] and [Marked app\
-support][marked-app-support].
+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
-[marked-app-support]: http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting

doc/md013.md

@@ -9,7 +9,6 @@ Parameters:
 - `code_block_line_length`: Number of characters for code blocks (`integer`,
   default `80`)
 - `code_blocks`: Include code blocks (`boolean`, default `true`)
-- `headers`: Include headings (`boolean`, default `true`)
 - `heading_line_length`: Number of characters for headings (`integer`, default
   `80`)
 - `headings`: Include headings (`boolean`, default `true`)
@@ -18,8 +17,6 @@ Parameters:
 - `strict`: Strict length checking (`boolean`, default `false`)
 - `tables`: Include tables (`boolean`, default `true`)
 
-> If `headings` is not provided, `headers` (deprecated) will be used.
-
 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
@@ -38,12 +35,12 @@ 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
-And this line is a violation because there are
-This-line-is-also-okay-because-there-are-no-spaces
+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` or `stern` modes, the two middle lines above are a violation. The
-third line is a violation in `strict` mode but allowed in `stern` mode.
+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.
@@ -52,9 +49,10 @@ 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 are always exempted from this rule
-(even in `strict` mode) because there is generally no way to split such lines
-without breaking the URL.
+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/md018.md

@@ -1,6 +1,6 @@
 # `MD018` - No space after hash on atx style heading
 
-Tags: `atx`, `headers`, `headings`, `spaces`
+Tags: `atx`, `headings`, `spaces`
 
 Aliases: `no-missing-space-atx`
 

doc/md019.md

@@ -1,6 +1,6 @@
 # `MD019` - Multiple spaces after hash on atx style heading
 
-Tags: `atx`, `headers`, `headings`, `spaces`
+Tags: `atx`, `headings`, `spaces`
 
 Aliases: `no-multiple-space-atx`
 

doc/md020.md

@@ -1,6 +1,6 @@
 # `MD020` - No space inside hashes on closed atx style heading
 
-Tags: `atx_closed`, `headers`, `headings`, `spaces`
+Tags: `atx_closed`, `headings`, `spaces`
 
 Aliases: `no-missing-space-closed-atx`
 

doc/md021.md

@@ -1,6 +1,6 @@
 # `MD021` - Multiple spaces inside hashes on closed atx style heading
 
-Tags: `atx_closed`, `headers`, `headings`, `spaces`
+Tags: `atx_closed`, `headings`, `spaces`
 
 Aliases: `no-multiple-space-closed-atx`
 

doc/md022.md

@@ -1,13 +1,13 @@
 # `MD022` - Headings should be surrounded by blank lines
 
-Tags: `blank_lines`, `headers`, `headings`
+Tags: `blank_lines`, `headings`
 
-Aliases: `blanks-around-headers`, `blanks-around-headings`
+Aliases: `blanks-around-headings`
 
 Parameters:
 
-- `lines_above`: Blank lines above heading (`integer`, default `1`)
-- `lines_below`: Blank lines below heading (`integer`, default `1`)
+- `lines_above`: Blank lines above heading (`integer|integer[]`, default `1`)
+- `lines_below`: Blank lines below heading (`integer|integer[]`, default `1`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -36,10 +36,16 @@ Some more text
 ```
 
 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.
+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).
 
-Note: If `lines_above` or `lines_below` are configured to require more than one
-blank line, [MD012/no-multiple-blanks](md012.md) should also be customized.
+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

doc/md023.md

@@ -1,8 +1,8 @@
 # `MD023` - Headings must start at the beginning of the line
 
-Tags: `headers`, `headings`, `spaces`
+Tags: `headings`, `spaces`
 
-Aliases: `header-start-left`, `heading-start-left`
+Aliases: `heading-start-left`
 
 Fixable: Some violations can be fixed by tooling
 
@@ -22,5 +22,12 @@ 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/md024.md

@@ -1,13 +1,11 @@
 # `MD024` - Multiple headings with the same content
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
-Aliases: `no-duplicate-header`, `no-duplicate-heading`
+Aliases: `no-duplicate-heading`
 
 Parameters:
 
-- `allow_different_nesting`: Only check sibling headings (`boolean`, default
-  `false`)
 - `siblings_only`: Only check sibling headings (`boolean`, default `false`)
 
 This rule is triggered if there are multiple headings in the document that have
@@ -27,9 +25,8 @@ To fix this, ensure that the content of each heading is different:
 ## Some more text
 ```
 
-If the parameter `siblings_only` (alternatively `allow_different_nesting`) is
-set to `true`, heading duplication is allowed for non-sibling headings (common
-in changelogs):
+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

doc/md025.md

@@ -1,6 +1,6 @@
 # `MD025` - Multiple top-level headings in the same document
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
 Aliases: `single-h1`, `single-title`
 

doc/md026.md

@@ -1,13 +1,12 @@
 # `MD026` - Trailing punctuation in heading
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
 Aliases: `no-trailing-punctuation`
 
 Parameters:
 
-- `punctuation`: Punctuation characters not allowed at end of headings
-  (`string`, default `.,;:!。，；：！`)
+- `punctuation`: Punctuation characters (`string`, default `.,;:!。，；：！`)
 
 Fixable: Some violations can be fixed by tooling
 

doc/md027.md

@@ -4,6 +4,10 @@ Tags: `blockquote`, `indentation`, `whitespace`
 
 Aliases: `no-multiple-space-blockquote`
 
+Parameters:
+
+- `list_items`: Include list items (`boolean`, default `true`)
+
 Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when blockquotes have more than one space after the
@@ -21,4 +25,8 @@ To fix, remove any extraneous space:
 > 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/md032.md

@@ -11,28 +11,45 @@ followed by a blank line:
 
 ```markdown
 Some text
-* Some
-* List
+* List item
+* List item
 
-1. Some
-2. List
-Some text
+1. List item
+2. List item
+***
 ```
 
-To fix this, ensure that all lists have a blank line both before and after
-(except where the block is at the beginning or end of the document):
+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
 
-* Some
-* List
+* List item
+* List item
 
-1. Some
-2. List
+1. List item
+2. List item
 
-Some text
+***
 ```
 
-Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
-not parse lists that don't have blank lines before and after them.
+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/md034.md

@@ -19,6 +19,11 @@ To fix this, add angle brackets around the URL or email address:
 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:
 

doc/md035.md

@@ -23,8 +23,7 @@ in the document:
 ****
 ```
 
-To fix this, ensure any horizontal rules used in the document are consistent,
-or match the given style if the rule is so configured:
+To fix this, use the same horizontal rule everywhere:
 
 ```markdown
 ---
@@ -32,11 +31,7 @@ or match the given style if the rule is so configured:
 ---
 ```
 
-Note: by default, this rule is configured to just require that all horizontal
-rules in the document are the same and will trigger if any of the horizontal
-rules are different than the first one encountered in the document. If you
-want to configure the rule to match a specific style, the parameter given to
-the 'style' option is a string containing the exact horizontal rule text that
-is allowed.
+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/md036.md

@@ -1,8 +1,8 @@
 # `MD036` - Emphasis used instead of a heading
 
-Tags: `emphasis`, `headers`, `headings`
+Tags: `emphasis`, `headings`
 
-Aliases: `no-emphasis-as-header`, `no-emphasis-as-heading`
+Aliases: `no-emphasis-as-heading`
 
 Parameters:
 

doc/md038.md

@@ -6,35 +6,47 @@ Aliases: `no-space-in-code`
 
 Fixable: Some violations can be fixed by tooling
 
-This rule is triggered for code span elements that have spaces adjacent to the
-backticks:
+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 any spaces adjacent to the backticks:
+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
-automatically trimmed (in order to allow for code spans that embed backticks):
+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: A single leading or trailing space is allowed if used to separate code
-span markers from an embedded backtick (though the space is not trimmed):
+Note: When single-space padding is present in the input, it will be preserved
+(even if unnecessary):
 
 ```markdown
-`` ` embedded backtick``
+` code `
 ```
 
-Rationale: Violations of this rule are usually unintentional and may lead to
-improperly-rendered content. If spaces beside backticks are intentional, this
-rule can be disabled for that line or file.
+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/md041.md

@@ -1,49 +1,64 @@
 # `MD041` - First line in a file should be a top-level heading
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
 Aliases: `first-line-h1`, `first-line-heading`
 
 Parameters:
 
+- `allow_preamble`: Allow content before first heading (`boolean`, default
+  `false`)
 - `front_matter_title`: RegExp for matching title in front matter (`string`,
   default `^\s*title\s*[:=]`)
 - `level`: Heading level (`integer`, default `1`)
 
 This rule is intended to ensure documents have a title and is triggered when
-the first line in the file isn't a top-level (h1) heading:
+the first line in a document is not a top-level ([HTML][HTML] `h1`) heading:
 
 ```markdown
-This is a file without a heading
+This is a document without a heading
 ```
 
-To fix this, add a top-level heading to the beginning of the file:
+To fix this, add a top-level heading to the beginning of the document:
 
 ```markdown
-# File with heading
+# Document Heading
 
-This is a file with a top-level 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 is not well-supported by Markdown, HTML headings are also
-permitted by this rule. For example:
+`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 file with a top-level HTML heading
+This is a document with a top-level HTML heading
 ```
 
-Note: The `level` parameter can be used to change the top-level (ex: to h2) in
-cases where an h1 is added externally.
+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`.
 
-If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
-contains a `title` property (commonly used with blog posts), this rule will not
-report a violation. To use a different property name in the front matter,
-specify the text of a regular expression via the `front_matter_title` parameter.
-To disable the use of front matter by this rule, specify `""` for
-`front_matter_title`.
+```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/md043.md

@@ -1,17 +1,14 @@
 # `MD043` - Required heading structure
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
-Aliases: `required-headers`, `required-headings`
+Aliases: `required-headings`
 
 Parameters:
 
-- `headers`: List of headings (`string[]`, default `[]`)
 - `headings`: List of headings (`string[]`, default `[]`)
 - `match_case`: Match case of headings (`boolean`, default `false`)
 
-> If `headings` is not provided, `headers` (deprecated) will be used.
-
 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.
@@ -19,7 +16,7 @@ structure for a set of files.
 To require exactly the following structure:
 
 ```markdown
-# Head
+# Heading
 ## Item
 ### Detail
 ```
@@ -28,7 +25,7 @@ Set the `headings` parameter to:
 
 ```json
 [
-    "# Head",
+    "# Heading",
     "## Item",
     "### Detail"
 ]
@@ -37,7 +34,7 @@ Set the `headings` parameter to:
 To allow optional headings as with the following structure:
 
 ```markdown
-# Head
+# Heading
 ## Item
 ### Detail (optional)
 ## Foot
@@ -50,7 +47,7 @@ special value `"+"` meaning "one or more unspecified headings" and set the
 
 ```json
 [
-    "# Head",
+    "# Heading",
     "## Item",
     "*",
     "## Foot",
@@ -58,6 +55,24 @@ special value `"+"` meaning "one or more unspecified headings" and set the
 ]
 ```
 
+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).
 

doc/md044.md

@@ -27,6 +27,16 @@ enforce the proper capitalization, specify the desired letter case in the
 ]
 ```
 
+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

doc/md045.md

@@ -4,7 +4,7 @@ Tags: `accessibility`, `images`
 
 Aliases: `no-alt-text`
 
-This rule is triggered when an image is missing alternate text (alt text)
+This rule reports a violation when an image is missing alternate text (alt text)
 information.
 
 Alternate text is commonly specified inline as:
@@ -23,12 +23,26 @@ Or with reference syntax as:
 [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/md046.md

@@ -34,7 +34,7 @@ document:
 To fix violations of this rule, use a consistent style (either indenting or code
 fences).
 
-The specified style can be specific (`fenced`, `indented`) or simply require
-that usage be consistent within the document (`consistent`).
+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/md048.md

@@ -35,7 +35,8 @@ document:
 ```
 ````
 
-The configured list style can be a specific symbol to use (backtick, tilde), or
-can require that usage be consistent within the document.
+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/md049.md

@@ -1,4 +1,4 @@
-# `MD049` - Emphasis style should be consistent
+# `MD049` - Emphasis style
 
 Tags: `emphasis`
 
@@ -6,8 +6,8 @@ Aliases: `emphasis-style`
 
 Parameters:
 
-- `style`: Emphasis style should be consistent (`string`, default `consistent`,
-  values `asterisk` / `consistent` / `underscore`)
+- `style`: Emphasis style (`string`, default `consistent`, values `asterisk` /
+  `consistent` / `underscore`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -26,7 +26,11 @@ To fix this issue, use the configured emphasis style throughout the document:
 *Text*
 ```
 
-The configured emphasis style can be a specific symbol to use ("asterisk",
-"underscore"), or can require that usage be consistent within the document.
+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/md050.md

@@ -1,4 +1,4 @@
-# `MD050` - Strong style should be consistent
+# `MD050` - Strong style
 
 Tags: `emphasis`
 
@@ -6,8 +6,8 @@ Aliases: `strong-style`
 
 Parameters:
 
-- `style`: Strong style should be consistent (`string`, default `consistent`,
-  values `asterisk` / `consistent` / `underscore`)
+- `style`: Strong style (`string`, default `consistent`, values `asterisk` /
+  `consistent` / `underscore`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -26,7 +26,10 @@ To fix this issue, use the configured strong style throughout the document:
 **Text**
 ```
 
-The configured strong style can be a specific symbol to use ("asterisk",
-"underscore"), or can require that usage be consistent within the document.
+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/md051.md

@@ -4,27 +4,58 @@ Tags: `links`
 
 Aliases: `link-fragments`
 
+Parameters:
+
+- `ignore_case`: Ignore case of fragments (`boolean`, default `false`)
+- `ignored_pattern`: Pattern for ignoring additional fragments (`string`,
+  default ``)
+
 Fixable: Some violations can be fixed by tooling
 
 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
-# Title
+# Heading Name
 
 [Link](#fragment)
 ```
 
-To fix this issue, change the link fragment to reference an existing heading:
+To fix this issue, change the link fragment to reference an existing heading's
+generated name (see below):
 
 ```markdown
-# Title
+# Heading Name
 
-[Link](#title)
+[Link](#heading-name)
 ```
 
-Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to
-define a fragment:
+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>
@@ -35,6 +66,34 @@ define a fragment:
 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.
@@ -48,3 +107,6 @@ 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/md052.md

@@ -4,6 +4,11 @@ Tags: `images`, `links`
 
 Aliases: `reference-links-images`
 
+Parameters:
+
+- `ignored_labels`: Ignored link labels (`string[]`, default `["x"]`)
+- `shortcut_syntax`: Include shortcut syntax (`boolean`, default `false`)
+
 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
@@ -24,10 +29,24 @@ Shortcut: ![image]
 [image]: https://example.com/image
 ```
 
-A link or image renders correctly when a corresponding label is defined, but
-the text displays with brackets if the label is not present. This rule warns
-of undefined labels for "full" and "collapsed" reference syntax.
+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.
 
-> "Shortcut" syntax is ambiguous and a missing label will not generate an
-  error. For example, `[shortcut]` could be a shortcut link or the text
-  "shortcut" in brackets.
+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/md053.md

@@ -11,9 +11,9 @@ Parameters:
 Fixable: Some violations can be fixed by tooling
 
 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.
+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
@@ -29,9 +29,9 @@ 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. The default value of
-this parameter ignores the following convention for adding non-HTML comments to
-Markdown:
+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/md054.md

@@ -0,0 +1,100 @@
+# `MD054` - Link and image style
+
+Tags: `images`, `links`
+
+Aliases: `link-image-style`
+
+Parameters:
+
+- `autolink`: Allow autolinks (`boolean`, default `true`)
+- `collapsed`: Allow collapsed reference links and images (`boolean`, default
+  `true`)
+- `full`: Allow full reference links and images (`boolean`, default `true`)
+- `inline`: Allow inline links and images (`boolean`, default `true`)
+- `shortcut`: Allow shortcut reference links and images (`boolean`, default
+  `true`)
+- `url_inline`: Allow URLs as inline links (`boolean`, default `true`)
+
+Fixable: Some violations can be fixed by tooling
+
+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/md055.md

@@ -0,0 +1,55 @@
+# `MD055` - Table pipe style
+
+Tags: `table`
+
+Aliases: `table-pipe-style`
+
+Parameters:
+
+- `style`: Table pipe style (`string`, default `consistent`, values
+  `consistent` / `leading_and_trailing` / `leading_only` /
+  `no_leading_or_trailing` / `trailing_only`)
+
+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/md056.md

@@ -0,0 +1,37 @@
+# `MD056` - Table column count
+
+Tags: `table`
+
+Aliases: `table-column-count`
+
+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/md058.md

@@ -0,0 +1,48 @@
+# `MD058` - Tables should be surrounded by blank lines
+
+Tags: `table`
+
+Aliases: `blanks-around-tables`
+
+Fixable: Some violations can be fixed by tooling
+
+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/md059.md

@@ -0,0 +1,30 @@
+# `MD059` - Link text should be descriptive
+
+Tags: `accessibility`, `links`
+
+Aliases: `descriptive-link-text`
+
+Parameters:
+
+- `prohibited_texts`: Prohibited link texts (`string[]`, default `["click
+  here","here","link","more"]`)
+
+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/>

eslint.config.mjs

@@ -0,0 +1,167 @@
+import js from "@eslint/js";
+import eslintPluginJsdoc from "eslint-plugin-jsdoc";
+import eslintPluginNode from "eslint-plugin-n";
+import eslintPluginRegexp from "eslint-plugin-regexp";
+import eslintPluginStylistic from "@stylistic/eslint-plugin";
+import eslintPluginUnicorn from "eslint-plugin-unicorn";
+
+export default [
+  js.configs.all,
+  eslintPluginJsdoc.configs["flat/recommended"],
+  eslintPluginNode.configs["flat/recommended"],
+  eslintPluginRegexp.configs["flat/recommended"],
+  eslintPluginStylistic.configs.customize({
+    "arrowParens": true,
+    "braceStyle": "1tbs",
+    "commaDangle": "never",
+    "jsx": false,
+    "quoteProps": "always",
+    "quotes": "double",
+    "semi": true
+  }),
+  eslintPluginUnicorn.configs["flat/all"],
+  {
+    "ignores": [
+      "demo/markdown-it.min.js",
+      "demo/markdownlint-browser.js",
+      "demo/markdownlint-browser.min.js",
+      "example/typescript/type-check-*",
+      "test-repos/**"
+    ]
+  },
+  {
+    "linterOptions": {
+      "reportUnusedDisableDirectives": true
+    },
+    "rules": {
+      "@stylistic/array-bracket-spacing": [ "error", "always" ],
+      "@stylistic/indent": [ "error", 2 ],
+      "@stylistic/indent-binary-ops": [ "off" ],
+      "@stylistic/operator-linebreak": [ "error", "after" ],
+      "@stylistic/padded-blocks": "off",
+      "@stylistic/space-before-function-paren": [ "error", "never" ],
+      "capitalized-comments": "off",
+      "complexity": "off",
+      "func-style": "off",
+      "id-length": "off",
+      "jsdoc/tag-lines": [ "error", "never", { "startLines": 1 } ],
+      "logical-assignment-operators": "off",
+      "max-depth": "off",
+      "max-lines-per-function": "off",
+      "max-lines": "off",
+      "max-params": "off",
+      "max-statements": "off",
+      "multiline-comment-style": [ "error", "separate-lines" ],
+      "no-empty-function": "off",
+      "no-implicit-coercion": "off",
+      "no-magic-numbers": "off",
+      "no-param-reassign": "off",
+      "no-plusplus": "off",
+      "no-ternary": "off",
+      "no-undef-init": "off",
+      "no-undefined": "off",
+      "no-useless-assignment": "off",
+      "object-shorthand": "off",
+      "one-var": "off",
+      "prefer-arrow-callback": "off",
+      "prefer-destructuring": "off",
+      "prefer-named-capture-group": "off",
+      "prefer-template": "off",
+      "require-unicode-regexp": "off",
+      "sort-imports": "off",
+      "sort-keys": "off",
+      "unicorn/better-regex": "off",
+      "unicorn/consistent-function-scoping": "off",
+      "unicorn/filename-case": "off",
+      "unicorn/no-array-callback-reference": "off",
+      "unicorn/no-keyword-prefix": "off",
+      "unicorn/no-new-array": "off",
+      "unicorn/no-null": "off",
+      "unicorn/no-useless-undefined": "off",
+      "unicorn/prefer-at": "off",
+      "unicorn/prefer-string-raw": "off",
+      "unicorn/prefer-string-replace-all": "off",
+      "unicorn/prefer-string-slice": "off",
+      "unicorn/prefer-switch": "off",
+      "unicorn/prevent-abbreviations": "off",
+      "unicorn/switch-case-braces": [ "error", "avoid" ],
+      "vars-on-top": "off"
+    },
+    "settings": {
+      "jsdoc": {
+        "preferredTypes": {
+          "object": "Object"
+        }
+      }
+    }
+  },
+  {
+    "files": [
+      "**/*.js",
+      "**/*.cjs"
+    ],
+    "languageOptions": {
+      "sourceType": "commonjs",
+      "globals": {
+        "module": "readonly",
+        "require": "readonly"
+      }
+    }
+  },
+  {
+    "files": [
+      "demo/default.js"
+    ],
+    "languageOptions": {
+      "globals": {
+        "alert": "readonly",
+        "document": "readonly",
+        "navigator": "readonly",
+        "window": "readonly"
+      }
+    },
+    "rules": {
+      "jsdoc/require-jsdoc": "off",
+      "n/no-unsupported-features/node-builtins": "off",
+      "no-invalid-this": "off",
+      "no-shadow": "off",
+      "no-var": "off",
+      "unicorn/prefer-module": "off",
+      "unicorn/prefer-query-selector": "off"
+    }
+  },
+  {
+    "files": [
+      "example/*.cjs"
+    ],
+    "languageOptions": {
+      "sourceType": "commonjs"
+    },
+    "rules": {
+      "n/no-missing-require": "off",
+      "no-console": "off",
+      "no-invalid-this": "off"
+    }
+  },
+  {
+    "files": [
+      "example/standalone.mjs"
+    ],
+    "rules": {
+      "no-console": "off",
+      "no-constant-condition": "off"
+    }
+  },
+  {
+    "files": [
+      "test/rules/**/*.js",
+      "test/rules/**/*.cjs"
+    ],
+    "languageOptions": {
+      "sourceType": "commonjs"
+    },
+    "rules": {
+      "unicorn/prefer-module": "off"
+    }
+  }
+];

example/Gruntfile.cjs

@@ -0,0 +1,28 @@
+// @ts-check
+
+"use strict";
+
+module.exports = function wrapper(grunt) {
+  grunt.initConfig({
+    "markdownlint": {
+      "example": {
+        "src": [ "*.md" ]
+      }
+    }
+  });
+
+  grunt.registerMultiTask("markdownlint", function task() {
+    const done = this.async();
+    import("markdownlint/async").then(({ lint }) => {
+      lint(
+        { "files": this.filesSrc },
+        function callback(err, result) {
+          const resultString = err || ((result || "").toString());
+          if (resultString) {
+            grunt.fail.warn("\n" + resultString + "\n");
+          }
+          done(!err || !resultString);
+        });
+    }).catch(done);
+  });
+};

example/Gruntfile.js

@@ -1,28 +0,0 @@
-// @ts-check
-
-"use strict";
-
-const markdownlint = require("../lib/markdownlint");
-
-module.exports = function wrapper(grunt) {
-  grunt.initConfig({
-    "markdownlint": {
-      "example": {
-        "src": [ "*.md" ]
-      }
-    }
-  });
-
-  grunt.registerMultiTask("markdownlint", function task() {
-    const done = this.async();
-    markdownlint(
-      { "files": this.filesSrc },
-      function callback(err, result) {
-        const resultString = err || ((result || "").toString());
-        if (resultString) {
-          grunt.fail.warn("\n" + resultString + "\n");
-        }
-        done(!err || !resultString);
-      });
-  });
-};

example/gulpfile.cjs

@@ -0,0 +1,24 @@
+// @ts-check
+
+"use strict";
+
+const gulp = require("gulp");
+const through2 = require("through2");
+
+// Simple task wrapper
+gulp.task("markdownlint", function task() {
+  return gulp.src("*.md", { "read": false })
+    .pipe(through2.obj(function obj(file, enc, next) {
+      import("markdownlint/async").then(({ lint }) => {
+        lint(
+          { "files": [ file.relative ] },
+          function callback(err, result) {
+            const resultString = (result || "").toString();
+            if (resultString) {
+              console.log(resultString);
+            }
+            next(err, file);
+          });
+      }).catch(next);
+    }));
+});

example/gulpfile.js

@@ -1,23 +0,0 @@
-// @ts-check
-
-"use strict";
-
-const gulp = require("gulp");
-const through2 = require("through2");
-const markdownlint = require("../lib/markdownlint");
-
-// Simple task wrapper
-gulp.task("markdownlint", function task() {
-  return gulp.src("*.md", { "read": false })
-    .pipe(through2.obj(function obj(file, enc, next) {
-      markdownlint(
-        { "files": [ file.relative ] },
-        function callback(err, result) {
-          const resultString = (result || "").toString();
-          if (resultString) {
-            console.log(resultString);
-          }
-          next(err, file);
-        });
-    }));
-});

example/standalone.js

@@ -1,31 +0,0 @@
-// @ts-check
-
-"use strict";
-
-const markdownlint = require("../lib/markdownlint");
-
-const options = {
-  "files": [ "good.md", "bad.md" ],
-  "strings": {
-    "good.string": "# good.string\n\nThis string passes all rules.\n",
-    "bad.string": "#bad.string\n\n#This string fails\tsome rules.\n"
-  }
-};
-
-// Makes a synchronous call, using result.toString for pretty formatting
-const result = markdownlint.sync(options);
-console.log(result.toString());
-
-// Makes an asynchronous call
-markdownlint(options, function callback(err, result) {
-  if (!err) {
-    console.log(result.toString());
-  }
-});
-
-// Displays the result object directly
-markdownlint(options, function callback(err, result) {
-  if (!err) {
-    console.dir(result, { "colors": true, "depth": null });
-  }
-});