From 9d3e13a68f6e2fb0d10bc486c33d271d5bb236bb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9Cljm42=E2=80=9D?= <“larry_meaney@iname.com”>
Date: Wed, 13 May 2026 10:52:07 -0700
Subject: [PATCH 1/2] Add optional VS Code devcontainer
---
.devcontainer/Dockerfile | 62 +++++++++++++++++++++++++++++++++
.devcontainer/devcontainer.json | 48 +++++++++++++++++++++++++
.gitignore | 1 +
README.md | 16 +++++++++
package.json | 4 +--
scripts/run-docusaurus.mjs | 48 +++++++++++++++++++++++++
6 files changed, 177 insertions(+), 2 deletions(-)
create mode 100644 .devcontainer/Dockerfile
create mode 100644 .devcontainer/devcontainer.json
create mode 100644 scripts/run-docusaurus.mjs
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 00000000000..21b3ef0280d
--- /dev/null
+++ b/.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
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 00000000000..46e071594ca
--- /dev/null
+++ b/.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"
+ }
+ }
+ }
+}
diff --git a/.gitignore b/.gitignore
index dd631d5aca8..808ebc903a1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
# Dependencies
/node_modules
+.pnpm-store/
# Production
/build
diff --git a/README.md b/README.md
index 35ef98918f6..0329bc5483b 100644
--- a/README.md
+++ b/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.
+
(back to top)
diff --git a/package.json b/package.json
index c9f94270fba..d801cb8f0af 100644
--- a/package.json
+++ b/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",
diff --git a/scripts/run-docusaurus.mjs b/scripts/run-docusaurus.mjs
new file mode 100644
index 00000000000..a42a116571c
--- /dev/null
+++ b/scripts/run-docusaurus.mjs
@@ -0,0 +1,48 @@
+#!/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 ");
+ 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";
+
+console.log(`Starting Docusaurus ${commandName} on ${host}:${port}`);
+
+const child = spawn(
+ command,
+ ["exec", "docusaurus", commandName, "--host", host, "--port", port],
+ {
+ 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);
+});
From e891d3c375f110f050977263e9b965f7825f8a6c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9Cljm42=E2=80=9D?= <“larry_meaney@iname.com”>
Date: Wed, 13 May 2026 11:04:34 -0700
Subject: [PATCH 2/2] Forward Docusaurus wrapper arguments
---
scripts/run-docusaurus.mjs | 12 +++++++++++-
1 file changed, 11 insertions(+), 1 deletion(-)
diff --git a/scripts/run-docusaurus.mjs b/scripts/run-docusaurus.mjs
index a42a116571c..020c922e81f 100644
--- a/scripts/run-docusaurus.mjs
+++ b/scripts/run-docusaurus.mjs
@@ -19,12 +19,22 @@ if (!Object.hasOwn(defaultPorts, commandName)) {
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],
+ [
+ "exec",
+ "docusaurus",
+ commandName,
+ "--host",
+ host,
+ "--port",
+ port,
+ ...passthroughArgs,
+ ],
{
stdio: "inherit",
},