markdownlint 0.21.0 → 0.23.1

package/CONTRIBUTING.md

@@ -43,6 +43,7 @@ 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.)

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2020 David Anson
+Copyright (c) 2015-2021 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

@@ -14,12 +14,13 @@ 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](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)
@@ -39,7 +40,7 @@ and test cases came directly from that project.
   * [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/DavidAnson.vscode-markdownlint)
+  * [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)
@@ -56,8 +57,10 @@ playground for learning and exploring.
 
 ## Rules / Aliases
 
+<!-- markdownlint-disable line-length -->
+
 * **[MD001](doc/Rules.md#md001)** *heading-increment/header-increment* - Heading levels should only increment by one level at a time
-* ~~**[MD002](doc/Rules.md#md002)** *first-heading-h1/first-header-h1* - First heading should be a top level heading~~
+* ~~**[MD002](doc/Rules.md#md002)** *first-heading-h1/first-header-h1* - First heading should be a top-level heading~~
 * **[MD003](doc/Rules.md#md003)** *heading-style/header-style* - Heading style
 * **[MD004](doc/Rules.md#md004)** *ul-style* - Unordered list style
 * **[MD005](doc/Rules.md#md005)** *list-indent* - Inconsistent indentation for list items at the same level
@@ -76,7 +79,7 @@ playground for learning and exploring.
 * **[MD022](doc/Rules.md#md022)** *blanks-around-headings/blanks-around-headers* - Headings should be surrounded by blank lines
 * **[MD023](doc/Rules.md#md023)** *heading-start-left/header-start-left* - Headings must start at the beginning of the line
 * **[MD024](doc/Rules.md#md024)** *no-duplicate-heading/no-duplicate-header* - Multiple headings with the same content
-* **[MD025](doc/Rules.md#md025)** *single-title/single-h1* - Multiple top level headings in the same document
+* **[MD025](doc/Rules.md#md025)** *single-title/single-h1* - Multiple top-level headings in the same document
 * **[MD026](doc/Rules.md#md026)** *no-trailing-punctuation* - Trailing punctuation in heading
 * **[MD027](doc/Rules.md#md027)** *no-multiple-space-blockquote* - Multiple spaces after blockquote symbol
 * **[MD028](doc/Rules.md#md028)** *no-blanks-blockquote* - Blank line inside blockquote
@@ -92,7 +95,7 @@ playground for learning and exploring.
 * **[MD038](doc/Rules.md#md038)** *no-space-in-code* - Spaces inside code span elements
 * **[MD039](doc/Rules.md#md039)** *no-space-in-links* - Spaces inside link text
 * **[MD040](doc/Rules.md#md040)** *fenced-code-language* - Fenced code blocks should have a language specified
-* **[MD041](doc/Rules.md#md041)** *first-line-heading/first-line-h1* - First line in file should be a top level heading
+* **[MD041](doc/Rules.md#md041)** *first-line-heading/first-line-h1* - First line in a file should be a top-level heading
 * **[MD042](doc/Rules.md#md042)** *no-empty-links* - No empty links
 * **[MD043](doc/Rules.md#md043)** *required-headings/required-headers* - Required heading structure
 * **[MD044](doc/Rules.md#md044)** *proper-names* - Proper names should have the correct capitalization
@@ -101,17 +104,20 @@ playground for learning and exploring.
 * **[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
 
+<!-- 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`).
+> 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.
 
 ## Tags
 
-Tags group related rules and can be used to enable/disable multiple rules at once.
+Tags group related rules and can be used to enable/disable multiple
+rules at once.
 
 * **accessibility** - MD045
 * **atx** - MD018, MD019
@@ -122,10 +128,10 @@ Tags group related rules and can be used to enable/disable multiple rules at onc
 * **code** - MD014, MD031, MD038, MD040, MD046, MD048
 * **emphasis** - MD036, MD037
 * **hard_tab** - MD010
-* **headers** - MD001, MD002, 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
+* **headers** - MD001, MD002, 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
@@ -138,30 +144,42 @@ Tags group related rules and can be used to enable/disable multiple rules at onc
 * **spelling** - MD044
 * **ul** - MD004, MD005, MD006, MD007, MD030, MD032
 * **url** - MD034
-* **whitespace** - MD009, MD010, MD012, MD027, MD028, MD030, MD037, MD038, MD039
+* **whitespace** - MD009, MD010, MD012, MD027, MD028, MD030, MD037,
+  MD038, MD039
 
 ## Configuration
 
-Text passed to `markdownlint` is parsed as Markdown, analyzed, and any issues reported.
-Two kinds of text are ignored:
+Text passed to `markdownlint` is parsed as Markdown, analyzed, and any
+issues reported. Two kinds of text are ignored:
 
 * [HTML comments](https://www.w3.org/TR/html5/syntax.html#comments)
-* [Front matter](https://jekyllrb.com/docs/frontmatter/) (see `options.frontMatter` below)
+* [Front matter](https://jekyllrb.com/docs/frontmatter/) (see
+  `options.frontMatter` below)
 
-Rules can be enabled, disabled, and configured via `options.config` (described
-below) to define the expected behavior for a set of inputs. To enable or disable
-rules at a particular location within a file, add one of these markers to the
-appropriate place (HTML comments don't appear in the final markup):
+Rules can be enabled, disabled, and configured via `options.config`
+(described below) to define the expected behavior for a set of inputs.
+To enable or disable rules at a particular location within a file, add
+one of these markers to the appropriate place (HTML comments don't
+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 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 -->`
 * Capture the current rule configuration: `<!-- markdownlint-capture -->`
 * Restore the captured rule configuration: `<!-- markdownlint-restore -->`
 
 For example:
 
+```markdown
+<!-- markdownlint-disable-next-line no-space-in-emphasis -->
+deliberate space * in * emphasis
+```
+
+Or:
+
 ```markdown
 <!-- markdownlint-disable no-space-in-emphasis -->
 deliberate space * in * emphasis
@@ -177,9 +195,9 @@ any violations you want
 <!-- markdownlint-restore -->
 ```
 
-The initial configuration is captured by default (as if every document began
-with `<!-- markdownlint-capture -->`), so the pattern above can be expressed
-more simply:
+The initial configuration is captured by default (as if every document
+began with `<!-- markdownlint-capture -->`), so the pattern above can
+be expressed more simply:
 
 ```markdown
 <!-- markdownlint-disable -->
@@ -204,8 +222,8 @@ the following syntax is supported:
 
 This can be used to "hide" `markdownlint` comments at the bottom of a file.
 
-In cases where it is desirable to change the configuration of one or more rules
-for a file, the following more advanced syntax is supported:
+In cases where it is desirable to change the configuration of one or
+more rules for a file, the following more advanced syntax is supported:
 
 * Configure: `<!-- markdownlint-configure-file { options.config JSON } -->`
 
@@ -228,8 +246,8 @@ 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.
 
 ## API
 
@@ -285,8 +303,9 @@ 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
+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:
@@ -298,7 +317,8 @@ const options = {
 };
 ```
 
-See [CustomRules.md](doc/CustomRules.md) for details about authoring custom rules.
+See [CustomRules.md](doc/CustomRules.md) for details about authoring
+custom rules.
 
 ##### options.files
 
@@ -307,8 +327,8 @@ 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.
+[globbing](https://en.wikipedia.org/wiki/Glob_%28programming%29) is the
+caller's responsibility.
 
 Example: `[ "one.md", "dir/two.md" ]`
 
@@ -318,9 +338,9 @@ 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.
+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:
 
@@ -340,12 +360,13 @@ Configures the rules to use.
 Object keys are rule names or aliases and 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.
+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.
 
-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:
 
@@ -359,8 +380,12 @@ Example:
 }
 ```
 
-Sets of rules (known as a "style") can be stored separately and loaded as
-[JSON](https://en.wikipedia.org/wiki/JSON).
+See [.markdownlint.jsonc](schema/.markdownlint.jsonc) and/or
+[.markdownlint.yaml](schema/.markdownlint.yaml) for an example
+configuration object with all properties set to the default value.
+
+Sets of rules (known as a "style") can be stored separately and loaded
+as [JSON](https://en.wikipedia.org/wiki/JSON).
 
 Example:
 
@@ -374,10 +399,12 @@ const options = {
 See the [style](style) directory for more samples.
 
 See [markdownlint-config-schema.json](schema/markdownlint-config-schema.json)
-for the [JSON Schema](https://json-schema.org/) of the `options.config` object.
+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.
+For more advanced scenarios, styles can reference and extend other styles.
+The `readConfig` and `readConfigSync` functions can be used to read such
+styles.
 
 For example, assuming a `base.json` configuration file:
 
@@ -419,21 +446,22 @@ const options = {
 
 Type: `RegExp`
 
-Matches any [front matter](https://jekyllrb.com/docs/frontmatter/) found at the
-beginning of a file.
+Matches any [front matter](https://jekyllrb.com/docs/frontmatter/)
+found at the beginning of a file.
 
-Some Markdown content begins with metadata; the default `RegExp` for this option
-ignores common forms of "front matter". To match differently, specify a custom
-`RegExp` or use the value `null` to disable the feature.
+Some Markdown content begins with metadata; the default `RegExp` for
+this option ignores common forms of "front matter". To match differently,
+specify a custom `RegExp` or use the value `null` to disable the feature.
 
 The default value:
 
 ```js
-/((^---\s*$[^]*?^---\s*$)|(^\+\+\+\s*$[^]*?^(\+\+\+|\.\.\.)\s*$))(\r\n|\r|\n|$)/m
+/((^---\s*$[^]*?^---\s*$)|(^\+\+\+\s*$[^]*?^(\+\+\+|\.\.\.)\s*$)|(^\{\s*$[^]*?^\}\s*$))(\r\n|\r|\n|$)/m
 ```
 
-Ignores [YAML](https://en.wikipedia.org/wiki/YAML) and
-[TOML](https://en.wikipedia.org/wiki/TOML) such as:
+Ignores [YAML](https://en.wikipedia.org/wiki/YAML),
+[TOML](https://en.wikipedia.org/wiki/TOML), and
+[JSON](https://en.wikipedia.org/wiki/JSON) front matter such as:
 
 ```text
 ---
@@ -448,16 +476,16 @@ Note: Matches must occur at the start of the file.
 
 Type: `Boolean`
 
-Catches exceptions thrown during rule processing and reports the problem as a
-rule violation.
+Catches exceptions thrown during rule processing and reports the problem
+as a rule violation.
 
 By default, exceptions thrown by rules (or the library itself) are unhandled
 and bubble up the stack to the caller in the conventional manner. By setting
-`handleRuleFailures` to `true`, exceptions thrown by failing rules will be
-handled by the library and the exception message logged as a rule violation.
+`handleRuleFailures` to `true`, exceptions thrown by failing rules will
+be handled by the library and the exception message logged as a rule violation.
 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.
+unexpected syntax and fail. By enabling this option, the linting process
+is allowed to continue and report any violations that were found.
 
 ##### options.noInlineConfig
 
@@ -597,7 +625,7 @@ should come before flexible parsers.
 For example:
 
 ```js
-[ JSON.parse, require("toml").parse, require("js-yaml").safeLoad ]
+[ JSON.parse, require("toml").parse, require("js-yaml").load ]
 ```
 
 #### callback
@@ -640,11 +668,11 @@ Output:
 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 file should be a top level heading [Context: "#bad.string"]
+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 file should be a top level heading [Context: "#bad.md"]
+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:
@@ -693,7 +721,7 @@ Output:
       "errorRange": [ 1, 2 ] },
     { "lineNumber": 1,
       "ruleNames": [ "MD041", "first-line-heading", "first-line-h1" ],
-      "ruleDescription": "First line in file should be a top level heading",
+      "ruleDescription": "First line in a file should be a top-level heading",
       "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md041",
       "errorDetail": null,
       "errorContext": "#bad.md",
@@ -732,7 +760,7 @@ Output:
 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 file should be a top level heading [Context: "#bad.md"]
+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
 ```
 
@@ -773,7 +801,7 @@ 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 file should be a top level heading [Context: "#bad.md"]
+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.
 ```
 
@@ -905,6 +933,14 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
            update TypeScript declaration file, hide `toString` on `LintResults`, add ability
            to fix in browser demo, allow custom rules in `.markdownlint.json` schema, improve
            MD042/MD044, improve documentation, update dependencies.
+  * 0.21.1 - Improve MD011/MD031, export `getVersion` API.
+* 0.22.0 - Allow `extends` in config to reference installed packages by name, add
+           `markdownlint-disable-next-line` inline comment, support JSON front matter, improve
+           MD009/MD026/MD028/MD043, update dependencies (including `markdown-it` to v12).
+* 0.23.0 - Add comprehensive example `.markdownlint.jsonc`/`.markdownlint.yaml` files, add fix
+           information for MD004/ul-style, improve MD018/MD019/MD020/MD021/MD037/MD041, improve
+           HTML comment handling, update test runner and test suite, update dependencies.
+  * 0.23.1 - Work around lack of webpack support for dynamic calls to `require` (`.resolve`).
 
 [npm-image]: https://img.shields.io/npm/v/markdownlint.svg
 [npm-url]: https://www.npmjs.com/package/markdownlint