markdownlint 0.24.0 → 0.26.0

package/CONTRIBUTING.md

@@ -23,17 +23,20 @@ Try to break the new code now, or else it will get broken later.
 
 Run tests before sending a pull request via `npm test` in the [usual manner](https://docs.npmjs.com/misc/scripts).
 Tests should all pass on all platforms.
-The test runner is [tape](https://www.npmjs.com/package/tape) and test cases are located in `test/markdownlint-test*.js`.
+The test runner is [AVA](https://github.com/avajs/ava) and test cases are located in `test/markdownlint-test*.js`.
 When running tests, `test/*.md` files are enumerated, linted, and fail if any violations are missing a corresponding `{MD###}` marker in the test file.
 For example, the line `### Heading {MD001}` is expected to trigger the rule `MD001`.
 For cases where the marker text can not be present on the same line, the syntax `{MD###:#}` can be used to include a line number.
 If `some-test.md` needs custom configuration, a `some-test.json` is used to provide a custom `options.config` for that scenario.
+Tests run by `markdownlint-test-scenarios.js` use [AVA's snapshot feature](https://github.com/avajs/ava/blob/main/docs/04-snapshot-testing.md).
+To update snapshots (for example, after modifying a test file), run `npm run update-snapshots` and include the updated files with the pull request.
 
 Lint before sending a pull request by running `npm run lint`.
 There should be no issues.
 
 Run a full continuous integration pass before sending a pull request via `npm run ci`.
-Code coverage should remain at 100%.
+Code coverage should always be 100%.
+As part of a continuous integration run, generated files may get updated and fail the run - commit them to the repository and rerun continuous integration.
 
 Pull requests should contain a single commit.
 If necessary, squash multiple commits before creating the pull request and when making changes.
@@ -43,9 +46,18 @@ Open pull requests against the `next` branch.
 That's where the latest changes are staged for the next release.
 Include the text "(fixes #??)" at the end of the commit message so the pull request will be associated with the relevant issue.
 End commit messages with a period (`.`).
-Do not include `package-lock.json` in the pull request.
 Once accepted, the tag `fixed in next` will be added to the issue.
 When the commit is merged to the main branch during the release process, the issue will be closed automatically.
 (See [Closing issues using keywords](https://help.github.com/articles/closing-issues-using-keywords/) for details.)
 
+Please refrain from using slang or meaningless placeholder words.
+Sample content can be "text", "code", "heading", or the like.
+Sample URLs should use [example.com](https://en.wikipedia.org/wiki/Example.com) which is safe for this purpose.
+Profanity is not allowed.
+
+In order to maintain the permissive MIT license this project uses, all contributions must be your own and released under that license.
+Code you add should be an original work and should not be copied from elsewhere.
+Taking code from a different project, Stack Overflow, or the like is not allowed.
+The use of tools such as GitHub Copilot that generate code from other projects is not allowed.
+
 Thank you!

package/LICENSE

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

package/README.md

@@ -33,17 +33,19 @@ and test cases came directly from that project.
 ### Related
 
 * CLI
-  * [markdownlint-cli command-line interface for Node.js](https://github.com/igorshubovych/markdownlint-cli)
-  * [markdownlint-cli2 command-line interface for Node.js](https://github.com/DavidAnson/markdownlint-cli2)
+  * [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli)
+    command-line interface for Node.js ([works with pre-commit](https://github.com/igorshubovych/markdownlint-cli#use-with-pre-commit))
+  * [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2)
+    command-line interface for Node.js ([works with pre-commit](https://github.com/DavidAnson/markdownlint-cli2#pre-commit))
 * GitHub
   * [GitHub Super-Linter Action](https://github.com/github/super-linter)
   * [GitHub Actions problem matcher for markdownlint-cli](https://github.com/xt0rted/markdownlint-problem-matcher)
 * Editor
   * [vscode-markdownlint extension for VS Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
   * [Sublime Text markdownlint for Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint)
-  * [linter-node-markdownlint extension for Atom](https://atom.io/packages/linter-node-markdownlint)
   * [coc-markdownlint extension for Vim/Neovim](https://github.com/fannheyward/coc-markdownlint)
 * Tooling
+  * [eslint-plugin-markdownlint for the ESLint analyzer](https://github.com/paweldrozd/eslint-plugin-markdownlint)
   * [grunt-markdownlint for the Grunt task runner](https://github.com/sagiegurari/grunt-markdownlint)
   * [Cake.Markdownlint addin for Cake build automation system](https://github.com/cake-contrib/Cake.Markdownlint)
 * Ruby
@@ -102,6 +104,11 @@ playground for learning and exploring.
 * **[MD046](doc/Rules.md#md046)** *code-block-style* - Code block style
 * **[MD047](doc/Rules.md#md047)** *single-trailing-newline* - Files should end with a single newline character
 * **[MD048](doc/Rules.md#md048)** *code-fence-style* - Code fence style
+* **[MD049](doc/Rules.md#md049)** *emphasis-style* - Emphasis style should be consistent
+* **[MD050](doc/Rules.md#md050)** *strong-style* - Strong style should be consistent
+* **[MD051](doc/Rules.md#md051)** *link-fragments* - Link fragments should be valid
+* **[MD052](doc/Rules.md#md052)** *reference-links-images* - Reference links and images should use a label that is defined
+* **[MD053](doc/Rules.md#md053)** *link-image-reference-definitions* - Link and image reference definitions should be needed
 
 <!-- markdownlint-restore -->
 
@@ -125,7 +132,7 @@ rules at once.
 * **blockquote** - MD027, MD028
 * **bullet** - MD004, MD005, MD006, MD007, MD032
 * **code** - MD014, MD031, MD038, MD040, MD046, MD048
-* **emphasis** - MD036, MD037
+* **emphasis** - MD036, MD037, MD049, MD050
 * **hard_tab** - MD010
 * **headers** - MD001, MD002, MD003, MD018, MD019, MD020, MD021, MD022,
   MD023, MD024, MD025, MD026, MD036, MD041, MD043
@@ -133,11 +140,11 @@ rules at once.
   MD023, MD024, MD025, MD026, MD036, MD041, MD043
 * **hr** - MD035
 * **html** - MD033
-* **images** - MD045
+* **images** - MD045, MD052, MD053
 * **indentation** - MD005, MD006, MD007, MD027
 * **language** - MD040
 * **line_length** - MD013
-* **links** - MD011, MD034, MD039, MD042
+* **links** - MD011, MD034, MD039, MD042, MD051, MD052, MD053
 * **ol** - MD029, MD030, MD032
 * **spaces** - MD018, MD019, MD020, MD021, MD023
 * **spelling** - MD044
@@ -163,10 +170,14 @@ appear in the final markup):
 
 * Disable all rules: `<!-- markdownlint-disable -->`
 * Enable all rules: `<!-- markdownlint-enable -->`
-* Disable all rules for the next line only: `<!-- markdownlint-disable-next-line -->`
+* Disable all rules for the current line: `<!-- markdownlint-disable-line -->`
+* Disable all rules for the next line: `<!-- markdownlint-disable-next-line -->`
 * Disable one or more rules by name: `<!-- markdownlint-disable MD001 MD005 -->`
 * Enable one or more rules by name: `<!-- markdownlint-enable MD001 MD005 -->`
-* Disable one or more rules by name for the next line only: `<!-- markdownlint-disable-next-line MD001 MD005 -->`
+* Disable one or more rules by name for the current line:
+  `<!-- markdownlint-disable-line MD001 MD005 -->`
+* Disable one or more rules by name for the next line:
+  `<!-- markdownlint-disable-next-line MD001 MD005 -->`
 * Capture the current rule configuration: `<!-- markdownlint-capture -->`
 * Restore the captured rule configuration: `<!-- markdownlint-restore -->`
 
@@ -179,6 +190,12 @@ deliberate space * in * emphasis
 
 Or:
 
+```markdown
+deliberate space * in * emphasis <!-- markdownlint-disable-line no-space-in-emphasis -->
+```
+
+Or:
+
 ```markdown
 <!-- markdownlint-disable no-space-in-emphasis -->
 deliberate space * in * emphasis
@@ -229,7 +246,7 @@ more rules for a file, the following more advanced syntax is supported:
 For example:
 
 ```markdown
-<!-- markdownlint-configure-file { "MD013": { "line_length": 70 } } -->
+<!-- markdownlint-configure-file { "MD013": { "code_blocks": false } } -->
 ```
 
 or
@@ -245,8 +262,11 @@ or
 -->
 ```
 
-These changes apply to the entire file regardless of where the comment
-is located. Multiple such comments (if present) are applied top-to-bottom.
+These changes apply to the entire file regardless of where the comment is
+located. Multiple such comments (if present) are applied top-to-bottom. By
+default, content of `markdownlint-configure-file` is assumed to be JSON, but
+[`options.configParsers`](#optionsconfigparsers) can be used to support
+alternate formats.
 
 ## API
 
@@ -297,60 +317,6 @@ Type: `Object`
 Configures the function. All properties are optional, but at least one
 of `files` or `strings` should be set to provide input.
 
-##### options.customRules
-
-Type: `Array` of `Object`
-
-List of custom rules to include with the default rule set for linting.
-
-Each array element should define a rule. Rules are typically exported
-by another package, but can be defined locally. Custom rules are
-identified by the
-[keyword `markdownlint-rule` on npm](https://www.npmjs.com/search?q=keywords:markdownlint-rule).
-
-Example:
-
-```js
-const extraRules = require("extraRules");
-const options = {
-  "customRules": [ extraRules.one, extraRules.two ]
-};
-```
-
-See [CustomRules.md](doc/CustomRules.md) for details about authoring
-custom rules.
-
-##### options.files
-
-Type: `Array` of `String`
-
-List of files to lint.
-
-Each array element should be a single file (via relative or absolute path);
-[globbing](https://en.wikipedia.org/wiki/Glob_%28programming%29) is the
-caller's responsibility.
-
-Example: `[ "one.md", "dir/two.md" ]`
-
-##### options.strings
-
-Type: `Object` mapping `String` to `String`
-
-Map of identifiers to strings for linting.
-
-When Markdown content is not available as files, it can be passed as
-strings. The keys of the `strings` object are used to identify each
-input value in the `result` summary.
-
-Example:
-
-```json
-{
-  "readme": "# README\n...",
-  "changelog": "# CHANGELOG\n..."
-}
-```
-
 ##### options.config
 
 Type: `Object` mapping `String` to `Boolean | Object`
@@ -442,6 +408,59 @@ const options = {
 };
 ```
 
+##### options.configParsers
+
+Type: *Optional* `Array` of `Function` taking (`String`) and returning `Object`
+
+Array of functions to parse the content of `markdownlint-configure-file` blocks.
+
+As shown in the [Configuration](#configuration) section, inline comments can be
+used to customize the [configuration object](#optionsconfig) for a document. By
+default, the `JSON.parse` built-in is used, but custom parsers can be specified.
+Content is passed to each parser function until one returns a value (vs. throwing
+an exception). As such, strict parsers should come before flexible ones.
+
+For example:
+
+```js
+[ JSON.parse, require("toml").parse, require("js-yaml").load ]
+```
+
+##### options.customRules
+
+Type: `Array` of `Object`
+
+List of custom rules to include with the default rule set for linting.
+
+Each array element should define a rule. Rules are typically exported
+by another package, but can be defined locally. Custom rules are
+identified by the
+[keyword `markdownlint-rule` on npm](https://www.npmjs.com/search?q=keywords:markdownlint-rule).
+
+Example:
+
+```js
+const extraRules = require("extraRules");
+const options = {
+  "customRules": [ extraRules.one, extraRules.two ]
+};
+```
+
+See [CustomRules.md](doc/CustomRules.md) for details about authoring
+custom rules.
+
+##### options.files
+
+Type: `Array` of `String`
+
+List of files to lint.
+
+Each array element should be a single file (via relative or absolute path);
+[globbing](https://en.wikipedia.org/wiki/Glob_%28programming%29) is the
+caller's responsibility.
+
+Example: `[ "one.md", "dir/two.md" ]`
+
 ##### options.frontMatter
 
 Type: `RegExp`
@@ -472,6 +491,16 @@ title: Title
 
 Note: Matches must occur at the start of the file.
 
+##### options.fs
+
+Type: `Object` implementing the [file system API](https://nodejs.org/api/fs.html)
+
+In advanced scenarios, it may be desirable to bypass the default file system API.
+If a custom file system implementation is provided, `markdownlint` will use that
+instead of invoking `require("fs")`.
+
+Note: The only methods called are `readFile` and `readFileSync`.
+
 ##### options.handleRuleFailures
 
 Type: `Boolean`
@@ -487,6 +516,20 @@ 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
+
+Type: `Array` of `Array` of `Function` and plugin parameters
+
+Specifies additional [markdown-it plugins](https://www.npmjs.com/search?q=keywords:markdown-it-plugin)
+to use when parsing input. Plugins can be used to support additional syntax and
+features for advanced scenarios.
+
+Each item in the top-level `Array` should be of the form:
+
+```js
+[ require("markdown-it-plugin"), plugin_param_0, plugin_param_1, ... ]
+```
+
 ##### options.noInlineConfig
 
 Type: `Boolean`
@@ -514,36 +557,31 @@ as any additional detail or context that is available. *This is 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 the default.*
+additional detail or context that is available. *This is 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).
-
-##### options.markdownItPlugins
-
-Type: `Array` of `Array` of `Function` and plugin parameters
-
-Specifies additional [markdown-it plugins](https://www.npmjs.com/search?q=keywords:markdown-it-plugin)
-to use when parsing input. Plugins can be used to support additional syntax and
-features for advanced scenarios.
+the first error for each rule). *This is the default.*
 
-Each item in the top-level `Array` should be of the form:
+##### options.strings
 
-```js
-[ require("markdown-it-plugin"), plugin_param_0, plugin_param_1, ... ]
-```
+Type: `Object` mapping `String` to `String`
 
-##### options.fs
+Map of identifiers to strings for linting.
 
-Type: `Object` implementing the [file system API](https://nodejs.org/api/fs.html)
+When Markdown content is not available as files, it can be passed as
+strings. The keys of the `strings` object are used to identify each
+input value in the `result` summary.
 
-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")`.
+Example:
 
-Note: The only methods called are `readFile` and `readFileSync`.
+```json
+{
+  "readme": "# README\n...",
+  "changelog": "# CHANGELOG\n..."
+}
+```
 
 #### callback
 
@@ -623,7 +661,8 @@ The `file` is resolved relative to the current working directory. If an `extends
 key is present once read, its value will be resolved as a path relative to `file`
 and loaded recursively. Settings from a file referenced by `extends` are applied
 first, then those of `file` are applied on top (overriding any of the same keys
-appearing in the referenced file).
+appearing in the referenced file). If either the `file` or `extends` path begins
+with the `~` directory, it will act as a placeholder for the home directory.
 
 #### parsers
 
@@ -859,7 +898,7 @@ const results = window.markdownlint.sync(options).toString();
 ## Examples
 
 For ideas how to integrate `markdownlint` into your workflow, refer to the
-following projects or one of the tools in the [Related section](#Related):
+following projects or one of the tools in the [Related section](#related):
 
 * [.NET Documentation](https://docs.microsoft.com/en-us/dotnet/) ([Search repository](https://github.com/dotnet/docs/search?q=markdownlint))
 * [ally.js](https://allyjs.io/) ([Search repository](https://github.com/medialize/ally.js/search?q=markdownlint))
@@ -870,6 +909,7 @@ following projects or one of the tools in the [Related section](#Related):
 * [MDN Web Docs](https://developer.mozilla.org/) ([Search repository](https://github.com/mdn/content/search?q=markdownlint))
 * [MkDocs](https://www.mkdocs.org/) ([Search repository](https://github.com/mkdocs/mkdocs/search?q=markdownlint))
 * [Mocha](https://mochajs.org/) ([Search repository](https://github.com/mochajs/mocha/search?q=markdownlint))
+* [Pi-hole documentation](https://docs.pi-hole.net) ([Search repository](https://github.com/pi-hole/docs/search?q=markdownlint))
 * [Reactable](https://glittershark.github.io/reactable/) ([Search repository](https://github.com/glittershark/reactable/search?q=markdownlint))
 * [Sinon.JS](https://sinonjs.org/) ([Search repository](https://github.com/sinonjs/sinon/search?q=markdownlint))
 * [TestCafe](https://devexpress.github.io/testcafe/) ([Search repository](https://github.com/DevExpress/testcafe/search?q=markdownlint))
@@ -968,6 +1008,17 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
 * 0.24.0 - Remove support for end-of-life Node version 10, add support for custom file system
            module, improve MD010/MD011/MD037/MD043/MD044, improve TypeScript declaration file
            and JSON schema, update dependencies.
+* 0.25.0 - Add MD049/MD050 for consistent emphasis/strong style (both auto-fixable), improve
+           MD007/MD010/MD032/MD033/MD035/MD037/MD039, support asynchronous custom rules,
+           improve performance, improve CI process, reduce dependencies, update dependencies.
+  * 0.25.1 - Update dependencies for CVE-2022-21670.
+* 0.26.0 - Add MD051/MD052/MD053 for validating link fragments & reference links/images &
+           link/image reference definitions (MD053 is auto-fixable), improve
+           MD010/MD031/MD035/MD039/MD042/MD044/MD049/MD050, add `markdownlint-disable-line`
+           inline comment, support `~` paths in `readConfig/Sync`, add `configParsers` option,
+           remove support for end-of-life Node version 12, default `resultVersion` to 3, update
+           browser script to use ES2015, simplify JSON schema, address remaining CodeQL issues,
+           improve performance, update dependencies.
 
 [npm-image]: https://img.shields.io/npm/v/markdownlint.svg
 [npm-url]: https://www.npmjs.com/package/markdownlint