Redesign (v2)

.eslintrc.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 const isVSCode = Boolean(process.env.VSCODE_PID)
 
 /** @type {import('eslint').Linter.Config} */
@@ -21,7 +23,11 @@ module.exports = {
       // Only lint the English pages because the Markdown for the other languages is auto-generated from English (via Crowdin).
       // But include all languages when running the ESLint extension in VS Code (in case the user has "eslint.validate": ["mdx"]),
       // otherwise there will be random errors since the non-English files don't match any ruleset.
-      files: [`website/pages/${!isVSCode ? 'en/' : ''}**/*.{md,mdx}`],
+      files: [`website/src/pages/${isVSCode ? '' : 'en/'}**/*.{md,mdx}`],
+      excludedFiles: [
+        'website/src/pages/*/subgraphs/developing/creating/graph-ts/*.md',
+        'website/src/pages/*/subgraphs/querying/graph-client/*.md',
+      ],
       parser: 'eslint-mdx',
       processor: 'mdx/remark',
       plugins: ['mdx'],

.github/workflows/ci-cd-pull-request.yml

@@ -19,10 +19,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up env
-        uses: the-guild-org/shared-config/setup@main
-        with:
-          nodeVersion: 20
-          packageManager: pnpm
+        uses: the-guild-org/shared-config/setup@v1
 
       - name: Install dependencies
         run: pnpm install
@@ -43,10 +40,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up env
-        uses: the-guild-org/shared-config/setup@main
-        with:
-          nodeVersion: 20
-          packageManager: pnpm
+        uses: the-guild-org/shared-config/setup@v1
 
       - name: Install dependencies
         run: pnpm install
@@ -67,10 +61,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up env
-        uses: the-guild-org/shared-config/setup@main
-        with:
-          nodeVersion: 20
-          packageManager: pnpm
+        uses: the-guild-org/shared-config/setup@v1
 
       - name: Install dependencies
         run: pnpm install
@@ -92,10 +83,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up env
-        uses: the-guild-org/shared-config/setup@main
-        with:
-          nodeVersion: 20
-          packageManager: pnpm
+        uses: the-guild-org/shared-config/setup@v1
 
       - name: Install dependencies
         run: pnpm install

.github/workflows/opengraph.yml

@@ -24,10 +24,7 @@ jobs:
           ref: ${{ env.COMMIT }}
 
       - name: Set up env
-        uses: the-guild-org/shared-config/setup@main
-        with:
-          nodeVersion: 20
-          packageManager: pnpm
+        uses: the-guild-org/shared-config/setup@v1
 
       - name: Deploy
         working-directory: ./packages/og-image

.github/workflows/website-integrity.yml

@@ -21,10 +21,7 @@ jobs:
         run: git fetch origin main
 
       - name: Set up env
-        uses: the-guild-org/shared-config/setup@main
-        with:
-          nodeVersion: 20
-          packageManager: pnpm
+        uses: the-guild-org/shared-config/setup@v1
 
       - name: Build Site
         run: pnpm build

.gitignore

@@ -37,5 +37,5 @@ build/
 .eslintcache
 dist/
 .turbo/
-packages/og-image/vender/*.wasm
+packages/og-image/vendor/*.wasm
 .wrangler/

.nvmrc

@@ -1 +1 @@
-20
+22

.prettierignore

@@ -3,4 +3,6 @@
 out/
 pnpm-lock.yaml
 dist/
-website/remote-files/*.json
+# ignore below md since they are fetched from GitHub
+website/src/pages/*/subgraphs/developing/creating/graph-ts/*.md
+website/src/pages/*/subgraphs/querying/graph-client/*.md

.remarkrc.mjs

@@ -1,6 +1,12 @@
+import remarkFrontmatter from 'remark-frontmatter'
+
+/**
+ * This config is used by `eslint-plugin-mdx` to lint the MDX files, not by Nextra.
+ * Nextra uses the remark and rehype plugins registered in `next.config.js`, under `mdxOptions`.
+ */
 export default {
   plugins: [
-    'frontmatter', // should be defined
+    remarkFrontmatter,
     ['remark-lint-first-heading-level', 2],
     ['remark-lint-restrict-elements', { type: 'heading', depth: 1 }],
     'remark-lint-heading-increment',

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:20-alpine as builder
+FROM node:22-alpine AS builder
 
 ARG ENVIRONMENT
 ARG ORIGIN
@@ -14,14 +14,11 @@ RUN corepack enable pnpm
 
 WORKDIR /app
 
-COPY . .
-
-# install the packages
-RUN pnpm install --frozen-lockfile --ignore-scripts
+COPY . ./
 
+RUN pnpm install --frozen-lockfile
 RUN pnpm build
 
-## production environment
 FROM nginx:1.16.0-alpine
 
 COPY --from=builder ./app/nginx.conf /etc/nginx/

README.md

@@ -8,7 +8,7 @@ Please read [`CONTRIBUTING.md`](https://github.com/graphprotocol/docs/blob/main/
 
 ## Local Setup
 
-This project is built on [Next.js](https://nextjs.org/). You can run it on your machine, provided you have [Node 20+](https://nodejs.org/en/) and [`pnpm`](https://pnpm.io) installed.
+This project is built on [Next.js](https://nextjs.org/). You can run it on your machine, provided you have [Node 22+](https://nodejs.org/en/) and [`pnpm`](https://pnpm.io) installed.
 
 First, clone the repo:
 

crowdin.yml

@@ -1,12 +1,10 @@
 preserve_hierarchy: 1
 files:
-  - source: /website/pages/en/**/*.mdx
-    ignore:
-      - '/website/pages/en/**/\[\[...slug\]\].mdx'
-    translation: /website/pages/%two_letters_code%/**/%original_file_name%
+  - source: /website/src/pages/en/**/*.mdx
+    translation: /website/src/pages/%two_letters_code%/**/%original_file_name%
     dest: /**/%original_file_name%
     content_segmentation: 0
-  - source: /website/pages/en/**/*.json
-    translation: /website/pages/%two_letters_code%/**/%original_file_name%
+  - source: /website/src/pages/en/**/*.json
+    translation: /website/src/pages/%two_letters_code%/**/%original_file_name%
     dest: /**/%original_file_name%
     content_segmentation: 0

nginx.conf

@@ -33,6 +33,10 @@ http {
         root /usr/share/nginx/html;
         index index.html index.htm;
 
+        # Short cache with revalidation
+        add_header Cache-Control "no-cache, must-revalidate";
+        expires 5m;
+
         # Redirect `http` to `https`
         if ($http_x_forwarded_proto = "http") {
             return 301 https://$host$request_uri;
@@ -150,13 +154,11 @@ http {
 
         location / {
             try_files $uri $uri.html $uri/index.html =404;
-
-            add_header Cache-Control 'no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0';
-            expires -1;
         }
 
+        # Use localized 404 pages for documentation paths
         location ~ ^/docs/([a-zA-Z][a-zA-Z])/(.*) {
-            error_page 404 /docs/$1/404/index.html;
+            try_files $uri $uri.html $uri/index.html /docs/$1/404/index.html;
         }
 
         error_page 500 502 503 504 /docs/50x/index.html;

package.json

@@ -1,34 +1,36 @@
 {
-  "name": "the-graph-docs-monorepo",
+  "name": "graph-docs",
   "private": true,
-  "packageManager": "pnpm@10.1.0",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.3.0",
   "scripts": {
-    "dev": "turbo run dev --parallel",
+    "dev": "turbo run dev",
     "build": "NODE_OPTIONS='--max_old_space_size=4096' turbo run build",
-    "docker:build": "source ./website/.env.local && DOCKER_BUILDKIT=1 docker build . -t docs --no-cache --build-arg ENVIRONMENT=$ENVIRONMENT --build-arg ORIGIN=$ORIGIN",
-    "docker:clean": "docker builder prune",
-    "docker:up": "docker run --rm -it -p 3000:80 -v \"$(pwd)/nginx.conf:/etc/nginx/nginx.conf\" docs",
     "check": "pnpm typecheck && pnpm lint && pnpm prettier:check",
     "check:fix": "pnpm lint:fix; pnpm prettier",
+    "lint": "eslint . --ignore-path .gitignore --max-warnings 0",
+    "lint:fix": "eslint . --ignore-path .gitignore --fix",
+    "prettier": "prettier . --write --list-different",
+    "prettier:check": "prettier . --check",
     "typecheck": "turbo run typecheck",
-    "lint": "eslint . --cache --ignore-path .gitignore --max-warnings 0",
-    "lint:fix": "eslint . --cache --ignore-path .gitignore --fix; pnpm prettier",
-    "prettier": "pnpm prettier:check --write",
-    "prettier:check": "prettier --cache --check .",
-    "test": "turbo run test"
+    "test": "turbo run test",
+    "docker:build": "source ./website/.env.local && DOCKER_BUILDKIT=1 docker build . -t docs --no-cache --build-arg ENVIRONMENT=$ENVIRONMENT --build-arg ORIGIN=$ORIGIN",
+    "docker:clean": "docker builder prune",
+    "docker:up": "docker run --rm -it -p 3000:80 -v \"$(pwd)/nginx.conf:/etc/nginx/nginx.conf\" docs"
   },
   "devDependencies": {
     "@edgeandnode/eslint-config": "^2.0.3",
+    "@types/node": "^22.13.4",
     "eslint": "^8.57.1",
-    "eslint-plugin-mdx": "^2.3.4",
-    "prettier": "^3.4.2",
+    "eslint-plugin-mdx": "^3.1.5",
+    "prettier": "^3.5.1",
     "prettier-plugin-tailwindcss": "^0.6.11",
     "remark-frontmatter": "^5.0.0",
-    "remark-lint-first-heading-level": "^3.1.2",
-    "remark-lint-heading-increment": "^3.1.2",
-    "remark-lint-no-heading-punctuation": "^3.1.2",
+    "remark-lint-first-heading-level": "^4.0.1",
+    "remark-lint-heading-increment": "^4.0.1",
+    "remark-lint-no-heading-punctuation": "^4.0.1",
     "remark-lint-restrict-elements": "workspace:*",
-    "turbo": "^1.13.4",
+    "turbo": "^2.4.2",
     "typescript": "^5.7.3"
   },
   "resolutions": {