chore(lint): enforce Docusaurus Link and Heading with ESLint

.github/workflows/CI.yml

@@ -48,6 +48,8 @@ jobs:
       run: npm run typecheck
     - name: 🔤 Spell Check
       run: npm run spellcheck
+    - name: 🧹 ESLint
+      run: npm run eslint
     # Docusaurus derives a heading's anchor from its text, so renaming a
     # heading moves the anchor and breaks every inbound link. An explicit id
     # survives the rename, and lets a translation keep the English anchor

.gitignore

@@ -7,6 +7,7 @@
 # Generated files
 .docusaurus
 .cache-loader
+.eslintcache
 .cspellcache
 src/components/page/reference/ReleaseNotes/release-notes.json
 

CONTRIBUTING.md

@@ -175,7 +175,11 @@ Use Markdown for links and headings whenever possible. When you need JSX, such a
 
 The build only checks links and anchors that go through Markdown or these components. A raw `<a href>` to a page that doesn't exist builds without errors, and a raw heading's `id` can't be used as a link target.
 
-Markup inside code samples is exempt, since it's example code rather than part of the page.
+Markup inside code samples is exempt, since it's example code rather than part of the page. CI fails on a raw `<a>` or heading anywhere else. To check before pushing, run:
+
+```
+npm run eslint
+```
 
 ### Reference Content
 

eslint.config.mjs

@@ -0,0 +1,48 @@
+import docusaurus from '@docusaurus/eslint-plugin';
+import tsParser from '@typescript-eslint/parser';
+import * as mdx from 'eslint-plugin-mdx';
+
+import versions from './versions.json' with { type: 'json' };
+
+// The current docs plus every older version still built, so an archived
+// version drops out of the lint as soon as it leaves versions.json.
+const docsDirs = ['docs', ...versions.map((version) => `versioned_docs/version-${version}`)];
+
+/**
+ * The build only checks links and anchors that go through Markdown or the
+ * Docusaurus `Link` and `Heading` components. A raw `<a>` or `<h1>` to `<h6>`
+ * is invisible to those checks, so these rules require the components.
+ */
+const rules = {
+  '@docusaurus/no-html-links': 'error',
+  '@docusaurus/prefer-docusaurus-heading': 'error',
+};
+
+export default [
+  {
+    // Generated from other repos when the site builds, so they are not edited here.
+    ignores: docsDirs.flatMap((dir) => [`${dir}/native/**`, `${dir}/cli/commands/**`]),
+  },
+  {
+    // Swizzled theme files keep upstream's eslint-disable comments for rules
+    // this repo does not run.
+    linterOptions: { reportUnusedDisableDirectives: 'off' },
+  },
+  {
+    // .ts files cannot contain JSX, so they have nothing for these rules to check.
+    files: ['src/**/*.{js,jsx,tsx}'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: { ecmaFeatures: { jsx: true } },
+    },
+    plugins: { '@docusaurus': docusaurus },
+    rules,
+  },
+  {
+    ...mdx.flat,
+    // Code samples are page content, not markup, so they are not linted.
+    files: docsDirs.map((dir) => `${dir}/**/*.mdx`),
+    plugins: { ...mdx.flat.plugins, '@docusaurus': docusaurus },
+    rules: { ...mdx.flat.rules, ...rules },
+  },
+];