markdownlint 0.39.0 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.40.0
+
+- Improve MD011/MD013/MD051/MD060
+- Update dependencies
+
 ## 0.39.0
 
 - Add MD060/table-column-style

package/CONTRIBUTING.md

@@ -83,7 +83,7 @@ Thank you!
 [ava-snapshots]: https://github.com/avajs/ava/blob/main/docs/04-snapshot-testing.md
 [closing-keywords]: https://help.github.com/articles/closing-issues-using-keywords/
 [custom-rules]: doc/CustomRules.md
-[dependencies]: https://docs.npmjs.com/files/package.json#dependencies
+[dependencies]: https://docs.npmjs.com/cli/v11/configuring-npm/package-json#dependencies
 [example-com]: https://en.wikipedia.org/wiki/Example.com
 [micromark]: https://www.npmjs.com/package/micromark
 [new-rule]: https://github.com/DavidAnson/markdownlint/labels/new%20rule

package/README.md

@@ -206,11 +206,10 @@ issues reported. Two kinds of text are ignored by most rules:
 - [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):
+All rules are enabled by default. Rules can be enabled, disabled, and configured
+for each call to the `lint` API by passing an `options.config` object (described
+below). To enable or disable rules within a file, use one of the following HTML
+comments (which are not rendered):
 
 - Disable all rules: `<!-- markdownlint-disable -->`
 - Enable all rules: `<!-- markdownlint-enable -->`
