docs: add documentation website

.craft.yml

@@ -19,3 +19,4 @@ requireNames:
 targets:
   - name: npm
   - name: github
+  - name: gh-pages

.github/workflows/ci.yml

@@ -185,9 +185,31 @@ jobs:
           name: npm-package
           path: '*.tgz'
 
+  build-docs:
+    name: Build Docs
+    needs: [lint]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - name: Build Docs
+        working-directory: docs
+        run: |
+          bun install --frozen-lockfile
+          bun run build
+      - name: Package Docs
+        run: |
+          cp .nojekyll docs/dist/
+          zip -r gh-pages.zip docs/dist/
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: gh-pages
+          path: gh-pages.zip
+
   merge-artifacts:
     name: Merge Artifacts
-    needs: [build-binary, build-npm, test-e2e]
+    needs: [build-binary, build-npm, build-docs, test-e2e]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/download-artifact@v4
@@ -197,3 +219,4 @@ jobs:
           path: |
             sentry-*/
             npm-package/*.tgz
+            gh-pages/gh-pages.zip

.github/workflows/docs-preview.yml

@@ -0,0 +1,67 @@
+name: Docs Preview
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs-preview.yml'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Build Docs for Preview
+        working-directory: docs
+        env:
+          # Override base path for PR preview (no /cli prefix since preview domain is different)
+          DOCS_BASE_PATH: /pr-preview/pr-${{ github.event.pull_request.number }}
+        run: |
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Ensure .nojekyll at gh-pages root
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # Try to fetch the gh-pages branch
+          if git fetch origin gh-pages:gh-pages 2>/dev/null; then
+            # Branch exists remotely, check if .nojekyll is present
+            if git show gh-pages:.nojekyll &>/dev/null; then
+              echo ".nojekyll already exists at gh-pages root"
+            else
+              echo "Adding .nojekyll to existing gh-pages branch"
+              git checkout gh-pages
+              touch .nojekyll
+              git add .nojekyll
+              git commit -m "Add .nojekyll to disable Jekyll processing"
+              git push origin gh-pages
+              git checkout -
+            fi
+          else
+            # Branch doesn't exist, create it as an orphan branch
+            echo "Creating gh-pages branch with .nojekyll"
+            git checkout --orphan gh-pages
+            git rm -rf .
+            touch .nojekyll
+            git add .nojekyll
+            git commit -m "Initialize gh-pages with .nojekyll"
+            git push origin gh-pages
+            git checkout -
+          fi
+
+      - name: Deploy Preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: docs/dist/
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview
+          action: auto

.gitignore

@@ -35,6 +35,11 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 *.tsbuildinfo
 .turbo
 
+# docs
+docs/dist
+docs/node_modules
+docs/.astro
+
 # IntelliJ based IDEs
 .idea
 

biome.jsonc

@@ -1,6 +1,9 @@
 {
   "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
   "extends": ["ultracite/core"],
+  "files": {
+    "includes": ["!docs"]
+  },
   "javascript": {
     "globals": ["Bun"]
   },

docs/astro.config.mjs

@@ -0,0 +1,178 @@
+import starlight from "@astrojs/starlight";
+import { defineConfig } from "astro/config";
+
+// Allow base path override via environment variable for PR previews
+const base = process.env.DOCS_BASE_PATH || "/cli";
+
+export default defineConfig({
+  site: "https://getsentry.github.io",
+  base,
+  integrations: [
+    starlight({
+      title: "Sentry CLI",
+      favicon: "/favicon.png",
+      logo: {
+        src: "./src/assets/logo.svg",
+        replacesTitle: true,
+      },
+      social: {
+        github: "https://github.com/getsentry/cli",
+      },
+      expressiveCode: {
+        themes: ["github-dark"],
+        styleOverrides: {
+          frames: {
+            frameBoxShadowCssValue: "none",
+            editorActiveTabIndicatorTopColor: "transparent",
+            editorActiveTabIndicatorBottomColor: "transparent",
+            editorTabBarBorderBottomColor: "transparent",
+            editorTabBarBackground: "transparent",
+            terminalTitlebarBorderBottomColor: "transparent",
+            terminalTitlebarBackground: "rgba(255, 255, 255, 0.03)",
+            terminalBackground: "#0a0a0f",
+          },
+          borderRadius: "12px",
+          borderColor: "rgba(255, 255, 255, 0.1)",
+          codeBackground: "#0a0a0f",
+        },
+      },
+      components: {
+        Header: "./src/components/Header.astro",
+        ThemeSelect: "./src/components/ThemeSelect.astro",
+        PageTitle: "./src/components/PageTitle.astro",
+      },
+      head: [
+        // Force dark mode - runs before page renders
+        {
+          tag: "script",
+          content: `document.documentElement.dataset.theme = 'dark';`,
+        },
+        // Overscroll easter egg - bottom of page, only on /cli route
+        {
+          tag: "script",
+          content: `
+            (function() {
+              let overscrollEl;
+              let pullDistance = 0;
+              let touchStartY = 0;
+              let isAtBottom = false;
+
+              function isLandingPage() {
+                const path = window.location.pathname;
+                // Works with both /cli (prod) and /pr-preview/pr-XX (preview)
+                return path === '/cli' || path === '/cli/' || 
+                       /^\\/pr-preview\\/pr-\\d+\\/?$/.test(path);
+              }
+
+              function checkAtBottom() {
+                const scrollTop = window.scrollY || document.documentElement.scrollTop;
+                const scrollHeight = document.documentElement.scrollHeight;
+                const clientHeight = document.documentElement.clientHeight;
+                return scrollTop + clientHeight >= scrollHeight - 5;
+              }
+
+              function createOverscrollMessage() {
+                if (!isLandingPage()) return;
+                overscrollEl = document.createElement('div');
+                overscrollEl.className = 'overscroll-message';
+                overscrollEl.innerHTML = '<span>You made it to the end. Might as well give it a try → <code>npx sentry@latest</code></span>';
+                document.body.appendChild(overscrollEl);
+              }
+
+              function updateOverscroll(distance) {
+                if (!overscrollEl) return;
+                const clampedDistance = Math.min(Math.max(distance, 0), 50);
+                const opacity = Math.min(clampedDistance / 15, 1);
+                const translateY = Math.min(clampedDistance * 2.5, 120);
+                overscrollEl.style.opacity = opacity;
+                overscrollEl.style.transform = 'translateX(-50%) translateY(-' + translateY + 'px)';
+              }
+
+              function handleTouchStart(e) {
+                if (!isLandingPage()) return;
+                touchStartY = e.touches[0].clientY;
+                isAtBottom = checkAtBottom();
+              }
+
+              function handleTouchMove(e) {
+                if (!isLandingPage() || !isAtBottom) return;
+                const touchY = e.touches[0].clientY;
+                pullDistance = touchStartY - touchY;
+                if (pullDistance > 0 && checkAtBottom()) {
+                  updateOverscroll(pullDistance);
+                }
+              }
+
+              function handleTouchEnd() {
+                pullDistance = 0;
+                updateOverscroll(0);
+              }
+
+              function handleWheel(e) {
+                if (!isLandingPage()) return;
+                if (checkAtBottom() && e.deltaY > 0) {
+                  pullDistance = Math.min(pullDistance + e.deltaY * 0.8, 50);
+                  updateOverscroll(pullDistance);
+                  clearTimeout(window.overscrollTimeout);
+                  window.overscrollTimeout = setTimeout(function() {
+                    pullDistance = 0;
+                    updateOverscroll(0);
+                  }, 300);
+                }
+              }
+
+              document.addEventListener('DOMContentLoaded', function() {
+                createOverscrollMessage();
+                document.addEventListener('touchstart', handleTouchStart, { passive: true });
+                document.addEventListener('touchmove', handleTouchMove, { passive: true });
+                document.addEventListener('touchend', handleTouchEnd, { passive: true });
+                document.addEventListener('wheel', handleWheel, { passive: true });
+              });
+            })();
+          `,
+        },
+        // Add fonts
+        {
+          tag: "link",
+          attrs: {
+            rel: "preconnect",
+            href: "https://fonts.googleapis.com",
+          },
+        },
+        {
+          tag: "link",
+          attrs: {
+            rel: "preconnect",
+            href: "https://fonts.gstatic.com",
+            crossorigin: true,
+          },
+        },
+        {
+          tag: "link",
+          attrs: {
+            rel: "stylesheet",
+            href: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap",
+          },
+        },
+      ],
+      sidebar: [
+        {
+          label: "Getting Started",
+          items: [
+            { label: "Introduction", slug: "" },
+            { label: "Installation", slug: "getting-started" },
+          ],
+        },
+        {
+          label: "Commands",
+          autogenerate: { directory: "commands" },
+        },
+        {
+          label: "Resources",
+          items: [{ label: "Contributing", slug: "contributing" }],
+        },
+      ],
+      customCss: ["./src/styles/custom.css"],
+    }),
+  ],
+});