feat(docs): replace Mintlify with a Nextra site + Cloudflare Pages deploy

Author: dylan-sutton-chavez

.github/workflows/README.md

@@ -15,19 +15,21 @@ check -> wasm -> runtime -> demo
 | `cli.yml` | Standalone (not part of the pipeline above): builds and tests `cli/`; on `main` pushes also publishes the release binary + `cli/setup/` scripts (`install.sh`, `uninstall.sh`) to GitHub Pages |
 | `host.yml` | Standalone: deno-lints and tests each host capability (`dom`, `network`, `storage`, `time`) in headless Chromium; on `main` pushes also deploys their ESM sources to Cloudflare Pages (`edge-python-host`) |
 | `std.yml` | Standalone: clippy + build + optimize + test each stdpkg (`json`, `re`, `math` as wasm; `test` is pure Edge Python, so its steps skip the wasm build and only run the corpus); on `main` pushes also deploys the per-package `.wasm` to Cloudflare Pages (`edge-python-std`) |
+| `docs.yml` | Standalone (triggered only by `docs/**` changes): `npm ci` + `next build` static export of the Nextra docs (`docs/out`, sitemap via `postbuild`); PRs build only, `main` pushes also deploy to Cloudflare Pages (`edge-python-docs`) |
 
 ## Cloudflare Pages
 
-Four **Direct Upload** projects, Actions pushes prebuilt directories via `wrangler pages deploy`; Cloudflare doesn't clone or build.
+Five **Direct Upload** projects, Actions pushes prebuilt directories via `wrangler pages deploy`; Cloudflare doesn't clone or build.
 
 | Project | Source | Production URL |
 |---------|--------|----------------|
 | `edge-python-demo` | `demo/` (wasm hashed for `version.json`, not bundled) | `https://edge-python-demo.pages.dev` |
 | `edge-python-runtime` | `runtime/` + bundled `compiler_lib.wasm` | `https://edge-python-runtime.pages.dev` |
 | `edge-python-host` | `host/<cap>/src/` for each capability, flattened to `<cap>/` | `https://edge-python-host.pages.dev` |
 | `edge-python-std` | per-package optimized `.wasm` from `std/<pkg>/` | `https://edge-python-std.pages.dev` |
+| `edge-python-docs` | `docs/out` (Nextra static export) | `https://edgepython.com` (custom domain; also `https://edge-python-docs.pages.dev`) |
 
-All four deploys run **only on pushes to `main`** and are pinned to the production `main` branch in the matching workflow (`_runtime.yml` / `_demo.yml` / `host.yml` / `std.yml`). PRs and tags never deploy; the next `main` push refreshes the projects.
+All five deploys run **only on pushes to `main`** and are pinned to the production `main` branch in the matching workflow (`_runtime.yml` / `_demo.yml` / `host.yml` / `std.yml` / `docs.yml`). PRs and tags never deploy; the next `main` push refreshes the projects.
 
 ### Cloudflare and GitHub setup
 
@@ -36,8 +38,11 @@ All four deploys run **only on pushes to `main`** and are pinned to the producti
 npx wrangler login
 npx wrangler pages project create edge-python-demo --production-branch=main
 npx wrangler pages project create edge-python-runtime --production-branch=main
+npx wrangler pages project create edge-python-docs --production-branch=main
 ```
 
+`edge-python-docs` serves `edgepython.com` (replacing the old Mintlify docs): after the first deploy, add `edgepython.com` as a custom domain on the project (Pages -> Custom domains) and remove it from Mintlify.
+
 Repo secrets (*Settings -> Secrets and variables -> Actions*):
 
 - `CLOUDFLARE_API_TOKEN`, `Account -> Cloudflare Pages -> Edit`. Create via dashboard: <https://dash.cloudflare.com/profile/api-tokens>.

.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**", ".github/workflows/docs.yml"]
+  pull_request:
+    branches: [main]
+    paths: ["docs/**", ".github/workflows/docs.yml"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Build the docs static export and deploy it to Cloudflare Pages.
+  deploy:
+    name: Cloudflare Pages
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      # Reproducible install from the committed lockfile.
+      - name: Install
+        working-directory: docs
+        run: npm ci
+
+      # `output: 'export'` makes `next build` emit a fully static site to docs/out.
+      - name: Build
+        working-directory: docs
+        run: npm run build
+
+      # Deploy only on main pushes; PRs stop after a successful build.
+      - name: Deploy to Cloudflare Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: cloudflare/wrangler-action@v4
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          # Pin to the Pages production branch (job is already gated to main).
+          command: pages deploy docs/out --project-name=edge-python-docs --branch=main

.gitignore

@@ -22,6 +22,12 @@ node_modules/
 dist/
 *.log
 
+# Next.js / Nextra (docs)
+.next/
+**/.next/
+out/
+**/out/
+
 # WASM
 pkg/
 **/pkg/

docs/README.md

@@ -0,0 +1,28 @@
+# Edge Python Docs
+
+## Local Development
+Install dependencies
+
+```sh
+npm install
+```
+
+To run locally:
+
+```sh
+npm run dev
+```
+
+Submit a PR to Edge Python.
+
+## Note on dev speed
+
+In dev (`npm run dev`), the first visit to each page takes a few seconds because
+Next.js compiles routes **on demand** (slower here since the repo lives on the
+Windows drive mounted in WSL, `/mnt/c`). Once a page is compiled, navigation is
+instant.
+
+This does **not** happen in production: `npm run build` pre-renders every page at
+build time (Nextra is static/SSG), so the deployed site serves pre-built HTML and all
+navigation is instant.
+

docs/docs.json

@@ -0,0 +1,12 @@
+/* Centers nav links on x-axis; logo stays left, search/icons right. */
+
+.nextra-nav-container nav {
+  position: relative;
+}
+
+.nextra-nav-container nav > div.nextra-scrollbar {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  transform: translate(-50%, -50%);
+}

docs/globals.css

@@ -0,0 +1,22 @@
+import nextra from 'nextra'
+
+const withNextra = nextra({
+    theme: 'nextra-theme-docs',
+    themeConfig: './theme.config.jsx',
+})
+
+export default withNextra({
+    // Static export for Cloudflare Pages Direct Upload (-> out/).
+    output: 'export',
+    images: { unoptimized: true },
+    // Dev convenience only: redirect the root to the first page. `output: 'export'` ignores this (Cloudflare serves the redirect via public/_redirects in prod).
+    async redirects() {
+        return [
+        {
+            source: '/',
+            destination: '/getting-started/quickstart',
+            permanent: false,
+        },
+        ]
+    },
+})