markdownlint 0.25.1 → 0.26.0

package/CONTRIBUTING.md

@@ -28,6 +28,8 @@ When running tests, `test/*.md` files are enumerated, linted, and fail if any vi
 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.

package/README.md

@@ -43,9 +43,9 @@ and test cases came directly from that project.
 * 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
@@ -106,6 +106,9 @@ playground for learning and exploring.
 * **[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 -->
 
@@ -137,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
@@ -167,11 +170,13 @@ 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:
+* 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 -->`
@@ -185,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
@@ -251,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
 
@@ -303,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`
@@ -448,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`
@@ -478,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`
@@ -493,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`
@@ -520,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
 
@@ -629,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
 
@@ -979,6 +1012,13 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
            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