markdownlint 0.38.0 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.40.0
+
+- Improve MD011/MD013/MD051/MD060
+- Update dependencies
+
+## 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

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

@@ -149,6 +149,7 @@ playground for learning and exploring.
 - **[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 -->
 
@@ -190,7 +191,7 @@ rules at once.
 - **`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`,
@@ -205,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 -->`
@@ -361,22 +361,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
 {
@@ -619,28 +715,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
+##### ~~options.resultVersion~~
 
-Type: `Number`
+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:
 
-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. *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. *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
 
@@ -671,9 +754,9 @@ 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
 
@@ -849,7 +932,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";
@@ -864,34 +947,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";
@@ -900,7 +970,7 @@ const results = await lintPromise(options);
 console.dir(results, { "colors": true, "depth": null });
 ```
 
-Output:
+All of which return an object like:
 
 ```json
 {
@@ -909,41 +979,43 @@ Output:
     { "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 ] },
+      "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",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.40.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",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.40.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",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.40.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.
@@ -969,7 +1041,7 @@ const options = {
   }
 };
 
-const results = globalThis.markdownlint.lintSync(options).toString();
+const results = globalThis.markdownlint.lintSync(options);
 ```
 
 ## Examples
@@ -980,7 +1052,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])
@@ -1004,8 +1075,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

package/doc/Rules.md

@@ -12,6 +12,11 @@ Tags: `headings`
 
 Aliases: `heading-increment`
 
+Parameters:
+
+- `front_matter_title`: RegExp for matching title in front matter (`string`,
+  default `^\s*title\s*[:=]`)
+
 This rule is triggered when you skip heading levels in a Markdown document, for
 example:
 
@@ -40,6 +45,15 @@ level at a time:
 ### Another Heading 3
 ```
 
+If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
+contains a `title` property (commonly used with blog posts), this rule treats
+that as a top level heading and will report a violation if the actual first
+heading is not a level 2 heading. To use a different property name in the
+front matter, specify the text of a regular expression via the
+`front_matter_title` parameter. To disable the use of front matter by this
+rule, specify `""` for `front_matter_title`. When front matter is not present,
+the first heading can be any level.
+
 Rationale: Headings represent the structure of a document and can be confusing
 when skipped - especially for accessibility scenarios. More information:
 <https://www.w3.org/WAI/tutorials/page-structure/headings/>.
@@ -281,6 +295,7 @@ Aliases: `no-trailing-spaces`
 Parameters:
 
 - `br_spaces`: Spaces for line break (`integer`, default `2`)
+- `code_blocks`: Include code blocks (`boolean`, default `false`)
 - `list_item_empty_lines`: Allow spaces for empty lines in list items
   (`boolean`, default `false`)
 - `strict`: Include unnecessary breaks (`boolean`, default `false`)
@@ -290,21 +305,19 @@ Fixable: Some violations can be fixed by tooling
 This rule is triggered on any lines that end with unexpected whitespace. To fix
 this, remove the trailing space from the end of the line.
 
-Note: Trailing space is allowed in indented and fenced code blocks because some
-languages require it.
-
 The `br_spaces` parameter allows an exception to this rule for a specific number
 of trailing spaces, typically used to insert an explicit line break. The default
-value allows 2 spaces to indicate a hard break (\<br> element).
+value allows 2 spaces to indicate a hard break (\<br> element). (You must set
+`br_spaces` to a value >= 2 for this parameter to take effect. Setting
+`br_spaces` to 1 behaves the same as 0, disallowing any trailing spaces.)
 
-Note: You must set `br_spaces` to a value >= 2 for this parameter to take
-effect. Setting `br_spaces` to 1 behaves the same as 0, disallowing any trailing
-spaces.
+By default, trailing space is allowed in indented and fenced code blocks because
+some programming languages require that. To report such instances, set the
+`code_blocks` parameter to `true`.
 
 By default, this rule will not trigger when the allowed number of spaces is
 used, even when it doesn't create a hard break (for example, at the end of a
-paragraph). To report such instances as well, set the `strict` parameter to
-`true`.
+paragraph). To report such instances, set the `strict` parameter to `true`.
 
 ```markdown
 Text text text
