typescript-eslint · JoshuaKGoldberg · Sep 12, 2024 · Sep 3, 2024
diff --git a/packages/website/package.json b/packages/website/package.json
@@ -60,6 +60,7 @@
     "cross-fetch": "*",
     "history": "^4.9.0",
     "make-dir": "*",
+    "mdast-util-from-markdown": "^2.0.1",
     "mdast-util-mdx": "^3.0.0",
     "monaco-editor": "~0.50.0",
     "raw-loader": "^4.0.2",

diff --git a/packages/website/plugins/generated-rule-docs/RuleDocsPage.ts b/packages/website/plugins/generated-rule-docs/RuleDocsPage.ts
@@ -1,4 +1,5 @@
 import type { ESLintPluginRuleModule } from '@typescript-eslint/eslint-plugin/use-at-your-own-risk/rules';
+import { fromMarkdown } from 'mdast-util-from-markdown';
 import type * as unist from 'unist';
 
 import type { VFileWithStem } from '../utils/rules';
@@ -57,9 +58,15 @@ export class RuleDocsPage {
   spliceChildren(
     start: number,
     deleteCount: number,
-    ...items: unist.Node[]
+    ...items: (string | unist.Node)[]
   ): void {
-    this.#children.splice(start, deleteCount, ...items);
+    this.#children.splice(
+      start,
+      deleteCount,
+      ...items.map(item =>
+        typeof item === 'string' ? fromMarkdown(item) : item,
+      ),
+    );
     this.#headingIndices = this.#recreateHeadingIndices();
   }
 

diff --git a/packages/website/plugins/generated-rule-docs/index.ts b/packages/website/plugins/generated-rule-docs/index.ts
@@ -6,7 +6,6 @@ import { isESLintPluginRuleModule, isVFileWithStem } from '../utils/rules';
 import { addESLintHashToCodeBlocksMeta } from './addESLintHashToCodeBlocksMeta';
 import { createRuleDocsPage } from './createRuleDocsPage';
 import { insertBaseRuleReferences } from './insertions/insertBaseRuleReferences';
-import { insertFormattingNotice } from './insertions/insertFormattingNotice';
 import { insertNewRuleReferences } from './insertions/insertNewRuleReferences';
 import { insertResources } from './insertions/insertResources';
 import { insertRuleDescription } from './insertions/insertRuleDescription';
