Add optional VS Code devcontainer

.devcontainer/Dockerfile

@@ -0,0 +1,62 @@
+FROM node:24.15.0-bookworm
+
+ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0
+ENV DEBIAN_FRONTEND=noninteractive
+ARG ACTIONLINT_VERSION=1.7.12
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        bash-completion \
+        build-essential \
+        ca-certificates \
+        curl \
+        dnsutils \
+        findutils \
+        gawk \
+        gh \
+        git \
+        git-lfs \
+        iputils-ping \
+        jq \
+        less \
+        lsof \
+        netcat-openbsd \
+        nvi \
+        openssh-client \
+        pkg-config \
+        procps \
+        python3 \
+        ripgrep \
+        rsync \
+        shellcheck \
+        sudo \
+        tree \
+        unzip \
+        xz-utils \
+        zip \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN set -eux; \
+    case "$(uname -m)" in \
+        x86_64) actionlint_arch="amd64"; actionlint_sha256="8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8" ;; \
+        aarch64|arm64) actionlint_arch="arm64"; actionlint_sha256="325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6" ;; \
+        *) echo "Unsupported actionlint architecture: $(uname -m)" >&2; exit 1 ;; \
+    esac; \
+    curl -fsSL "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_${actionlint_arch}.tar.gz" -o /tmp/actionlint.tar.gz; \
+    echo "${actionlint_sha256}  /tmp/actionlint.tar.gz" | sha256sum -c -; \
+    tar -xzf /tmp/actionlint.tar.gz -C /usr/local/bin actionlint; \
+    chmod +x /usr/local/bin/actionlint; \
+    rm /tmp/actionlint.tar.gz
+
+RUN corepack enable \
+    && corepack prepare pnpm@10.33.2 --activate \
+    && usermod -l vscode node \
+    && groupmod -n vscode node \
+    && usermod -d /home/vscode -m vscode \
+    && usermod -aG sudo vscode \
+    && echo 'vscode ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/90-vscode \
+    && chmod 0440 /etc/sudoers.d/90-vscode \
+    && mkdir -p /workspaces/docs \
+    && chown -R vscode:vscode /workspaces /home/vscode
+
+WORKDIR /workspaces/docs

.devcontainer/devcontainer.json

@@ -0,0 +1,48 @@
+{
+  "name": "docs",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "remoteUser": "vscode",
+  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+  "containerEnv": {
+    "COREPACK_ENABLE_DOWNLOAD_PROMPT": "0",
+    "DOCUSAURUS_BIND_HOST": "0.0.0.0"
+  },
+  "remoteEnv": {
+    "DOCUSAURUS_BIND_HOST": "0.0.0.0"
+  },
+  "mounts": [
+    "source=gh-config,target=/home/vscode/.config/gh,type=volume"
+  ],
+  "postCreateCommand": "sudo chown -R vscode:vscode /home/vscode/.config && corepack enable && pnpm install --store-dir /home/vscode/.local/share/pnpm/store --frozen-lockfile --prefer-offline",
+  "postStartCommand": "sudo chown -R vscode:vscode /home/vscode/.config",
+  "forwardPorts": [
+    3000,
+    3001
+  ],
+  "portsAttributes": {
+    "3000": {
+      "label": "Docusaurus static preview",
+      "onAutoForward": "notify"
+    },
+    "3001": {
+      "label": "Docusaurus",
+      "onAutoForward": "notify"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "davidanson.vscode-markdownlint",
+        "esbenp.prettier-vscode",
+        "github.vscode-github-actions",
+        "redhat.vscode-yaml",
+        "unifiedjs.vscode-mdx"
+      ],
+      "settings": {
+        "typescript.tsdk": "node_modules/typescript/lib"
+      }
+    }
+  }
+}

.gitignore

@@ -1,5 +1,6 @@
 # Dependencies
 /node_modules
+.pnpm-store/
 
 # Production
 /build

README.md

@@ -127,6 +127,22 @@ nvm use
    pnpm install
    ```
 
+### Optional: VS Code Dev Container
+
+This repo includes a VS Code dev container for contributors who want a local environment that closely matches the GitHub Actions Ubuntu/Node/pnpm setup.
+
+To use it:
+
+1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) or another compatible container runtime.
+2. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) for VS Code.
+3. Open this repo in VS Code and choose **Dev Containers: Reopen in Container**.
+
+The container uses the Node.js version from `.nvmrc`, enables Corepack/pnpm, installs repo dependencies, forwards the Docusaurus dev server on port `3001`, and includes useful CLI tools such as `git`, `gh`, `jq`, `ripgrep`, `nvi`, `shellcheck`, and `actionlint`.
+
+Once the container is ready, see [Usage](#usage) for local development commands.
+
+VS Code Dev Containers can share host Git credentials with the container. See [Sharing Git credentials with your container](https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials) for SSH agent and credential-helper setup. GitHub CLI authentication is separate; run `gh auth login` inside the container if you need authenticated `gh` commands. The container stores GitHub CLI config in a Docker named volume (`gh-config`) so `gh` authentication can persist across dev container rebuilds and can be shared with other dev containers on the same Docker engine.
+
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 <!-- USAGE EXAMPLES -->

package.json

@@ -4,12 +4,12 @@
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
-    "start": "docusaurus start --port 3001",
+    "start": "node scripts/run-docusaurus.mjs start",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
-    "serve": "docusaurus serve",
+    "serve": "node scripts/run-docusaurus.mjs serve",
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc",
     "lint:mdx": "remark . --ext .md,.mdx --quiet --frail",

scripts/run-docusaurus.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+
+const commandName = process.argv[2];
+const defaultPorts = {
+  serve: "3000",
+  start: "3001",
+};
+
+if (!Object.hasOwn(defaultPorts, commandName)) {
+  console.error("Usage: node scripts/run-docusaurus.mjs <start|serve>");
+  process.exit(1);
+}
+
+// Docusaurus defaults to localhost, which is right for direct local runs.
+// Dev containers set DOCUSAURUS_BIND_HOST=0.0.0.0 so VS Code/Docker can
+// forward container ports for both the dev server and static preview server.
+const host = process.env.DOCUSAURUS_BIND_HOST || "localhost";
+const port = process.env.DOCUSAURUS_PORT || defaultPorts[commandName];
+const command = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
+const passthroughArgs = process.argv.slice(3);
+
+console.log(`Starting Docusaurus ${commandName} on ${host}:${port}`);
+
+const child = spawn(
+  command,
+  [
+    "exec",
+    "docusaurus",
+    commandName,
+    "--host",
+    host,
+    "--port",
+    port,
+    ...passthroughArgs,
+  ],
+  {
+    stdio: "inherit",
+  },
+);
+
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, () => {
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  });
+}
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code ?? 1);
+});