markdownlint 0.37.4 → 0.39.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.39.0
+
+- Add MD060/table-column-style
+- Improve MD001/MD007/MD009/MD010/MD029/MD033/MD037/MD059
+- Add support for reporting violations as severity `warning`
+- Deprecate `resultVersion` and `toString` (breaking change)
+- Improve type definitions
+- Improve demo web page
+- Update dependencies
+
+## 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`

package/CONTRIBUTING.md

@@ -14,8 +14,8 @@ 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
@@ -85,7 +85,6 @@ 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

package/README.md

@@ -24,7 +24,7 @@ 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`][micromark] parser and honors the
+`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
@@ -55,6 +55,7 @@ as well as directives, footnotes, and math syntax - all implemented by
   - [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]
@@ -65,6 +66,7 @@ as well as directives, footnotes, and math syntax - all implemented by
 
 [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
@@ -146,6 +148,8 @@ playground for learning and exploring.
 - **[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
+- **[MD060](doc/md060.md)** *table-column-style* - Table column style
 
 <!-- markdownlint-restore -->
 
@@ -165,7 +169,7 @@ 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`
@@ -183,11 +187,11 @@ rules at once.
 - **`language`** - `MD040`
 - **`line_length`** - `MD013`
 - **`links`** - `MD011`, `MD034`, `MD039`, `MD042`, `MD051`, `MD052`, `MD053`,
-  `MD054`
+  `MD054`, `MD059`
 - **`ol`** - `MD029`, `MD030`, `MD032`
 - **`spaces`** - `MD018`, `MD019`, `MD020`, `MD021`, `MD023`
 - **`spelling`** - `MD044`
-- **`table`** - `MD055`, `MD056`, `MD058`
+- **`table`** - `MD055`, `MD056`, `MD058`, `MD060`
 - **`ul`** - `MD004`, `MD005`, `MD007`, `MD030`, `MD032`
 - **`url`** - `MD034`
 - **`whitespace`** - `MD009`, `MD010`, `MD012`, `MD027`, `MD028`, `MD030`,
@@ -358,22 +362,118 @@ of `files` or `strings` should be set to provide input.
 
 ##### options.config
 
-Type: `Object` mapping `String` to `Boolean | Object`
+Type: `Object` mapping `String` to `Boolean | "error" | "warning" | Object`
 
 Configures the rules to use.
 
 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 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 value `false` disables a rule. The values `true` or `"error"` enable a rule
+in its default configuration and report violations as errors. The value
+`"warning"` enables a rule in its default configuration and reports violations
+as warnings. Passing an object enables *and* customizes the rule; the properties
+`severity` (`"error" | "warning"`) and `enabled` (`false | true`) can be used in
+this context. The special `default` rule assigns the default for all rules.
+Using a tag name (e.g., `whitespace`) and a setting of `false`, `true`,
+`"error"`, or `"warning"` applies that setting to all rules with that tag. When
+no configuration object is passed or the optional `default` setting is not
+present, all rules are enabled.
+
+The following syntax disables the specified rule, tag, or `default`:
 
-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.
+```javascript
+{
+  "rule_tag_or_default": false
+}
+```
 
-Example:
+The following syntax enables the specified rule, tag, or `default` to report
+violations as errors:
+
+```javascript
+{
+  "rule_tag_or_default": true
+  // OR
+  "rule_tag_or_default": "error"
+}
+```
+
+The following syntax enables the specified rule, tag, or `default` to report
+violations as warnings:
+
+```javascript
+{
+  "rule_tag_or_default": "warning"
+}
+```
+
+The following syntax enables and configures the specified rule to report
+violations as errors:
+
+```javascript
+{
+  "rule": {
+    "severity": "error"
+  }
+  // OR
+  "rule": {
+    "rule_parameter": "value"
+  }
+  // OR
+  "rule": {
+    "severity": "error",
+    "rule_parameter": "value"
+  }
+}
+```
+
+The following syntax enables and configures the specified rule to report
+violations as warnings:
+
+```javascript
+{
+  "rule": {
+    "severity": "warning"
+  }
+  // OR
+  "rule": {
+    "severity": "warning",
+    "rule_parameter": "value"
+  }
+}
+```
+
+> Note that values `"error"` and `"warning"` and the property `severity` are not
+> supported by library versions earlier than `0.39.0`. However, the examples
+> above behave the same there, with warnings being reported as errors.
+
+The following syntax disables and configures the specified rule:
+
+```javascript
+{
+  "rule": {
+    "enabled": false,
+    "rule_parameter": "value"
+  }
+  // OR
+  "rule": {
+    "enabled": false,
+    "severity": "warning",
+    "rule_parameter": "value"
+  }
+}
+```
+
+> Note that this example behaves **differently** with library versions earlier
+> than `0.39.0` because the property `enabled` is not supported: it **enables**
+> the rule instead of **disabling** it. As such, this syntax is discouraged when
+> interoperability is important.
+
+To evaluate a configuration object, the `default` setting is applied first, then
+keys are processed in order from top to bottom. If multiple values apply to a
+rule (because of tag names or duplication), later values override earlier ones.
+Keys (including rule names, aliases, tags, or `default`) are not case-sensitive.
+
+Example using `default`, rule names, and tag names together:
 
 ```json
 {
@@ -418,9 +518,9 @@ object.
 See [ValidatingConfiguration.md](schema/ValidatingConfiguration.md) for ways to
 use the JSON Schema to validate configuration.
 
-For more advanced scenarios, styles can reference and extend other styles.
-The `readConfig` and `readConfigSync` functions can be used to read such
-styles.
+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:
 
@@ -567,28 +667,43 @@ 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. *Deprecated.*
+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.
+
+For compatibility with previous versions of `markdownlint`, this function should
+be similar to:
+
+```javascript
+import markdownIt from "markdown-it";
+const markdownItFactory = () => markdownIt({ "html": true });
+```
 
-Each item in the top-level `Array` should be of the form:
+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
-[ require("markdown-it-plugin"), plugin_param_0, plugin_param_1, ... ]
+const markdownItFactory = () => import("markdown-it").then((module) => module.default({ "html": true }));
 ```
 
-> Note that `markdown-it` plugins are only called when the `markdown-it` parser
-> is invoked. None of the built-in rules use the `markdown-it` parser, so
-> `markdown-it` plugins will only be invoked when one or more
-> [custom rules][custom-rules] that use the `markdown-it` parser are present.
+> 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
 
@@ -601,28 +716,15 @@ By default, properly-formatted inline comments can be used to create exceptions
 for parts of a document. Setting `noInlineConfig` to `true` ignores all such
 comments.
 
-##### options.resultVersion
-
-Type: `Number`
-
-Specifies which version of the `result` object to return (see the "Usage"
-section below for examples).
+##### ~~options.resultVersion~~
 
-Passing a `resultVersion` of `0` corresponds to the original, simple format
-where each error is identified by rule name and line number. *Deprecated*
+This property is *deprecated* and should be removed. The default format of the
+`result` object remains the same as setting `resultVersion` to `3`. For
+continued access to other (previously *deprecated*) formats:
 
-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. *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. *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 behavior.
+```javascript
+import { convertToResultVersion0, convertToResultVersion1, convertToResultVersion2 } from "markdownlint/helpers";
+```
 
 ##### options.strings
 
@@ -653,16 +755,16 @@ Standard completion callback.
 
 Type: `Object`
 
-Call `result.toString()` for convenience or see below for an example of the
-structure of the `result` object. Passing the value `true` to `toString()`
-uses rule aliases (ex: `no-hard-tabs`) instead of names (ex: `MD010`).
+Map of input file names and string identifiers to issues within.
+
+See the [Usage section](#usage) for an example of the structure of this object.
 
 ### 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
@@ -831,7 +933,7 @@ console.log(getVersion());
 
 ## Usage
 
-Invoke `lint` and use the `result` object's `toString` method:
+Invoke `lint` as an asynchronous call:
 
 ```javascript
 import { lint as lintAsync } from "markdownlint/async";
@@ -846,34 +948,21 @@ const options = {
 
 lintAsync(options, function callback(error, results) {
   if (!error && results) {
-    console.log(results.toString());
+    console.dir(results, { "colors": true, "depth": null });
   }
 });
 ```
 
-Output:
-
-```text
-bad.string: 3: MD010/no-hard-tabs Hard tabs [Column: 19]
-bad.string: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.string"]
-bad.string: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This string fails        some rules."]
-bad.string: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "#bad.string"]
-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"]
-```
-
 Or as a synchronous call:
 
 ```javascript
 import { lint as lintSync } from "markdownlint/sync";
 
 const results = lintSync(options);
-console.log(results.toString());
+console.dir(results, { "colors": true, "depth": null });
 ```
 
-To examine the `result` object directly via a `Promise`-based call:
+Or as a `Promise`-based call:
 
 ```javascript
 import { lint as lintPromise } from "markdownlint/promise";
@@ -882,7 +971,7 @@ const results = await lintPromise(options);
 console.dir(results, { "colors": true, "depth": null });
 ```
 
-Output:
+All of which return an object like:
 
 ```json
 {
@@ -894,38 +983,40 @@ Output:
       "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md010.md",
       "errorDetail": "Column: 17",
       "errorContext": null,
-      "errorRange": [ 17, 1 ] },
+      "errorRange": [ 17, 1 ],
+      "fixInfo": { "editColumn": 17, "deleteCount": 1, "insertText": " " },
+      "severity": "error" },
     { "lineNumber": 1,
       "ruleNames": [ "MD018", "no-missing-space-atx" ],
       "ruleDescription": "No space after hash on atx style heading",
       "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md018.md",
       "errorDetail": null,
       "errorContext": "#bad.md",
-      "errorRange": [ 1, 2 ] },
+      "errorRange": [ 1, 2 ],
+      "fixInfo": { "editColumn": 2, "insertText": " " },
+      "severity": "error" },
     { "lineNumber": 3,
       "ruleNames": [ "MD018", "no-missing-space-atx" ],
       "ruleDescription": "No space after hash on atx style heading",
       "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md018.md",
       "errorDetail": null,
       "errorContext": "#This file fails\tsome rules.",
-      "errorRange": [ 1, 2 ] },
+      "errorRange": [ 1, 2 ],
+      "fixInfo": { "editColumn": 2, "insertText": " " },
+      "severity": "error" },
     { "lineNumber": 1,
       "ruleNames": [ "MD041", "first-line-heading", "first-line-h1" ],
       "ruleDescription": "First line in a file should be a top-level heading",
       "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md041.md",
       "errorDetail": null,
       "errorContext": "#bad.md",
-      "errorRange": null }
+      "errorRange": null,
+      "fixInfo": null,
+      "severity": "error" }
   ]
 }
 ```
 
-Integration with the [gulp](https://gulpjs.com/) build system is
-straightforward: [`gulpfile.cjs`](example/gulpfile.cjs).
-
-Integration with the [Grunt](https://gruntjs.com/) build system is similar:
-[`Gruntfile.cjs`](example/Gruntfile.cjs).
-
 ## Browser
 
 `markdownlint` also works in the browser.
@@ -951,7 +1042,7 @@ const options = {
   }
 };
 
-const results = globalThis.markdownlint.lintSync(options).toString();
+const results = globalThis.markdownlint.lintSync(options);
 ```
 
 ## Examples
@@ -962,7 +1053,6 @@ following projects or one of the tools in the [Related section](#related):
 - [.NET Documentation][dot-net-doc] ([Search repository][dot-net-doc-search])
 - [ally.js][ally-js] ([Search repository][ally-js-search])
 - [Apache Airflow][airflow] ([Search repository][airflow-search])
-- [Boostnote][boostnote] ([Search repository][boostnote-search])
 - [CodiMD][codimd] ([Search repository][codimd-search])
 - [Electron][electron] ([Search repository][electron-search])
 - [ESLint][eslint] ([Search repository][eslint-search])
@@ -986,8 +1076,6 @@ For more advanced integration scenarios:
 [ally-js-search]: https://github.com/medialize/ally.js/search?q=markdownlint
 [airflow]: https://airflow.apache.org
 [airflow-search]: https://github.com/apache/airflow/search?q=markdownlint
-[boostnote]: https://boostnote.io/
-[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