Migrate docs to Astro and deploy main to CoreWeave

.github/workflows/docs.yml

@@ -0,0 +1,93 @@
+name: Docs
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4
+        with:
+          package_json_file: docs/package.json
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "22"
+          cache: pnpm
+          cache-dependency-path: docs/pnpm-lock.yaml
+      - name: Install docs dependencies
+        working-directory: docs
+        run: pnpm install --frozen-lockfile
+      - name: Check and build docs with search
+        working-directory: docs
+        run: pnpm build
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: docs-site
+          path: docs/dist
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 7
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    environment:
+      name: cloudflare-docs
+      url: https://openpipe-art-docs.coreweave.workers.dev
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4
+        with:
+          package_json_file: docs/package.json
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "22"
+          cache: pnpm
+          cache-dependency-path: docs/pnpm-lock.yaml
+      - name: Install deployment dependencies
+        working-directory: docs
+        run: pnpm install --frozen-lockfile
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: docs-site
+          path: docs/dist
+      - name: Deploy CoreWeave docs Worker
+        working-directory: docs
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          WRANGLER_SEND_METRICS: "false"
+        run: |
+          if [ -z "$CLOUDFLARE_API_TOKEN" ]; then
+            echo "::error::Configure CLOUDFLARE_API_TOKEN in the cloudflare-docs environment. See docs/README.md."
+            exit 1
+          fi
+          pnpm deploy:coreweave
+      - name: Verify deployed docs and search assets
+        run: |
+          for path in getting-started/about/ getting-started/quick-start/ pagefind/pagefind.js llms.txt; do
+            curl --fail --silent --show-error --retry 5 --retry-all-errors --retry-delay 2 \
+              "https://openpipe-art-docs.coreweave.workers.dev/$path" --output /dev/null
+          done

AGENT.md

@@ -17,13 +17,14 @@ This project uses the `uv` package manager.
 
 ## Documentation
 
-- All documentation is in the `docs` directory.
-- If you add a new page, be sure to add it to the sidebar in `docs/docs.json`.
-- If you move a page, be sure to update the sidebar in `docs/docs.json` and check for any broken links.
+- All documentation is in the `docs` directory. Pages are in `docs/src/content/docs`.
+- Use Node.js 22.12+ and pnpm. Run `pnpm install --frozen-lockfile` and `pnpm build` from `docs/` to validate changes.
+- If you add a new page, be sure to add it to the sidebar in `docs/src/navigation.ts`.
+- If you move a page, be sure to update the sidebar in `docs/src/navigation.ts` and check for any broken links.
 
 ### Adding images
 
-- Add images to the `docs/images` directory
+- Add images to the `docs/public/images` directory
 - If the image is a png, first convert it to webp using `magick <input.png> <output.webp>`. Do not include the original png in the repo.
 - Use the `<Frame>` tag to add images with captions as seen in the page `checkpoint-forking.mdx`.
 

CONTRIBUTING.md

@@ -185,14 +185,16 @@ uv run sky down art
 
 ### Adding Docs
 
-We use Mintlify to serve our docs. Here are the steps for adding a new page:
-1. Clone the ART repo
-2. Open the /docs directory in your CLI and IDE
-3. Run npx mintlify dev to start serving a local version of the docs in your browser
-4. Create a new .mdx file in the relevant directory
-5. Add a title and sidebar title (see other pages for examples)
-6. In docs.json, add a link to the new page within one of the `navigation`.`groups`
-7. Ensure everything works by navigating to and viewing the page in your browser
-8. Submit a PR
+We use Astro to build our public docs from this repository.
+
+1. Open `docs/` and run `pnpm install --frozen-lockfile` with Node.js 22.12+.
+2. Run `pnpm dev` to preview the docs locally.
+3. Add a `.mdx` page under `docs/src/content/docs` with a title and description.
+4. Add the page to `docs/src/navigation.ts` and put images in `docs/public/images`.
+5. Run `pnpm build` to check the site and generate its Pagefind search index.
+6. Verify the page in your browser and submit a PR.
+
+The Docs workflow validates changes on PRs and deploys merges to `main` to the
+CoreWeave Cloudflare Worker. See `docs/README.md` for deployment configuration.
 
 When you're done, shut down your GPU instance (if using a cloud VM) or stop the local training process.

docs/.gitignore

@@ -1,2 +1,5 @@
 node_modules
-package-lock.json
+dist
+.astro
+.wrangler
+package-lock.json

docs/README.md

@@ -1,31 +1,57 @@
-# OpenPipe Documentation
+# ART Documentation
 