@@ -28,7 +27,6 @@ export const generatedRuleDocs: Plugin = () => {
 
     removeSourceCodeNotice(page);
     insertRuleDescription(page);
-    insertFormattingNotice(page);
 
     const eslintrc = rule.meta.docs.extendsBaseRule
       ? insertBaseRuleReferences(page)

diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertBaseRuleReferences.ts b/packages/website/plugins/generated-rule-docs/insertions/insertBaseRuleReferences.ts
@@ -10,33 +10,11 @@ export function insertBaseRuleReferences(page: RuleDocsPage): string {
       ? page.rule.meta.docs.extendsBaseRule
       : page.file.stem;
 
-  page.spliceChildren(page.headingIndices.options + 1, 0, {
-    children: [
-      {
-        value: 'See ',
-        type: 'text',
-      },
-      {
-        children: [
-          {
-            type: 'inlineCode',
-            value: `eslint/${extendsBaseRuleName}`,
-          },
-          {
-            type: 'text',
-            value: ' options',
-          },
-        ],
-        type: 'link',
-        url: `https://eslint.org/docs/rules/${extendsBaseRuleName}#options`,
-      },
-      {
-        type: 'text',
-        value: '.',
-      },
-    ],
-    type: 'paragraph',
-  } as mdast.Paragraph);
+  page.spliceChildren(
+    page.headingIndices.options + 1,
+    0,
+    `See [\`eslint/${extendsBaseRuleName}\`'s options](https://eslint.org/docs/rules/${extendsBaseRuleName}#options).`,
+  );
 
   const eslintrc = getEslintrcString(
     extendsBaseRuleName,

diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertFormattingNotice.ts b/packages/website/plugins/generated-rule-docs/insertions/insertFormattingNotice.ts
diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertNewRuleReferences.ts b/packages/website/plugins/generated-rule-docs/insertions/insertNewRuleReferences.ts
@@ -1,6 +1,7 @@
 import { EOL } from 'node:os';
 import * as path from 'node:path';
 
+import type { ESLintPluginDocs } from '@typescript-eslint/eslint-plugin/use-at-your-own-risk/rules';
 import { compile } from '@typescript-eslint/rule-schema-to-typescript-types';
 import type * as mdast from 'mdast';
 import type { MdxJsxFlowElement } from 'mdast-util-mdx';
@@ -62,12 +63,9 @@ export async function insertNewRuleReferences(
   page.spliceChildren(
     firstH2Index,
     0,
-    {
-      lang: 'js',
-      type: 'code',
-      meta: 'title=".eslintrc.cjs"',
-      value: `module.exports = ${eslintrc};`,
-    } as mdast.Code,
+    `\`\`\`js title=".eslintrc.cjs"
+module.exports = ${eslintrc};
+\`\`\``,
     {
       attributes: [
         {
@@ -97,46 +95,18 @@ export async function insertNewRuleReferences(
     : Object.keys(page.rule.meta.schema).length === 0;
 
   if (hasNoConfig) {
-    page.spliceChildren(page.headingIndices.options + 1, 0, {
-      children: [
-        {
-          type: 'text',
-          value: 'This rule is not configurable.',
-        },
-      ],
-      type: 'paragraph',
-    } as mdast.Paragraph);
+    page.spliceChildren(
+      page.headingIndices.options + 1,
+      0,
+      'This rule is not configurable.',
+    );
   } else if (!COMPLICATED_RULE_OPTIONS.has(page.file.stem)) {
     page.spliceChildren(
       page.headingIndices.options + 1,
       0,
-      {
-        children:
-          typeof page.rule.meta.docs.recommended === 'object'
-            ? [
-                {
-                  type: 'text',
-                  value:
-                    'This rule accepts the following options, and has more strict settings in the ',
-                } as mdast.Text,
-                ...linkToConfigs(
-                  page.rule.meta.docs.requiresTypeChecking
-                    ? ['strict', 'strict-type-checked']
-                    : ['strict'],
-                ),
-                {
-                  type: 'text',
-                  value: ` config${page.rule.meta.docs.requiresTypeChecking ? 's' : ''}.`,
-                } as mdast.Text,
-              ]
-            : [
-                {
-                  type: 'text',
-                  value: 'This rule accepts the following options:',
-                } as mdast.Text,
-              ],
-        type: 'paragraph',
-      } as mdast.Paragraph,
+      typeof page.rule.meta.docs.recommended === 'object'
+        ? linkToConfigsForObject(page.rule.meta.docs)
+        : 'This rule accepts the following options:',
       {
         lang: 'ts',
         type: 'code',
@@ -156,30 +126,14 @@ export async function insertNewRuleReferences(
   return eslintrc;
 }
 
-function linkToConfigs(configs: string[]): mdast.Node[] {
-  const links = configs.map(
-    (config): mdast.Link => ({
-      children: [
-        {
-          type: 'inlineCode',
-          value: config,
-        } as mdast.InlineCode,
-      ],
-      type: 'link',
-      url: `/users/configs#${config}`,
-    }),
-  );
-
-  return links.length === 1
-    ? links
-    : [
-        links[0],
-        {
-          type: 'text',
-          value: ' and ',
-        } as mdast.Text,
-        links[1],
-      ];
+function linkToConfigsForObject(docs: ESLintPluginDocs): string {
+  return [
+    'This rule accepts the following options, and has more strict settings in the',
+    (docs.requiresTypeChecking ? ['strict', 'strict-type-checked'] : ['strict'])
+      .map(config => `[${config}](/users/configs#${config})`)
+      .join(' and '),
+    `config${docs.requiresTypeChecking ? 's' : ''}.`,
+  ].join(' ');
 }
 
 function getRuleDefaultOptions(page: RuleDocsPage): string {

diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertResources.ts b/packages/website/plugins/generated-rule-docs/insertions/insertResources.ts
@@ -1,4 +1,3 @@
-import type * as mdast from 'mdast';
 import type { MdxJsxFlowElement } from 'mdast-util-mdx';
 
 import { getUrlForRuleTest, sourceUrlPrefix } from '../../utils/rules';
@@ -9,61 +8,11 @@ export function insertResources(page: RuleDocsPage): void {
   page.spliceChildren(
     page.children.length,
     0,
-    {
-      children: [
-        {
-          type: 'text',
-          value: 'Resources',
-        },
-      ],
-      depth: 2,
-      type: 'heading',
-    } as mdast.Heading,
-    {
-      children: [
-        {
-          children: [
-            {
-              children: [
-                {
-                  type: 'link',
-                  url: `${sourceUrlPrefix}src/rules/${page.file.stem}.ts`,
-                  children: [
-                    {
-                      type: 'text',
-                      value: 'Rule source',
-                    },
-                  ],
-                },
-              ],
-              type: 'paragraph',
-            },
-          ],
-          type: 'listItem',
-        },
-        {
-          children: [
-            {
-              children: [
-                {
-                  type: 'link',
-                  url: getUrlForRuleTest(page.file.stem),
-                  children: [
-                    {
-                      type: 'text',
-                      value: 'Test source',
-                    },
-                  ],
-                },
-              ],
-              type: 'paragraph',
-            },
-          ],
-          type: 'listItem',
-        },
-      ],
-      type: 'list',
-    } as mdast.List,
+    `## Resources
+
+- [Rule source](${sourceUrlPrefix}src/rules/${page.file.stem}.ts)
+- [Test source](${getUrlForRuleTest(page.file.stem)})
+    `,
   );
 
   // Also add a notice about coming from ESLint core for extension rules