@@ -980,7 +979,7 @@ All of which return an object like:
     { "lineNumber": 3,
       "ruleNames": [ "MD010", "no-hard-tabs" ],
       "ruleDescription": "Hard tabs",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md010.md",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md010.md",
       "errorDetail": "Column: 17",
       "errorContext": null,
       "errorRange": [ 17, 1 ],
@@ -989,7 +988,7 @@ All of which return an object like:
     { "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",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md018.md",
       "errorDetail": null,
       "errorContext": "#bad.md",
       "errorRange": [ 1, 2 ],
@@ -998,7 +997,7 @@ All of which return an object like:
     { "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",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md018.md",
       "errorDetail": null,
       "errorContext": "#This file fails\tsome rules.",
       "errorRange": [ 1, 2 ],
@@ -1007,7 +1006,7 @@ All of which return an object like:
     { "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",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md041.md",
       "errorDetail": null,
       "errorContext": "#bad.md",
       "errorRange": null,

package/doc/Rules.md

@@ -2284,14 +2284,19 @@ This makes it easy to link directly to different sections within a document.
 However, section links change if headings are renamed or removed. This rule
 helps identify broken section links within a document.
 
-Section links are **not** part of the CommonMark specification. This rule
-enforces the [GitHub heading algorithm][github-heading-algorithm] which is:
-convert heading to lowercase, remove punctuation, convert spaces to dashes,
-append an incrementing integer as needed for uniqueness.
+Note: Section links are **not** part of the CommonMark specification; this rule
+enforces the [GitHub heading algorithm][github-heading-algorithm]:
 
+1. Convert text to lowercase
+2. Remove punctuation characters
+3. Convert spaces to dashes
+4. Append an incrementing integer (as needed for uniqueness)
+5. [URI-encode][encodeURIComponent] the result
+
+[encodeURIComponent]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent
 [github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
 [github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/f13a1534cb650ba17af400d1acd3a22c28004c09/lib/html/pipeline/toc_filter.rb
-[github-linking-to-content]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet#linking-to-markdown#linking-to-markdown
+[github-linking-to-content]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet#linking-to-markdown
 [html-top-fragment]: https://html.spec.whatwg.org/multipage/browsing-the-web.html#scrolling-to-a-fragment
 [RegEx]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions
 
@@ -2689,15 +2694,16 @@ Aliases: `table-column-style`
 
 Parameters:
 
+- `aligned_delimiter`: Aligned delimiter columns (`boolean`, default `false`)
 - `style`: Table column style (`string`, default `any`, values `aligned` /
   `any` / `compact` / `tight`)
 
-This rule is triggered when the column separators of a
+This rule is triggered when the column separator pipe characters (`|`) of a
 [GitHub Flavored Markdown table][gfm-table-060] are used inconsistently.
 
-This rule recognizes three table column styles based on popular use:
+This rule recognizes three table column styles based on popular use.
 
-Style `aligned` looks the most like a table:
+Style `aligned` ensures pipe characters are vertically aligned:
 
 ```markdown
 | Character | Meaning |
@@ -2706,7 +2712,16 @@ Style `aligned` looks the most like a table:
 | N         | No      |
 ```
 
-Style `compact` uses a single space to pad cell content:
+The `aligned` style ignores cell content, so the following is also valid:
+
+```markdown
+| Character | Meaning |
+|-----------|---------|
+|     Y     |     Yes |
+|     N     |      No |
+```
+
+Style `compact` avoids extra padding with a single space around cell content:
 
 ```markdown
 | Character | Meaning |
@@ -2715,7 +2730,7 @@ Style `compact` uses a single space to pad cell content:
 | N | No |
 ```
 
-Style `tight` uses no padding for cell content:
+Style `tight` uses no padding at all for cell content:
 
 ```markdown
 |Character|Meaning|
@@ -2725,16 +2740,51 @@ Style `tight` uses no padding for cell content:
 ```
 
 When this rule's `style` parameter is set to `aligned`, `compact`, or `tight`,
-every table must match the corresponding pattern and errors will be reported for
-any violations. By default, or when the `any` style is used, each table is
-analyzed to see if it satisfies any supported style. If so, no errors are
-reported. If not, errors are be reported for whichever style would produce the
-*fewest* errors (i.e., whichever style is the closest match).
+every table must match the corresponding pattern and any violations will be
+reported. By default, or when the `any` style is used, each table is analyzed to
+see if it satisfies any supported style. If so, no violations are reported. If
+not, violations are be reported for whichever style would produce the *fewest*
+issues (i.e., whichever style is the closest match).
+
+Setting the `aligned_delimiter` parameter to `true` requires pipe characters in
+the delimiter row to align with those in the header row. This can be used with
+`compact` and `tight` tables to make the header text more obvious. (It's already
+required for tables with style `aligned`.)
+
+Style `compact` with `aligned_delimiter`:
+
+```markdown
+| Character | Meaning |
+| --------- | ------- |
+| Y | Yes |
+| N | No |
+```
+
+Style `tight` with `aligned_delimiter`:
+
+```markdown
+|Character|Meaning|
+|---------|-------|
+|Y|Yes|
+|N|No|
+```
+
+**Note**: This rule does not require leading/trailing pipe characters, so this
+is also a valid table for style `compact`:
+
+```markdown
+Character | Meaning
+--- | ---
+Y | Yes
+N | No
+```
 
-Note: Pipe alignment for the `aligned` style is based on character count, so
-wide characters and multi-character encodings can produce unexpected results.
-The following table is correctly aligned based on character count, though some
-editors render the emoji wider:
+**Note**: Pipe alignment for the `aligned` style is based on visual appearance
+and not character count. Because editors typically render [emoji][emoji] and
+[CJK characters][cjk-characters] at *twice* the width of
+[Latin characters][latin-script], this rule takes that into account for tables
+using the `aligned` style. The following table is correctly formatted and will
+appear aligned in most editors and monospaced fonts:
 
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable extended-ascii -->
@@ -2742,15 +2792,18 @@ editors render the emoji wider:
 ```markdown
 | Response | Emoji |
 | -------- | ----- |
-| Yes      | ✅     |
-| No       | ❎     |
+| Yes      | ✅    |
+| No       | ❎    |
 ```
 
 <!-- markdownlint-restore -->
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
+[cjk-characters]: https://en.wikipedia.org/wiki/CJK_characters
+[emoji]: https://en.wikipedia.org/wiki/Emoji
 [gfm-table-060]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables
+[latin-script]: https://en.wikipedia.org/wiki/Latin_script
 
 <!-- markdownlint-configure-file {
   "no-inline-html": {

package/doc/md051.md

@@ -100,13 +100,18 @@ This makes it easy to link directly to different sections within a document.
 However, section links change if headings are renamed or removed. This rule
 helps identify broken section links within a document.
 
-Section links are **not** part of the CommonMark specification. This rule
-enforces the [GitHub heading algorithm][github-heading-algorithm] which is:
-convert heading to lowercase, remove punctuation, convert spaces to dashes,
-append an incrementing integer as needed for uniqueness.
+Note: Section links are **not** part of the CommonMark specification; this rule
+enforces the [GitHub heading algorithm][github-heading-algorithm]:
 
+1. Convert text to lowercase
+2. Remove punctuation characters
+3. Convert spaces to dashes
+4. Append an incrementing integer (as needed for uniqueness)
+5. [URI-encode][encodeURIComponent] the result
+
+[encodeURIComponent]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent
 [github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
 [github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/f13a1534cb650ba17af400d1acd3a22c28004c09/lib/html/pipeline/toc_filter.rb
-[github-linking-to-content]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet#linking-to-markdown#linking-to-markdown
+[github-linking-to-content]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet#linking-to-markdown
 [html-top-fragment]: https://html.spec.whatwg.org/multipage/browsing-the-web.html#scrolling-to-a-fragment
 [RegEx]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions

package/doc/md060.md

@@ -6,15 +6,16 @@ Aliases: `table-column-style`
 
 Parameters:
 
+- `aligned_delimiter`: Aligned delimiter columns (`boolean`, default `false`)
 - `style`: Table column style (`string`, default `any`, values `aligned` /
   `any` / `compact` / `tight`)
 
-This rule is triggered when the column separators of a
+This rule is triggered when the column separator pipe characters (`|`) of a
 [GitHub Flavored Markdown table][gfm-table-060] are used inconsistently.
 
-This rule recognizes three table column styles based on popular use:
+This rule recognizes three table column styles based on popular use.
 
-Style `aligned` looks the most like a table:
+Style `aligned` ensures pipe characters are vertically aligned:
 
 ```markdown
 | Character | Meaning |
@@ -23,7 +24,16 @@ Style `aligned` looks the most like a table:
 | N         | No      |
 ```
 
-Style `compact` uses a single space to pad cell content:
+The `aligned` style ignores cell content, so the following is also valid:
+
+```markdown
+| Character | Meaning |
+|-----------|---------|
+|     Y     |     Yes |
+|     N     |      No |
+```
+
+Style `compact` avoids extra padding with a single space around cell content:
 
 ```markdown
 | Character | Meaning |
@@ -32,7 +42,7 @@ Style `compact` uses a single space to pad cell content:
 | N | No |
 ```
 
-Style `tight` uses no padding for cell content:
+Style `tight` uses no padding at all for cell content:
 
 ```markdown
 |Character|Meaning|
@@ -42,16 +52,51 @@ Style `tight` uses no padding for cell content:
 ```
 
 When this rule's `style` parameter is set to `aligned`, `compact`, or `tight`,
-every table must match the corresponding pattern and errors will be reported for
-any violations. By default, or when the `any` style is used, each table is
-analyzed to see if it satisfies any supported style. If so, no errors are
-reported. If not, errors are be reported for whichever style would produce the
-*fewest* errors (i.e., whichever style is the closest match).
+every table must match the corresponding pattern and any violations will be
+reported. By default, or when the `any` style is used, each table is analyzed to
+see if it satisfies any supported style. If so, no violations are reported. If
+not, violations are be reported for whichever style would produce the *fewest*
+issues (i.e., whichever style is the closest match).
+
+Setting the `aligned_delimiter` parameter to `true` requires pipe characters in
+the delimiter row to align with those in the header row. This can be used with
+`compact` and `tight` tables to make the header text more obvious. (It's already
+required for tables with style `aligned`.)
+
+Style `compact` with `aligned_delimiter`:
+
+```markdown
+| Character | Meaning |
+| --------- | ------- |
+| Y | Yes |
+| N | No |
+```
+
+Style `tight` with `aligned_delimiter`:
+
+```markdown
+|Character|Meaning|
+|---------|-------|
+|Y|Yes|
+|N|No|
+```
+
+**Note**: This rule does not require leading/trailing pipe characters, so this
+is also a valid table for style `compact`:
+
+```markdown
+Character | Meaning
+--- | ---
+Y | Yes
+N | No
+```
 
-Note: Pipe alignment for the `aligned` style is based on character count, so
-wide characters and multi-character encodings can produce unexpected results.
-The following table is correctly aligned based on character count, though some
-editors render the emoji wider:
+**Note**: Pipe alignment for the `aligned` style is based on visual appearance
+and not character count. Because editors typically render [emoji][emoji] and
+[CJK characters][cjk-characters] at *twice* the width of
+[Latin characters][latin-script], this rule takes that into account for tables
+using the `aligned` style. The following table is correctly formatted and will
+appear aligned in most editors and monospaced fonts:
 
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable extended-ascii -->
@@ -59,12 +104,15 @@ editors render the emoji wider:
 ```markdown
 | Response | Emoji |
 | -------- | ----- |
-| Yes      | ✅     |
-| No       | ❎     |
+| Yes      | ✅    |
+| No       | ❎    |
 ```
 
 <!-- markdownlint-restore -->
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
+[cjk-characters]: https://en.wikipedia.org/wiki/CJK_characters
+[emoji]: https://en.wikipedia.org/wiki/Emoji
 [gfm-table-060]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables
+[latin-script]: https://en.wikipedia.org/wiki/Latin_script

package/helpers/README.md

@@ -22,8 +22,8 @@ be useful to custom rule authors and may avoid duplicating code.
 *None* - The entire body of code is tested to 100% coverage by the core
 `markdownlint` project, so there are no additional tests here.
 
-[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.39.0/doc/CustomRules.md
+[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/CustomRules.md
 [jsdoc]: https://en.m.wikipedia.org/wiki/JSDoc
 [markdown]: https://en.wikipedia.org/wiki/Markdown
 [markdownlint]: https://github.com/DavidAnson/markdownlint
-[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.39.0/doc/Rules.md
+[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/Rules.md