Forbid h1 # ... elements, enforce h2 ## ... as first heading on page (#334)

Author: Dimitri POSTOLOV

.eslintrc.cjs

@@ -0,0 +1,28 @@
+module.exports = {
+  root: true,
+  overrides: [
+    {
+      files: ['*.{ts,tsx,js,jsx,mjs,cjs}'],
+      extends: ['@edgeandnode/eslint-config', '@edgeandnode/eslint-config/next'],
+      settings: {
+        next: { rootDir: 'website' },
+      },
+    },
+    {
+      files: ['*.{ts,tsx}'],
+      parserOptions: {
+        project: 'tsconfig.json',
+      },
+    },
+    {
+      // We lint only english pages because other languages will be translated from english
+      files: ['website/pages/en/**/*.{md,mdx}'],
+      parser: 'eslint-mdx',
+      processor: 'mdx/remark',
+      plugins: ['mdx'],
+      rules: {
+        'mdx/remark': 'error',
+      },
+    },
+  ],
+}

.eslintrc.js

@@ -0,0 +1,8 @@
+module.exports = {
+  plugins: [
+    'frontmatter', // should be defined
+    ['remark-lint-first-heading-level', 2],
+    ['remark-lint-restrict-elements', { type: 'heading', depth: 1 }],
+    // 'remark-lint-heading-increment',
+  ],
+}

.remarkrc.cjs

@@ -11,8 +11,8 @@
     "docker:clean": "docker builder prune",
     "docker:up": "docker run --rm -it -p 3000:80 -v \"$(pwd)/nginx.conf:/etc/nginx/nginx.conf\" docs",
     "export": "pnpm --filter @graphprotocol/docs export",
-    "lint": "eslint . --cache --ext .js,.jsx,.ts,.tsx,.mjs --ignore-path .gitignore --max-warnings 0",
-    "lint:fix": "eslint . --cache --ext .js,.jsx,.ts,.tsx,.mjs --ignore-path .gitignore --fix && pnpm prettier",
+    "lint": "eslint . --cache --ignore-path .gitignore --max-warnings 0",
+    "lint:fix": "eslint . --cache --ignore-path .gitignore --fix && pnpm prettier",
     "pre-commit": "lint-staged --concurrent false",
     "pre-push": "pnpm build",
     "prepare": "husky install && chmod +x .husky/*",
@@ -23,11 +23,16 @@
   },
   "devDependencies": {
     "@edgeandnode/eslint-config": "^1.3.1",
-    "eslint": "^8.38.0",
+    "eslint": "^8.39.0",
+    "eslint-plugin-mdx": "^2.0.5",
     "husky": "^8.0.3",
     "lint-staged": "^13.2.1",
-    "prettier": "^2.8.7",
+    "prettier": "^2.8.8",
     "prettier-plugin-pkg": "^0.17.1",
+    "remark-frontmatter": "^4.0.1",
+    "remark-lint-first-heading-level": "^3.1.1",
+    "remark-lint-heading-increment": "^3.1.1",
+    "remark-lint-restrict-elements": "workspace:*",
     "typescript": "5.0.4"
   },
   "lint-staged": {

package.json

@@ -0,0 +1,22 @@
+import { lintRule } from 'unified-lint-rule'
+import { visit } from 'unist-util-visit'
+
+export default lintRule(
+  {
+    origin: 'remark-lint:restrict-elements',
+    url: '',
+  },
+  /** @type {import('unified-lint-rule').Rule<Root, void>} */
+  (tree, file, settings) => {
+    if (!settings) {
+      throw new Error('Missing config with restrict elements')
+    }
+    const selectors = Array.isArray(settings) ? settings : [settings]
+
+    for (const selector of selectors) {
+      visit(tree, settings, (node) => {
+        file.message(`Element ${JSON.stringify(selector)} is restricted`, node)
+      })
+    }
+  }
+)

packages/remark-lint-restrict-elements/index.js

@@ -0,0 +1,19 @@
+{
+  "name": "remark-lint-restrict-elements",
+  "version": "0.0.0",
+  "type": "module",
+  "author": "Dimitri POSTOLOV <[email protected]>",
+  "module": "index.js",
+  "keywords": [
+    "remark",
+    "lint",
+    "rule",
+    "remark forbid elements",
+    "remark restricts elements"
+  ],
+  "dependencies": {
+    "unified-lint-rule": "^2.1.1",
+    "unist-util-visit": "^4.1.2"
+  },
+  "sideEffects": false
+}