Enable "line-length": { "strict": true } for all user-facing Markdown files in the repository.

doc-build/.markdownlint.jsonc

@@ -1,3 +1,6 @@
 {
+  "extends": "../.markdownlint.json",
+
+  // Headings are added by the "build-docs" script (build-rules.mjs)
   "first-line-heading": false
 }

doc-build/build-rules.mjs

@@ -4,10 +4,26 @@ import { default as rules } from "../lib/rules.js";
 import { newLineRe } from "../helpers/helpers.js";
 import { deprecatedRuleNames, fixableRuleNames } from "../lib/constants.js";
 
+const maxLineLength = 80;
+
 const pathFor = (relativePath) => new URL(relativePath, import.meta.url);
 const inCode = (items) => items.map((item) => `\`${item}\``);
 const sortedComma = (items) => items.sort().join(", ");
 const linesFrom = (text) => text.split(newLineRe);
+const wrapListItem = (line) => {
+  const wrappedLines = [];
+  let remainingLine = line;
+  while (remainingLine.length > maxLineLength) {
+    let index = maxLineLength - 1;
+    while (remainingLine[index] !== " ") {
+      index--;
+    }
+    wrappedLines.push(remainingLine.slice(0, index + 1).trimEnd());
+    remainingLine = "  " + remainingLine.slice(index + 1).trimStart();
+  }
+  wrappedLines.push(remainingLine);
+  return wrappedLines;
+};
 
 // import { default as schema } from "file.json" assert { type: "json" };
 const importJson =
