Migrate docs buildsystem from pnpm to bun (#1268)

Fixes #1082

.github/styles/config/vocabularies/TraceMachina/accept.txt

@@ -53,3 +53,5 @@ quantiles
 Config
 Grafana
 GitHub
+Deno
+shipstorm

.github/workflows/docs.yaml

@@ -0,0 +1,54 @@
+---
+name: Deploy NativeLink Docs
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions: read-all
+
+jobs:
+  deploy:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-24.04, macos-14 ]
+    name: Docs Deployment / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout
+        uses: >- # v4.1.1
+          actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+
+      - name: Install Nix
+        uses: >- # v10
+          DeterminateSystems/nix-installer-action@de22e16c4711fca50c816cc9081563429d1cf563
+
+      - name: Cache Nix derivations
+        uses: >- # v4
+          DeterminateSystems/magic-nix-cache-action@fc6aaceb40b9845a02b91e059ec147e78d1b4e41
+
+      - name: Test deployment on Ubuntu
+        if: matrix.os == 'ubuntu-24.04' && github.event_name == 'pull_request'
+        working-directory: docs
+        run: |
+          nix develop --impure --command bash -c "
+            bun staging --project=nativelink-docs --org=nativelink
+          "
+
+      - name: Test deployment on macOS
+        if: matrix.os == 'macos-14' && github.event_name == 'pull_request'
+        working-directory: docs
+        run: |
+          nix develop --impure --command bash -c "bun setup && bun run build"
+
+
+      - name: Production deployment
+        if: matrix.os == 'ubuntu-22.04' && github.ref == 'refs/heads/main'
+        working-directory: docs
+        run: |
+          nix develop --impure --command bash -c "
+            bun prod --project=nativelink-docs --org=nativelink
+          "

docs/.gitignore

@@ -1,5 +1,6 @@
 # build output
 dist/
+
 # generated types
 .astro/
 
@@ -11,7 +12,11 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
+bun-debug.log*
+bun-error.log*
 
+# tests
+test-results
 
 # environment variables
 .env
@@ -26,6 +31,9 @@ pnpm-debug.log*
 # Generated during the build and only intended to debug bundle size.
 stats.html
 
+# Deno Deploy file
+deno.json
+
 # Generated files
 src/content/docs/contribute/docs.mdx
 src/content/docs/contribute/guidelines.mdx

docs/README.md

@@ -2,76 +2,62 @@
 
 The NativeLink documentation gets deployed to <https://docs.nativelink.com>.
 
-> [!CAUTION]
-> Setup for working on these docs differs between Linux and Mac.
->
-> For Linux: Use the Nix flake and run `pnpm i`.
->
-> For Mac: If you're in the Nix flake, exit it, for instance with `direnv
-> revoke`. Then manually install `pnpm`, run `pnpm i` and run `pnpm exec
-> playwright install`.
->
-> It's a long term goal to add the automated setup to Mac.
-
 ## 📚 Stack
 
 The NativeLink documentation uses a custom, highly efficient, high performance
 stack. Getting a bunch of bleeding-edge tools to work well together can be
 challenging. Feel free to copy-paste it into your own projects.
 
 - [Diátaxis](https://diataxis.fr/) as overarching documentation philosophy.
-- [Pnpm](https://github.com/pnpm/pnpm) as production bundler.
-- [Bun](https://github.com/oven-sh/bun) as build-time TypeScript interpreter.
+- [Bun](https://github.com/oven-sh/bun) as production bundler.
 - [Biome](https://biomejs.dev/) as linting toolchain.
 - [Astro](https://astro.build/) as meta-framework.
 - [Starlight](https://starlight.astro.build/de/) as documentation framework.
 - [TailwindCSS 4.0-alpha](https://tailwindcss.com/blog/tailwindcss-v4-alpha) for
   component styling which makes use of [LightningCSS](https://lightningcss.dev/)
   for faster CSS processing.
-- [Cloudflare Pages/Workers](https://pages.cloudflare.com/) for deployments.
+- [Deno Deploy](https://deno.com/deploy) for deployments.
 
 ## 🚀 Common workflows
 
 See [`docs/package.json`](https://github.com/TraceMachina/nativelink/blob/main/docs/package.json)
 for build scripts.
 
-This project requires `pnpm`. The nix flake ships a compatible version.
+This project requires `bun`. The nix flake ships a compatible version.
 
 ```bash
-# Install dependencies with pnpm. Don't install with bun.
-pnpm install
+# Install dependencies with bun.
+bun install
 
-# Rebuild the API reference.
-pnpm metaphase
+# Rebuild the docs reference.
+bun run docs.build
 
-# Rebuild the simple parts of the autogenerated docs.
-pnpm transform
+# Generate the simple parts of the autogenerated docs.
+bun run docs.generate
 
 # Rebuild everything. Make sure to remove the `dist` directory beforehand.
-pnpm build
+bun run build
+
+# Serve the dist directory with deno
+bun serve
 
 # Run a development server. Doesn't rebuild the autogenerated parts of the docs.
-pnpm dev
+bun dev
 
 # Run formatter and linter checks.
-pnpm check
+bun check
 
 # Apply formatter and linter fixes.
-pnpm fix
+bun fix
 
-# Test cloudflare deployments locally. Useful when debugging SSR. Rebuilds the
+# Test Deno deployments locally. Useful when debugging SSR. Rebuilds the
 # autogenerated parts of the docs.
-pnpm preview
+bun preview
 ```
 
-When deploying to Cloudflare, make sure to set the `PNPM_VERSION` to `8.15.5` to
-stay in sync with the flake. Also, use `pnpm exec playwright install && pnpm
-build` on the Cloudflare worker. This sets up headless Chromium which to
-generate mermaid diagrams during the build. You don't need to set playwright up
-locally as it's already configured in the flake.
 
 ## 🐛 Known issues
 
-- The build process uses Bun as internal TypeScript processor, but can't use it
-  as bundler yet.
-- `"@playform/compress": "=0.0.12"` because `0.0.13` doesn't compress CSS.
+- `bun run docs.build` doesn't work on MacOS with the nix version of Bazel.
+  As a workaround install Bun and Bazel on your host and build the docs outside the flake.
+- `bun dev` doesn't reload the changes in the starlight.conf.ts