Generate Rules.md and md###.md files from metadata, improve Parameter…

…s documentation by referencing schema.
DavidAnson · Oct 30, 2022 · 37baddc · 37baddc
1 parent 32c75eb
commit 37baddc
Show file tree

Hide file tree

Showing 110 changed files with 3,875 additions and 179 deletions.
diff --git a/.github/dictionary.txt b/.github/dictionary.txt
@@ -3,6 +3,7 @@ APIs
 async
 atx
 ATX
+atx_closed
 atx-style
 axibase
 backtick

diff --git a/README.md b/README.md
@@ -115,7 +115,7 @@ playground for learning and exploring.
 
 See [Rules.md](doc/Rules.md) for more details.
 
-~~Struck through~~ rules are deprecated, and provided for backward-compatibility.
+~~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`).

diff --git a/demo/markdownlint-browser.js b/demo/markdownlint-browser.js
@@ -1199,6 +1199,13 @@ module.exports.referenceLinkImageData =
 // @ts-check
 
 module.exports.deprecatedRuleNames = ["MD002", "MD006"];
+module.exports.fixableRuleNames = [
+    "MD004", "MD005", "MD006", "MD007", "MD009", "MD010",
+    "MD011", "MD012", "MD014", "MD018", "MD019", "MD020",
+    "MD021", "MD022", "MD023", "MD026", "MD027", "MD030",
+    "MD031", "MD032", "MD034", "MD037", "MD038", "MD039",
+    "MD044", "MD047", "MD049", "MD050", "MD053"
+];
 module.exports.homepage = "https://github.com/DavidAnson/markdownlint";
 module.exports.version = "0.26.2";
 

diff --git a/doc-build/.markdownlint.jsonc b/doc-build/.markdownlint.jsonc
@@ -0,0 +1,3 @@
+{
+  "first-line-heading": false
+}
diff --git a/doc-build/build-rules.mjs b/doc-build/build-rules.mjs
@@ -0,0 +1,96 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { EOL } from "node:os";
+import { default as rules } from "../lib/rules.js";
+import { newLineRe } from "../helpers/helpers.js";
+import { deprecatedRuleNames, fixableRuleNames } from "../lib/constants.js";
+
+const pathFor = (relativePath) => new URL(relativePath, import.meta.url);
+const sortedComma = (items) => items.sort().join(", ");
+const linesFrom = (text) => text.split(newLineRe);
+
+// import { default as schema } from "file.json" assert { type: "json" };
+const importJson =
+  async(file) => JSON.parse(await readFile(pathFor(file)));
+const schema = await importJson("../schema/markdownlint-config-schema.json");
+
+const lines = [];
+
+const heading = await readFile(pathFor("./heading.md"), "utf8");
+lines.push(...linesFrom(heading));
+
+for (const rule of rules) {
+  const name = rule.names[0];
+  const deprecated = deprecatedRuleNames.includes(name);
+  const decorator = deprecated ? "~~" : "";
+  lines.push(
+    `<a name="${name.toLowerCase()}"></a>`,
+    ""
+  );
+  const section = [];
+  section.push(
+    `## ${decorator}${name} - ${rule.description}${decorator}`,
+    ""
+  );
+  if (deprecated) {
+    section.push(
+      "> This rule is deprecated and provided for backward-compatibility",
+      ""
+    );
+  }
+  section.push(
+    `Tags: ${sortedComma(rule.tags)}`,
+    "",
+    `Aliases: ${sortedComma(rule.names.slice(1))}`,
+    ""
+  );
+  const ruleData = schema.properties[name];
+  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("/")}` :
+            ""
+          ) +
+          ")";
+      }),
+      ""
+    );
+  }
+  if (fixableRuleNames.includes(name)) {
+    section.push(
+      "Fixable: Most violations can be fixed by tooling",
+      ""
+    );
+  }
+  const contents =
+    // eslint-disable-next-line no-await-in-loop
+    await readFile(pathFor(`./${name.toLowerCase()}.md`), "utf8");
+  section.push(...linesFrom(contents));
+
+  // eslint-disable-next-line no-await-in-loop
+  await writeFile(
+    pathFor(`../doc/${name.toLowerCase()}.md`),
+    section.join(EOL).slice(1),
+    "utf8"
+  );
+
+  lines.push(...section);
+}
+
+const footing = await readFile(pathFor("./footing.md"), "utf8");
+lines.push(...linesFrom(footing));
+
+const content = lines.join(EOL);
+await writeFile(pathFor("../doc/Rules.md"), content, "utf8");
diff --git a/doc-build/footing.md b/doc-build/footing.md
@@ -0,0 +1,7 @@
+<!-- markdownlint-configure-file {
+  "no-inline-html": {
+    "allowed_elements": [
+      "a"
+    ]
+  }
+} -->
diff --git a/doc-build/heading.md b/doc-build/heading.md
@@ -0,0 +1,6 @@
+# Rules
+
+This document contains a description of all rules, what they are checking for,
+as well as examples of documents that break the rule and corrected
+versions of the examples. Any rule whose heading is ~~struck through~~ is
+deprecated, but still provided for backward-compatibility.
diff --git a/doc-build/md001.md b/doc-build/md001.md
@@ -0,0 +1,31 @@
+This rule is triggered when you skip heading levels in a Markdown document, for
+example:
+
+```markdown
+# Heading 1
+
+### Heading 3
+
+We skipped out a 2nd level heading in this document
+```
+
+When using multiple heading levels, nested headings should increase by only one
+level at a time:
+
+```markdown
+# Heading 1
+
+## Heading 2
+
+### Heading 3
+
+#### Heading 4
+
+## Another Heading 2
+
+### Another Heading 3
+```
+
+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/>.
diff --git a/doc-build/md002.md b/doc-build/md002.md
@@ -0,0 +1,25 @@
+> Note: *MD002 has been deprecated and is disabled by default.*
+> [MD041/first-line-heading](md041.md) offers an improved implementation.
+
+This rule is intended to ensure document headings start at the top level and
+is triggered when the first heading in the document isn't an h1 heading:
+
+```markdown
+## This isn't an H1 heading
+
+### Another heading
+```
+
+The first heading in the document should be an h1 heading:
+
+```markdown
+# Start with an H1 heading
+
+## Then use an H2 for subsections
+```
+
+Note: The `level` parameter can be used to change the top-level (ex: to h2) in
+cases where an h1 is added externally.
+
+Rationale: The top-level heading often acts as the title of a document. More
+information: <https://cirosantilli.com/markdown-style-guide#top-level-header>.
diff --git a/doc-build/md003.md b/doc-build/md003.md
@@ -0,0 +1,38 @@
+This rule is triggered when different heading styles (atx, setext, and 'closed'
+atx) are used in the same document:
+
+```markdown
+# ATX style H1
+
+## Closed ATX style H2 ##
+
+Setext style H1
+===============
+```
+
+Be consistent with the style of heading used in a document:
+
+```markdown
+# ATX style H1
+
+## ATX style H2
+```
+
+The setext_with_atx and setext_with_atx_closed doc styles allow atx-style
+headings of level 3 or more in documents with setext style headings:
+
+```markdown
+Setext style H1
+===============
+
+Setext style H2
+---------------
+
+### ATX style H3
+```
+
+Note: the configured heading style can be a specific style to use (atx,
+atx_closed, setext, setext_with_atx, setext_with_atx_closed), or simply require
+that the usage is consistent within the document.
+
+Rationale: Consistent formatting makes it easier to understand a document.
diff --git a/doc-build/md004.md b/doc-build/md004.md
@@ -0,0 +1,36 @@
+This rule is triggered when the symbols used in the document for unordered
+list items do not match the configured unordered list style:
+
+```markdown
+* Item 1
++ Item 2
+- Item 3
+```
+
+To fix this issue, use the configured style for list items throughout the
+document:
+
+```markdown
+* Item 1
+* Item 2
+* 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
+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:
+
+```markdown
+* Item 1
+  + Item 2
+    - Item 3
+  + Item 4
+* Item 4
+  + Item 5
+```
+
+Rationale: Consistent formatting makes it easier to understand a document.
diff --git a/doc-build/md005.md b/doc-build/md005.md
@@ -0,0 +1,45 @@
+This rule is triggered when list items are parsed as being at the same level,
+but don't have the same indentation:
+
+```markdown
+* Item 1
+  * Nested Item 1
+  * Nested Item 2
+   * A misaligned item
+```
+
+Usually, this rule will be triggered because of a typo. Correct the indentation
+for the list to fix it:
+
+```markdown
+* Item 1
+  * Nested Item 1
+  * Nested Item 2
+  * Nested Item 3
+```
+
+Sequentially-ordered list markers are usually left-aligned such that all items
+have the same starting column:
+
+```markdown
+...
+8. Item
+9. Item
+10. Item
+11. Item
+...
+```
+
+This rule also supports right-alignment of list markers such that all items have
+the same ending column:
+
+```markdown
+...
+ 8. Item
+ 9. Item
+10. Item
+11. Item
+...
+```
+
+Rationale: Violations of this rule can lead to improperly rendered content.
diff --git a/doc-build/md006.md b/doc-build/md006.md
@@ -0,0 +1,36 @@
+This rule is triggered when top-level lists don't start at the beginning of a
+line:
+
+```markdown
+Some text
+
+  * List item
+  * List item
+```
+
+To fix, ensure that top-level list items are not indented:
+
+```markdown
+Some test
+
+* List item
+* List item
+```
+
+Note: This rule is triggered for the following scenario because the unordered
+sublist is not recognized as such by the parser. Not being nested 3 characters
+as required by the outer ordered list, it creates a top-level unordered list
+instead.
+
+```markdown
+1. List item
+  - List item
+  - List item
+1. List item
+```
+
+Rationale: Starting lists at the beginning of the line means that nested list
+items can all be indented by the same amount when an editor's indent function
+or the tab key is used to indent. Starting a list 1 space in means that the
+indent of the first nested list is less than the indent of the second level (3
+characters if you use 4 space tabs, or 1 character if you use 2 space tabs).
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,6 +3,7 @@ APIs @@
     async
     atx
     ATX
+    atx_closed
     atx-style
     axibase
     backtick
@@ Expand Down @@