markdownlint 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 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

package/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.
-
-`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.
+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][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`][micromark] parser 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
 
@@ -136,6 +145,7 @@ playground for learning and exploring.
 - **[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
 
 <!-- markdownlint-restore -->
 
@@ -177,7 +187,7 @@ rules at once.
 - **`ol`** - `MD029`, `MD030`, `MD032`
 - **`spaces`** - `MD018`, `MD019`, `MD020`, `MD021`, `MD023`
 - **`spelling`** - `MD044`
-- **`table`** - `MD055`, `MD056`
+- **`table`** - `MD055`, `MD056`, `MD058`
 - **`ul`** - `MD004`, `MD005`, `MD007`, `MD030`, `MD032`
 - **`url`** - `MD034`
 - **`whitespace`** - `MD009`, `MD010`, `MD012`, `MD027`, `MD028`, `MD030`,
@@ -353,16 +363,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:
 
@@ -515,7 +525,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),
@@ -562,9 +572,9 @@ is allowed to continue and report any violations that were found.
 
 Type: `Array` of `Array` of `Function` and plugin parameters
 
-Specifies additional [markdown-it plugins][markdown-it-plugin] to use when
+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.
+advanced scenarios. *Deprecated.*
 
 [markdown-it-plugin]: https://www.npmjs.com/search?q=keywords:markdown-it-plugin
 
@@ -574,6 +584,13 @@ Each item in the top-level `Array` should be of the form:
 [ require("markdown-it-plugin"), plugin_param_0, plugin_param_1, ... ]
 ```
 
+> 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.
+
+[custom-rules]: #custom-rules
+
 ##### options.noInlineConfig
 
 Type: `Boolean`
@@ -593,23 +610,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
 
@@ -754,6 +768,44 @@ Type: `Object`
 
 Configuration object.
 
+### 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 fixes consistently, the `applyFix`/`applyFixes` methods may be used:
+
+```javascript
+/**
+ * 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
+const { "sync": markdownlintSync, applyFixes } = require("markdownlint");
+
+function fixMarkdownlintViolations(content) {
+  const fixResults = markdownlintSync({ strings: { content } });
+  return applyFixes(content, fixResults.content);
+}
+```
+
 ## Usage
 
 Invoke `markdownlint` and use the `result` object's `toString` method:
@@ -920,14 +972,6 @@ bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be
  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.
-
 ## Browser
 
 `markdownlint` also works in the browser.
@@ -938,10 +982,11 @@ Generate normal and minified scripts with:
 npm run build-demo
 ```
 
-Then reference `markdown-it` and `markdownlint`:
+Then reference `markdownlint` and `micromark` scripts:
 
 ```html
-<script src="demo/markdown-it.min.js"></script>
+<script src="demo/micromark-browser.js"></script>
+<script src="demo/micromark-html-browser.js"></script>
 <script src="demo/markdownlint-browser.min.js"></script>
 ```
 
@@ -979,6 +1024,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
@@ -987,6 +1037,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
@@ -995,6 +1046,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/