tenzir · mavam · Oct 20, 2025 · Oct 20, 2025 · Oct 20, 2025 · Oct 20, 2025
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -4,27 +4,32 @@ on:
   push:
     branches: ["main"]
   pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
   workflow_dispatch:
 
 permissions:
-  contents: write # needed for committing changes
+  contents: write
   pages: write
   id-token: write
-  pull-requests: write # needed for commenting on PRs
+  pull-requests: write
 
 concurrency:
-  group: "pages-${{ github.ref }}"
+  group: docs-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
   build:
-    name: Build
+    if: github.event_name != 'pull_request' || github.event.action != 'closed'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0 # needed for checking changes and pushing
+          fetch-depth: 0
           submodules: recursive
 
       - name: Install pnpm
@@ -45,76 +50,128 @@ jobs:
 
       - name: Build with Astro
         run: |
+          ORIGIN="${{ steps.pages.outputs.origin }}"
+          BASE_PATH="${{ steps.pages.outputs.base_path }}"
+
+          if [[ "$BASE_PATH" == "/" ]]; then
+            BASE_PATH=""
+          fi
+
           if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            PREVIEW_ORIGIN="https://tenzir.github.io/docs"
+            PREVIEW_BASE_PREFIX="$BASE_PATH"
+            if [[ "$PREVIEW_BASE_PREFIX" == "/" ]]; then
+              PREVIEW_BASE_PREFIX=""
+            fi
+            PREVIEW_BASE="${PREVIEW_BASE_PREFIX}/pr-preview/pr-${{ github.event.pull_request.number }}/"
+            PREVIEW_BASE="/${PREVIEW_BASE#/}"
             pnpm astro build \
-              --site "https://tenzir-docs-preview-${{ github.event.pull_request.number }}.surge.sh"
+              --site "$PREVIEW_ORIGIN" \
+              --base "$PREVIEW_BASE"
           else
+            FINAL_BASE="$BASE_PATH"
+            [[ -z "$FINAL_BASE" ]] && FINAL_BASE="/"
             pnpm astro build \
-              --site "${{ steps.pages.outputs.origin }}" \
-              --base "${{ steps.pages.outputs.base_path }}"
+              --site "$ORIGIN" \
+              --base "$FINAL_BASE"
           fi
 
-      - name: Upload artifact
-        if: github.event_name != 'pull_request'
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: ./dist
+      - name: Ensure static site deployment metadata
+        run: |
+          touch ./dist/.nojekyll
+          cat <<'EOF' > ./dist/_config.yml
+          defaults:
+            - scope:
+                path: ""
+              values:
+                layout: null
+                render_with_liquid: false
+          EOF
+
+      - name: Remove CNAME from preview builds
+        if: github.event_name == 'pull_request'
+        run: rm -f ./dist/CNAME
 
-      - name: Deploy PR Preview
+      - name: Deploy PR preview
         if: github.event_name == 'pull_request'
-        run: |
-          # To create a surge.sh token, run `npx durge login` and `npx surge token`.
-          npm install -g surge
-          surge ./dist https://tenzir-docs-preview-${{ github.event.pull_request.number }}.surge.sh --token ${{ secrets.SURGE_TOKEN }}
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: dist
+          target-folder: pr-preview/pr-${{ github.event.pull_request.number }}
+          clean: true
+          force: false
 
-      - name: Comment PR
+      - name: Comment PR with preview link
         if: github.event_name == 'pull_request'
-        uses: actions/github-script@v7
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-preview
+          message: |
+            ## 🚀 Documentation Preview
+
+            Your changes are live! View the preview deployment:
+
+            ### 👀 [**View Preview →**](https://docs.tenzir.com/pr-preview/pr-${{ github.event.pull_request.number }}/)
+
+            ---
+
+            <table>
+            <tr>
+            <td>📦 Commit</td>
+            <td><code>${{ github.sha }}</code></td>
+            </tr>
+            <tr>
+            <td>🌿 Branch</td>
+            <td><code>${{ github.event.pull_request.head.ref }}</code></td>
+            </tr>
+            <tr>
+            <td>⚙️ Workflow</td>
+            <td><a href="https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}">#${{ github.run_number }}</a></td>
+            </tr>
+            </table>
+
+            > **Note:** This preview updates automatically with each push to the PR.
+
+      - name: Deploy to GitHub Pages
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        uses: JamesIves/github-pages-deploy-action@v4
         with:
-          script: |
-            const comment = `🚀 **Preview deployed!**
-
-            Visit the preview at: https://tenzir-docs-preview-${{ github.event.pull_request.number }}.surge.sh
-
-            This preview will be updated automatically on new commits.`;
-
-            // Find existing comment
-            const { data: comments } = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.issue.number,
-            });
-
-            const botComment = comments.find(comment =>
-              comment.user.type === 'Bot' &&
-              comment.body.includes('Preview deployed!')
-            );
-
-            if (botComment) {
-              await github.rest.issues.updateComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                comment_id: botComment.id,
-                body: comment
-              });
-            } else {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: context.issue.number,
-                body: comment
-              });
-            }
-
-  deploy:
-    name: Deploy
-    if: github.ref == 'refs/heads/main'
-    needs: build
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+          branch: gh-pages
+          folder: dist
+          clean: true
+          clean-exclude: |
+            pr-preview/
+          force: false
+
+  cleanup:
+    if: github.event_name == 'pull_request' && github.event.action == 'closed'
     runs-on: ubuntu-latest
     steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+      - name: Prepare empty preview directory
+        run: |
+          mkdir -p empty-preview
+          touch empty-preview/.gitkeep
+
+      - name: Remove PR preview
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: empty-preview
+          target-folder: pr-preview/pr-${{ github.event.pull_request.number }}
+          clean: true
+          force: false
+
+      - name: Comment PR cleanup
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-preview
+          message: |
+            ## 🧹 Preview Removed
+
+            The documentation preview has been cleaned up because this PR was closed.
+
+            The preview URL is no longer accessible:
+            ~~`https://docs.tenzir.com/pr-preview/pr-${{ github.event.pull_request.number }}/`~~
+
+            > Reopen this PR or push new commits to restore the preview deployment.
diff --git a/.github/workflows/pr-preview-cleanup.yaml b/.github/workflows/pr-preview-cleanup.yaml
diff --git a/src/components/InteractiveDocsStructure.astro b/src/components/InteractiveDocsStructure.astro
@@ -6,6 +6,9 @@ export interface Props {
 
 const { imageSrc = "/docs-structure.svg", activeSection = null } = Astro.props;
 
+// Get base URL for proper path resolution in PR previews
+const base = import.meta.env.BASE_URL;
+
 // Define which sections should be clickable based on the active section
 const getClickableStatus = (section: string) => {
   return activeSection !== section;
@@ -14,7 +17,7 @@ const getClickableStatus = (section: string) => {
 // Get the appropriate href for each section
 const getHref = (section: string) => {
   if (activeSection === section) return undefined;
-  return `/${section}/`;
+  return `${base}${section}/`;
 };
 ---
 

diff --git a/src/content/docs/index.mdoc → src/content/docs/index.mdx b/src/content/docs/index.mdoc → src/content/docs/index.mdx
@@ -4,6 +4,9 @@ description: The data pipeline engine for security teams
 #template: splash
 ---
 
+import { Card, CardGrid, LinkButton } from "@astrojs/starlight/components";
+import InteractiveDocsStructure from "../../components/InteractiveDocsStructure.astro";
+
 **Tenzir** is the data pipeline engine for security teams. Our pipelines
 collect, shape, normalize, optimize, enrich, store, replay, and route your
 telemetry data.
@@ -14,7 +17,7 @@ telemetry data.
 
 The Tenzir documentation consists of four different types of materials:
 
-{% InteractiveDocsStructure /%}
+<InteractiveDocsStructure />
 
 - **Guides**: Practical step-by-step explanation to help you achieve a
   specific goal. Most useful when you're trying to get something done.
@@ -27,30 +30,30 @@ The Tenzir documentation consists of four different types of materials:
 
 ## How do I start?
 
-{% cardgrid %}
+<CardGrid>
 
-{% card title="Ready to dive in?" icon="pencil" %}
+<Card title="Ready to dive in?" icon="pencil">
 Get your fingers dirty and explore the demo node with just a few clicks and
 a guided tour. Security data has never been easier.
-{% linkbutton href="guides/quickstart" %}
+<LinkButton href="guides/quickstart">
 Quickstart
-{% /linkbutton %}
-{% /card %}
+</LinkButton>
+</Card>
 
-{% card title="New to Tenzir?" icon="add-document" %}
+<Card title="New to Tenzir?" icon="add-document">
 Learn the basics of pipelines and get familiar with the Tenzir Query
 Language (TQL). You'll master security data in no time.
-{% linkbutton href="explanations/architecture/pipeline" %}
+<LinkButton href="explanations/architecture/pipeline">
 Learn TQL
-{% /linkbutton %}
-{% /card %}
+</LinkButton>
+</Card>
 
-{% /cardgrid %}
+</CardGrid>
 
-{% card title="More questions? Need answers?" icon="discord" %}
+<Card title="More questions? Need answers?" icon="discord">
 Tenzir is a community-driven open-source project. Join our friendly
 Discord server to chat with security data enthusiasts and the Tenzir team.
-{% linkbutton href="/discord" icon="external" %}
+<LinkButton href="/discord" icon="external">
 Join Discord
-{% /linkbutton %}
-{% /card %}
+</LinkButton>
+</Card>