feat: more work on the docs

Author: jacksyrm

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  validate:
+    name: Lint, Check, Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6.0.2
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2.1.2
+        with:
+          bun-version: latest
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6.2.0
+        with:
+          node-version: '22'
+
+      - name: Cache dependencies
+        uses: actions/cache@v5.0.3
+        with:
+          path: ~/.bun/install/cache
+          key: bun-${{ runner.os }}-${{ hashFiles('bun.lock', 'bun.lockb') }}
+          restore-keys: bun-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Type check
+        run: bun run check
+
+      - name: Build
+        run: bun run build
+
+      - name: Validate Cloudflare Worker bundle
+        run: bunx wrangler deploy --dry-run --outdir .wrangler-dry-run

.github/workflows/deploy-workers.yml

@@ -33,7 +33,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v6.2.0
         with:
-          node-version: "22"
+          node-version: '22'
 
       - name: Cache dependencies
         uses: actions/cache@v5.0.3
@@ -45,9 +45,18 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - name: Lint
+        run: bun run lint
+
+      - name: Type check
+        run: bun run check
+
       - name: Build
         run: bun run build
 
+      - name: Validate Cloudflare Worker bundle
+        run: bunx wrangler deploy --dry-run --outdir .wrangler-dry-run
+
       - name: Deploy to Cloudflare Workers
         id: deploy
         uses: cloudflare/wrangler-action@v3.14.1

.gitignore

@@ -26,5 +26,6 @@ nul
 # jetbrains setting folder
 .idea/
 
-# jampack cache
+# legacy jampack cache
 .jampack/
+.wrangler-dry-run/

.tmp-sidebar-redesign.png

@@ -27,28 +27,42 @@ bun install
 
 ## Available Scripts
 
-| Command                      | Description                                      |
-| ---------------------------- | ------------------------------------------------ |
-| `bun dev`                    | Start the development server                     |
-| `bun run build`              | Build for production with optimization           |
-| `bun run build:raw`          | Build for production without optimization        |
-| `bun run compress:postbuild` | Compress assets in `dist` (`.gz`, `.br`, `.zst`) |
-| `bun preview`                | Preview the production build locally             |
-| `bun format`                 | Format code with Prettier                        |
-| `bun run lint`               | Lint code with ESLint                            |
-| `bun run check`              | Run Astro type checking                          |
-| `bun run search:index`       | Build the Pagefind search index                  |
+| Command                                                     | Description                                             |
+| ----------------------------------------------------------- | ------------------------------------------------------- |
+| `bun dev`                                                   | Start the development server                            |
+| `bun run build`                                             | Build for production with Astro + Jampack               |
+| `bun run build:raw`                                         | Build for production without Jampack optimization       |
+| `bun run preview`                                           | Preview the production build locally                    |
+| `bun format`                                                | Format code with Prettier                               |
+| `bun run lint`                                              | Lint code with ESLint                                   |
+| `bun run check`                                             | Run Astro type checking                                 |
+| `bun run search:index`                                      | Build the Pagefind search index                         |
+| `bunx wrangler deploy --dry-run --outdir .wrangler-dry-run` | Validate the Cloudflare Worker bundle without deploying |
+
+## Deployment
+
+The site deploys as a static Astro build served by Cloudflare Workers static assets. The Worker only runs for `/api/*` routes, including the Microsoft ISO helper.
+
+Required Cloudflare setup:
+
+- `CLOUDFLARE_API_TOKEN` GitHub secret with Workers deploy access
+- `CLOUDFLARE_ACCOUNT_ID` GitHub secret
+- `BROWSER` Browser Rendering binding in `wrangler.jsonc`
+- `MS_ISO_LINKS` KV namespace binding in `wrangler.jsonc`
+
+The deploy workflow runs install, lint, Astro check, production build, Wrangler dry-run validation, then `wrangler deploy`.
 
 ## Configuration
 
-| File               | Purpose                                           |
-| ------------------ | ------------------------------------------------- |
-| `astro.config.mjs` | Astro settings, site URL, and Pagefind indexing   |
-| `wrangler.jsonc`   | Cloudflare Workers deployment config             |
-| `globals.css`      | Tailwind theme and global styles                  |
-| `eslint.config.js` | ESLint rules for Astro and TypeScript             |
-| `.editorconfig`    | Editor settings for consistent formatting         |
-| `.gitignore`       | Excludes `.jampack/`, build output, and lockfiles |
+| File                    | Purpose                                               |
+| ----------------------- | ----------------------------------------------------- |
+| `astro.config.mjs`      | Astro settings, site URL, and Pagefind indexing       |
+| `jampack.config.js`     | Jampack post-build optimization settings              |
+| `wrangler.jsonc`        | Cloudflare Workers deployment config                  |
+| `src/styles/global.css` | Tailwind theme and global styles                      |
+| `eslint.config.js`      | ESLint rules for Astro and TypeScript                 |
+| `.editorconfig`         | Editor settings for consistent formatting             |
+| `.gitignore`            | Excludes build output and local development artifacts |
 
 ## Project Structure
 
@@ -66,15 +80,7 @@ Components live in `src/components/` and follow a purpose-based organization:
 
 ### Utilities
 
-Utilities in `src/utils/`:
-
-- `navigation.ts` — Routing and navigation
-- `locale.ts` — Internationalization
-- `navbar.ts` — Navbar interactions
-- `sidebar.ts` — Sidebar state
-- `scroll-animations.ts` — Animation utilities
-
-Import utilities through `src/utils/index.ts`.
+Utilities in `src/utils/` include docs content helpers, navigation helpers, UI initializers, and browser interaction scripts.
 
 ### Constants
 

.tmp-sidebar.png

@@ -7,12 +7,17 @@ import { defineConfig, fontProviders } from 'astro/config';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import pagefindIntegration from './src/integrations/pagefind';
+import rehypeExternalLinks from './src/utils/rehype-external-links.mjs';
 
 export default defineConfig({
   site: 'https://atlasos.net',
   output: 'static',
   trailingSlash: 'always',
 
+  // Add redirects here when docs pages are moved or renamed to avoid broken links.
+  // Example: '/old-path/': '/new-path/'
+  redirects: {},
+
   fonts: [
     {
       name: 'Inter',
@@ -64,6 +69,7 @@ export default defineConfig({
     icon(),
     mdx({
       optimize: true,
+      rehypePlugins: [rehypeExternalLinks],
     }),
     sitemap({
       changefreq: 'weekly',