-This repository contains the source for the ART documentation website hosted at [https://art.openpipe.ai](https://art.openpipe.ai).
+This directory contains the source for the ART documentation website hosted at [https://art.openpipe.ai](https://art.openpipe.ai). It is a static Astro site that can be deployed to any static host.
 
 ## Prerequisites
 
-Ensure you have the following packages installed on your machine:
-
 - [pnpm](https://pnpm.io/installation)
-- [node](https://nodejs.org/en/download/)
-
-## Contributing
+- [Node.js](https://nodejs.org/en/download/)
 
-To edit the documentation follow these steps:
+## Local development
 
-1. Clone the repository
-2. Navigate to the `docs` directory
-3. Run `pnpm install` to install the dependencies
-4. Run `pnpm dev` to start the development server
-5. Edit the files in the `docs` directory
+1. Navigate to the `docs` directory.
+2. Run `pnpm install`.
+3. Run `pnpm dev` to start the development server on port 3001.
+4. Edit pages in `src/content/docs`.
 
-Edits to files should immediately be reflected in the development server.
+Edits are reflected immediately by the development server.
 
 ### Adding new pages
 
-1. Create a new .mdx file in the `docs` directory
-2. Navigate to the `mint.json` file and add the new page to the appropriate section to the `navigation` array, or create a new section. Ensure that the path to the new page is correct.
+1. Create a new `.md` or `.mdx` file in `src/content/docs`.
+2. Add the page to the appropriate group in `src/navigation.ts`.
+
+### Building and deploying
+
+Run `pnpm build` before opening a pull request. This checks the project, builds the static pages, and creates the Pagefind search index. The output in `dist` can be hosted on Cloudflare Workers, Cloudflare Pages, GitHub Pages, or another static host.
+
+### CoreWeave deployment
+
+`wrangler.coreweave.jsonc` defines the `openpipe-art-docs` Worker with Static
+Assets. It serves `dist` on the CoreWeave account's assigned `workers.dev`
+hostname, including the custom 404 page. It does not bind `art.openpipe.ai` or
+deploy to the OpenPipe `art-docs` Pages project. Canonicals, sitemap URLs, and
+`llms.txt` links retain `art.openpipe.ai` until the domain cutover.
+
+The GitHub **Docs** workflow builds docs on relevant pull requests and pushes
+to `main`. A successful build on `main` automatically deploys the same artifact
+to CoreWeave. **Run workflow** on `main` can also redeploy without a new commit.
+PR builds have no Cloudflare credentials and cannot deploy.
+
+Configure the GitHub environment **cloudflare-docs** before merging:
+
+- Secret `CLOUDFLARE_API_TOKEN`: a token scoped to that account with
+  **Account / Workers Scripts / Edit** permission. No DNS permission is needed.
+- Restrict environment deployment branches to `main`. Leave required reviewers
+  unset so documentation deployments do not require manual approval.
 
-### Deploying changes
+The workflow creates or updates the Worker. No custom domain or DNS change is
+required to test it. If the account has not enabled a `workers.dev` subdomain,
+an account administrator must configure one first. Validate the temporary URL,
+including search and existing deep links, before moving `art.openpipe.ai`.
 
-To deploy changes to the hosted docs, commit your changes in a new git branch and create a pull request. Once the pull request is merged, the changes will be deployed to the hosted docs.
+Use the workflow for deployments; no dashboard upload or local deployment is
+needed. CI uses the locked Wrangler version and does not depend on a personal
+Cloudflare login. Never commit `CLOUDFLARE_API_TOKEN`.
+The deployment config pins the CoreWeave account ID
+`81820de800df4910fe9d0efd69585ddf` so it cannot accidentally target OpenPipe.

docs/astro.config.mjs

@@ -0,0 +1,15 @@
+import { defineConfig } from "astro/config";
+import mdx from "@astrojs/mdx";
+import sitemap from "@astrojs/sitemap";
+import expressiveCode from "astro-expressive-code";
+
+export default defineConfig({
+  site: "https://art.openpipe.ai",
+  integrations: [
+    expressiveCode({
+      themes: ["github-light-default", "dark-plus"],
+    }),
+    mdx(),
+    sitemap(),
+  ],
+});

docs/package.json

@@ -1,17 +1,32 @@
 {
-  "name": "docs",
+  "name": "art-docs",
   "version": "1.0.0",
-  "description": "",
-  "main": "index.js",
+  "private": true,
+  "type": "module",
   "scripts": {
-    "dev": "mintlify dev --port 3001",
-    "build": "mintlify build",
-    "generate:routes": "npx @mintlify/scraping@latest openapi-file ./openapi.json --outDir ./api-reference"
+    "dev": "astro dev --port 3001",
+    "build": "astro check && astro build && pagefind --site dist",
+    "preview": "astro preview --port 3001",
+    "preview:cloudflare": "pnpm build && wrangler dev --config wrangler.coreweave.jsonc",
+    "check": "astro check",
+    "deploy:coreweave": "wrangler deploy --config wrangler.coreweave.jsonc"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
   "dependencies": {
-    "mintlify": "^4.0.433"
+    "@astrojs/check": "^0.9.6",
+    "@astrojs/mdx": "^7.0.8",
+    "@astrojs/sitemap": "^3.7.3",
+    "@fontsource-variable/inter": "^5.3.0",
+    "astro": "^7.2.7",
+    "astro-expressive-code": "^0.44.1",
+    "pagefind": "^1.5.2",
+    "sharp": "^0.34.4",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "wrangler": "^4.126.0"
+  },
+  "packageManager": "pnpm@10.30.3",
+  "engines": {
+    "node": ">=22.12.0"
   }
 }