@@ -383,6 +396,12 @@ parameter to the desired value.
 Rationale: Hard tabs are often rendered inconsistently by different editors and
 can be harder to work with than spaces.
 
+More information:
+
+- <https://agiletribe.wordpress.com/2011/10/27/18-dont-use-tab-characters/>
+- <https://www.jwz.org/doc/tabs-vs-spaces.html>
+- <https://adamspiers.org/computing/why_no_tabs.html>
+
 <a name="md011"></a>
 
 ## `MD011` - Reversed link syntax
@@ -1026,6 +1045,8 @@ Parameters:
 - `style`: List style (`string`, default `one_or_ordered`, values `one` /
   `one_or_ordered` / `ordered` / `zero`)
 
+Fixable: Some violations can be fixed by tooling
+
 This rule is triggered for ordered lists that do not either start with '1.' or
 do not have a prefix that increases in numerical order (depending on the
 configured style). The less-common pattern of using '0.' as a first prefix or
@@ -1321,6 +1342,8 @@ Aliases: `no-inline-html`
 Parameters:
 
 - `allowed_elements`: Allowed elements (`string[]`, default `[]`)
+- `table_allowed_elements`: Allowed elements in tables (`string[]`, default
+  `[]`)
 
 This rule is triggered whenever raw HTML is used in a Markdown document:
 
@@ -1334,7 +1357,11 @@ To fix this, use 'pure' Markdown instead of including raw HTML:
 # Markdown heading
 ```
 
-Note: To allow specific HTML elements, use the `allowed_elements` parameter.
+To allow specific HTML elements anywhere in Markdown content, set the
+`allowed_elements` parameter to a list of HTML element names. To allow a
+specific set of HTML elements within Markdown tables, set the
+`table_allowed_elements` parameter to a list of HTML element names. This can be
+used to permit the use of `<br>`-style line breaks only within Markdown tables.
 
 Rationale: Raw HTML is allowed in Markdown, but this rule is included for
 those who want their documents to only include "pure" Markdown, or for those
@@ -2257,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
 
@@ -2523,7 +2555,7 @@ Rationale: Some parsers have difficulty with tables that are missing their
 leading or trailing pipe characters. The use of leading/trailing pipes can also
 help provide visual clarity.
 
-[gfm-table-055]: https://github.github.com/gfm/#tables-extension-
+[gfm-table-055]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables
 
 <a name="md056"></a>
 
@@ -2563,7 +2595,7 @@ of cells or it will not be recognized as a table (per specification).
 Rationale: Extra cells in a row are usually not shown, so their data is lost.
 Missing cells in a row create holes in the table and suggest an omission.
 
-[gfm-table-056]: https://github.github.com/gfm/#tables-extension-
+[gfm-table-056]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables
 
 <a name="md058"></a>
 
@@ -2647,7 +2679,131 @@ translations for every language.
 
 Note: This rule checks Markdown links; HTML links are ignored.
 
-More information: <https://webaim.org/techniques/hypertext/>
+More information:
+
+- <https://webaim.org/techniques/hypertext/>
+- <https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-link-only.html>
+
+<a name="md060"></a>
+
+## `MD060` - Table column style
+
+Tags: `table`
+
+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 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.
+
+Style `aligned` ensures pipe characters are vertically aligned:
+
+```markdown
+| Character | Meaning |
+| --------- | ------- |
+| Y         | Yes     |
+| N         | No      |
+```
+
+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 |
+| --- | --- |
+| Y | Yes |
+| N | No |
+```
+
+Style `tight` uses no padding at all for cell content:
+
+```markdown
+|Character|Meaning|
+|---|---|
+|Y|Yes|
+|N|No|
+```
+
+When this rule's `style` parameter is set to `aligned`, `compact`, or `tight`,
+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 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 -->
+
+```markdown
+| Response | Emoji |
+| -------- | ----- |
+| 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": {