docs: add linting and code snippet validation (#1983)

* Add linting and code snippet validation for docs

* Remove unused link checkers

* Add link checking to CONTRIBUTING.md and remove package-lock.json

* update pnpm lockfile to sync with package.json

* feedback from Benjie

* build docs locally to test broken links

* fix failing build

* fix another snippets ignore

---------

Co-authored-by: Saihajpreet Singh <[email protected]>

Author: sarahxsanders

.eslintrc.cjs

@@ -1,18 +1,14 @@
 /* eslint-env node */
 
 const CODE_EXT = "js,jsx,cjs,mjs,ts,tsx,cts,mts"
-
 const MARKDOWN_EXT = "md,mdx"
 
 module.exports = {
   root: true,
+  plugins: ["@graphql-eslint", "mdx", "@typescript-eslint", "tailwindcss"],
   overrides: [
     {
       files: [`**/*.{${CODE_EXT}}`],
-      // TODO: extract graphql documents from code files
-      // to lint graphql documents marked with /* GraphQL */ comments inside js/ts codeblocks in markdown
-      // processor: '@graphql-eslint/graphql',
-      // plugins: ['@graphql-eslint'],
       extends: [
         "eslint:recommended",
         "plugin:@typescript-eslint/recommended",
@@ -34,7 +30,6 @@ module.exports = {
           },
         ],
         "prefer-const": ["error", { destructuring: "all" }],
-        // TODO: fix below
         "prefer-rest-params": "off",
         "@typescript-eslint/no-explicit-any": "off",
         "@typescript-eslint/no-unused-vars": "off",
@@ -51,27 +46,45 @@ module.exports = {
     {
       files: [`**/*.{${MARKDOWN_EXT}}`],
       parser: "eslint-mdx",
+      extends: ["plugin:mdx/recommended"],
       processor: "mdx/remark",
-      plugins: ["mdx"],
       parserOptions: {
         ecmaVersion: 13,
         sourceType: "module",
       },
       settings: {
         "mdx/code-blocks": true,
+        "mdx/language-mapper": {
+          js: "espree",
+          graphql: "@graphql-eslint/parser",
+          ts: "@typescript-eslint/parser",
+          typescript: "@typescript-eslint/parser",
+        },
       },
       rules: {
         "mdx/remark": "error",
       },
     },
     {
-      files: [`**/*.{${MARKDOWN_EXT}}/*.{${CODE_EXT}}`],
+      files: ["**/*.graphql"],
+      parser: "@graphql-eslint/parser",
       rules: {
-        "no-unused-labels": "off",
-        "no-undef": "off",
-        "no-redeclare": "off",
-        "no-import-assign": "off",
-        "no-prototype-builtins": "off",
+        "@graphql-eslint/no-syntax-errors": "error",
+        "@graphql-eslint/unique-operation-name": "error",
+        "@graphql-eslint/unique-fragment-name": "error",
+        "@graphql-eslint/no-anonymous-operations": "warn",
+        "@graphql-eslint/lone-anonymous-operation": "error",
+        "@graphql-eslint/no-duplicate-fields": "error",
+        "@graphql-eslint/no-unused-fragments": "warn",
+        "@graphql-eslint/no-duplicate-fragment-names": "error",
+        "@graphql-eslint/no-undefined-variables": "error",
+        "@graphql-eslint/unique-variable-names": "error",
+      },
+    },
+    {
+      files: [`**/*.{${CODE_EXT}}`, `**/*.{${MARKDOWN_EXT}}`],
+      parserOptions: {
+        plugins: ["graphql"],
       },
     },
     {
@@ -84,9 +97,5 @@ module.exports = {
         "mdx/remark": "off",
       },
     },
-    {
-      files: ["**/*.graphql"],
-      parser: "@graphql-eslint/eslint-plugin",
-    },
   ],
 }

.github/workflows/docs-validation.yml

@@ -0,0 +1,64 @@
+# Docs validation workflow runs on each PR on main w/ broken link checker
+# and code snippet validation
+
+name: Docs validation
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+link-check:
+  name: Broken link checker
+  runs-on: ubuntu-latest
+
+  steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: "20"
+        cache: "pnpm"
+
+    - name: Install dependencies
+      run: pnpm install --frozen-lockfile
+
+    - name: Build static site
+      run: pnpm build
+
+    - name: Set up Rust
+      uses: actions-rs/toolchain@v1
+      with:
+        toolchain: stable
+
+    - name: Install lychee
+      run: cargo install lychee
+
+    - name: Check links
+      run: lychee --verbose --no-progress './out/**/*.html'
+
+code-validate:
+  name: Code snippet and GraphQL validation
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+
+    - uses: actions/setup-node@v4
+      with:
+        node-version: "20"
+        cache: "pnpm"
+
+    - name: Install dependencies
+      run: pnpm install --frozen-lockfile
+
+    - name: Run validation w/ annotations
+      run: pnpm lint:docs:ci
+
+    - name: Validate code snippets
+      run: pnpm validate:snippets

CONTRIBUTING.md

@@ -10,6 +10,7 @@ There are many ways to get involved. Follow this guide and feel free to [reach o
 
 - [Development guide](#development-guide)
   - [Running the site locally](#running-the-site-locally)
+  - [Checking for broken links](#checking-for-broken-links)
   - [Branching](#branching)
   - [Project structure](#project-structure)
   - [Publishing the updated site](#publishing-the-updated-site)
@@ -53,6 +54,21 @@ Finally, open http://localhost:3000 to view it in the browser.
 
 The GraphQL website is built with [Nextra](https://nextra.site). This means that a hot-reloading development environment will be accessible by default.
 
+### Checking for broken links
+
+We use [Lychee](https://github.com/lycheeverse/lychee), a Rust-based CLI tool, to check for broken links in our documentation.
+
+To install Lychee locally:
+
+1. Install Rust: https://www.rust-lang.org/tools/install
+2. After installing Rust, run:
+
+```bash
+cargo install lychee
+```
+
+With Rust and Lychee installed, run the link checker: `pnpm run check:links`.
+
 ### Branching
 
 Active development for graphql.org happens on the `source` branch. Be sure to create any new branches or direct any pull requests back to `source`.

package.json

@@ -6,14 +6,18 @@
   "packageManager": "[email protected]",
   "scripts": {
     "build": "next build && next-image-export-optimizer",
+    "check:links": "lychee --verbose --no-progress './src/pages/**/*.mdx' --base https://graphql.org",
     "dev": "next",
     "format": "pnpm format:check --write",
     "format:check": "prettier --cache --check .",
     "lint": "eslint --ignore-path .gitignore .",
+    "lint:docs": "eslint --ignore-path .gitignore src/pages/learn --format stylish",
+    "lint:docs:ci": "eslint --ignore-path .gitignore src/pages/learn --format eslint-formatter-github",
     "postbuild": "next-sitemap",
     "prebuild": "tsx src/get-github-info.ts",
     "start": "next start",
-    "test": "echo \"no tests\" && exit 1"
+    "test": "echo \"no tests\" && exit 1",
+    "validate:snippets": "node scripts/validate-snippets.js"
   },
   "dependencies": {
     "@graphql-tools/schema": "10.0.15",
@@ -23,7 +27,7 @@
     "@tailwindcss/typography": "^0.5.10",
     "autoprefixer": "^10.4.17",
     "clsx": "^2.1.0",
-    "codemirror": "5.65.1",
+    "codemirror": "^5.65.19",
     "codemirror-graphql": "1.3.2",
     "date-fns": "^2.30.0",
     "fast-glob": "^3.3.2",