@@ -48,24 +64,27 @@ for (const rule of rules) {
   if (ruleData.properties) {
     section.push(
       "Parameters:",
-      "",
-      ...Object.keys(ruleData.properties).sort().map((property) => {
-        const propData = ruleData.properties[property];
-        const propType = (propData.type === "array") ?
-          `${propData.items.type}[]` :
-          propData.type;
-        const defaultValue = Array.isArray(propData.default) ?
-          JSON.stringify(propData.default) :
-          propData.default;
-        const allValues = propData.enum?.sort();
-        return `* \`${property}\`: ${propData.description} (` +
-          `\`${propType}\`, default \`${defaultValue}\`` +
-          (propData.enum ?
-            `, values ${allValues.map((value) => `\`${value}\``).join("/")}` :
-            ""
-          ) +
-          ")";
-      }),
+      ""
+    );
+    for (const property of Object.keys(ruleData.properties).sort()) {
+      const propData = ruleData.properties[property];
+      const propType = (propData.type === "array") ?
+        `${propData.items.type}[]` :
+        propData.type;
+      const defaultValue = Array.isArray(propData.default) ?
+        JSON.stringify(propData.default) :
+        propData.default;
+      const allValues = propData.enum?.sort();
+      const listItem = `* \`${property}\`: ${propData.description} (` +
+        `\`${propType}\`, default \`${defaultValue}\`` +
+        (propData.enum ?
+          `, values ${allValues.map((value) => `\`${value}\``).join(" / ")}` :
+          ""
+        ) +
+        ")";
+      section.push(...wrapListItem(listItem));
+    }
+    section.push(
       ""
     );
   }

doc-build/md004.md

@@ -16,13 +16,13 @@ document:
 * Item 3
 ```
 
-The configured list style can be a specific symbol to use (asterisk, plus, dash),
-to ensure that all list styling is consistent, or to ensure that each
+The configured list style can be a specific symbol to use (asterisk, plus,
+dash), to ensure that all list styling is consistent, or to ensure that each
 sublist has a consistent symbol that differs from its parent list.
 
-For example, the following is valid for the `sublist` style because the outer-most
-indent uses asterisk, the middle indent uses plus, and the inner-most indent uses
-dash:
+For example, the following is valid for the `sublist` style because the
+outer-most indent uses asterisk, the middle indent uses plus, and the inner-most
+indent uses dash:
 
 ```markdown
 * Item 1

doc-build/md007.md

@@ -21,16 +21,19 @@ rule).
 
 The `start_indented` parameter allows the first level of lists to be indented by
 the configured number of spaces rather than starting at zero (the inverse of
-MD006). The `start_indent` parameter allows the first level of lists to be indented
-by a different number of spaces than the rest (ignored when `start_indented` is not
-set).
+MD006). The `start_indent` parameter allows the first level of lists to be
+indented by a different number of spaces than the rest (ignored when
+`start_indented` is not set).
 
 Rationale: Indenting by 2 spaces allows the content of a nested list to be in
 line with the start of the content of the parent list when a single space is
 used after the list marker. Indenting by 4 spaces is consistent with code blocks
 and simpler for editors to implement. Additionally, this can be a compatibility
-issue for other Markdown parsers, which require 4-space indents. More information:
-<https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists>
-and <http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting>.
+issue for other Markdown parsers, which require 4-space indents. More
+information: [Markdown Style Guide][markdown-style-guide] and [Marked app\
+support][marked-app-support].
 
 Note: See [Prettier.md](Prettier.md) for compatibility information.
+
+[markdown-style-guide]: https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists
+[marked-app-support]: http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting

doc-build/md009.md

@@ -1,5 +1,5 @@
-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.
+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.
@@ -8,12 +8,14 @@ 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).
 
-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.
+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, 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`.
+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`.
 
 ```markdown
 Text text text

doc-build/md022.md

@@ -22,12 +22,12 @@ Some more text
 ## Heading 2
 ```
 
-The `lines_above` and `lines_below` parameters can be used to specify a different
-number of blank lines (including 0) above or below each heading.
+The `lines_above` and `lines_below` parameters can be used to specify a
+different number of blank lines (including 0) above or below each heading.
 
 Note: If `lines_above` or `lines_below` are configured to require more than one
 blank line, [MD012/no-multiple-blanks](md012.md) should also be customized.
 
-Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`, will
-not parse headings that don't have a blank line before, and will parse them as
-regular text.
+Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`,
+will not parse headings that don't have a blank line before, and will parse them
+as regular text.

doc-build/md025.md

@@ -23,14 +23,15 @@ lower-level headings (h2, h3, etc.):
 Note: The `level` parameter can be used to change the top-level (ex: to h2) in
 cases where an h1 is added externally.
 
-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 for any subsequent top-level headings.
-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`.
+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 for any subsequent
+top-level headings. 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`.
 
 Rationale: A top-level heading is an h1 on the first line of the file, and
 serves as the title for the document. If this convention is in use, then there
-can not be more than one title for the document, and the entire document
-should be contained within this heading.
+can not be more than one title for the document, and the entire document should
+be contained within this heading.

doc-build/md026.md

@@ -14,13 +14,15 @@ To fix this, remove the trailing punctuation:
 Note: The `punctuation` parameter can be used to specify what characters count
 as punctuation at the end of a heading. For example, you can change it to
 `".,;:"` to allow headings that end with an exclamation point. `?` is
-allowed by default because of how common it is in headings of FAQ-style documents.
-Setting the `punctuation` parameter to `""` allows all characters - and is
-equivalent to disabling the rule.
+allowed by default because of how common it is in headings of FAQ-style
+documents. Setting the `punctuation` parameter to `""` allows all characters -
+and is equivalent to disabling the rule.
 
-Note: The trailing semicolon of
-[HTML entity references](https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references)
+Note: The trailing semicolon of [HTML entity references][html-entity-references]
 like `©`, `©`, and `©` is ignored by this rule.
 
 Rationale: Headings are not meant to be full sentences. More information:
-<https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers>
+[Punctuation at the end of headers][end-punctuation].
+
+[end-punctuation]: https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers
+[html-entity-references]: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

doc-build/md038.md

@@ -20,8 +20,8 @@ automatically trimmed (to allow for embedded backticks):
 `` `backticks` ``
 ```
 
-Note: A single leading or trailing space is allowed if used to separate code span
-markers from an embedded backtick:
+Note: A single leading or trailing space is allowed if used to separate code
+span markers from an embedded backtick:
 
 ```markdown
 `` ` embedded backtick``

doc-build/md041.md

@@ -23,14 +23,15 @@ permitted by this rule. For example:
 This is a file with a top-level HTML heading
 ```
 
-Note: The `level` parameter can be used to change the top-level (ex: to h2) in cases
-where an h1 is added externally.
+Note: The `level` parameter can be used to change the top-level (ex: to h2) in
+cases where an h1 is added externally.
 
 If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
 contains a `title` property (commonly used with blog posts), this rule will not
 report a violation. 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`.
+To disable the use of front matter by this rule, specify `""` for
+`front_matter_title`.
 
 Rationale: The top-level heading often acts as the title of a document. More
 information: <https://cirosantilli.com/markdown-style-guide#top-level-header>.

doc-build/md042.md

@@ -22,4 +22,5 @@ But non-empty fragments will not:
 [a valid fragment](#fragment)
 ```
 
-Rationale: Empty links do not lead anywhere and therefore don't function as links.
+Rationale: Empty links do not lead anywhere and therefore don't function as
+links.

doc-build/md043.md

@@ -49,12 +49,12 @@ special value `"+"` meaning "one or more unspecified headings" and set the
 When an error is detected, this rule outputs the line number of the first
 problematic heading (otherwise, it outputs the last line number of the file).
 
-Note that while the `headings` parameter uses the "## Text" ATX heading style for
-simplicity, a file may use any supported heading style.
+Note that while the `headings` parameter uses the "## Text" ATX heading style
+for simplicity, a file may use any supported heading style.
 
-By default, the case of headings in the document is not required to match that of
-`headings`. To require that case match exactly, set the `match_case` parameter to
-`true`.
+By default, the case of headings in the document is not required to match that
+of `headings`. To require that case match exactly, set the `match_case`
+parameter to `true`.
 
 Rationale: Projects may wish to enforce a consistent document structure across
 a set of similar content.

doc-build/md044.md

@@ -3,8 +3,9 @@ the specified capitalization. It can be used to enforce a standard letter case
 for the names of projects and products.
 
 For example, the language "JavaScript" is usually written with both the 'J' and
-'S' capitalized - though sometimes the 's' or 'j' appear in lower-case. To enforce
-the proper capitalization, specify the desired letter case in the `names` array:
+'S' capitalized - though sometimes the 's' or 'j' appear in lower-case. To
+enforce the proper capitalization, specify the desired letter case in the
+`names` array:
 
 ```json
 [

doc-build/md045.md

@@ -1,4 +1,5 @@
-This rule is triggered when an image is missing alternate text (alt text) information.
+This rule is triggered when an image is missing alternate text (alt text)
+information.
 
 Alternate text is commonly specified inline as:
 
@@ -16,9 +17,12 @@ Or with reference syntax as:
 [ref]: image.jpg "Optional title"
 ```
 
-Guidance for writing alternate text is available from the [W3C](https://www.w3.org/WAI/alt/),
-[Wikipedia](https://en.wikipedia.org/wiki/Alt_attribute), and
-[other locations](https://www.phase2technology.com/blog/no-more-excuses).
+Guidance for writing alternate text is available from the [W3C][w3c],
+[Wikipedia][wikipedia], and [other locations][phase2technology].
 
 Rationale: Alternate text is important for accessibility and describes the
 content of an image for people who may not be able to see it.
+
+[phase2technology]: https://www.phase2technology.com/blog/no-more-excuses
+[w3c]: https://www.w3.org/WAI/alt/
+[wikipedia]: https://en.wikipedia.org/wiki/Alt_attribute

doc-build/md046.md

@@ -1,7 +1,8 @@
 This rule is triggered when unwanted or different code block styles are used in
 the same document.
 
-In the default configuration this rule reports a violation for the following document:
+In the default configuration this rule reports a violation for the following
+document:
 
 <!-- markdownlint-disable code-block-style -->
 

doc-build/md047.md

@@ -19,4 +19,8 @@ This file ends with a newline.
 ```
 
 Rationale: Some programs have trouble with files that do not end with a newline.
-More information: <https://unix.stackexchange.com/questions/18743/whats-the-point-in-adding-a-new-line-to-the-end-of-a-file>.
+
+More information: [What's the point in adding a new line to the end of a
+file?][stack-exchange]
+
+[stack-exchange]: https://unix.stackexchange.com/questions/18743/whats-the-point-in-adding-a-new-line-to-the-end-of-a-file

doc-build/md051.md

@@ -27,16 +27,16 @@ define a fragment:
 An `a` tag can be useful in scenarios where a heading is not appropriate or for
 control over the text of the fragment identifier.
 
-Rationale: [GitHub section links][github-section-links] are created automatically
-for every heading when Markdown content is displayed on GitHub. 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.
+Rationale: [GitHub section links][github-section-links] are created
+automatically for every heading when Markdown content is displayed on GitHub.
+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.
+convert heading to lowercase, remove punctuation, convert spaces to dashes,
+append an incrementing integer as needed for uniqueness.
 
 [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/main/lib/html/pipeline/toc_filter.rb