Version Packages (#3180)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.github/CONTRIBUTING.md

@@ -63,9 +63,9 @@ To start your local version of GitBook, run the command `bun dev`.
 
 When running the development server, published GitBook sites can be rendered through your local version at `http://localhost:3000/`.
 
-For example, our published docs can be viewed using the local version by visiting `http://localhost:3000/docs.gitbook.com` after running the development server.
+For example, our published docs can be viewed using the local version by visiting `http://localhost:3000/gitbook.com/docs` after running the development server.
 
-You can visit any published GitBook site behind your development server. Please make sure your site is [published publicly](https://docs.gitbook.com/published-documentation/publish-your-content-as-a-docs-site) to ensure you can view the site correctly in your development version.
+You can visit any published GitBook site behind your development server. Please make sure your site is [published publicly](https://gitbook.com/docs/published-documentation/publish-your-content-as-a-docs-site) to ensure you can view the site correctly in your development version.
 
 ### Commit your update
 

.github/composite/deploy-cloudflare/action.yaml

@@ -19,6 +19,12 @@ inputs:
   deploy:
     description: 'Deploy as main version for all traffic instead of uploading versions'
     required: true
+  commitTag:
+    description: 'Commit branch to associate with the deployment'
+    required: true
+  commitMessage:
+    description: 'Commit message to associate with the deployment'
+    required: true
 outputs:
     deployment-url: 
       description: "Deployment URL"
@@ -44,13 +50,18 @@ runs:
             GITBOOK_SECRET: ${{ inputs.opItem }}/GITBOOK_SECRET
             GITBOOK_APP_URL: ${{ inputs.opItem }}/GITBOOK_APP_URL
             GITBOOK_API_URL: ${{ inputs.opItem }}/GITBOOK_API_URL
+            GITBOOK_API_PUBLIC_URL: ${{ inputs.opItem }}/GITBOOK_API_PUBLIC_URL
             GITBOOK_API_TOKEN: ${{ inputs.opItem }}/GITBOOK_API_TOKEN
             GITBOOK_INTEGRATIONS_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_HOST
             GITBOOK_IMAGE_RESIZE_SIGNING_KEY: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SIGNING_KEY
             GITBOOK_IMAGE_RESIZE_URL: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_URL
+            GITBOOK_IMAGE_RESIZE_MODE: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_MODE
             GITBOOK_ASSETS_PREFIX: ${{ inputs.opItem }}/GITBOOK_ASSETS_PREFIX
+            GITBOOK_FONTS_URL: ${{ inputs.opItem }}/GITBOOK_FONTS_URL
         - name: Build worker
           run: bun run turbo build:v2:cloudflare
+          env:
+            GITBOOK_RUNTIME: cloudflare
           shell: bash
         - id: deploy
           name: Deploy to Cloudflare
@@ -59,9 +70,9 @@ runs:
               apiToken: ${{ inputs.apiToken }}
               accountId: ${{ inputs.accountId }}
               workingDirectory: ./
-              wranglerVersion: '3.112.0'
+              wranglerVersion: '4.10.0'
               environment: ${{ inputs.environment }}
-              command: ${{ fromJSON(inputs.deploy) == true && 'deploy' || 'versions upload' }} --config ./packages/gitbook-v2/wrangler.toml
+              command: ${{ inputs.deploy == 'true' && 'deploy' || format('versions upload --tag {0} --message "{1}"', inputs.commitTag, inputs.commitMessage) }} --config ./packages/gitbook-v2/wrangler.jsonc
         - name: Outputs
           shell: bash
           env:

.github/composite/deploy-vercel/action.yaml

@@ -49,17 +49,21 @@ runs:
             GITBOOK_SECRET: ${{ inputs.opItem }}/GITBOOK_SECRET
             GITBOOK_APP_URL: ${{ inputs.opItem }}/GITBOOK_APP_URL
             GITBOOK_API_URL: ${{ inputs.opItem }}/GITBOOK_API_URL
+            GITBOOK_API_PUBLIC_URL: ${{ inputs.opItem }}/GITBOOK_API_PUBLIC_URL
             GITBOOK_API_TOKEN: ${{ inputs.opItem }}/GITBOOK_API_TOKEN
             GITBOOK_INTEGRATIONS_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_HOST
             GITBOOK_IMAGE_RESIZE_SIGNING_KEY: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SIGNING_KEY
             GITBOOK_IMAGE_RESIZE_URL: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_URL
+            GITBOOK_IMAGE_RESIZE_MODE: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_MODE
             GITBOOK_ASSETS_PREFIX: ${{ inputs.opItem }}/GITBOOK_ASSETS_PREFIX
+            GITBOOK_FONTS_URL: ${{ inputs.opItem }}/GITBOOK_FONTS_URL
         - name: Build Project Artifacts
           run: bun run vercel build --target=${{ inputs.environment }} --token=${{ inputs.vercelToken }}
           shell: bash
           env:
             VERCEL_ORG_ID: ${{ inputs.vercelOrg }}
             VERCEL_PROJECT_ID: ${{ inputs.vercelProject }}
+            GITBOOK_RUNTIME: vercel
         - name: Deploy Project Artifacts to Vercel
           id: deploy
           shell: bash
@@ -73,3 +77,4 @@ runs:
           shell: bash
           run: |
               echo "URL: ${{ steps.deploy.outputs.deployment-url }}"
+

.github/composite/setup-bun/action.yaml

@@ -3,15 +3,6 @@ description: 'Install Bun and cache dependencies'
 runs:
     using: 'composite'
     steps:
-        # We cache dependencies even if Bun is fast to avoid downloading fontawesome too many times
-        # and impacting bandwidth there.
-        - name: Cache bun
-          uses: actions/cache@v4
-          with:
-              path: ~/.bun/install/cache
-              key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lockb') }}-${{ hashFiles('**/bun.lock') }}
-              restore-keys: |
-                  ${{ runner.os }}-bun-
         - name: Setup bun
           uses: oven-sh/setup-bun@v2
           with:

.github/workflows/deploy-preview.yaml

@@ -10,7 +10,7 @@ jobs:
     deploy-v1-cloudflare:
         name: Deploy v1 to Cloudflare Pages
         runs-on: ubuntu-latest
-        environment: 
+        environment:
           name: ${{ github.ref == 'refs/heads/main' && '1c-production' || '1c-preview' }}
           url: ${{ steps.deploy.outputs.deployment-url }}
         permissions:
@@ -35,21 +35,12 @@ jobs:
             - name: Sets env vars for production
               if: github.ref == 'refs/heads/main'
               run: |
-                echo "SENTRY_ENVIRONMENT=production" >> $GITHUB_ENV
                 echo "GITBOOK_ASSETS_PREFIX=https://static.gitbook.com" >> $GITHUB_ENV
-            - name: Sets env vars for preview
-              if: github.ref != 'refs/heads/main'
-              run: |
-                  echo "SENTRY_ENVIRONMENT=preview" >> $GITHUB_ENV
             - name: Build Next.js with next-on-pages
               run: bun run turbo gitbook#build:cloudflare
               env:
-                  SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
                   NEXT_SERVER_ACTIONS_ENCRYPTION_KEY: ${{ secrets.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY }}
-                  SENTRY_ORG: ${{ vars.SENTRY_ORG }}
+                  GITBOOK_RUNTIME: cloudflare
-                  SENTRY_PROJECT: ${{ vars.SENTRY_PROJECT }}
-                  SENTRY_DSN: ${{ vars.SENTRY_DSN }}
-                  SENTRY_RELEASE: ${{ github.sha }}
             - id: deploy
               name: Deploy to Cloudflare
               uses: cloudflare/wrangler-action@v3.14.0
@@ -66,7 +57,7 @@ jobs:
     deploy-v2-vercel:
         name: Deploy v2 to Vercel (preview)
         runs-on: ubuntu-latest
-        environment: 
+        environment:
           name: 2v-preview
           url: ${{ steps.deploy.outputs.deployment-url }}
         outputs:
@@ -87,11 +78,11 @@ jobs:
     deploy-v2-cloudflare:
         name: Deploy v2 to Cloudflare Worker (preview)
         runs-on: ubuntu-latest
-        environment: 
+        environment:
           name: 2c-preview
           url: ${{ steps.deploy.outputs.deployment-url }}
         outputs:
-            deployment-url: ${{ steps.deploy.outputs.deployment-url }}
+            deployment-url: ${{ steps.deploy.outputs.deployment-url || steps.extract-worker-id.outputs.worker-url }}
         steps:
             - name: Checkout
               uses: actions/checkout@v4
@@ -105,9 +96,19 @@ jobs:
                   accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
                   opItem: op://gitbook-open/2c-preview
                   opServiceAccount: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+                  commitTag: ${{ github.ref == 'refs/heads/main' && 'main' || format('pr{0}', github.event.pull_request.number) }}
+                  commitMessage: ${{ github.sha }}
+            - name: Extract Worker ID
+              id: extract-worker-id
+              if: ${{ !steps.deploy.outputs.deployment-url }}
+              run: |
+                if [[ "${{ steps.deploy.outputs.command-output }}" =~ Worker\ Version\ ID:\ ([0-9a-f]{8})-([0-9a-f-]+) ]]; then
+                  WORKER_ID_FIRST_PART="${BASH_REMATCH[1]}"
+                  echo "worker-url=https://${WORKER_ID_FIRST_PART}-gitbook-open-v2-preview.gitbook.workers.dev/" >> $GITHUB_OUTPUT
+                fi
             - name: Outputs
               run: |
-                  echo "URL: ${{ steps.deploy.outputs.deployment-url }}"
+                  echo "URL: ${{ steps.deploy.outputs.deployment-url || steps.extract-worker-id.outputs.worker-url }}"
     comment-deployments:
         runs-on: ubuntu-latest
         name: Comment Deployments (preview)
@@ -133,14 +134,14 @@ jobs:
                   body: |
                       Summary of the deployments:
 
-                      ### Version 1 (production)
+                      ### Version 1
 
                       | Version | URL | Status |
                       | --- | --- | --- |
                       | Latest commit | [${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}](${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}) | ${{ needs.deploy-v1-cloudflare.result == 'success' && '✅' || '❌' }} |
                       | PR | [${{ needs.deploy-v1-cloudflare.outputs.deployment-alias-url }}](${{ needs.deploy-v1-cloudflare.outputs.deployment-alias-url }}) | ${{ needs.deploy-v1-cloudflare.result == 'success' && '✅' || '❌' }} |
 
-                      ### Version 2 (experimental)
+                      ### Version 2
 
                       | Version | URL | Status |
                       | --- | --- | --- |
@@ -149,10 +150,10 @@ jobs:
 
                       ### Test content
 
-                      | Site | v1 | v2 |
+                      | Site | `v1` | `2v` | `2c` |
-                      | --- | --- | --- |
+                      | --- | --- | --- | --- |
-                      | GitBook | [${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}/docs.gitbook.com](${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}/docs.gitbook.com) | [${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/docs.gitbook.com](${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/docs.gitbook.com) |
+                      | GitBook | [${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}/gitbook.com/docs](${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}/gitbook.com/docs) | [${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.com/docs](${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.com/docs) | [${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.com/docs](${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.com/docs) |
-                      | E2E | [${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}/gitbook.gitbook.io/test-gitbook-open](${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}/gitbook.gitbook.io/test-gitbook-open) | [${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open](${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open) |
+                      | E2E | [${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}/gitbook.gitbook.io/test-gitbook-open](${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}/gitbook.gitbook.io/test-gitbook-open) | [${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open](${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open) | [${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open](${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open) |
                   edit-mode: replace
     visual-testing-v1:
         runs-on: ubuntu-latest
@@ -190,14 +191,36 @@ jobs:
             - name: Run Playwright tests
               run: bun e2e
               env:
-                  BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/
+                  BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}
+                  SITE_BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/
                   ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
                   ARGOS_BUILD_NAME: 'v2-vercel'
+    visual-testing-v2-cloudflare:
+        runs-on: ubuntu-latest
+        name: Visual Testing v2 (Cloudflare)
+        needs: deploy-v2-cloudflare
+        timeout-minutes: 10
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+            - name: Setup Bun
+              uses: ./.github/composite/setup-bun
+            - name: Install dependencies
+              run: bun install --frozen-lockfile
+            - name: Setup Playwright
+              uses: ./.github/actions/setup-playwright
+            - name: Run Playwright tests
+              run: bun e2e
+              env:
+                  BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}
+                  SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/
+                  ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
+                  ARGOS_BUILD_NAME: 'v2-cloudflare'
     visual-testing-customers-v1:
         runs-on: ubuntu-latest
         name: Visual Testing Customers v1
         needs: deploy-v1-cloudflare
-        timeout-minutes: 6
+        timeout-minutes: 8
         steps:
             - name: Checkout
               uses: actions/checkout@v4
@@ -217,7 +240,7 @@ jobs:
         runs-on: ubuntu-latest
         name: Visual Testing Customers v2
         needs: deploy-v2-vercel
-        timeout-minutes: 6
+        timeout-minutes: 8
         steps:
             - name: Checkout
               uses: actions/checkout@v4
@@ -230,7 +253,29 @@ jobs:
             - name: Run Playwright tests
               run: bun e2e-customers
               env:
-                  BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/
+                  BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}
+                  SITE_BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/
+                  ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
+                  ARGOS_BUILD_NAME: 'customers-v2'
+    visual-testing-customers-v2-cloudflare:
+        runs-on: ubuntu-latest
+        name: Visual Testing Customers v2 (Cloudflare)
+        needs: deploy-v2-cloudflare
+        timeout-minutes: 8
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+            - name: Setup Bun
+              uses: ./.github/composite/setup-bun
+            - name: Install dependencies
+              run: bun install --frozen-lockfile
+            - name: Setup Playwright
+              uses: ./.github/actions/setup-playwright
+            - name: Run Playwright tests
+              run: bun e2e-customers
+              env:
+                  BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}
+                  SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/
                   ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
                   ARGOS_BUILD_NAME: 'customers-v2'
     pagespeed-testing-v1:
@@ -247,7 +292,7 @@ jobs:
               env:
                   PUPPETEER_SKIP_DOWNLOAD: 1
             - name: Run pagespeed tests
-              run: bun ./packages/gitbook/tests/pagespeed-testing.ts $DEPLOYMENT_URL
+              run: bun ./packages/gitbook/tests/pagespeed-testing.ts
               env:
-                  DEPLOYMENT_URL: ${{needs.deploy-v1-cloudflare.outputs.deployment-url}}
+                  BASE_URL: ${{needs.deploy-v1-cloudflare.outputs.deployment-url}}
                   PAGESPEED_API_KEY: ${{ secrets.PAGESPEED_API_KEY }}

.github/workflows/deploy-production.yaml

@@ -17,7 +17,7 @@ jobs:
         steps:
             - name: Checkout
               uses: actions/checkout@v4
-            - name: Deploy staging
+            - name: Deploy
               id: deploy
               uses: ./.github/composite/deploy-vercel
               with:
@@ -48,6 +48,8 @@ jobs:
                   accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
                   opItem: op://gitbook-open/2c-production
                   opServiceAccount: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+                  commitTag: main
+                  commitMessage: ${{ github.sha }}
             - name: Outputs
               run: |
                   echo "URL: ${{ steps.deploy.outputs.deployment-url }}"

.github/workflows/deploy-staging.yaml

@@ -17,7 +17,7 @@ jobs:
         steps:
             - name: Checkout
               uses: actions/checkout@v4
-            - name: Deploy staging
+            - name: Deploy
               id: deploy
               uses: ./.github/composite/deploy-vercel
               with:
@@ -48,6 +48,8 @@ jobs:
                   accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
                   opItem: op://gitbook-open/2c-staging
                   opServiceAccount: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+                  commitTag: main
+                  commitMessage: ${{ github.sha }}
             - name: Outputs
               run: |
                   echo "URL: ${{ steps.deploy.outputs.deployment-url }}"

.github/workflows/publish.yaml

@@ -5,6 +5,9 @@ on:
         branches:
             - main
 
+env:
+    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+    
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 jobs:

.prettierignore

@@ -1,17 +0,0 @@
-.next
-.vercel
-.open-next
-
-# Generated
-packages/emoji-codepoints/index.ts
-packages/gitbook/public/~gitbook/static/
-packages/icons/src/data/*.json
-
-# Build files
-dist/
-
-README.md
-CHANGELOG.md
-
-# v2
-packages/gitbook-v2/public/~gitbook/static/

.prettierrc.json

@@ -1,5 +0,0 @@
-{
-    "printWidth": 100,
-    "singleQuote": true,
-    "tabWidth": 4
-}

.vscode/settings.json

@@ -9,9 +9,13 @@
     ],
     "tailwindCSS.classAttributes": ["class", "className", "style", ".*Style"],
     "prettier.enable": false,
+    "editor.formatOnSave": true,
     "editor.defaultFormatter": "biomejs.biome",
     "editor.codeActionsOnSave": {
         "source.organizeImports.biome": "explicit",
         "source.fixAll.biome": "explicit"
+    },
+    "[typescript]": {
+        "editor.defaultFormatter": "biomejs.biome"
     }
 }

README.md

@@ -1,7 +1,7 @@
 <h1 align="center">GitBook</h1>
 
 <p align="center">
-  <a href="https://docs.gitbook.com/">Docs</a> - <a href="https://github.com/GitbookIO/community">Community</a> - <a href="https://developer.gitbook.com/">Developer Docs</a> - <a href="https://changelog.gitbook.com/">Changelog</a> - <a href="https://github.com/GitbookIO/gitbook/issues/new?assignees=&labels=bug&template=bug_report.md">Bug reports</a> 
+  <a href="https://gitbook.com/docs/">Docs</a> - <a href="https://github.com/GitbookIO/community">Community</a> - <a href="https://developer.gitbook.com/">Developer Docs</a> - <a href="https://changelog.gitbook.com/">Changelog</a> - <a href="https://github.com/GitbookIO/gitbook/issues/new?assignees=&labels=bug&template=bug_report.md">Bug reports</a> 
 </p>
 
 <p align="center">
@@ -59,15 +59,15 @@ bun install
 4. Start your local development server.
 
 ```
-bun dev
+bun dev:v2
 ```
 
 5. Open a published GitBook space in your web browser, prefixing it with `http://localhost:3000/`.
 
 examples:
 
--   http://localhost:3000/docs.gitbook.com
+-   http://localhost:3000/url/gitbook.com/docs
--   http://localhost:3000/open-source.gitbook.io/midjourney
+-   http://localhost:3000/url/open-source.gitbook.io/midjourney
 
 Any published GitBook site can be accessed through your local development instance, and any updates you make to the codebase will be reflected in your browser.
 

biome.json

@@ -18,7 +18,10 @@
             "**/.vercel/**/*",
             "**/.cache/**/*",
             "**/.wrangler/**/*",
-            "packages/openapi-parser/src/fixtures/**/*"
+            "packages/openapi-parser/src/fixtures/**/*",
+            "packages/emoji-codepoints/index.ts",
+            "packages/icons/src/data/*.json",
+            "packages/cache-do/worker-configuration.d.ts"
         ]
     },
     "formatter": {

package.json

@@ -4,14 +4,15 @@
     "devDependencies": {
         "@biomejs/biome": "^1.9.4",
         "@changesets/cli": "^2.27.12",
-        "turbo": "^2.4.4",
+        "turbo": "^2.5.0",
         "vercel": "^39.3.0"
     },
-    "packageManager": "bun@1.2.4",
+    "packageManager": "bun@1.2.11",
     "overrides": {
         "@codemirror/state": "6.4.1",
-        "react": "18.3.1",
+        "@gitbook/api": "^0.115.0",
-        "react-dom": "18.3.1"
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
     },
     "private": true,
     "scripts": {

packages/cache-do/package.json

@@ -21,10 +21,10 @@
     },
     "devDependencies": {
         "typescript": "^5.5.3",
-        "wrangler": "^3.112.0"
+        "wrangler": "^4.10.0"
     },
     "scripts": {
-        "generate": "wrangler types --experimental-include-runtime",
+        "generate": "wrangler types",
         "build": "tsc",
         "typecheck": "tsc --noEmit",
         "dev": "tsc -w",

packages/cache-do/tsconfig.json

@@ -14,7 +14,7 @@
         "resolveJsonModule": true,
         "isolatedModules": true,
         "incremental": true,
-        "types": ["./.wrangler/types/runtime.d.ts"]
+        "types": ["./worker-configuration.d.ts"]
     },
     "include": ["src/**/*.ts"],
     "exclude": ["node_modules"]

packages/cache-do/turbo.json

@@ -0,0 +1,8 @@
+{
+    "extends": ["//"],
+    "tasks": {
+        "generate": {
+            "outputs": ["worker-configuration.d.ts"]
+        }
+    }
+}

packages/cache-tags/CHANGELOG.md

@@ -1,7 +1,25 @@
 # @gitbook/cache-tags
 
+## 0.3.1
+
+### Patch Changes
+
+- 77397ca: Fix version of @gitbook/api referenced in package.json
+
+## 0.3.0
+
+### Minor Changes
+
+- 116575c: Improve typing of getComputedContentSourceCacheTags to match latest API specification
+
+## 0.2.0
+
+### Minor Changes
+
+- f32bf1f: Export function `getCacheTagForURL` to easily get the cache tag for a URL.
+
 ## 0.1.0
 
 ### Minor Changes
 
--   05ffd0e: Initial version of the package
+- 05ffd0e: Initial version of the package

packages/cache-tags/package.json

@@ -8,9 +8,9 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "0.1.0",
+    "version": "0.3.1",
     "dependencies": {
-        "@gitbook/api": "0.96.1",
+        "@gitbook/api": "^0.115.0",
         "assert-never": "^1.2.1"
     },
     "devDependencies": {

packages/cache-tags/src/index.ts

@@ -60,7 +60,7 @@ export function getCacheTag(
         | {
               tag: 'computed-document';
               space: string;
-              integration: string;
+              sourceType: string;
           }
         /**
          * All data related to the URL of a content
@@ -84,6 +84,14 @@ export function getCacheTag(
               organization: string;
               openAPISpec: string;
           }
+        /**
+         * All data related to a translation
+         */
+        | {
+              tag: 'translation';
+              organization: string;
+              translationSettings: string;
+          }
 ): string {
     switch (spec.tag) {
         case 'user':
@@ -99,18 +107,31 @@ export function getCacheTag(
         case 'document':
             return `space:${spec.space}:document:${spec.document}`;
         case 'computed-document':
-            return `space:${spec.space}:computed-document:${spec.integration}`;
+            return `space:${spec.space}:computed-document:${spec.sourceType}`;
         case 'site':
             return `site:${spec.site}`;
         case 'integration':
             return `integration:${spec.integration}`;
         case 'openapi':
             return `organization:${spec.organization}:openapi:${spec.openAPISpec}`;
+        case 'translation':
+            return `organization:${spec.organization}:translation:${spec.translationSettings}`;
         default:
             assertNever(spec);
     }
 }
 
+/**
+ * Get the cache tag for a given URL.
+ */
+export function getCacheTagForURL(url: string | URL) {
+    const parsedURL = url instanceof URL ? url : new URL(url);
+    return getCacheTag({
+        tag: 'url',
+        hostname: parsedURL.hostname,
+    });
+}
+
 /**
  * Get the tags for a computed content source.
  */
@@ -146,6 +167,15 @@ export function getComputedContentSourceCacheTags(
                         })
                     );
                     break;
+                case 'translation-language':
+                    tags.push(
+                        getCacheTag({
+                            tag: 'translation',
+                            organization: inContext.organizationId,
+                            translationSettings: dependency.ref.translationSettings,
+                        })
+                    );
+                    break;
                 default:
                     // Do not throw for unknown dependency types
                     // as it might mean we are lacking behind the API version
@@ -158,18 +188,22 @@ export function getComputedContentSourceCacheTags(
             getCacheTag({
                 tag: 'computed-document',
                 space: inContext.spaceId,
-                integration: source.integration,
+                sourceType: source.type,
             })
         );
     }
 
     // We invalidate the computed content when a new version of the integration is deployed.
-    tags.push(
+
-        getCacheTag({
+    if (source.type.startsWith('integration:')) {
-            tag: 'integration',
+        const integration = source.type.split(':')[1];
-            integration: source.integration,
+        tags.push(
-        })
+            getCacheTag({
-    );
+                tag: 'integration',
+                integration,
+            })
+        );
+    }
 
     return tags;
 }

packages/colors/CHANGELOG.md

@@ -1,7 +1,33 @@
 # @gitbook/colors
 
+## 0.3.3
+
+### Patch Changes
+
+- c3f6b8c: Update chroma ratio per step
+- 5e975ab: Fix code highlighting for HTTP
+- f7a3470: Change lightness check for color step 9 to allow input colors with a higher-than-needed contrast
+
+## 0.3.2
+
+### Patch Changes
+
+- cdffd7c: Desaturate text colors by decreasing chroma for the last steps of the color scale
+
+## 0.3.1
+
+### Patch Changes
+
+- fb90eb0: Reduce chroma of first color scale step
+
+## 0.3.0
+
+### Minor Changes
+
+- 4f0a772: Override tint lightness if supplied color is out of bounds
+
 ## 0.2.0
 
 ### Minor Changes
 
--   445baaa: Initial release
+- 445baaa: Initial release

packages/colors/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "0.2.0",
+    "version": "0.3.3",
     "devDependencies": {
         "typescript": "^5.5.3"
     },

packages/colors/src/transformations.ts

@@ -184,6 +184,7 @@ export function colorScale(
     const mixColor = mix?.color ? rgbToOklch(hexToRgbArray(mix.color)) : null;
     const foregroundColor = rgbToOklch(hexToRgbArray(foreground));
     const backgroundColor = rgbToOklch(hexToRgbArray(background));
+    let mapping = darkMode ? colorMixMapping.dark : colorMixMapping.light;
 
     if (mixColor && mix?.ratio && mix.ratio > 0) {
         // If defined, we mix in a (tiny) bit of the mix color with the base color.
@@ -192,7 +193,20 @@ export function colorScale(
         baseColor.H = mix.color === DEFAULT_TINT_COLOR ? baseColor.H : mixColor.H;
     }
 
-    const mapping = darkMode ? colorMixMapping.dark : colorMixMapping.light;
+    if (
+        (darkMode && baseColor.L < backgroundColor.L) ||
+        (!darkMode && baseColor.L > backgroundColor.L)
+    ) {
+        // If the supplied color is outside of our lightness bounds, use the supplied color's lightness.
+        // This is mostly used to allow darker-than-dark backgrounds for brands that specifically want that look.
+        const difference = (backgroundColor.L - baseColor.L) / backgroundColor.L;
+        backgroundColor.L = baseColor.L;
+        // At the edges of the scale, the subtle lightness changes stop being perceptible. We need to amp up our mapping to still stand out.
+        const amplifier = 1;
+        mapping = mapping.map((step, index) =>
+            index < 9 ? step + step * amplifier * difference : step
+        );
+    }
 
     const result = [];
 
@@ -200,13 +214,31 @@ export function colorScale(
         const targetL =
             foregroundColor.L * mapping[index] + backgroundColor.L * (1 - mapping[index]);
 
-        if (index === 8 && !mix && Math.abs(baseColor.L - targetL) < 0.2) {
+        if (
+            index === 8 &&
+            !mix &&
+            (darkMode ? targetL - baseColor.L < 0.2 : baseColor.L - targetL < 0.2)
+        ) {
             // Original colour is close enough to target, so let's use the original colour as step 9.
             result.push(hex);
             continue;
         }
 
-        const chromaRatio = index < 8 ? (index + 1) * 0.05 : 1;
+        const chromaRatio = (() => {
+            switch (index) {
+                // Step 9 and 10 have max chroma, meaning they are fully saturated.
+                case 8:
+                case 9:
+                    return 1;
+                // Step 11 and 12 have a reduced chroma
+                case 10:
+                    return 0.4;
+                case 11:
+                    return 0.1;
+                default:
+                    return index * 0.05;
+            }
+        })();
 
         const shade = {
             L: targetL, // Blend lightness

packages/gitbook-v2/.gitignore

@@ -6,6 +6,7 @@
 
 # cloudflare
 .open-next
+.wrangler
 
 # Symbolic links
 public

packages/gitbook-v2/CHANGELOG.md

@@ -1,27 +1,81 @@
 # gitbook-v2
 
+## 0.3.0
+
+### Minor Changes
+
+- 3119066: Add support for reusable content across spaces.
+- 7d7806d: Pass SVG images through image resizing without resizing them to serve them from optimal host.
+
+### Patch Changes
+
+- 1c8d9fe: keep data cache in OpenNext between deployment
+- 778624a: Only resize images with supported extensions.
+- e6ddc0f: Fix URL in sitemap
+- 5e975ab: Fix code highlighting for HTTP
+- e15757d: Fix crash on Cloudflare by using latest stable version of Next.js instead of canary
+- 634e0b4: Improve error messages around undefined site sections.
+- 97b7c79: Increase logging around caching behaviour causing page crashes.
+- 3f29206: Update the regex for validating site redirect
+- dd043df: Revert investigation work around URL caches.
+
+## 0.2.5
+
+### Patch Changes
+
+- Updated dependencies [77397ca]
+  - @gitbook/cache-tags@0.3.1
+
+## 0.2.4
+
+### Patch Changes
+
+- 4234289: Fix incoming URL for requests that were proxied
+- Updated dependencies [116575c]
+  - @gitbook/cache-tags@0.3.0
+
+## 0.2.3
+
+### Patch Changes
+
+- 5b2bf82: Use stable site URL data for route rewrite in the middleware
+
+## 0.2.2
+
+### Patch Changes
+
+- 54ee014: Add initial support for loading custom fonts
+- bba2e52: Fix site redirects when it includes a section/variant path
+
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [f32bf1f]
+  - @gitbook/cache-tags@0.2.0
+
 ## 0.2.0
 
 ### Minor Changes
 
--   76c7974: Add route to revalidate cached data
+- 76c7974: Add route to revalidate cached data
 
 ## 0.1.2
 
 ### Patch Changes
 
--   05ffd0e: Improving data cache management for computed content
+- 05ffd0e: Improving data cache management for computed content
--   Updated dependencies [05ffd0e]
+- Updated dependencies [05ffd0e]
-    -   @gitbook/cache-tags@0.1.0
+  - @gitbook/cache-tags@0.1.0
 
 ## 0.1.1
 
 ### Patch Changes
 
--   3e11678: fix: lost section groups
+- 3e11678: fix: lost section groups
 
 ## 0.1.0
 
 ### Minor Changes
 
--   cfccc44: Setup structure and deployment for new version
+- cfccc44: Setup structure and deployment for new version

packages/gitbook-v2/next.config.mjs

@@ -5,7 +5,15 @@
  */
 const nextConfig = {
     experimental: {
+        // This is needed to throw "forbidden" when the api token expired during revalidation
+        authInterrupts: true,
         useCache: true,
+
+        // Content is fully static, we can cache it in the session memory cache for a long time
+        staleTimes: {
+            dynamic: 3600, // 1 hour
+            static: 3600, // 1 hour
+        },
     },
 
     env: {
@@ -23,6 +31,9 @@ const nextConfig = {
         GITBOOK_ASSETS_PREFIX: process.env.GITBOOK_ASSETS_PREFIX,
         GITBOOK_SECRET: process.env.GITBOOK_SECRET,
         GITBOOK_IMAGE_RESIZE_SIGNING_KEY: process.env.GITBOOK_IMAGE_RESIZE_SIGNING_KEY,
+        GITBOOK_IMAGE_RESIZE_MODE: process.env.GITBOOK_IMAGE_RESIZE_MODE,
+        GITBOOK_FONTS_URL: process.env.GITBOOK_FONTS_URL,
+        GITBOOK_RUNTIME: process.env.GITBOOK_RUNTIME,
 
         // Next.js envs
         NEXT_SERVER_ACTIONS_ENCRYPTION_KEY: process.env.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY,
@@ -42,6 +53,24 @@ const nextConfig = {
             },
         ],
     },
+
+    async headers() {
+        return [
+            {
+                source: '/~gitbook/static/:path*',
+                headers: [
+                    {
+                        key: 'Cache-Control',
+                        value: 'public, max-age=31536000, immutable',
+                    },
+                    {
+                        key: 'Access-Control-Allow-Origin',
+                        value: '*',
+                    },
+                ],
+            },
+        ];
+    },
 };
 
 export default nextConfig;

packages/gitbook-v2/open-next.config.ts

@@ -1,10 +1,27 @@
 import { defineCloudflareConfig } from '@opennextjs/cloudflare';
-import d1TagCache from '@opennextjs/cloudflare/d1-tag-cache';
+import doQueue from '@opennextjs/cloudflare/overrides/queue/do-queue';
-import kvIncrementalCache from '@opennextjs/cloudflare/kv-cache';
+import doShardedTagCache from '@opennextjs/cloudflare/overrides/tag-cache/do-sharded-tag-cache';
-import memoryQueue from '@opennextjs/cloudflare/memory-queue';
+import {
+    softTagFilter,
+    withFilter,
+} from '@opennextjs/cloudflare/overrides/tag-cache/tag-cache-filter';
 
 export default defineCloudflareConfig({
-    incrementalCache: kvIncrementalCache,
+    incrementalCache: () => import('./openNext/incrementalCache').then((m) => m.default),
-    queue: memoryQueue,
+    tagCache: withFilter({
-    tagCache: d1TagCache,
+        tagCache: doShardedTagCache({
+            baseShardSize: 12,
+            regionalCache: true,
+            shardReplication: {
+                numberOfSoftReplicas: 2,
+                numberOfHardReplicas: 1,
+            },
+        }),
+        // We don't use `revalidatePath`, so we filter out soft tags
+        filterFn: softTagFilter,
+    }),
+    queue: doQueue,
+
+    // Performance improvements as we don't use PPR
+    enableCacheInterception: true,
 });

packages/gitbook-v2/openNext/incrementalCache.ts

@@ -0,0 +1,186 @@
+import { createHash } from 'node:crypto';
+
+import { trace } from '@/lib/tracing';
+import type {
+    CacheEntryType,
+    CacheValue,
+    IncrementalCache,
+    WithLastModified,
+} from '@opennextjs/aws/types/overrides.js';
+import { getCloudflareContext } from '@opennextjs/cloudflare';
+
+export const BINDING_NAME = 'NEXT_INC_CACHE_R2_BUCKET';
+export const DEFAULT_PREFIX = 'incremental-cache';
+
+export type KeyOptions = {
+    cacheType?: CacheEntryType;
+};
+
+/**
+ *
+ * It is very similar to the `R2IncrementalCache` in the `@opennextjs/cloudflare` package, but it allow us to trace
+ * the cache operations. It also integrates both R2 and Cache API in a single class.
+ * Having our own, will allow us to customize it in the future if needed.
+ */
+class GitbookIncrementalCache implements IncrementalCache {
+    name = 'GitbookIncrementalCache';
+
+    protected localCache: Cache | undefined;
+
+    async get<CacheType extends CacheEntryType = 'cache'>(
+        key: string,
+        cacheType?: CacheType
+    ): Promise<WithLastModified<CacheValue<CacheType>> | null> {
+        const cacheKey = this.getR2Key(key, cacheType);
+        return trace(
+            {
+                operation: 'openNextIncrementalCacheGet',
+                name: cacheKey,
+            },
+            async (span) => {
+                span.setAttribute('cacheType', cacheType ?? 'cache');
+                const r2 = getCloudflareContext().env[BINDING_NAME];
+                const localCache = await this.getCacheInstance();
+                if (!r2) throw new Error('No R2 bucket');
+                try {
+                    // Check local cache first if available
+                    const localCacheEntry = await localCache.match(this.getCacheUrlKey(cacheKey));
+                    if (localCacheEntry) {
+                        span.setAttribute('cacheHit', 'local');
+                        return localCacheEntry.json();
+                    }
+
+                    const r2Object = await r2.get(cacheKey);
+                    if (!r2Object) return null;
+
+                    span.setAttribute('cacheHit', 'r2');
+                    return {
+                        value: await r2Object.json(),
+                        lastModified: r2Object.uploaded.getTime(),
+                    };
+                } catch (e) {
+                    console.error('Failed to get from cache', e);
+                    return null;
+                }
+            }
+        );
+    }
+
+    async set<CacheType extends CacheEntryType = 'cache'>(
+        key: string,
+        value: CacheValue<CacheType>,
+        cacheType?: CacheType
+    ): Promise<void> {
+        const cacheKey = this.getR2Key(key, cacheType);
+        return trace(
+            {
+                operation: 'openNextIncrementalCacheSet',
+                name: cacheKey,
+            },
+            async (span) => {
+                span.setAttribute('cacheType', cacheType ?? 'cache');
+                const r2 = getCloudflareContext().env[BINDING_NAME];
+                const localCache = await this.getCacheInstance();
+                if (!r2) throw new Error('No R2 bucket');
+
+                try {
+                    await r2.put(cacheKey, JSON.stringify(value));
+
+                    //TODO: Check if there is any places where we don't have tags
+                    // Ideally we should always have tags, but in case we don't, we need to decide how to handle it
+                    // For now we default to a build ID tag, which allow us to invalidate the cache in case something is wrong in this deployment
+                    const tags = this.getTagsFromCacheEntry(value) ?? [
+                        `build_id/${process.env.NEXT_BUILD_ID}`,
+                    ];
+
+                    // We consider R2 as the source of truth, so we update the local cache
+                    // only after a successful R2 write
+                    await localCache.put(
+                        this.getCacheUrlKey(cacheKey),
+                        new Response(
+                            JSON.stringify({
+                                value,
+                                // Note: `Date.now()` returns the time of the last IO rather than the actual time.
+                                //       See https://developers.cloudflare.com/workers/reference/security-model/
+                                lastModified: Date.now(),
+                            }),
+                            {
+                                headers: {
+                                    // Cache-Control default to 30 minutes, will be overridden by `revalidate`
+                                    // In theory we should always get the `revalidate` value
+                                    'cache-control': `max-age=${value.revalidate ?? 60 * 30}`,
+                                    'cache-tag': tags.join(','),
+                                },
+                            }
+                        )
+                    );
+                } catch (e) {
+                    console.error('Failed to set to cache', e);
+                }
+            }
+        );
+    }
+
+    async delete(key: string): Promise<void> {
+        const cacheKey = this.getR2Key(key);
+        return trace(
+            {
+                operation: 'openNextIncrementalCacheDelete',
+                name: cacheKey,
+            },
+            async () => {
+                const r2 = getCloudflareContext().env[BINDING_NAME];
+                const localCache = await this.getCacheInstance();
+                if (!r2) throw new Error('No R2 bucket');
+
+                try {
+                    await r2.delete(cacheKey);
+
+                    // Here again R2 is the source of truth, so we delete from local cache first
+                    await localCache.delete(this.getCacheUrlKey(cacheKey));
+                } catch (e) {
+                    console.error('Failed to delete from cache', e);
+                }
+            }
+        );
+    }
+
+    async getCacheInstance(): Promise<Cache> {
+        if (this.localCache) return this.localCache;
+        this.localCache = await caches.open('incremental-cache');
+        return this.localCache;
+    }
+
+    // Utility function to generate keys for R2/Cache API
+    getR2Key(key: string, cacheType: CacheEntryType = 'cache'): string {
+        const hash = createHash('sha256').update(key).digest('hex');
+        return `${DEFAULT_PREFIX}/${cacheType === 'cache' ? process.env?.NEXT_BUILD_ID : 'dataCache'}/${hash}.${cacheType}`.replace(
+            /\/+/g,
+            '/'
+        );
+    }
+
+    getCacheUrlKey(cacheKey: string): string {
+        return `http://cache.local/${cacheKey}`;
+    }
+
+    getTagsFromCacheEntry<CacheType extends CacheEntryType>(
+        entry: CacheValue<CacheType>
+    ): string[] | undefined {
+        if ('tags' in entry && entry.tags) {
+            return entry.tags;
+        }
+
+        if ('meta' in entry && entry.meta && 'headers' in entry.meta && entry.meta.headers) {
+            const rawTags = entry.meta.headers['x-next-cache-tags'];
+            if (typeof rawTags === 'string') {
+                return rawTags.split(',');
+            }
+        }
+        if ('value' in entry) {
+            return entry.tags;
+        }
+    }
+}
+
+export default new GitbookIncrementalCache();

packages/gitbook-v2/package.json

@@ -1,20 +1,24 @@
 {
     "name": "gitbook-v2",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "private": true,
     "dependencies": {
-        "next": "^15.2.1",
+        "@gitbook/api": "^0.115.0",
+        "@gitbook/cache-tags": "workspace:*",
+        "@opennextjs/cloudflare": "1.0.3",
+        "@sindresorhus/fnv1a": "^3.1.0",
+        "assert-never": "^1.2.1",
+        "jwt-decode": "^4.0.0",
+        "next": "^15.3.2",
         "react": "^19.0.0",
         "react-dom": "^19.0.0",
-        "@gitbook/api": "0.96.1",
+        "rison": "^0.1.1",
-        "@gitbook/cache-tags": "workspace:*",
-        "@sindresorhus/fnv1a": "^3.1.0",
         "server-only": "^0.0.1",
         "warn-once": "^0.1.1"
     },
     "devDependencies": {
         "gitbook": "*",
-        "@opennextjs/cloudflare": "https://pkg.pr.new/opennextjs/opennextjs-cloudflare/@opennextjs/cloudflare@40fec7d",
+        "@types/rison": "^0.0.9",
         "tailwindcss": "^3.4.0",
         "postcss": "^8"
     },
@@ -24,8 +28,9 @@
         "build": "next build",
         "build:v2": "next build",
         "start": "next start",
-        "build:v2:cloudflare": "opennextjs-cloudflare",
+        "build:v2:cloudflare": "opennextjs-cloudflare build",
-        "dev:v2:cloudflare": "wrangler dev --port 8771",
+        "dev:v2:cloudflare": "wrangler dev --port 8771 --env preview",
-        "unit": "bun test"
+        "unit": "bun test",
+        "typecheck": "tsc --noEmit"
     }
 }

packages/gitbook-v2/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/(content)/[pagePath]/page.tsx

@@ -13,26 +13,24 @@ type PageProps = {
 
 export default async function Page(props: PageProps) {
     const params = await props.params;
-    const context = await getDynamicSiteContext(params);
+    const { context } = await getDynamicSiteContext(params);
     const pathname = getPagePathFromParams(params);
 
-    return <SitePage context={context} pageParams={{ pathname }} redirectOnFallback={true} />;
+    return <SitePage context={context} pageParams={{ pathname }} />;
 }
 
 export async function generateViewport(props: PageProps): Promise<Viewport> {
-    const context = await getDynamicSiteContext(await props.params);
+    const { context } = await getDynamicSiteContext(await props.params);
     return generateSitePageViewport(context);
 }
 
 export async function generateMetadata(props: PageProps): Promise<Metadata> {
-    const [params, searchParams] = await Promise.all([props.params, props.searchParams]);
+    const params = await props.params;
-    const context = await getDynamicSiteContext(params);
+    const { context } = await getDynamicSiteContext(params);
     const pathname = getPagePathFromParams(params);
 
     return generateSitePageMetadata({
         context,
         pageParams: { pathname },
-        redirectOnFallback: true,
-        fallback: !!searchParams.fallback,
     });
 }

packages/gitbook-v2/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/(content)/layout.tsx

@@ -6,7 +6,7 @@ import {
 } from '@/components/SiteLayout';
 import { type RouteLayoutParams, getDynamicSiteContext } from '@v2/app/utils';
 import { GITBOOK_DISABLE_TRACKING } from '@v2/lib/env';
-import { getThemeFromMiddleware, getVisitorAuthTokenFromMiddleware } from '@v2/lib/middleware';
+import { getThemeFromMiddleware } from '@v2/lib/middleware';
 
 interface SiteDynamicLayoutProps {
     params: Promise<RouteLayoutParams>;
@@ -16,17 +16,16 @@ export default async function SiteDynamicLayout({
     params,
     children,
 }: React.PropsWithChildren<SiteDynamicLayoutProps>) {
-    const context = await getDynamicSiteContext(await params);
+    const { context, visitorAuthClaims } = await getDynamicSiteContext(await params);
     const forcedTheme = await getThemeFromMiddleware();
-    const visitorAuthToken = await getVisitorAuthTokenFromMiddleware();
 
     return (
-        <CustomizationRootLayout customization={context.customization}>
+        <CustomizationRootLayout forcedTheme={forcedTheme} customization={context.customization}>
             <SiteLayout
                 context={context}
                 forcedTheme={forcedTheme}
                 withTracking={!GITBOOK_DISABLE_TRACKING}
-                visitorAuthToken={visitorAuthToken}
+                visitorAuthClaims={visitorAuthClaims}
             >
                 {children}
             </SiteLayout>
@@ -35,11 +34,11 @@ export default async function SiteDynamicLayout({
 }
 
 export async function generateViewport({ params }: SiteDynamicLayoutProps) {
-    const context = await getDynamicSiteContext(await params);
+    const { context } = await getDynamicSiteContext(await params);
     return generateSiteLayoutViewport(context);
 }
 
 export async function generateMetadata({ params }: SiteDynamicLayoutProps) {
-    const context = await getDynamicSiteContext(await params);
+    const { context } = await getDynamicSiteContext(await params);
     return generateSiteLayoutMetadata(context);
 }

packages/gitbook-v2/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/icon/route.ts

@@ -7,6 +7,6 @@ export async function GET(
     request: NextRequest,
     { params }: { params: Promise<RouteLayoutParams> }
 ) {
-    const context = await getDynamicSiteContext(await params);
+    const { context } = await getDynamicSiteContext(await params);
     return serveIcon(context, request);
 }

packages/gitbook-v2/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/ogimage/[pageId]/route.ts

@@ -8,6 +8,6 @@ export async function GET(
     _request: NextRequest,
     { params }: { params: Promise<RouteLayoutParams & PageIdParams> }
 ) {
-    const context = await getDynamicSiteContext(await params);
+    const { context } = await getDynamicSiteContext(await params);
     return serveOGImage(context, await params);
 }

packages/gitbook-v2/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/pdf/layout.tsx

@@ -0,0 +1,12 @@
+import { PDFRootLayout } from '@/components/PDF';
+import { type RouteLayoutParams, getDynamicSiteContext } from '@v2/app/utils';
+
+export default async function RootLayout(props: {
+    params: Promise<RouteLayoutParams>;
+    children: React.ReactNode;
+}) {
+    const { params, children } = props;
+    const { context } = await getDynamicSiteContext(await params);
+
+    return <PDFRootLayout context={context}>{children}</PDFRootLayout>;
+}

packages/gitbook-v2/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/pdf/page.tsx

@@ -0,0 +1,20 @@
+import { PDFPage, generatePDFMetadata } from '@/components/PDF';
+import { type RouteLayoutParams, getDynamicSiteContext } from '@v2/app/utils';
+
+export async function generateMetadata({
+    params,
+}: {
+    params: Promise<RouteLayoutParams>;
+}) {
+    const { context } = await getDynamicSiteContext(await params);
+    return generatePDFMetadata(context);
+}
+
+export default async function Page(props: {
+    params: Promise<RouteLayoutParams>;
+    searchParams: Promise<{ [key: string]: string }>;
+}) {
+    const { params, searchParams } = props;
+    const { context } = await getDynamicSiteContext(await params);
+    return <PDFPage context={context} searchParams={await searchParams} />;
+}

packages/gitbook-v2/src/app/sites/dynamic/[mode]/[siteURL]/llms.txt/route.ts

@@ -1,12 +0,0 @@
-import type { NextRequest } from 'next/server';
-
-import { serveLLMsTxt } from '@/routes/llms';
-import { type RouteLayoutParams, getDynamicSiteContext } from '@v2/app/utils';
-
-export async function GET(
-    _request: NextRequest,
-    { params }: { params: Promise<RouteLayoutParams> }
-) {
-    const context = await getDynamicSiteContext(await params);
-    return serveLLMsTxt(context);
-}

packages/gitbook-v2/src/app/sites/dynamic/[mode]/[siteURL]/robots.txt/route.ts

@@ -1,12 +0,0 @@
-import type { NextRequest } from 'next/server';
-
-import { serveRobotsTxt } from '@/routes/robots';
-import { type RouteLayoutParams, getDynamicSiteContext } from '@v2/app/utils';
-
-export async function GET(
-    _request: NextRequest,
-    { params }: { params: Promise<RouteLayoutParams> }
-) {
-    const context = await getDynamicSiteContext(await params);
-    return serveRobotsTxt(context);
-}

packages/gitbook-v2/src/app/sites/dynamic/[mode]/[siteURL]/sitemap-pages.xml/route.ts

@@ -1,12 +0,0 @@
-import type { NextRequest } from 'next/server';
-
-import { servePagesSitemap } from '@/routes/sitemap';
-import { type RouteLayoutParams, getDynamicSiteContext } from '@v2/app/utils';
-
-export async function GET(
-    _request: NextRequest,
-    { params }: { params: Promise<RouteLayoutParams> }
-) {
-    const context = await getDynamicSiteContext(await params);
-    return servePagesSitemap(context);
-}

packages/gitbook-v2/src/app/sites/dynamic/[mode]/[siteURL]/sitemap.xml/route.ts

@@ -1,12 +0,0 @@
-import type { NextRequest } from 'next/server';
-
-import { serveRootSitemap } from '@/routes/sitemap';
-import { type RouteLayoutParams, getDynamicSiteContext } from '@v2/app/utils';
-
-export async function GET(
-    _request: NextRequest,
-    { params }: { params: Promise<RouteLayoutParams> }
-) {
-    const context = await getDynamicSiteContext(await params);
-    return serveRootSitemap(context);
-}

packages/gitbook-v2/src/app/sites/static/[mode]/[siteURL]/[siteData]/[pagePath]/page.tsx

@@ -3,10 +3,9 @@ import {
     generateSitePageMetadata,
     generateSitePageViewport,
 } from '@/components/SitePage';
-import { getCacheTag } from '@gitbook/cache-tags';
 import { type RouteParams, getPagePathFromParams, getStaticSiteContext } from '@v2/app/utils';
+
 import type { Metadata, Viewport } from 'next';
-import { unstable_cacheTag as cacheTag } from 'next/cache';
 
 export const dynamic = 'force-static';
 
@@ -15,35 +14,25 @@ type PageProps = {
 };
 
 export default async function Page(props: PageProps) {
-    'use cache';
-
     const params = await props.params;
-    const context = await getStaticSiteContext(params);
+    const { context } = await getStaticSiteContext(params);
     const pathname = getPagePathFromParams(params);
 
-    cacheTag(
+    return <SitePage context={context} pageParams={{ pathname }} />;
-        getCacheTag({
-            tag: 'site',
-            site: context.site.id,
-        })
-    );
-
-    return <SitePage context={context} pageParams={{ pathname }} redirectOnFallback={true} />;
 }
 
 export async function generateViewport(props: PageProps): Promise<Viewport> {
-    const context = await getStaticSiteContext(await props.params);
+    const { context } = await getStaticSiteContext(await props.params);
     return generateSitePageViewport(context);
 }
 
 export async function generateMetadata(props: PageProps): Promise<Metadata> {
     const params = await props.params;
-    const context = await getStaticSiteContext(params);
+    const { context } = await getStaticSiteContext(params);
     const pathname = getPagePathFromParams(params);
 
     return generateSitePageMetadata({
         context,
         pageParams: { pathname },
-        redirectOnFallback: true,
     });
 }

packages/gitbook-v2/src/app/sites/static/[mode]/[siteURL]/[siteData]/layout.tsx

@@ -4,10 +4,8 @@ import {
     generateSiteLayoutMetadata,
     generateSiteLayoutViewport,
 } from '@/components/SiteLayout';
-import { getCacheTag } from '@gitbook/cache-tags';
 import { type RouteLayoutParams, getStaticSiteContext } from '@v2/app/utils';
 import { GITBOOK_DISABLE_TRACKING } from '@v2/lib/env';
-import { unstable_cacheTag as cacheTag } from 'next/cache';
 
 interface SiteStaticLayoutProps {
     params: Promise<RouteLayoutParams>;
@@ -17,23 +15,14 @@ export default async function SiteStaticLayout({
     params,
     children,
 }: React.PropsWithChildren<SiteStaticLayoutProps>) {
-    'use cache';
+    const { context, visitorAuthClaims } = await getStaticSiteContext(await params);
-
-    const context = await getStaticSiteContext(await params);
-
-    cacheTag(
-        getCacheTag({
-            tag: 'site',
-            site: context.site.id,
-        })
-    );
 
     return (
         <CustomizationRootLayout customization={context.customization}>
             <SiteLayout
                 context={context}
                 withTracking={!GITBOOK_DISABLE_TRACKING}
-                visitorAuthToken={null}
+                visitorAuthClaims={visitorAuthClaims}
             >
                 {children}
             </SiteLayout>
@@ -42,11 +31,11 @@ export default async function SiteStaticLayout({
 }
 
 export async function generateViewport({ params }: SiteStaticLayoutProps) {
-    const context = await getStaticSiteContext(await params);
+    const { context } = await getStaticSiteContext(await params);
     return generateSiteLayoutViewport(context);
 }
 
 export async function generateMetadata({ params }: SiteStaticLayoutProps) {
-    const context = await getStaticSiteContext(await params);
+    const { context } = await getStaticSiteContext(await params);
     return generateSiteLayoutMetadata(context);
 }

packages/gitbook-v2/src/app/sites/static/[mode]/[siteURL]/[siteData]/llms.txt/route.ts

@@ -9,6 +9,6 @@ export async function GET(
     _request: NextRequest,
     { params }: { params: Promise<RouteLayoutParams> }
 ) {
-    const context = await getStaticSiteContext(await params);
+    const { context } = await getStaticSiteContext(await params);
-    return serveLLMsTxt(context);
+    return serveLLMsTxt(context, { withMarkdownPages: true });
 }

packages/gitbook-v2/src/app/sites/static/[mode]/[siteURL]/[siteData]/robots.txt/route.ts

@@ -9,6 +9,6 @@ export async function GET(
     _request: NextRequest,
     { params }: { params: Promise<RouteLayoutParams> }
 ) {
-    const context = await getStaticSiteContext(await params);
+    const { context } = await getStaticSiteContext(await params);
     return serveRobotsTxt(context);
 }

packages/gitbook-v2/src/app/sites/static/[mode]/[siteURL]/[siteData]/sitemap-pages.xml/route.ts

@@ -9,6 +9,6 @@ export async function GET(
     _request: NextRequest,
     { params }: { params: Promise<RouteLayoutParams> }
 ) {
-    const context = await getStaticSiteContext(await params);
+    const { context } = await getStaticSiteContext(await params);
     return servePagesSitemap(context);
 }

packages/gitbook-v2/src/app/sites/static/[mode]/[siteURL]/[siteData]/sitemap.xml/route.ts

@@ -9,6 +9,6 @@ export async function GET(
     _request: NextRequest,
     { params }: { params: Promise<RouteLayoutParams> }
 ) {
-    const context = await getStaticSiteContext(await params);
+    const { context } = await getStaticSiteContext(await params);
     return serveRootSitemap(context);
 }

packages/gitbook-v2/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/icon/route.ts

@@ -9,6 +9,6 @@ export async function GET(
     request: NextRequest,
     { params }: { params: Promise<RouteLayoutParams> }
 ) {
-    const context = await getStaticSiteContext(await params);
+    const { context } = await getStaticSiteContext(await params);
     return serveIcon(context, request);
 }

packages/gitbook-v2/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/markdown/[pagePath]/route.ts

@@ -0,0 +1,11 @@
+import { servePageMarkdown } from '@/routes/markdownPage';
+import { type RouteParams, getPagePathFromParams, getStaticSiteContext } from '@v2/app/utils';
+import type { NextRequest } from 'next/server';
+
+export const dynamic = 'force-static';
+
+export async function GET(_request: NextRequest, { params }: { params: Promise<RouteParams> }) {
+    const { context } = await getStaticSiteContext(await params);
+    const pathname = getPagePathFromParams(await params);
+    return servePageMarkdown(context, pathname);
+}

packages/gitbook-v2/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/ogimage/[pageId]/route.ts

@@ -10,6 +10,6 @@ export async function GET(
     _request: NextRequest,
     { params }: { params: Promise<RouteLayoutParams & PageIdParams> }
 ) {
-    const context = await getStaticSiteContext(await params);
+    const { context } = await getStaticSiteContext(await params);
     return serveOGImage(context, await params);
 }

packages/gitbook-v2/src/app/utils.ts

@@ -1,9 +1,9 @@
-import {
+import { getVisitorAuthClaims, getVisitorAuthClaimsFromToken } from '@/lib/adaptive';
-    fetchSiteContextByURL,
+import type { SiteAPIToken } from '@gitbook/api';
-    fetchSiteContextByURLLookup,
+import { type SiteURLData, fetchSiteContextByURLLookup, getBaseContext } from '@v2/lib/context';
-    getBaseContext,
+import { jwtDecode } from 'jwt-decode';
-} from '@v2/lib/context';
+import { forbidden } from 'next/navigation';
-import { getSiteURLDataFromMiddleware } from '@v2/lib/middleware';
+import rison from 'rison';
 
 export type RouteParamMode = 'url-host' | 'url';
 
@@ -12,6 +12,9 @@ export type RouteLayoutParams = {
 
     /** URL encoded site URL */
     siteURL: string;
+
+    /** URL and Rison encoded site data from getPublishedContentByUrl */
+    siteData: string;
 };
 
 export type RouteParams = RouteLayoutParams & {
@@ -21,19 +24,30 @@ export type RouteParams = RouteLayoutParams & {
 /**
  * Get the static context when rendering statically a site.
  */
-export function getStaticSiteContext(params: RouteLayoutParams) {
+export async function getStaticSiteContext(params: RouteLayoutParams) {
     const siteURL = getSiteURLFromParams(params);
-    return fetchSiteContextByURL(
+    const siteURLData = getSiteURLDataFromParams(params);
+
+    // For static routes, we check the expiration of the JWT token
+    // as the route might be revalidated after expiration
+    const decoded = jwtDecode<SiteAPIToken & { exp: number }>(siteURLData.apiToken);
+    if (decoded.exp && decoded.exp < Date.now() / 1000 + 120) {
+        forbidden();
+    }
+
+    const context = await fetchSiteContextByURLLookup(
         getBaseContext({
             siteURL,
+            siteURLData,
             urlMode: getModeFromParams(params.mode),
         }),
-        {
+        siteURLData
-            url: siteURL.toString(),
-            visitorAuthToken: null,
-            redirectOnError: false,
-        }
     );
+
+    return {
+        context,
+        visitorAuthClaims: getVisitorAuthClaimsFromToken(decoded),
+    };
 }
 
 /**
@@ -42,15 +56,21 @@ export function getStaticSiteContext(params: RouteLayoutParams) {
  */
 export async function getDynamicSiteContext(params: RouteLayoutParams) {
     const siteURL = getSiteURLFromParams(params);
-    const siteURLData = await getSiteURLDataFromMiddleware();
+    const siteURLData = getSiteURLDataFromParams(params);
 
-    return fetchSiteContextByURLLookup(
+    const context = await fetchSiteContextByURLLookup(
         getBaseContext({
             siteURL,
+            siteURLData,
             urlMode: getModeFromParams(params.mode),
         }),
         siteURLData
     );
+
+    return {
+        context,
+        visitorAuthClaims: getVisitorAuthClaims(siteURLData),
+    };
 }
 
 /**
@@ -74,3 +94,11 @@ function getModeFromParams(mode: string): RouteParamMode {
 
     return 'url';
 }
+
+/**
+ * Get the decoded site data from the params.
+ */
+function getSiteURLDataFromParams(params: RouteLayoutParams): SiteURLData {
+    const decoded = decodeURIComponent(params.siteData);
+    return rison.decode(decoded);
+}

packages/gitbook-v2/src/app/~gitbook/env/route.ts

@@ -1,11 +1,13 @@
 import { type NextRequest, NextResponse } from 'next/server';
 
 import {
+    GITBOOK_API_PUBLIC_URL,
     GITBOOK_API_TOKEN,
     GITBOOK_API_URL,
     GITBOOK_APP_URL,
     GITBOOK_ASSETS_URL,
     GITBOOK_DISABLE_TRACKING,
+    GITBOOK_FONTS_URL,
     GITBOOK_ICONS_URL,
     GITBOOK_IMAGE_RESIZE_SIGNING_KEY,
     GITBOOK_INTEGRATIONS_HOST,
@@ -22,7 +24,9 @@ export async function GET(_req: NextRequest) {
         GITBOOK_URL,
         GITBOOK_APP_URL,
         GITBOOK_API_URL,
+        GITBOOK_API_PUBLIC_URL,
         GITBOOK_ASSETS_URL,
+        GITBOOK_FONTS_URL,
         GITBOOK_ICONS_URL,
         GITBOOK_USER_AGENT,
         GITBOOK_INTEGRATIONS_HOST,

packages/gitbook-v2/src/app/~space/[spaceId]/pdf.ts

@@ -0,0 +1,59 @@
+import {
+    type GitBookBaseContext,
+    type GitBookSpaceContext,
+    fetchSpaceContextByIds,
+} from '@v2/lib/context';
+import { createDataFetcher } from '@v2/lib/data';
+import { createLinker } from '@v2/lib/links';
+import { getAPITokenFromMiddleware } from '@v2/lib/middleware';
+
+export type SpacePDFRouteParams = {
+    spaceId: string;
+    changeRequestId?: string;
+    revisionId?: string;
+};
+
+export async function getSpacePDFContext(
+    params: SpacePDFRouteParams
+): Promise<GitBookSpaceContext> {
+    const { spaceId } = params;
+
+    const apiToken = await getAPITokenFromMiddleware();
+
+    const basePath = getPDFRoutePath(params);
+    const linker = createLinker({
+        spaceBasePath: basePath,
+        siteBasePath: basePath,
+    });
+    const dataFetcher = createDataFetcher({
+        apiToken: apiToken,
+    });
+
+    const baseContext: GitBookBaseContext = {
+        linker,
+        dataFetcher,
+    };
+
+    return await fetchSpaceContextByIds(baseContext, {
+        space: spaceId,
+        shareKey: undefined,
+        changeRequest: params.changeRequestId,
+        revision: params.revisionId,
+    });
+}
+
+function getPDFRoutePath(params: SpacePDFRouteParams) {
+    let path = `/~space/${params.spaceId}`;
+
+    if (params.changeRequestId) {
+        path += `/~/changes/${params.changeRequestId}`;
+    }
+
+    if (params.revisionId) {
+        path += `/~/revisions/${params.revisionId}`;
+    }
+
+    path += '~gitbook/pdf';
+
+    return path;
+}

packages/gitbook-v2/src/app/~space/[spaceId]/~/changes/[changeRequestId]/~gitbook/pdf/layout.tsx

@@ -0,0 +1,2 @@
+import RootLayout from '@v2/app/~space/[spaceId]/~gitbook/pdf/layout';
+export default RootLayout;

packages/gitbook-v2/src/app/~space/[spaceId]/~/changes/[changeRequestId]/~gitbook/pdf/page.tsx

@@ -0,0 +1,4 @@
+import PDFPage, { generateMetadata } from '@v2/app/~space/[spaceId]/~gitbook/pdf/page';
+
+export default PDFPage;
+export { generateMetadata };

packages/gitbook-v2/src/app/~space/[spaceId]/~/revisions/[changeRequestId]/~gitbook/pdf/layout.tsx

@@ -0,0 +1,2 @@
+import RootLayout from '@v2/app/~space/[spaceId]/~gitbook/pdf/layout';
+export default RootLayout;

packages/gitbook-v2/src/app/~space/[spaceId]/~/revisions/[changeRequestId]/~gitbook/pdf/page.tsx

@@ -0,0 +1,4 @@
+import PDFPage, { generateMetadata } from '@v2/app/~space/[spaceId]/~gitbook/pdf/page';
+
+export default PDFPage;
+export { generateMetadata };

packages/gitbook-v2/src/app/~space/[spaceId]/~gitbook/pdf/layout.tsx

@@ -0,0 +1,12 @@
+import { PDFRootLayout } from '@/components/PDF';
+import { type SpacePDFRouteParams, getSpacePDFContext } from '@v2/app/~space/[spaceId]/pdf';
+
+export default async function RootLayout(props: {
+    params: Promise<SpacePDFRouteParams>;
+    children: React.ReactNode;
+}) {
+    const { params, children } = props;
+    const context = await getSpacePDFContext(await params);
+
+    return <PDFRootLayout context={context}>{children}</PDFRootLayout>;
+}

packages/gitbook-v2/src/app/~space/[spaceId]/~gitbook/pdf/page.tsx

@@ -0,0 +1,20 @@
+import { PDFPage, generatePDFMetadata } from '@/components/PDF';
+import { type SpacePDFRouteParams, getSpacePDFContext } from '@v2/app/~space/[spaceId]/pdf';
+
+export async function generateMetadata({
+    params,
+}: {
+    params: Promise<SpacePDFRouteParams>;
+}) {
+    const context = await getSpacePDFContext(await params);
+    return generatePDFMetadata(context);
+}
+
+export default async function Page(props: {
+    params: Promise<SpacePDFRouteParams>;
+    searchParams: Promise<{ [key: string]: string }>;
+}) {
+    const { params, searchParams } = props;
+    const context = await getSpacePDFContext(await params);
+    return <PDFPage context={context} searchParams={await searchParams} />;
+}

packages/gitbook-v2/src/lib/context.ts

@@ -1,7 +1,7 @@
 import { getSiteStructureSections } from '@/lib/sites';
 import type {
     ChangeRequest,
-    PublishedSiteContentLookup,
+    PublishedSiteContent,
     RevisionPage,
     RevisionPageDocument,
     Site,
@@ -13,12 +13,42 @@ import type {
     SiteStructure,
     Space,
 } from '@gitbook/api';
-import { type GitBookDataFetcher, createDataFetcher, throwIfDataError } from '@v2/lib/data';
+import {
-import { redirect } from 'next/navigation';
+    type GitBookDataFetcher,
+    createDataFetcher,
+    getDataOrNull,
+    throwIfDataError,
+} from '@v2/lib/data';
+import assertNever from 'assert-never';
+import { notFound } from 'next/navigation';
 import { assert } from 'ts-essentials';
-import { GITBOOK_API_TOKEN, GITBOOK_API_URL, GITBOOK_URL } from './env';
+import { GITBOOK_URL } from './env';
 import { type ImageResizer, createImageResizer } from './images';
-import { type GitBookSpaceLinker, createLinker } from './links';
+import { type GitBookLinker, createLinker } from './links';
+
+/**
+ * Data about the site URL. Provided by the middleware.
+ * These data are stable between pages in the same site space.
+ */
+export type SiteURLData = Pick<
+    PublishedSiteContent,
+    | 'organization'
+    | 'apiToken'
+    | 'site'
+    | 'siteSpace'
+    | 'space'
+    | 'revision'
+    | 'changeRequest'
+    | 'shareKey'
+    | 'siteSection'
+    | 'siteBasePath'
+    | 'basePath'
+> & {
+    /**
+     * Identifier used for image resizing.
+     */
+    imagesContextId: string;
+};
 
 /**
  * Generic context when rendering content.
@@ -32,7 +62,7 @@ export type GitBookBaseContext = {
     /**
      * Linker to generate links in the current space.
      */
-    linker: GitBookSpaceLinker;
+    linker: GitBookLinker;
 
     /**
      * Image resizer to resize images.
@@ -102,44 +132,45 @@ export type GitBookPageContext = (GitBookSpaceContext | GitBookSiteContext) & {
 };
 
 /**
- * Get the base context for a request.
+ * Get the base context for a request on a site.
  */
 export function getBaseContext(input: {
     siteURL: URL | string;
+    siteURLData: SiteURLData;
     urlMode: 'url' | 'url-host';
-    apiToken?: string | null;
 }) {
-    const url = typeof input.siteURL === 'string' ? new URL(input.siteURL) : input.siteURL;
+    const { urlMode, siteURLData } = input;
-    const urlMode = input.urlMode;
+    const siteURL = typeof input.siteURL === 'string' ? new URL(input.siteURL) : input.siteURL;
 
     const dataFetcher = createDataFetcher({
-        apiToken: input.apiToken ?? GITBOOK_API_TOKEN,
+        apiToken: siteURLData.apiToken ?? null,
-        apiEndpoint: GITBOOK_API_URL,
     });
-    const gitbookURL = GITBOOK_URL ? new URL(GITBOOK_URL) : undefined;
 
+    const gitbookURL = GITBOOK_URL ? new URL(GITBOOK_URL) : undefined;
     const linker =
         urlMode === 'url-host'
             ? createLinker({
-                  host: url.host,
+                  host: siteURL.host,
-                  pathname: url.pathname,
+                  siteBasePath: siteURLData.siteBasePath,
+                  spaceBasePath: siteURLData.basePath,
               })
             : createLinker({
                   protocol: gitbookURL?.protocol,
                   host: gitbookURL?.host,
-                  pathname: `/url/${url.host}${url.pathname}`,
+                  siteBasePath: `/url/${siteURL.host}${siteURLData.siteBasePath}`,
+                  spaceBasePath: `/url/${siteURL.host}${siteURLData.basePath}`,
               });
 
     if (urlMode === 'url') {
         // Create link in the same format for links to other sites/sections.
         linker.toLinkForContent = (rawURL: string) => {
             const urlObject = new URL(rawURL);
-            return `/url/${urlObject.host}${urlObject.pathname}`;
+            return `/url/${urlObject.host}${urlObject.pathname}${urlObject.search}`;
         };
     }
 
     const imageResizer = createImageResizer({
-        host: url.host,
+        imagesContextId: siteURLData.imagesContextId,
         // To ensure image resizing work for proxied sites,
         // we serve images from the root of the site.
         linker: linker,
@@ -152,59 +183,23 @@ export function getBaseContext(input: {
     };
 }
 
-/**
- * Fetch the context of a site for a given URL and a base context.
- */
-export async function fetchSiteContextByURL(
-    baseContext: GitBookBaseContext,
-    input: {
-        url: string;
-        visitorAuthToken: string | null;
-        redirectOnError: boolean;
-    }
-): Promise<GitBookSiteContext> {
-    const { dataFetcher } = baseContext;
-    const data = await throwIfDataError(
-        dataFetcher.getPublishedContentByUrl({
-            url: input.url,
-            visitorAuthToken: input.visitorAuthToken,
-            redirectOnError: input.redirectOnError,
-        })
-    );
-
-    return fetchSiteContextByURLLookup(baseContext, data);
-}
-
 /**
  * Fetch the context of a site using the resolution of a URL
  */
 export async function fetchSiteContextByURLLookup(
     baseContext: GitBookBaseContext,
-    data: PublishedSiteContentLookup
+    data: SiteURLData
 ): Promise<GitBookSiteContext> {
-    const { dataFetcher } = baseContext;
+    return await fetchSiteContextByIds(baseContext, {
-    if ('redirect' in data) {
+        organization: data.organization,
-        redirect(data.redirect);
+        site: data.site,
-    }
+        siteSection: data.siteSection,
-
+        siteSpace: data.siteSpace,
-    return await fetchSiteContextByIds(
+        space: data.space,
-        {
+        shareKey: data.shareKey,
-            ...baseContext,
+        changeRequest: data.changeRequest,
-            dataFetcher: dataFetcher.withToken({
+        revision: data.revision,
-                apiToken: data.apiToken,
+    });
-            }),
-        },
-        {
-            organization: data.organization,
-            site: data.site,
-            siteSection: data.siteSection,
-            siteSpace: data.siteSpace,
-            space: data.space,
-            shareKey: data.shareKey,
-            changeRequest: data.changeRequest,
-            revision: data.revision,
-        }
-    );
 }
 
 /**
@@ -248,19 +243,45 @@ export async function fetchSiteContextByIds(
         ? parseSiteSectionsAndGroups(siteStructure, ids.siteSection)
         : null;
 
-    const siteSpace = (
+    // Parse the current siteSpace and siteSpaces based on the site structure type.
-        siteStructure.type === 'siteSpaces' && siteStructure.structure
+    const { siteSpaces, siteSpace }: { siteSpaces: SiteSpace[]; siteSpace: SiteSpace } = (() => {
-            ? siteStructure.structure
+        if (siteStructure.type === 'siteSpaces') {
-            : sections?.current.siteSpaces
+            const siteSpaces = siteStructure.structure;
-    )?.find((siteSpace) => siteSpace.id === ids.siteSpace);
+            const siteSpace = siteSpaces.find((siteSpace) => siteSpace.id === ids.siteSpace);
-    if (!siteSpace) {
-        throw new Error('Site space not found');
-    }
 
-    const siteSpaces =
+            if (!siteSpace) {
-        siteStructure.type === 'siteSpaces'
+                throw new Error(
-            ? siteStructure.structure
+                    `Site space "${ids.siteSpace}" not found in structure type="siteSpaces"`
-            : (sections?.current.siteSpaces ?? []);
+                );
+            }
+
+            return { siteSpaces, siteSpace };
+        }
+
+        if (siteStructure.type === 'sections') {
+            assert(
+                sections,
+                `cannot find site space "${ids.siteSpace}" because parsed sections are missing siteStructure.type="sections" siteSection="${ids.siteSection}"`
+            );
+
+            const currentSection = sections.current;
+            const siteSpaces = currentSection.siteSpaces;
+            const siteSpace = currentSection.siteSpaces.find(
+                (siteSpace) => siteSpace.id === ids.siteSpace
+            );
+
+            if (!siteSpace) {
+                throw new Error(
+                    `Site space "${ids.siteSpace}" not found in structure type="sections" currentSection="${currentSection.id}"`
+                );
+            }
+
+            return { siteSpaces, siteSpace };
+        }
+
+        // @ts-expect-error
+        assertNever(siteStructure, `cannot handle site structure of type ${siteStructure.type}`);
+    })();
 
     const customization = (() => {
         if (ids.siteSpace) {
@@ -313,7 +334,7 @@ export async function fetchSpaceContextByIds(
             })
         ),
         ids.changeRequest
-            ? throwIfDataError(
+            ? getDataOrNull(
                   dataFetcher.getChangeRequest({
                       spaceId: ids.space,
                       changeRequestId: ids.changeRequest,
@@ -322,17 +343,30 @@ export async function fetchSpaceContextByIds(
             : null,
     ]);
 
-    const revisionId = changeRequest?.revision ?? ids.revision ?? space.revision;
+    if (ids.changeRequest && !changeRequest) {
+        // When trying to render a change request with an invalid / non-existing ID,
+        // we should return a 404.
+        notFound();
+    }
 
-    const pages = await throwIfDataError(
+    const revisionId = ids.revision ?? changeRequest?.revision ?? space.revision;
+
+    const pages = await getDataOrNull(
         dataFetcher.getRevisionPages({
             spaceId: ids.space,
             revisionId,
             // We only care about the Git metadata when the Git sync is enabled,
             // otherwise we can optimize performance by not fetching it
             metadata: !!space.gitSync,
-        })
+        }),
+
+        // When trying to render a revision with an invalid / non-existing ID,
+        // we should handle gracefully the 404 and throw notFound.
+        ids.revision ? [404] : undefined
     );
+    if (!pages) {
+        notFound();
+    }
 
     return {
         ...baseContext,
@@ -373,7 +407,7 @@ export function checkIsRootSiteContext(context: GitBookSiteContext): boolean {
 function parseSiteSectionsAndGroups(structure: SiteStructure, siteSectionId: string) {
     const sectionsAndGroups = getSiteStructureSections(structure, { ignoreGroups: false });
     const section = parseCurrentSection(structure, siteSectionId);
-    assert(section, 'A section must be defined when there are multiple sections');
+    assert(section, `couldn't find section "${siteSectionId}" in site structure`);
     return { list: sectionsAndGroups, current: section } satisfies SiteSections;
 }
 

packages/gitbook-v2/src/lib/data/cloudflare.ts

@@ -0,0 +1,25 @@
+import { getCloudflareContext as getCloudflareContextOpenNext } from '@opennextjs/cloudflare';
+import { GITBOOK_RUNTIME } from '../env';
+
+/**
+ * Return the Cloudflare context or null when not running in Cloudflare.
+ */
+export function getCloudflareContext() {
+    if (GITBOOK_RUNTIME !== 'cloudflare') {
+        return null;
+    }
+
+    return getCloudflareContextOpenNext();
+}
+
+/**
+ * Return an object representing the current request.
+ */
+export function getCloudflareRequestGlobal() {
+    const context = getCloudflareContext();
+    if (!context) {
+        return null;
+    }
+
+    return context.cf;
+}

packages/gitbook-v2/src/lib/data/errors.ts

@@ -93,8 +93,15 @@ export async function wrapDataFetcherError<T>(
     }
 }
 
-function getExposableError(error: Error): DataFetcherErrorData {
+/**
+ * Get a data fetcher exposable error from a JS error.
+ */
+export function getExposableError(error: Error): DataFetcherErrorData {
     if (error instanceof GitBookAPIError) {
+        if (error.code >= 500) {
+            throw error;
+        }
+
         return {
             code: error.code,
             message: error.errorMessage,
@@ -102,6 +109,10 @@ function getExposableError(error: Error): DataFetcherErrorData {
     }
 
     if (error instanceof DataFetcherError) {
+        if (error.code >= 500) {
+            throw error;
+        }
+
         return {
             code: error.code,
             message: error.message,

packages/gitbook-v2/src/lib/data/index.ts

@@ -4,3 +4,5 @@ export * from './pages';
 export * from './urls';
 export * from './errors';
 export * from './lookup';
+export * from './proxy';
+export * from './visitor';

packages/gitbook-v2/src/lib/data/lookup.ts

@@ -1,49 +1,103 @@
 import { race, tryCatch } from '@/lib/async';
-import { joinPath } from '@/lib/paths';
+import { joinPath, joinPathWithBaseURL } from '@/lib/paths';
-import { GitBookAPI, type GitBookAPIError, type PublishedSiteContentLookup } from '@gitbook/api';
+import { trace } from '@/lib/tracing';
-import { GITBOOK_API_TOKEN, GITBOOK_API_URL, GITBOOK_USER_AGENT } from '@v2/lib/env';
+import type { GitBookAPI, PublishedSiteContentLookup, SiteVisitorPayload } from '@gitbook/api';
+import { apiClient } from './api';
+import { getExposableError } from './errors';
+import type { DataFetcherResponse } from './types';
 import { getURLLookupAlternatives, stripURLSearch } from './urls';
 
+interface LookupPublishedContentByUrlInput {
+    url: string;
+    redirectOnError: boolean;
+    apiToken: string | null;
+    visitorPayload: SiteVisitorPayload;
+}
+
 /**
- * Lookup a content by its URL using the GitBook API.
+ * Lookup a content by its URL using the GitBook resolvePublishedContentByUrl API endpoint.
  * To optimize caching, we try multiple lookup alternatives and return the first one that matches.
  */
-export async function getPublishedContentByURL(input: {
+export async function resolvePublishedContentByUrl(input: LookupPublishedContentByUrlInput) {
+    return lookupPublishedContentByUrl({
+        url: input.url,
+        fetchLookupAPIResult: ({ url, signal }) => {
+            const api = apiClient({ apiToken: input.apiToken });
+            return trace(
+                {
+                    operation: 'resolvePublishedContentByUrl',
+                    name: url,
+                },
+                () =>
+                    tryCatch(
+                        api.urls.resolvePublishedContentByUrl(
+                            {
+                                url,
+                                ...(input.visitorPayload ? { visitor: input.visitorPayload } : {}),
+                                redirectOnError: input.redirectOnError,
+                            },
+                            { signal }
+                        )
+                    )
+            );
+        },
+    });
+}
+
+/**
+ * Lookup a content by its URL using the GitBook getPublishedContentByUrl API endpoint.
+ * To optimize caching, we try multiple lookup alternatives and return the first one that matches.
+ *
+ * @deprecated use resolvePublishedContentByUrl.
+ *
+ */
+export async function getPublishedContentByURL(input: LookupPublishedContentByUrlInput) {
+    return lookupPublishedContentByUrl({
+        url: input.url,
+        fetchLookupAPIResult: ({ url, signal }) => {
+            const api = apiClient({ apiToken: input.apiToken });
+            return trace(
+                {
+                    operation: 'getPublishedContentByURL',
+                    name: url,
+                },
+                () =>
+                    tryCatch(
+                        api.urls.getPublishedContentByUrl(
+                            {
+                                url,
+                                visitorAuthToken: input.visitorPayload.jwtToken ?? undefined,
+                                redirectOnError: input.redirectOnError,
+                                // @ts-expect-error - cacheVersion is not a real query param
+                                cacheVersion: 'v2',
+                            },
+                            { signal }
+                        )
+                    )
+            );
+        },
+    });
+}
+
+type TryCatch<T> = ReturnType<typeof tryCatch<T>>;
+
+async function lookupPublishedContentByUrl(input: {
     url: string;
-    visitorAuthToken: string | null;
+    fetchLookupAPIResult: (args: {
-    redirectOnError: boolean;
+        url: string;
-}): Promise<
+        signal: AbortSignal;
-    | { data: PublishedSiteContentLookup; error?: undefined }
+    }) => TryCatch<Awaited<ReturnType<GitBookAPI['urls']['resolvePublishedContentByUrl']>>>;
-    | { data?: undefined; error: Error | GitBookAPIError }
+}): Promise<DataFetcherResponse<PublishedSiteContentLookup>> {
-> {
     const lookupURL = new URL(input.url);
     const url = stripURLSearch(lookupURL);
     const lookup = getURLLookupAlternatives(url);
 
     const result = await race(lookup.urls, async (alternative, { signal }) => {
-        const api = new GitBookAPI({
+        const callResult = await input.fetchLookupAPIResult({
-            authToken: GITBOOK_API_TOKEN ?? undefined,
+            url: alternative.url,
-            endpoint: GITBOOK_API_URL,
+            signal,
-            userAgent: GITBOOK_USER_AGENT,
         });
 
-        const callResult = await tryCatch(
-            api.urls.getPublishedContentByUrl(
-                {
-                    url: alternative.url,
-                    visitorAuthToken: input.visitorAuthToken ?? undefined,
-                    redirectOnError: input.redirectOnError,
-                    cache: true,
-                },
-                {
-                    signal,
-                    headers: {
-                        'x-gitbook-force-cache': 'true',
-                    },
-                }
-            )
-        );
-
         if (callResult.error) {
             if (alternative.primary) {
                 // We only return an error for the primary alternative (full URL),
@@ -95,12 +149,16 @@ export async function getPublishedContentByURL(input: {
          * In both cases, the idea is to use the deepest/longest/most inclusive path to resolve the content.
          */
         if (alternative.primary || ('site' in data && data.complete)) {
+            const changeRequest = data.changeRequest ?? lookup.changeRequest;
+            const revision = data.revision ?? lookup.revision;
+
             const siteResult: PublishedSiteContentLookup = {
                 ...data,
-                changeRequest: data.changeRequest ?? lookup.changeRequest,
+                canonicalUrl: joinPathWithBaseURL(data.canonicalUrl, alternative.extraPath),
-                revision: data.revision ?? lookup.revision,
                 basePath: joinPath(data.basePath, lookup.basePath ?? ''),
                 pathname: joinPath(data.pathname, alternative.extraPath),
+                ...(changeRequest ? { changeRequest } : {}),
+                ...(revision ? { revision } : {}),
             };
             return { data: siteResult };
         }
@@ -110,9 +168,20 @@ export async function getPublishedContentByURL(input: {
 
     if (!result) {
         return {
-            error: new Error('No content found'),
+            error: {
+                code: 404,
+                message: 'No content found',
+            },
         };
     }
 
-    return result;
+    if (result.error) {
+        return {
+            error: getExposableError(result.error),
+        };
+    }
+
+    return {
+        data: result.data,
+    };
 }

packages/gitbook-v2/src/lib/data/memoize.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it, mock } from 'bun:test';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { withCacheKey, withoutConcurrentExecution } from './memoize';
+
+describe('withoutConcurrentExecution', () => {
+    it('should memoize the function based on the cache key', async () => {
+        const fn = mock(async (_cacheKey: string, a: number, b: number) => a + b);
+        const memoized = withoutConcurrentExecution(() => null, fn);
+
+        const p1 = memoized('c1', 1, 2);
+        const p2 = memoized('c1', 1, 2);
+        const p3 = memoized('c3', 2, 3);
+
+        expect(await p1).toBe(await p2);
+        expect(await p1).not.toBe(await p3);
+        expect(fn.mock.calls.length).toBe(2);
+    });
+
+    it('should support caching per request', async () => {
+        const fn = mock(async () => Math.random());
+
+        const request1 = { id: 'request1' };
+        const request2 = { id: 'request2' };
+
+        const requestContext = new AsyncLocalStorage<{ id: string }>();
+
+        const memoized = withoutConcurrentExecution(() => requestContext.getStore(), fn);
+
+        // Both in the same request
+        const promise1 = requestContext.run(request1, () => memoized('c1'));
+        const promise2 = requestContext.run(request1, () => memoized('c1'));
+
+        // In a different request
+        const promise3 = requestContext.run(request2, () => memoized('c1'));
+
+        expect(await promise1).toBe(await promise2);
+        expect(await promise1).not.toBe(await promise3);
+        expect(fn.mock.calls.length).toBe(2);
+    });
+});
+
+describe('withCacheKey', () => {
+    it('should wrap the function by passing the cache key', async () => {
+        const fn = mock(
+            async (cacheKey: string, arg: { a: number; b: number }, c: number) =>
+                `${cacheKey}, result=${arg.a + arg.b + c}`
+        );
+        const memoized = withCacheKey(fn);
+        expect(await memoized({ a: 1, b: 2 }, 4)).toBe('[[["a",1],["b",2]],4], result=7');
+        expect(fn.mock.calls.length).toBe(1);
+    });
+});

packages/gitbook-v2/src/lib/data/memoize.ts

@@ -0,0 +1,87 @@
+/**
+ * Wrap a function by preventing concurrent executions of the same function.
+ * With a logic to work per-request in Cloudflare Workers.
+ */
+export function withoutConcurrentExecution<ArgsType extends any[], ReturnType>(
+    getGlobalContext: () => object | null | undefined,
+    wrapped: (key: string, ...args: ArgsType) => Promise<ReturnType>
+): (cacheKey: string, ...args: ArgsType) => Promise<ReturnType> {
+    const globalPromiseCache = new WeakMap<object, Map<string, Promise<ReturnType>>>();
+
+    return (key: string, ...args: ArgsType) => {
+        const globalContext = getGlobalContext() ?? globalThis;
+
+        /**
+         * Cache storage that is scoped to the current request when executed in Cloudflare Workers,
+         * to avoid "Cannot perform I/O on behalf of a different request" errors.
+         */
+        const promiseCache =
+            globalPromiseCache.get(globalContext) ?? new Map<string, Promise<ReturnType>>();
+        globalPromiseCache.set(globalContext, promiseCache);
+
+        const concurrent = promiseCache.get(key);
+        if (concurrent) {
+            return concurrent;
+        }
+
+        const promise = (async () => {
+            try {
+                const result = await wrapped(key, ...args);
+                return result;
+            } finally {
+                promiseCache.delete(key);
+            }
+        })();
+
+        promiseCache.set(key, promise);
+
+        return promise;
+    };
+}
+
+/**
+ * Wrap a function by passing it a cache key that is computed from the function arguments.
+ */
+export function withCacheKey<ArgsType extends any[], ReturnType>(
+    wrapped: (cacheKey: string, ...args: ArgsType) => Promise<ReturnType>
+): (...args: ArgsType) => Promise<ReturnType> {
+    return (...args: ArgsType) => {
+        const cacheKey = getCacheKey(args);
+        return wrapped(cacheKey, ...args);
+    };
+}
+
+/**
+ * Compute a cache key from the function arguments.
+ */
+function getCacheKey(args: any[]) {
+    return JSON.stringify(deepSortValue(args));
+}
+
+function deepSortValue(value: unknown): unknown {
+    if (
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        value === null ||
+        value === undefined
+    ) {
+        return value;
+    }
+
+    if (Array.isArray(value)) {
+        return value.map(deepSortValue);
+    }
+
+    if (value && typeof value === 'object') {
+        return Object.entries(value)
+            .map(([key, subValue]) => {
+                return [key, deepSortValue(subValue)] as const;
+            })
+            .sort((a, b) => {
+                return a[0].localeCompare(b[0]);
+            });
+    }
+
+    return value;
+}

packages/gitbook-v2/src/lib/data/pages.ts

@@ -15,12 +15,13 @@ export async function getPageDocument(
             dataFetcher.getDocument({ spaceId: space.id, documentId: page.documentId })
         );
     }
-    if (page.computed) {
+    if ('computed' in page && page.computed) {
         return getDataOrNull(
             dataFetcher.getComputedDocument({
                 organizationId: space.organization,
                 spaceId: space.id,
                 source: page.computed,
+                seed: page.computedSeed,
             })
         );
     }

packages/gitbook-v2/src/lib/data/proxy.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'bun:test';
+import { getProxyRequestIdentifier, isProxyRequest } from './proxy';
+
+describe('isProxyRequest', () => {
+    it('should return true for proxy requests', () => {
+        const proxyRequestURL = new URL('https://proxy.gitbook.site/sites/site_foo/hello/world');
+        expect(isProxyRequest(proxyRequestURL)).toBe(true);
+    });
+
+    it('should return false for non-proxy requests', () => {
+        const nonProxyRequestURL = new URL('https://example.com/docs/foo/hello/world');
+        expect(isProxyRequest(nonProxyRequestURL)).toBe(false);
+    });
+});
+
+describe('getProxyRequestIdentifier', () => {
+    it('should return the correct identifier for proxy requests', () => {
+        const proxyRequestURL = new URL('https://proxy.gitbook.site/sites/site_foo/hello/world');
+        expect(getProxyRequestIdentifier(proxyRequestURL)).toBe('sites/site_foo');
+    });
+});

packages/gitbook-v2/src/lib/data/proxy.ts

@@ -0,0 +1,15 @@
+/**
+ * Check if the request to the site was through a proxy.
+ */
+export function isProxyRequest(requestURL: URL): boolean {
+    return (
+        requestURL.host === 'proxy.gitbook.site' || requestURL.host === 'proxy.gitbook-staging.site'
+    );
+}
+
+export function getProxyRequestIdentifier(requestURL: URL): string {
+    // For proxy requests, we extract the site ID from the pathname
+    // e.g. https://proxy.gitbook.site/site/siteId/...
+    const pathname = requestURL.pathname.slice(1).split('/');
+    return pathname.slice(0, 2).join('/');
+}

packages/gitbook-v2/src/lib/data/types.ts

@@ -20,11 +20,6 @@ export type DataFetcherResponse<T> =
  * It is used between v1 and v2.
  */
 export interface GitBookDataFetcher {
-    /**
-     * Endpoint of the API.
-     */
-    apiEndpoint: string;
-
     /**
      * Get an API client for the current context.
      */
@@ -42,15 +37,6 @@ export interface GitBookDataFetcher {
      */
     getUserById(userId: string): Promise<DataFetcherResponse<api.User>>;
 
-    /**
-     * Get a published content by its URL.
-     */
-    getPublishedContentByUrl(params: {
-        url: string;
-        visitorAuthToken: string | null;
-        redirectOnError: boolean;
-    }): Promise<DataFetcherResponse<api.PublishedSiteContentLookup>>;
-
     /**
      * Get a published content site by its organization ID and site ID.
      */
@@ -111,6 +97,15 @@ export interface GitBookDataFetcher {
         path: string;
     }): Promise<DataFetcherResponse<api.RevisionPageDocument | api.RevisionPageGroup>>;
 
+    /**
+     * Get the markdown content of a page by its path.
+     */
+    getRevisionPageMarkdown(params: {
+        spaceId: string;
+        revisionId: string;
+        pageId: string;
+    }): Promise<DataFetcherResponse<string>>;
+
     /**
      * Get a document by its space ID and document ID.
      */
@@ -125,6 +120,7 @@ export interface GitBookDataFetcher {
         organizationId: string;
         spaceId: string;
         source: api.ComputedContentSource;
+        seed: string;
     }): Promise<DataFetcherResponse<api.JSONDocument>>;
 
     /**
@@ -175,4 +171,23 @@ export interface GitBookDataFetcher {
         /** Cache bust to ensure the search results are fresh when the space is updated. */
         cacheBust?: string;
     }): Promise<DataFetcherResponse<api.SearchSpaceResult[]>>;
+
+    /**
+     * Render an integration UI.
+     */
+    renderIntegrationUi(params: {
+        integrationName: string;
+        request: api.RenderIntegrationUI;
+    }): Promise<DataFetcherResponse<api.ContentKitRenderOutput>>;
+
+    /**
+     * Stream an AI response.
+     */
+    streamAIResponse(params: {
+        organizationId: string;
+        siteId: string;
+        input: api.AIMessageInput[];
+        output: api.AIOutputFormat;
+        model: api.AIModel;
+    }): AsyncGenerator<api.AIStreamResponse, void, unknown>;
 }

packages/gitbook-v2/src/lib/data/visitor.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'bun:test';
+import { getVisitorAuthBasePath } from './visitor';
+
+describe('getVisitorAuthBasePath', () => {
+    it('should return the correct base path for proxy requests', () => {
+        expect(
+            getVisitorAuthBasePath(
+                new URL('https://proxy.gitbook.site/sites/site_foo/hello/world'),
+                {
+                    site: 'site_foo',
+                    siteSpace: 'sitesp_foo',
+                    basePath: '/foo',
+                    siteBasePath: '/foo',
+                    organization: 'org_foo',
+                    space: 'space_foo',
+                    pathname: '/hello/world',
+                    complete: false,
+                    apiToken: 'api_token_foo',
+                    canonicalUrl: 'https://example.com/docs/foo/hello/world',
+                }
+            )
+        ).toBe('/sites/site_foo/');
+    });
+
+    it('should return the correct base path for non-proxy requests', () => {
+        expect(
+            getVisitorAuthBasePath(new URL('https://example.com/docs/foo/hello/world'), {
+                site: 'site_foo',
+                siteSpace: 'sitesp_foo',
+                basePath: '/foo/',
+                siteBasePath: '/foo/',
+                organization: 'org_foo',
+                space: 'space_foo',
+                pathname: '/hello/world',
+                complete: false,
+                apiToken: 'api_token_foo',
+                canonicalUrl: 'https://example.com/docs/foo/hello/world',
+            })
+        ).toBe('/foo/');
+    });
+});

packages/gitbook-v2/src/lib/data/visitor.ts

@@ -0,0 +1,19 @@
+import { withLeadingSlash, withTrailingSlash } from '@/lib/paths';
+import type { PublishedSiteContent } from '@gitbook/api';
+import { getProxyRequestIdentifier, isProxyRequest } from './proxy';
+
+/**
+ * Get the appropriate base path for the visitor authentication cookie.
+ */
+export function getVisitorAuthBasePath(
+    siteRequestURL: URL,
+    siteURLData: PublishedSiteContent
+): string {
+    // The siteRequestURL for proxy requests is of the form `https://proxy.gitbook.com/site/siteId/...`
+    // In such cases, we should not use the resolved siteBasePath for the cookie because for subsequent requests
+    // we will not have the siteBasePath in the request URL in order to retrieve the cookie. So we use the
+    // proxy identifier instead.
+    return isProxyRequest(siteRequestURL)
+        ? withLeadingSlash(withTrailingSlash(getProxyRequestIdentifier(siteRequestURL)))
+        : siteURLData.siteBasePath;
+}

packages/gitbook-v2/src/lib/env/globals.ts

@@ -6,6 +6,14 @@ import 'server-only';
  * and not from the `process.env` object.
  */
 
+/**
+ * Runtime environment.
+ */
+export const GITBOOK_RUNTIME = (process.env.GITBOOK_RUNTIME ?? 'unknown') as
+    | 'vercel'
+    | 'cloudflare'
+    | 'unknown';
+
 /**
  * Main host on which GitBook is running.
  */
@@ -34,6 +42,11 @@ export const GITBOOK_APP_URL = process.env.GITBOOK_APP_URL || 'https://app.gitbo
  */
 export const GITBOOK_API_URL = process.env.GITBOOK_API_URL || 'https://api.gitbook.com';
 
+/**
+ * Default GitBook API URL endpoint, to be shared with the client.
+ */
+export const GITBOOK_API_PUBLIC_URL = process.env.GITBOOK_API_PUBLIC_URL || GITBOOK_API_URL;
+
 /**
  * Default GitBook API token.
  * It can be use to avoid rate-limiting.
@@ -59,6 +72,11 @@ export const GITBOOK_DISABLE_TRACKING = Boolean(
 export const GITBOOK_INTEGRATIONS_HOST =
     process.env.GITBOOK_INTEGRATIONS_HOST || 'integrations.gitbook.com';
 
+/**
+ * Hostname for fonts.
+ */
+export const GITBOOK_FONTS_URL = process.env.GITBOOK_FONTS_URL || 'https://fonts.gitbook.com';
+
 /**
  * Endpoint to use for resizing images.
  * It should be a Cloudflare domain with image resizing enabled.
@@ -67,6 +85,15 @@ export const GITBOOK_IMAGE_RESIZE_URL = process.env.GITBOOK_IMAGE_RESIZE_URL ??
 export const GITBOOK_IMAGE_RESIZE_SIGNING_KEY =
     process.env.GITBOOK_IMAGE_RESIZE_SIGNING_KEY ?? null;
 
+/**
+ * Mode used for resizing images.
+ */
+export const GITBOOK_IMAGE_RESIZE_MODE = enforceEnum(
+    'GITBOOK_IMAGE_RESIZE_MODE',
+    process.env.GITBOOK_IMAGE_RESIZE_MODE || 'cdn-cgi',
+    ['cdn-cgi', 'cf-fetch']
+);
+
 /**
  * Endpoint where icons are served.
  */
@@ -82,3 +109,12 @@ export const GITBOOK_ICONS_TOKEN = process.env.GITBOOK_ICONS_TOKEN;
  * Secret used to validate requests from the GitBook app.
  */
 export const GITBOOK_SECRET = process.env.GITBOOK_SECRET ?? null;
+
+function enforceEnum<T extends string>(key: string, value: string, enumValues: T[]): T {
+    if (!enumValues.includes(value as T)) {
+        throw new Error(
+            `Invalid value for ${key}: "${value}", expected one of: ${enumValues.join(', ')}`
+        );
+    }
+    return value as T;
+}

packages/gitbook-v2/src/lib/images/checkIsSizableImageURL.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'bun:test';
+import { SizableImageAction, checkIsSizableImageURL } from './checkIsSizableImageURL';
+
+describe('checkIsSizableImageURL', () => {
+    it('should return Skip for non-parsable URLs', () => {
+        expect(checkIsSizableImageURL('not a url')).toBe(SizableImageAction.Skip);
+    });
+
+    it('should return Skip for non-http(s) URLs', () => {
+        expect(checkIsSizableImageURL('data:image/png;base64,abc')).toBe(SizableImageAction.Skip);
+        expect(checkIsSizableImageURL('file:///path/to/image.jpg')).toBe(SizableImageAction.Skip);
+    });
+
+    it('should return Skip for localhost URLs', () => {
+        expect(checkIsSizableImageURL('http://localhost:3000/image.jpg')).toBe(
+            SizableImageAction.Skip
+        );
+        expect(checkIsSizableImageURL('https://localhost/image.png')).toBe(SizableImageAction.Skip);
+    });
+
+    it('should return Skip for GitBook image URLs', () => {
+        expect(checkIsSizableImageURL('https://example.com/~gitbook/image/test.jpg')).toBe(
+            SizableImageAction.Skip
+        );
+    });
+
+    it('should return Resize for supported image extensions', () => {
+        expect(checkIsSizableImageURL('https://example.com/image.jpg')).toBe(
+            SizableImageAction.Resize
+        );
+        expect(checkIsSizableImageURL('https://example.com/image.jpeg')).toBe(
+            SizableImageAction.Resize
+        );
+        expect(checkIsSizableImageURL('https://example.com/image.png')).toBe(
+            SizableImageAction.Resize
+        );
+        expect(checkIsSizableImageURL('https://example.com/image.gif')).toBe(
+            SizableImageAction.Resize
+        );
+        expect(checkIsSizableImageURL('https://example.com/image.webp')).toBe(
+            SizableImageAction.Resize
+        );
+    });
+
+    it('should return Resize for URLs without extensions', () => {
+        expect(checkIsSizableImageURL('https://example.com/image')).toBe(SizableImageAction.Resize);
+    });
+
+    it('should return Passthrough for unsupported image extensions', () => {
+        expect(checkIsSizableImageURL('https://example.com/image.svg')).toBe(
+            SizableImageAction.Passthrough
+        );
+        expect(checkIsSizableImageURL('https://example.com/image.bmp')).toBe(
+            SizableImageAction.Passthrough
+        );
+        expect(checkIsSizableImageURL('https://example.com/image.tiff')).toBe(
+            SizableImageAction.Passthrough
+        );
+        expect(checkIsSizableImageURL('https://example.com/image.ico')).toBe(
+            SizableImageAction.Passthrough
+        );
+    });
+
+    it('should handle URLs with query parameters correctly', () => {
+        expect(checkIsSizableImageURL('https://example.com/image.jpg?width=100')).toBe(
+            SizableImageAction.Resize
+        );
+        expect(checkIsSizableImageURL('https://example.com/image.svg?height=200')).toBe(
+            SizableImageAction.Passthrough
+        );
+    });
+
+    it('should be case-insensitive for extensions', () => {
+        expect(checkIsSizableImageURL('https://example.com/image.JPG')).toBe(
+            SizableImageAction.Resize
+        );
+        expect(checkIsSizableImageURL('https://example.com/image.PNG')).toBe(
+            SizableImageAction.Resize
+        );
+    });
+});

packages/gitbook-v2/src/lib/images/checkIsSizableImageURL.ts

@@ -0,0 +1,43 @@
+import { getExtension } from '@/lib/paths';
+
+export enum SizableImageAction {
+    Resize = 'resize',
+    Skip = 'skip',
+    Passthrough = 'passthrough',
+}
+
+/**
+ * https://developers.cloudflare.com/images/transform-images/#supported-input-formats
+ */
+const SUPPORTED_IMAGE_EXTENSIONS = ['.jpg', '.jpeg', '.png', '.gif', '.webp'];
+
+/**
+ * Check if an image URL is resizable.
+ * Skip it for non-http(s) URLs (data, etc).
+ * Skip it for SVGs.
+ * Skip it for GitBook images (to avoid recursion).
+ */
+export function checkIsSizableImageURL(input: string): SizableImageAction {
+    if (!URL.canParse(input)) {
+        return SizableImageAction.Skip;
+    }
+
+    const parsed = new URL(input);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return SizableImageAction.Skip;
+    }
+    if (parsed.hostname === 'localhost') {
+        return SizableImageAction.Skip;
+    }
+    if (parsed.pathname.includes('/~gitbook/image')) {
+        return SizableImageAction.Skip;
+    }
+
+    const extension = getExtension(parsed.pathname).toLowerCase();
+    if (!extension || SUPPORTED_IMAGE_EXTENSIONS.includes(extension)) {
+        // If no extension, we consider it resizable.
+        return SizableImageAction.Resize;
+    }
+
+    return SizableImageAction.Passthrough;
+}

packages/gitbook-v2/src/lib/images/createImageResizer.ts

@@ -1,45 +1,22 @@
 import 'server-only';
-
 import { GITBOOK_IMAGE_RESIZE_SIGNING_KEY, GITBOOK_IMAGE_RESIZE_URL } from '../env';
-import type { GitBookSpaceLinker } from '../links';
+import type { GitBookLinker } from '../links';
+import { SizableImageAction, checkIsSizableImageURL } from './checkIsSizableImageURL';
+import { getImageSize } from './resizer';
 import { type SignatureVersion, generateImageSignature } from './signatures';
 import type { ImageResizer } from './types';
 
-interface CloudflareImageJsonFormat {
-    width: number;
-    height: number;
-    original: {
-        file_size: number;
-        width: number;
-        height: number;
-        format: string;
-    };
-}
-
-/**
- * https://developers.cloudflare.com/images/image-resizing/resize-with-workers/
- */
-export interface CloudflareImageOptions {
-    format?: 'webp' | 'avif' | 'json' | 'jpeg';
-    fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
-    width?: number;
-    height?: number;
-    dpr?: number;
-    anim?: boolean;
-    quality?: number;
-}
-
 /**
  * Create an image resizer for a rendering context.
  */
 export function createImageResizer({
-    host,
+    imagesContextId,
     linker,
 }: {
     /** The linker to use to create URLs. */
-    linker: GitBookSpaceLinker;
+    linker: GitBookLinker;
-    /** The host name of the current site. */
+    /** The site identifier to use for verifying the image signature. */
-    host: string;
+    imagesContextId: string;
 }): ImageResizer {
     if (!GITBOOK_IMAGE_RESIZE_URL || !GITBOOK_IMAGE_RESIZE_SIGNING_KEY) {
         return createNoopImageResizer();
@@ -47,7 +24,7 @@ export function createImageResizer({
 
     return {
         getResizedImageURL: (urlInput) => {
-            if (!checkIsSizableImageURL(urlInput)) {
+            if (checkIsSizableImageURL(urlInput) === SizableImageAction.Skip) {
                 return null;
             }
 
@@ -58,11 +35,11 @@ export function createImageResizer({
 
             return async (options) => {
                 cachedSignature ??= await generateImageSignature({
-                    host,
+                    imagesContextId,
                     url: urlInput,
                 });
 
-                const url = linker.toAbsoluteURL(linker.toPathInContent('/~gitbook/image'));
+                const url = linker.toAbsoluteURL(linker.toPathInSite('/~gitbook/image'));
                 const searchParams = new URLSearchParams();
                 searchParams.set('url', getImageAPIUrl(urlInput));
 
@@ -87,7 +64,7 @@ export function createImageResizer({
         },
 
         getImageSize: async (input, options) => {
-            if (!checkIsSizableImageURL(input)) {
+            if (checkIsSizableImageURL(input) !== SizableImageAction.Resize) {
                 return null;
             }
 
@@ -106,124 +83,6 @@ export function createNoopImageResizer(): ImageResizer {
     };
 }
 
-/**
- * Check if a URL is an HTTP URL.
- */
-export function checkIsHttpURL(input: string | URL): boolean {
-    if (!URL.canParse(input)) {
-        return false;
-    }
-    const parsed = new URL(input);
-    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
-}
-
-/**
- * Check if an image URL is resizable.
- * Skip it for non-http(s) URLs (data, etc).
- * Skip it for SVGs.
- * Skip it for GitBook images (to avoid recursion).
- */
-export function checkIsSizableImageURL(input: string): boolean {
-    if (!URL.canParse(input)) {
-        return false;
-    }
-
-    if (input.includes('/~gitbook/image')) {
-        return false;
-    }
-
-    const parsed = new URL(input);
-    if (parsed.pathname.endsWith('.svg') || parsed.pathname.endsWith('.avif')) {
-        return false;
-    }
-    if (!checkIsHttpURL(parsed)) {
-        return false;
-    }
-
-    return true;
-}
-
-/**
- * Get the size of an image.
- */
-export async function getImageSize(
-    input: string,
-    defaultSize: Partial<CloudflareImageOptions> = {}
-): Promise<{ width: number; height: number } | null> {
-    if (!checkIsSizableImageURL(input)) {
-        return null;
-    }
-
-    try {
-        const response = await resizeImage(input, {
-            // Abort the request after 2 seconds to avoid blocking rendering for too long
-            signal: AbortSignal.timeout(2000),
-            // Measure size and resize it to the most common size
-            // to optimize caching
-            ...defaultSize,
-            format: 'json',
-            anim: false,
-        });
-
-        const json = (await response.json()) as CloudflareImageJsonFormat;
-        return {
-            width: json.original.width,
-            height: json.original.height,
-        };
-    } catch (_error) {
-        return null;
-    }
-}
-
-/**
- * Execute a Cloudflare Image Resize operation on an image.
- */
-export async function resizeImage(
-    input: string,
-    options: CloudflareImageOptions & {
-        signal?: AbortSignal;
-    }
-): Promise<Response> {
-    const { signal, ...resizeOptions } = options;
-
-    const parsed = new URL(input);
-    if (parsed.protocol === 'data:') {
-        throw new Error('Cannot resize data: URLs');
-    }
-
-    if (parsed.hostname === 'localhost') {
-        throw new Error('Cannot resize localhost URLs');
-    }
-
-    // Since Cloudflare Images options on fetch are not supported on Cloudflare Pages,
-    // we need to use the Cloudflare Image Resize API directly.
-    if (!GITBOOK_IMAGE_RESIZE_URL) {
-        throw new Error('GITBOOK_IMAGE_RESIZE_URL is not set');
-    }
-
-    return await fetch(
-        `${GITBOOK_IMAGE_RESIZE_URL}${stringifyOptions(
-            resizeOptions
-        )}/${encodeURIComponent(input)}`,
-        {
-            headers: {
-                // Pass the `Accept` header, as Cloudflare uses this to validate the format.
-                Accept:
-                    resizeOptions.format === 'json'
-                        ? 'application/json'
-                        : `image/${resizeOptions.format || 'jpeg'}`,
-            },
-            signal,
-        }
-    );
-}
-
-function stringifyOptions(options: CloudflareImageOptions): string {
-    return Object.entries({ ...options }).reduce((rest, [key, value]) => {
-        return `${rest}${rest ? ',' : ''}${key}=${value}`;
-    }, '');
-}
-
 /**
  * Because of a bug in Cloudflare, 127.0.0.1 is replaced by localhost.
  * We protect against it by converting to a special token, and then parsing

packages/gitbook-v2/src/lib/images/getImageResizingContextId.ts

@@ -0,0 +1,13 @@
+import { getProxyRequestIdentifier, isProxyRequest } from '../data';
+
+/**
+ * Get the site identifier to use for image resizing for an incoming request.
+ * This identifier can be obtained before resolving the request URL.
+ */
+export function getImageResizingContextId(url: URL): string {
+    if (isProxyRequest(url)) {
+        return getProxyRequestIdentifier(url);
+    }
+
+    return url.host;
+}

packages/gitbook-v2/src/lib/images/index.ts

@@ -2,3 +2,6 @@ export * from './types';
 export * from './createImageResizer';
 export * from './signatures';
 export * from './utils';
+export * from './getImageResizingContextId';
+export * from './resizer';
+export * from './checkIsSizableImageURL';

packages/gitbook-v2/src/lib/images/resizer/cdn-cgi.ts

@@ -0,0 +1,48 @@
+import { GITBOOK_IMAGE_RESIZE_URL } from '@v2/lib/env';
+import type { CloudflareImageOptions } from './types';
+import { copyImageResponse } from './utils';
+
+/**
+ * Resize an image by doing a request to a /cdn/cgi/ endpoint.
+ * https://developers.cloudflare.com/images/transform-images/transform-via-url/
+ */
+export async function resizeImageWithCDNCgi(
+    input: string,
+    options: CloudflareImageOptions & {
+        signal?: AbortSignal;
+    }
+): Promise<Response> {
+    const { signal, ...resizeOptions } = options;
+
+    // Since Cloudflare Images options on fetch are not supported on Cloudflare Pages,
+    // we need to use the Cloudflare Image Resize API directly.
+    if (!GITBOOK_IMAGE_RESIZE_URL) {
+        throw new Error('GITBOOK_IMAGE_RESIZE_URL is not set for cdn-cgi image resize mode');
+    }
+
+    const resizeURL = `${GITBOOK_IMAGE_RESIZE_URL}${stringifyOptions(
+        resizeOptions
+    )}/${encodeURIComponent(input)}`;
+
+    // biome-ignore lint/suspicious/noConsole: this log is useful for debugging
+    console.log(`resize image using cdn-cgi: ${resizeURL}`);
+
+    return copyImageResponse(
+        await fetch(resizeURL, {
+            headers: {
+                // Pass the `Accept` header, as Cloudflare uses this to validate the format.
+                Accept:
+                    resizeOptions.format === 'json'
+                        ? 'application/json'
+                        : `image/${resizeOptions.format || 'jpeg'}`,
+            },
+            signal,
+        })
+    );
+}
+
+function stringifyOptions(options: CloudflareImageOptions): string {
+    return Object.entries({ ...options }).reduce((rest, [key, value]) => {
+        return `${rest}${rest ? ',' : ''}${key}=${value}`;
+    }, '');
+}

packages/gitbook-v2/src/lib/images/resizer/cf-fetch.ts

@@ -0,0 +1,34 @@
+import type { CloudflareImageOptions } from './types';
+import { copyImageResponse } from './utils';
+
+/**
+ * Resize an image by doing a request to the image itself using the Cloudflare fetch.
+ * https://developers.cloudflare.com/images/transform-images/transform-via-workers/
+ *
+ * This method doesn't work in Cloudflare Pages and is only supported in workers.
+ */
+export async function resizeImageWithCFFetch(
+    input: string,
+    options: CloudflareImageOptions & {
+        signal?: AbortSignal;
+    }
+): Promise<Response> {
+    const { signal, ...resizeOptions } = options;
+
+    // biome-ignore lint/suspicious/noConsole: this log is useful for debugging
+    console.log(`resize image using cf-fetch: ${input}`);
+
+    return copyImageResponse(
+        await fetch(input, {
+            headers: {
+                // Pass the `Accept` header, as Cloudflare uses this to validate the format.
+                Accept:
+                    resizeOptions.format === 'json'
+                        ? 'application/json'
+                        : `image/${resizeOptions.format || 'jpeg'}`,
+            },
+            signal,
+            cf: { image: resizeOptions },
+        })
+    );
+}

packages/gitbook-v2/src/lib/images/resizer/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './resizeImage';

packages/gitbook-v2/src/lib/images/resizer/resizeImage.ts

@@ -0,0 +1,72 @@
+import 'server-only';
+import assertNever from 'assert-never';
+import { GITBOOK_IMAGE_RESIZE_MODE } from '../../env';
+import { SizableImageAction, checkIsSizableImageURL } from '../checkIsSizableImageURL';
+import { resizeImageWithCDNCgi } from './cdn-cgi';
+import { resizeImageWithCFFetch } from './cf-fetch';
+import type { CloudflareImageJsonFormat, CloudflareImageOptions } from './types';
+
+/**
+ * Get the size of an image.
+ */
+export async function getImageSize(
+    input: string,
+    defaultSize: Partial<CloudflareImageOptions> = {}
+): Promise<{ width: number; height: number } | null> {
+    if (checkIsSizableImageURL(input) !== SizableImageAction.Resize) {
+        return null;
+    }
+
+    try {
+        const response = await resizeImage(input, {
+            // Abort the request after 2 seconds to avoid blocking rendering for too long
+            signal: AbortSignal.timeout(2000),
+            // Measure size and resize it to the most common size
+            // to optimize caching
+            ...defaultSize,
+            format: 'json',
+            anim: false,
+        });
+
+        const json = (await response.json()) as CloudflareImageJsonFormat;
+        return {
+            width: json.original.width,
+            height: json.original.height,
+        };
+    } catch (error) {
+        console.warn(`Error getting image size for ${input}:`, error);
+        return null;
+    }
+}
+
+/**
+ * Execute a Cloudflare Image Resize operation on an image.
+ */
+export async function resizeImage(
+    input: string,
+    options: CloudflareImageOptions & {
+        signal?: AbortSignal;
+    }
+): Promise<Response> {
+    const action = checkIsSizableImageURL(input);
+    if (action === SizableImageAction.Skip) {
+        throw new Error(
+            'Cannot resize this image, this function should have never been called on this url'
+        );
+    }
+
+    if (action === SizableImageAction.Passthrough) {
+        return fetch(input, {
+            signal: options.signal,
+        });
+    }
+
+    switch (GITBOOK_IMAGE_RESIZE_MODE) {
+        case 'cdn-cgi':
+            return resizeImageWithCDNCgi(input, options);
+        case 'cf-fetch':
+            return resizeImageWithCFFetch(input, options);
+        default:
+            assertNever(GITBOOK_IMAGE_RESIZE_MODE);
+    }
+}

packages/gitbook-v2/src/lib/images/resizer/types.ts

@@ -0,0 +1,23 @@
+export interface CloudflareImageJsonFormat {
+    width: number;
+    height: number;
+    original: {
+        file_size: number;
+        width: number;
+        height: number;
+        format: string;
+    };
+}
+
+/**
+ * https://developers.cloudflare.com/images/image-resizing/resize-with-workers/
+ */
+export interface CloudflareImageOptions {
+    format?: 'webp' | 'avif' | 'json' | 'jpeg';
+    fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
+    width?: number;
+    height?: number;
+    dpr?: number;
+    anim?: boolean;
+    quality?: number;
+}

packages/gitbook-v2/src/lib/images/resizer/utils.ts

@@ -0,0 +1,7 @@
+/**
+ * Copy a response to make sure it can be mutated by the rest of the middleware.
+ * To avoid errors "Can't modify immutable headers".
+ */
+export function copyImageResponse(response: Response) {
+    return new Response(response.body, response);
+}

packages/gitbook-v2/src/lib/images/signatures.ts

@@ -18,7 +18,7 @@ export const CURRENT_SIGNATURE_VERSION: SignatureVersion = '2';
 
 type SignFnInput = {
     url: string;
-    host: string;
+    imagesContextId: string;
 };
 
 type SignFn = (input: SignFnInput) => MaybePromise<string>;
@@ -32,6 +32,11 @@ export async function verifyImageSignature(
 ): Promise<boolean> {
     const generator = IMAGE_SIGNATURE_FUNCTIONS[version];
     const generated = await generator(input);
+
+    // biome-ignore lint/suspicious/noConsole: we want to log the signature comparison
+    console.log(
+        `comparing image signature for "${input.url}" on identifier "${input.imagesContextId}": "${generated}" (expected) === "${signature}" (actual)`
+    );
     return generated === signature;
 }
 
@@ -60,12 +65,14 @@ const generateSignatureV2: SignFn = async (input) => {
     assert(GITBOOK_IMAGE_RESIZE_SIGNING_KEY, 'GITBOOK_IMAGE_RESIZE_SIGNING_KEY is not set');
     const all = [
         input.url,
-        input.host, // The hostname is used to avoid serving images from other sites on the same domain
+        input.imagesContextId, // The hostname is used to avoid serving images from other sites on the same domain
         GITBOOK_IMAGE_RESIZE_SIGNING_KEY,
     ]
         .filter(Boolean)
         .join(':');
-    return fnv1a(all, { utf8Buffer: fnv1aUtf8Buffer }).toString(16);
+
+    const signature = fnv1a(all, { utf8Buffer: fnv1aUtf8Buffer }).toString(16);
+    return signature;
 };
 
 // Reused buffer for FNV-1a hashing in the v1 algorithm

packages/gitbook-v2/src/lib/links.test.ts

@@ -1,25 +1,51 @@
 import { describe, expect, it } from 'bun:test';
-import { appendBasePathToLinker, createLinker } from './links';
+import { createLinker } from './links';
 
 const root = createLinker({
     host: 'docs.company.com',
-    pathname: '/',
+    spaceBasePath: '/',
+    siteBasePath: '/',
 });
 
 const variantInSection = createLinker({
     host: 'docs.company.com',
-    pathname: '/section/variant',
+    spaceBasePath: '/section/variant',
+    siteBasePath: '/',
+});
+
+const siteGitBookIO = createLinker({
+    host: 'org.gitbook.io',
+    spaceBasePath: '/sitename/variant/',
+    siteBasePath: '/sitename/',
 });
 
 describe('toPathInContent', () => {
     it('should return the correct path', () => {
-        expect(root.toPathInContent('some/path')).toBe('/some/path');
+        expect(root.toPathInSpace('some/path')).toBe('/some/path');
-        expect(variantInSection.toPathInContent('some/path')).toBe('/section/variant/some/path');
+        expect(variantInSection.toPathInSpace('some/path')).toBe('/section/variant/some/path');
     });
 
     it('should handle leading slash', () => {
-        expect(root.toPathInContent('/some/path')).toBe('/some/path');
+        expect(root.toPathInSpace('/some/path')).toBe('/some/path');
-        expect(variantInSection.toPathInContent('/some/path')).toBe('/section/variant/some/path');
+        expect(variantInSection.toPathInSpace('/some/path')).toBe('/section/variant/some/path');
+    });
+});
+
+describe('toPathInSite', () => {
+    it('should return the correct path', () => {
+        expect(root.toPathInSite('some/path')).toBe('/some/path');
+        expect(siteGitBookIO.toPathInSite('some/path')).toBe('/sitename/some/path');
+    });
+});
+
+describe('toRelativePathInSite', () => {
+    it('should return the correct path', () => {
+        expect(root.toRelativePathInSite('/some/path')).toBe('some/path');
+        expect(siteGitBookIO.toRelativePathInSite('/sitename/some/path')).toBe('some/path');
+    });
+
+    it('should preserve absolute paths outside of the site', () => {
+        expect(siteGitBookIO.toRelativePathInSite('/outside/some/path')).toBe('/outside/some/path');
     });
 });
 
@@ -32,27 +58,17 @@ describe('toAbsoluteURL', () => {
     });
 });
 
-describe('appendBasePathToLinker', () => {
+describe('toLinkForContent', () => {
-    const prefixedRoot = appendBasePathToLinker(root, '/section/variant');
+    it('should return the correct path', () => {
-    const prefixedVariantInSection = appendBasePathToLinker(variantInSection, '/base');
+        expect(root.toLinkForContent('https://docs.company.com/some/path')).toBe('/some/path');
-
+        expect(siteGitBookIO.toLinkForContent('https://org.gitbook.io/sitename/some/path')).toBe(
-    describe('toPathInContent', () => {
+            '/sitename/some/path'
-        it('should return the correct path', () => {
+        );
-            expect(prefixedRoot.toPathInContent('some/path')).toBe('/section/variant/some/path');
-            expect(prefixedVariantInSection.toPathInContent('some/path')).toBe(
-                '/section/variant/base/some/path'
-            );
-        });
     });
 
-    describe('toAbsoluteURL', () => {
+    it('should preserve an absolute URL if the site is not the same', () => {
-        it('should return the correct path', () => {
+        expect(siteGitBookIO.toLinkForContent('https://org.gitbook.io/anothersite/some/path')).toBe(
-            expect(prefixedRoot.toAbsoluteURL('some/path')).toBe(
+            'https://org.gitbook.io/anothersite/some/path'
-                'https://docs.company.com/some/path'
+        );
-            );
-            expect(prefixedVariantInSection.toAbsoluteURL('some/path')).toBe(
-                'https://docs.company.com/some/path'
-            );
-        });
     });
 });

packages/gitbook-v2/src/lib/links.ts

@@ -1,4 +1,5 @@
 import { getPagePath } from '@/lib/pages';
+import { withLeadingSlash, withTrailingSlash } from '@/lib/paths';
 import type { RevisionPage, RevisionPageDocument, RevisionPageGroup } from '@gitbook/api';
 import warnOnce from 'warn-once';
 
@@ -7,17 +8,28 @@ import warnOnce from 'warn-once';
  *
  * URL levels:
  *
- * https://docs.company.com/section/variant/page
+ * https://docs.company.com/basename/section/variant/page
  *
- * toPathInContent('some/path') => /section/variant/some/path
+ * toPathInSpace('some/path') => /basename/section/variant/some/path
- * toPathForPage({ pages, page }) => /section/variant/some/path
+ * toPathInSite('some/path') => /basename/some/path
+ * toPathForPage({ pages, page }) => /basename/section/variant/some/path
  * toAbsoluteURL('some/path') => https://docs.company.com/some/path
  */
-export interface GitBookSpaceLinker {
+export interface GitBookLinker {
     /**
      * Generate an absolute path for a relative path to the current content.
      */
-    toPathInContent(relativePath: string): string;
+    toPathInSpace(relativePath: string): string;
+
+    /**
+     * Generate an absolute path for a relative path to the current site.
+     */
+    toPathInSite(relativePath: string): string;
+
+    /**
+     * Transform an absolute path in a site, to a relative path from the root of the site.
+     */
+    toRelativePathInSite(absolutePath: string): string;
 
     /**
      * Generate an absolute path for a page in the current content.
@@ -48,17 +60,44 @@ export function createLinker(
     servedOn: {
         protocol?: string;
         host?: string;
-        pathname: string;
+
+        /** The base path of the space */
+        spaceBasePath: string;
+
+        /** The base path of the site */
+        siteBasePath: string;
     }
-): GitBookSpaceLinker {
+): GitBookLinker {
     warnOnce(!servedOn.host, 'No host provided to createLinker. It can lead to issues with links.');
 
-    const linker: GitBookSpaceLinker = {
+    const siteBasePath = withTrailingSlash(withLeadingSlash(servedOn.siteBasePath));
-        toPathInContent(relativePath: string): string {
+    const spaceBasePath = withTrailingSlash(withLeadingSlash(servedOn.spaceBasePath));
-            return joinPaths(servedOn.pathname, relativePath);
+
+    const linker: GitBookLinker = {
+        toPathInSpace(relativePath: string): string {
+            return joinPaths(spaceBasePath, relativePath);
+        },
+
+        toPathInSite(relativePath: string): string {
+            return joinPaths(siteBasePath, relativePath);
+        },
+
+        toRelativePathInSite(absolutePath: string): string {
+            const normalizedPath = withLeadingSlash(absolutePath);
+
+            if (!normalizedPath.startsWith(servedOn.siteBasePath)) {
+                return normalizedPath;
+            }
+
+            return normalizedPath.slice(servedOn.siteBasePath.length);
         },
 
         toAbsoluteURL(absolutePath: string): string {
+            // If the path is already a full URL, we return it as is.
+            if (URL.canParse(absolutePath)) {
+                return absolutePath;
+            }
+
             if (!servedOn.host) {
                 return absolutePath;
             }
@@ -67,48 +106,25 @@ export function createLinker(
         },
 
         toPathForPage({ pages, page, anchor }) {
-            return linker.toPathInContent(getPagePath(pages, page)) + (anchor ? `#${anchor}` : '');
+            return linker.toPathInSpace(getPagePath(pages, page)) + (anchor ? `#${anchor}` : '');
         },
 
-        toLinkForContent(url: string): string {
+        toLinkForContent(rawURL: string): string {
-            return url;
+            const url = new URL(rawURL);
+
+            // If the link points to a content in the same site, we return an absolute path
+            // instead of a full URL; it makes it possible to use router navigation
+            if (url.hostname === servedOn.host && url.pathname.startsWith(servedOn.siteBasePath)) {
+                return url.pathname;
+            }
+
+            return rawURL;
         },
     };
 
     return linker;
 }
 
-/**
- * Append a prefix to a linker.
- */
-export function appendBasePathToLinker(
-    linker: GitBookSpaceLinker,
-    basePath: string
-): GitBookSpaceLinker {
-    const linkerWithPrefix: GitBookSpaceLinker = {
-        toPathInContent(relativePath: string): string {
-            return linker.toPathInContent(joinPaths(basePath, relativePath));
-        },
-
-        toAbsoluteURL(absolutePath: string): string {
-            return linker.toAbsoluteURL(absolutePath);
-        },
-
-        toPathForPage({ pages, page, anchor }) {
-            return (
-                linkerWithPrefix.toPathInContent(getPagePath(pages, page)) +
-                (anchor ? `#${anchor}` : '')
-            );
-        },
-
-        toLinkForContent(url: string): string {
-            return linker.toLinkForContent(url);
-        },
-    };
-
-    return linkerWithPrefix;
-}
-
 function joinPaths(prefix: string, path: string): string {
     const prefixPath = prefix.endsWith('/') ? prefix : `${prefix}/`;
     const suffixPath = path.startsWith('/') ? path.slice(1) : path;

packages/gitbook-v2/src/lib/middleware.ts

@@ -1,5 +1,6 @@
-import { CustomizationThemeMode, type PublishedSiteContent } from '@gitbook/api';
+import { CustomizationThemeMode } from '@gitbook/api';
 import { headers } from 'next/headers';
+import type { SiteURLData } from './context';
 
 export enum MiddlewareHeaders {
     /**
@@ -33,9 +34,10 @@ export enum MiddlewareHeaders {
     Customization = 'x-gitbook-customization',
 
     /**
-     * The visitor token used to access this content
+     * The API token used to fetch the content.
+     * This should only be passed for non-site dynamic routes.
      */
-    VisitorAuthToken = 'x-gitbook-visitor-token',
+    APIToken = 'x-gitbook-api-token',
 }
 
 /**
@@ -56,7 +58,7 @@ export async function getURLModeFromMiddleware(): Promise<'url' | 'url-host'> {
  * Get the site URL data from the middleware headers.
  * This function should only be called in a server action or a dynamic route.
  */
-export async function getSiteURLDataFromMiddleware(): Promise<PublishedSiteContent> {
+export async function getSiteURLDataFromMiddleware(): Promise<SiteURLData> {
     const headersList = await headers();
     const siteURLData = headersList.get(MiddlewareHeaders.SiteURLData);
 
@@ -100,15 +102,15 @@ export async function getThemeFromMiddleware() {
 }
 
 /**
- * Get the visitor auth token from the middleware headers.
+ * Get the API token from the middleware headers.
  * This function should only be called in a dynamic route.
  */
-export async function getVisitorAuthTokenFromMiddleware(): Promise<string | null> {
+export async function getAPITokenFromMiddleware(): Promise<string> {
     const headersList = await headers();
-    const visitorAuthToken = headersList.get(MiddlewareHeaders.VisitorAuthToken);
+    const apiToken = headersList.get(MiddlewareHeaders.APIToken);
-    if (!visitorAuthToken) {
+    if (!apiToken) {
-        return null;
+        throw new Error('API token is not set by the middleware');
     }
 
-    return visitorAuthToken;
+    return apiToken;
 }

packages/gitbook-v2/src/lib/server-actions.ts

@@ -16,8 +16,8 @@ export async function getServerActionBaseContext() {
 
     return getBaseContext({
         siteURL,
+        siteURLData,
         urlMode,
-        apiToken: siteURLData.apiToken,
     });
 }
 

packages/gitbook-v2/src/middleware.ts

@@ -1,16 +1,31 @@
-import { CustomizationThemeMode, GitBookAPIError } from '@gitbook/api';
+import { CustomizationThemeMode } from '@gitbook/api';
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
+import rison from 'rison';
 
 import { getContentSecurityPolicy } from '@/lib/csp';
 import { validateSerializedCustomization } from '@/lib/customization';
 import { removeLeadingSlash, removeTrailingSlash } from '@/lib/paths';
-import { getResponseCookiesForVisitorAuth, getVisitorToken } from '@/lib/visitor-token';
+import {
+    type ResponseCookies,
+    getPathScopedCookieName,
+    getResponseCookiesForVisitorAuth,
+    getVisitorData,
+    normalizeVisitorAuthURL,
+} from '@/lib/visitors';
 import { serveResizedImage } from '@/routes/image';
-import { getPublishedContentByURL } from '@v2/lib/data';
+import {
+    DataFetcherError,
+    getPublishedContentByURL,
+    getVisitorAuthBasePath,
+    normalizeURL,
+    resolvePublishedContentByUrl,
+    throwIfDataError,
+} from '@v2/lib/data';
 import { isGitBookAssetsHostURL, isGitBookHostURL } from '@v2/lib/env';
+import { getImageResizingContextId } from '@v2/lib/images';
 import { MiddlewareHeaders } from '@v2/lib/middleware';
-
+import type { SiteURLData } from './lib/context';
 export const config = {
     matcher: [
         '/((?!_next/static|_next/image|~gitbook/static|~gitbook/revalidate|~gitbook/monitoring|~scalar/proxy).*)',
@@ -19,29 +34,32 @@ export const config = {
 
 type URLWithMode = { url: URL; mode: 'url' | 'url-host' };
 
+/**
+ * Temporary list of hosts to test adaptive content using the new resolution API.
+ */
+const ADAPTIVE_CONTENT_HOSTS = [
+    'docs.gitbook.com',
+    'adaptive-docs.gitbook-staging.com',
+    'enriched-content-playground.gitbook-staging.io',
+];
+
 export async function middleware(request: NextRequest) {
     try {
-        // Route all requests to a site
+        const requestURL = new URL(request.url);
-        const extracted = getSiteURLFromRequest(request);
-        if (extracted) {
-            /**
-             * Serve image resizing requests (all requests containing `/~gitbook/image`).
-             * All URLs containing `/~gitbook/image` are rewritten to `/~gitbook/image`
-             * and serve from a single route handler.
-             *
-             * In GitBook v1: image resizing was done at the root of the hostname (docs.company.com/~gitbook/image)
-             * In GitBook v2: image resizing is done at the content level (docs.company.com/section/variant/~gitbook/image)
-             */
-            if (extracted.url.pathname.endsWith('/~gitbook/image')) {
-                return await serveResizedImage(request, {
-                    host: extracted.url.host,
-                });
-            }
 
-            return await serveSiteByURL(request, extracted);
+        // Redirect to normalize the URL
+        const normalized = normalizeURL(requestURL);
+        if (normalized.toString() !== requestURL.toString()) {
+            return NextResponse.redirect(normalized.toString());
+        }
+
+        for (const handler of [serveSiteRoutes, serveSpacePDFRoutes]) {
+            const result = await handler(requestURL, request);
+            if (result) {
+                return result;
+            }
         }
 
-        // Handle the rest with the router default logic
         return NextResponse.next();
     } catch (error) {
         return serveErrorResponse(error as Error);
@@ -49,110 +67,271 @@ export async function middleware(request: NextRequest) {
 }
 
 /**
- * Serve site by URL.
+ * Handle request that are targetting the site routes group.
  */
-async function serveSiteByURL(request: NextRequest, urlWithMode: URLWithMode) {
+async function serveSiteRoutes(requestURL: URL, request: NextRequest) {
-    const { url, mode } = urlWithMode;
+    const match = getSiteURLFromRequest(request);
+    if (!match) {
+        return null;
+    }
 
-    // Visitor authentication
+    const { url: siteRequestURL, mode } = match;
-    // @ts-ignore - request typing
+    const imagesContextId = getImageResizingContextId(siteRequestURL);
-    const visitorToken = getVisitorToken(request, url);
 
-    const result = await getPublishedContentByURL({
+    /**
-        url: url.toString(),
+     * Serve image resizing requests (all requests containing `/~gitbook/image`).
-        visitorAuthToken: visitorToken?.token ?? null,
+     * All URLs containing `/~gitbook/image` are rewritten to `/~gitbook/image`
-        // When the visitor auth token is pulled from the cookie, set redirectOnError when calling getPublishedContentByUrl to allow
+     * and serve from a single route handler.
-        // redirecting when the token is invalid as we could be dealing with stale token stored in the cookie.
+     *
-        // For example when the VA backend signature has changed but the token stored in the cookie is not yet expired.
+     * In GitBook v1: image resizing was done at the root of the hostname (docs.company.com/~gitbook/image)
-        redirectOnError: visitorToken?.source === 'visitor-auth-cookie',
+     * In GitBook v2: image resizing is done at the content level (docs.company.com/section/variant/~gitbook/image)
+     */
+    if (siteRequestURL.pathname.endsWith('/~gitbook/image')) {
+        return await serveResizedImage(request, {
+            imagesContextId: imagesContextId,
+        });
+    }
+
+    //
+    // Detect and extract the visitor authentication token from the request
+    //
+    const { visitorToken, unsignedClaims, visitorParamsCookie } = getVisitorData({
+        cookies: request.cookies.getAll(),
+        url: siteRequestURL,
     });
 
-    if (result.error) {
+    const withAPIToken = async (apiToken: string | null) => {
-        throw result.error;
+        const resolve = ADAPTIVE_CONTENT_HOSTS.includes(siteRequestURL.hostname)
-    }
+            ? resolvePublishedContentByUrl
+            : getPublishedContentByURL;
+        const siteURLData = await throwIfDataError(
+            resolve({
+                url: siteRequestURL.toString(),
+                visitorPayload: {
+                    jwtToken: visitorToken?.token ?? undefined,
+                    unsignedClaims,
+                },
+                // When the visitor auth token is pulled from the cookie, set redirectOnError when calling getPublishedContentByUrl to allow
+                // redirecting when the token is invalid as we could be dealing with stale token stored in the cookie.
+                // For example when the VA backend signature has changed but the token stored in the cookie is not yet expired.
+                redirectOnError: visitorToken?.source === 'visitor-auth-cookie',
 
-    const { data } = result;
+                // Use the API token passed in the request, if any
+                // as it could be used for .preview hostnames
+                apiToken,
+            })
+        );
 
-    if ('redirect' in data) {
+        const cookies: ResponseCookies = visitorParamsCookie
-        return NextResponse.redirect(data.redirect);
+            ? [
-    }
+                  // If visitor.* params were passed to the site URL, include a session cookie to persist these params across navigation.
+                  visitorParamsCookie,
+              ]
+            : [];
 
-    // When visitor has authentication (adaptive content or VA), we serve dynamic routes.
+        //
-    let routeType = visitorToken ? 'dynamic' : 'static';
+        // Handle redirects
+        //
+        if ('redirect' in siteURLData) {
+            // biome-ignore lint/suspicious/noConsole: we want to log the redirect
+            console.log('redirect', siteURLData.redirect);
+            if (siteURLData.target === 'content') {
+                let contentRedirect = new URL(siteURLData.redirect, request.url);
 
-    const requestHeaders = new Headers(request.headers);
+                // For content redirects, we redirect using the /url/:url format
-    requestHeaders.set(MiddlewareHeaders.RouteType, routeType);
+                // during development and testing in 'url' mode.
-    requestHeaders.set(MiddlewareHeaders.URLMode, mode);
+                if (mode === 'url') {
-    requestHeaders.set(MiddlewareHeaders.SiteURL, `${url.origin}${data.basePath}`);
+                    const urlObject = new URL(siteURLData.redirect);
-    requestHeaders.set(MiddlewareHeaders.SiteURLData, JSON.stringify(data));
+                    contentRedirect = new URL(
+                        `/url/${urlObject.host}${urlObject.pathname}${urlObject.search}`,
+                        request.url
+                    );
+                }
 
-    // Preview of customization/theme
+                // Keep the same search params as the original request
-    const customization = url.searchParams.get('customization');
+                // as it might contain a VA token
-    if (customization && validateSerializedCustomization(customization)) {
+                contentRedirect.search = request.nextUrl.search;
-        routeType = 'dynamic';
-        requestHeaders.set(MiddlewareHeaders.Customization, customization);
-    }
-    const theme = url.searchParams.get('theme');
-    if (theme === CustomizationThemeMode.Dark || theme === CustomizationThemeMode.Light) {
-        routeType = 'dynamic';
-        requestHeaders.set(MiddlewareHeaders.Theme, theme);
-    }
 
-    // We support forcing dynamic routes by setting a `gitbook-dynamic-route` cookie
+                return NextResponse.redirect(contentRedirect);
-    // This is useful for testing dynamic routes.
+            }
-    if (request.cookies.has('gitbook-dynamic-route')) {
-        routeType = 'dynamic';
-    }
 
-    // Pass a x-forwarded-host and origin that are equal to ensure Next doesn't block server actions when proxied
+            return NextResponse.redirect(siteURLData.redirect);
-    requestHeaders.set('x-forwarded-host', request.nextUrl.host);
-    requestHeaders.set('origin', request.nextUrl.origin);
-
-    const siteURL = `${url.host}${data.basePath}`;
-
-    const route = [
-        'sites',
-        routeType,
-        mode,
-        encodeURIComponent(siteURL),
-        encodePathInSiteContent(data.pathname),
-    ].join('/');
-
-    console.log(`rewriting ${request.nextUrl.toString()} to ${route}`);
-
-    const rewrittenURL = new URL(`/${route}`, request.nextUrl.toString());
-    const response = NextResponse.rewrite(rewrittenURL, {
-        request: {
-            headers: requestHeaders,
-        },
-    });
-
-    // Add Content Security Policy header
-    response.headers.set('content-security-policy', getContentSecurityPolicy());
-    // Basic security headers
-    response.headers.set('strict-transport-security', 'max-age=31536000');
-    response.headers.set('referrer-policy', 'no-referrer-when-downgrade');
-    response.headers.set('x-content-type-options', 'nosniff');
-    // Debug header
-    response.headers.set('x-gitbook-route-type', routeType);
-    response.headers.set('x-gitbook-site-url', siteURL);
-
-    if (visitorToken) {
-        const cookies = getResponseCookiesForVisitorAuth(data.basePath, visitorToken);
-        for (const [key, value] of Object.entries(cookies)) {
-            response.cookies.set(key, value.value, value.options);
         }
+
+        cookies.push(
+            ...getResponseCookiesForVisitorAuth(
+                getVisitorAuthBasePath(siteRequestURL, siteURLData),
+                visitorToken
+            )
+        );
+
+        // We use the host/origin from the canonical URL to ensure the links are
+        // correctly generated when the site is proxied. e.g. https://proxy.gitbook.com/site/siteId/...
+        const siteCanonicalURL = new URL(siteURLData.canonicalUrl);
+
+        let incomingURL = requestURL;
+        // For cases where the site is proxied, we use the canonical URL
+        // as the incoming URL along with all the search params from the request.
+        if (mode !== 'url') {
+            incomingURL = siteCanonicalURL;
+            incomingURL.search = requestURL.search;
+        }
+        //
+        // Make sure the URL is clean of any va token after a successful lookup
+        // The token is stored in a cookie that is set on the redirect response
+        //
+        const incomingURLWithoutToken = normalizeVisitorAuthURL(incomingURL);
+        if (incomingURLWithoutToken.toString() !== incomingURL.toString()) {
+            return writeResponseCookies(
+                NextResponse.redirect(incomingURLWithoutToken.toString()),
+                cookies
+            );
+        }
+
+        //
+        // Render and serve the content
+        //
+
+        // The route is static, except when using dynamic parameters from query params
+        // (customization override, theme, etc)
+        let routeType: 'dynamic' | 'static' = 'static';
+
+        // We pick only stable data from the siteURL data to prevent re-rendering of
+        // the root layout when changing pages..
+        const stableSiteURLData: SiteURLData = {
+            site: siteURLData.site,
+            siteSection: siteURLData.siteSection,
+            siteSpace: siteURLData.siteSpace,
+            siteBasePath: siteURLData.siteBasePath,
+            basePath: siteURLData.basePath,
+            space: siteURLData.space,
+            organization: siteURLData.organization,
+            changeRequest: siteURLData.changeRequest,
+            revision: siteURLData.revision,
+            shareKey: siteURLData.shareKey,
+            apiToken: siteURLData.apiToken,
+            imagesContextId: imagesContextId,
+        };
+
+        const requestHeaders = new Headers(request.headers);
+        requestHeaders.set(MiddlewareHeaders.RouteType, routeType);
+        requestHeaders.set(MiddlewareHeaders.URLMode, mode);
+        requestHeaders.set(
+            MiddlewareHeaders.SiteURL,
+            `${siteCanonicalURL.origin}${siteURLData.basePath}`
+        );
+        requestHeaders.set(MiddlewareHeaders.SiteURLData, JSON.stringify(stableSiteURLData));
+
+        // Preview of customization/theme
+        const customization = siteRequestURL.searchParams.get('customization');
+        if (customization && validateSerializedCustomization(customization)) {
+            routeType = 'dynamic';
+            requestHeaders.set(MiddlewareHeaders.Customization, customization);
+        }
+        const theme = siteRequestURL.searchParams.get('theme');
+        if (theme === CustomizationThemeMode.Dark || theme === CustomizationThemeMode.Light) {
+            routeType = 'dynamic';
+            requestHeaders.set(MiddlewareHeaders.Theme, theme);
+        }
+
+        // We support forcing dynamic routes by setting a `gitbook-dynamic-route` cookie
+        // This is useful for testing dynamic routes.
+        if (request.cookies.has('gitbook-dynamic-route')) {
+            routeType = 'dynamic';
+        }
+
+        // Pass a x-forwarded-host and origin that are equal to ensure Next doesn't block server actions when proxied
+        requestHeaders.set('x-forwarded-host', request.nextUrl.host);
+        requestHeaders.set('origin', request.nextUrl.origin);
+
+        const siteURLWithoutProtocol = `${siteCanonicalURL.host}${siteURLData.basePath}`;
+        const { pathname, routeType: routeTypeFromPathname } = encodePathInSiteContent(
+            siteURLData.pathname
+        );
+        routeType = routeTypeFromPathname ?? routeType;
+
+        const route = [
+            'sites',
+            routeType,
+            mode,
+            encodeURIComponent(siteURLWithoutProtocol),
+            encodeURIComponent(
+                rison.encode(
+                    // rison can't encode undefined values
+                    Object.fromEntries(
+                        Object.entries(stableSiteURLData).filter(
+                            ([_, v]) => typeof v !== 'undefined'
+                        )
+                    )
+                )
+            ),
+            pathname,
+        ].join('/');
+
+        console.log(`rewriting ${request.nextUrl.toString()} to ${route}`);
+
+        const rewrittenURL = new URL(`/${route}`, request.nextUrl.toString());
+        const response = NextResponse.rewrite(rewrittenURL, {
+            request: {
+                headers: requestHeaders,
+            },
+        });
+
+        // Add Content Security Policy header
+        response.headers.set('content-security-policy', getContentSecurityPolicy());
+        // Basic security headers
+        response.headers.set('strict-transport-security', 'max-age=31536000');
+        response.headers.set('referrer-policy', 'no-referrer-when-downgrade');
+        response.headers.set('x-content-type-options', 'nosniff');
+        // Debug header
+        response.headers.set('x-gitbook-route-type', routeType);
+        response.headers.set('x-gitbook-route-site', siteURLWithoutProtocol);
+
+        return writeResponseCookies(response, cookies);
+    };
+
+    // For https://preview/<siteURL> requests,
+    if (siteRequestURL.hostname === 'preview') {
+        return serveWithQueryAPIToken(
+            // We scope the API token to the site ID.
+            `${siteRequestURL.hostname}/${requestURL.pathname.slice(1).split('/')[0]}`,
+            request,
+            withAPIToken
+        );
     }
 
-    return response;
+    return withAPIToken(null);
+}
+
+/**
+ * Serve routes for PDF export for a space: /~space/:spaceId/~gitbook/pdf
+ */
+async function serveSpacePDFRoutes(requestURL: URL, request: NextRequest) {
+    const pathnameParts = requestURL.pathname.slice(1).split('/');
+    if (pathnameParts[0] !== '~space' && pathnameParts[0] !== '~site') {
+        return null;
+    }
+
+    return serveWithQueryAPIToken(
+        pathnameParts.slice(0, 2).join('/'),
+        request,
+        async (apiToken) => {
+            // Handle the rest with the router default logic
+            return NextResponse.next({
+                headers: {
+                    [MiddlewareHeaders.APIToken]: apiToken,
+                },
+            });
+        }
+    );
 }
 
 /**
  * Serve an error response.
  */
 function serveErrorResponse(error: Error) {
-    if (error instanceof GitBookAPIError) {
+    if (error instanceof DataFetcherError) {
-        return new Response(error.errorMessage, {
+        return new Response(error.message, {
             status: error.code,
             headers: { 'content-type': 'text/plain' },
         });
@@ -161,6 +340,45 @@ function serveErrorResponse(error: Error) {
     throw error;
 }
 
+/**
+ * Server a response with an API token obtained from the query params.
+ */
+async function serveWithQueryAPIToken(
+    scopePath: string,
+    request: NextRequest,
+    serve: (apiToken: string) => Promise<NextResponse>
+) {
+    // We store the API token in a cookie that is scoped to the specific route
+    // to avoid errors when multiple previews are opened in different tabs.
+    const cookieName = getPathScopedCookieName('gitbook-api-token', scopePath);
+
+    // Extract a potential GitBook API token passed in the request
+    // If found, we redirect to the same URL but with the token in the cookie
+    const queryAPIToken = request.nextUrl.searchParams.get('token');
+    if (queryAPIToken) {
+        request.nextUrl.searchParams.delete('token');
+        return writeResponseCookies(NextResponse.redirect(request.nextUrl.toString()), [
+            {
+                name: cookieName,
+                value: queryAPIToken,
+                options: {
+                    httpOnly: true,
+                    sameSite: process.env.NODE_ENV === 'production' ? 'none' : undefined,
+                    secure: process.env.NODE_ENV === 'production',
+                    maxAge: 60 * 60, // 1 hour
+                },
+            },
+        ]);
+    }
+
+    const apiToken = request.cookies.get(cookieName)?.value;
+    if (!apiToken) {
+        throw new DataFetcherError('Missing API token', 400);
+    }
+
+    return serve(apiToken);
+}
+
 /**
  * The URL of the GitBook content can be passed in 3 different ways (in order of priority):
  * - The request has a `X-GitBook-URL` header:
@@ -219,22 +437,41 @@ function getSiteURLFromRequest(request: NextRequest): URLWithMode | null {
  * Encode path in a site content.
  * Special paths are not encoded and passed to be handled by the route handlers.
  */
-function encodePathInSiteContent(rawPathname: string) {
+function encodePathInSiteContent(rawPathname: string): {
+    pathname: string;
+    routeType?: 'static' | 'dynamic';
+} {
     const pathname = removeLeadingSlash(removeTrailingSlash(rawPathname));
 
     if (pathname.match(/^~gitbook\/ogimage\/\S+$/)) {
-        return pathname;
+        return { pathname };
+    }
+
+    // If the pathname is a markdown file, we rewrite it to ~gitbook/markdown/:pathname
+    if (pathname.match(/\.md$/)) {
+        const pagePathWithoutMD = pathname.slice(0, -3);
+        return {
+            pathname: `~gitbook/markdown/${encodeURIComponent(pagePathWithoutMD)}`,
+            // The markdown content is always static and doesn't depend on the dynamic parameter (customization, theme, etc)
+            routeType: 'static',
+        };
     }
 
     switch (pathname) {
         case '~gitbook/icon':
-        case '~gitbook/image':
+            return { pathname };
         case 'llms.txt':
         case 'sitemap.xml':
+        case 'sitemap-pages.xml':
         case 'robots.txt':
-            return pathname;
+            // LLMs.txt, sitemap, sitemap-pages and robots.txt are always static
+            // as they only depend on the site structure / pages.
+            return { pathname, routeType: 'static' };
+        case '~gitbook/pdf':
+            // PDF routes are always dynamic as they depend on the search params.
+            return { pathname, routeType: 'dynamic' };
         default:
-            return encodeURIComponent(pathname || '/');
+            return { pathname: encodeURIComponent(pathname || '/') };
     }
 }
 
@@ -248,3 +485,14 @@ function appendQueryParams(url: URL, from: URLSearchParams) {
 
     return url;
 }
+
+/**
+ * Write the cookies to a response.
+ */
+function writeResponseCookies<R extends NextResponse>(response: R, cookies: ResponseCookies): R {
+    cookies.forEach((cookie) => {
+        response.cookies.set(cookie.name, cookie.value, cookie.options);
+    });
+
+    return response;
+}

packages/gitbook-v2/wrangler.jsonc

@@ -0,0 +1,149 @@
+{
+    "main": ".open-next/worker.js",
+    "name": "gitbook-open-v2",
+    "compatibility_date": "2025-04-14",
+    "compatibility_flags": [
+        "nodejs_compat",
+        "allow_importable_env",
+        "global_fetch_strictly_public"
+    ],
+    "assets": {
+        "directory": ".open-next/assets",
+        "binding": "ASSETS"
+    },
+    "observability": {
+        "enabled": true
+    },
+    "vars": {
+        "NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE": "true"
+    },
+    "env": {
+        "preview": {
+            "r2_buckets": [
+                {
+                    "binding": "NEXT_INC_CACHE_R2_BUCKET",
+                    "bucket_name": "gitbook-open-v2-cache-preview"
+                }
+            ],
+            "services": [
+                {
+                    "binding": "WORKER_SELF_REFERENCE",
+                    "service": "gitbook-open-v2-preview"
+                },
+                {
+                    "binding": "GITBOOK_API",
+                    "service": "gitbook-x-prod-api-cache"
+                }
+            ]
+            // No durable objects on preview, as they block the generation of preview URLs
+            // and we don't need tags invalidation on preview
+        },
+        "staging": {
+            "routes": [
+                {
+                    "pattern": "open-2c.gitbook-staging.com/*",
+                    "zone_name": "gitbook-staging.com"
+                },
+                {
+                    "pattern": "static-2c.gitbook-staging.com/*",
+                    "zone_name": "gitbook-staging.com"
+                }
+            ],
+            "r2_buckets": [
+                {
+                    "binding": "NEXT_INC_CACHE_R2_BUCKET",
+                    "bucket_name": "gitbook-open-v2-cache-staging"
+                }
+            ],
+            "services": [
+                {
+                    "binding": "WORKER_SELF_REFERENCE",
+                    "service": "gitbook-open-v2-staging"
+                },
+                {
+                    "binding": "GITBOOK_API",
+                    "service": "gitbook-x-staging-api-cache"
+                }
+            ],
+            "tail_consumers": [
+                {
+                    "service": "gitbook-x-staging-tail"
+                }
+            ],
+            "durable_objects": {
+                "bindings": [
+                    {
+                        "name": "NEXT_CACHE_DO_QUEUE",
+                        "class_name": "DOQueueHandler"
+                    },
+                    {
+                        "name": "NEXT_TAG_CACHE_DO_SHARDED",
+                        "class_name": "DOShardedTagCache"
+                    }
+                ]
+            },
+            "migrations": [
+                {
+                    "tag": "v1",
+                    "new_sqlite_classes": ["DOQueueHandler", "DOShardedTagCache"]
+                }
+            ]
+        },
+        "production": {
+            "vars": {
+                // This is a bit misleading, but it means that we can have 100 concurrent revalidations
+                // This means that we'll have up to 20 durable objects instance running at the same time
+                "MAX_REVALIDATE_CONCURRENCY": "20"
+            },
+            "routes": [
+                {
+                    "pattern": "open-2c.gitbook.com/*",
+                    "zone_name": "gitbook.com"
+                },
+                {
+                    "pattern": "static-2c.gitbook.com/*",
+                    "zone_name": "gitbook.com"
+                }
+            ],
+            "r2_buckets": [
+                {
+                    "binding": "NEXT_INC_CACHE_R2_BUCKET",
+                    "bucket_name": "gitbook-open-v2-cache-production"
+                }
+            ],
+            "services": [
+                {
+                    "binding": "WORKER_SELF_REFERENCE",
+                    "service": "gitbook-open-v2-production"
+                },
+                {
+                    "binding": "GITBOOK_API",
+                    "service": "gitbook-x-prod-api-cache"
+                }
+            ],
+            "tail_consumers": [
+                {
+                    "service": "gitbook-x-prod-tail"
+                }
+            ],
+            "durable_objects": {
+                "bindings": [
+                    {
+                        "name": "NEXT_CACHE_DO_QUEUE",
+                        "class_name": "DOQueueHandler"
+                    },
+                    {
+                        "name": "NEXT_TAG_CACHE_DO_SHARDED",
+                        "class_name": "DOShardedTagCache"
+                    }
+                ]
+            },
+            "migrations": [
+                {
+                    "tag": "v1",
+                    "new_sqlite_classes": ["DOQueueHandler", "DOShardedTagCache"]
+                }
+            ]
+        }
+    }
+}

packages/gitbook-v2/wrangler.toml

@@ -1,38 +0,0 @@
-main = ".open-next/worker.js"
-name = "gitbook-open-v2"
-compatibility_date = "2024-09-23"
-compatibility_flags = ["nodejs_compat"]
-assets = { directory = ".open-next/assets", binding = "ASSETS" }
-observability = { enabled = true }
-
-[env.preview]
-kv_namespaces = [
-  { binding = "NEXT_CACHE_WORKERS_KV", id = "b7dd9cf58bf2458f84812a2d83b3760c" } # gitbook-open-v2-cache-preview
-]
-d1_databases = [
-  { binding = "NEXT_CACHE_D1", database_id = "f59ddb40-ad72-4312-9395-0ac6a129af8e", database_name = "gitbook-open-v2-tags-preview" }
-]
-
-[env.staging]
-routes = [
-  { pattern = "open-2c.gitbook-staging.com/*", zone_name = "gitbook-staging.com" },
-  { pattern = "static-2c.gitbook-staging.com/*", zone_name = "gitbook-staging.com" }
-]
-kv_namespaces = [
-  { binding = "NEXT_CACHE_WORKERS_KV", id = "a446e25f12b741afb185f1e5b4474f0a" } # gitbook-open-v2-cache-staging
-]
-d1_databases = [
-  { binding = "NEXT_CACHE_D1", database_id = "9df62e39-1f35-4066-83aa-e9b8ed3ac8d5", database_name = "gitbook-open-v2-tags-staging" }
-]
-
-[env.production]
-routes = [
-  { pattern = "open-2c.gitbook.com/*", zone_name = "gitbook.com" },
-  { pattern = "static-2c.gitbook.com/*", zone_name = "gitbook.com" }
-]
-kv_namespaces = [
-  { binding = "NEXT_CACHE_WORKERS_KV", id = "72379746280d4e79acf24440eea950dc" } # gitbook-open-v2-cache-production
-]
-d1_databases = [
-  { binding = "NEXT_CACHE_D1", database_id = "a6f16fce-5f45-43a9-89a4-7b83ddf25b77", database_name = "gitbook-open-v2-tags-production" }
-]

packages/gitbook/.env.example

@@ -23,8 +23,5 @@
 ## Caching
 # GITBOOK_OUTPUT_CACHE=true
 
-### Sentry ###
-# SENTRY_DSN=xxx
-
 ### Silent logs
 # SILENT=true

packages/gitbook/.gitignore

@@ -23,9 +23,6 @@ next-env.d.ts
 # visual tests
 screenshots/
 
-# Sentry Config File
-.sentryclirc
-
 /test-results/
 /playwright-report/
 /blob-report/

packages/gitbook/e2e/customers.spec.ts

@@ -1,234 +1,252 @@
-import { type TestsCase, runTestCases } from './util';
+import { type TestsCase, runTestCases, waitForCookiesDialog } from './util';
 
 /** A list of test cases to run on the customers' docs sites. */
 const testCases: TestsCase[] = [
     {
         name: 'Snyk',
-        baseUrl: 'https://docs.snyk.io',
+        contentBaseURL: 'https://docs.snyk.io',
         tests: [
-            { name: 'Home', url: '/' },
+            { name: 'Home', url: '/', run: waitForCookiesDialog },
-            { name: 'OpenAPI', url: '/snyk-api/reference/apps' },
+            { name: 'OpenAPI', url: '/snyk-api/reference/apps', run: waitForCookiesDialog },
         ],
     },
-    {
+    // {
-        name: 'Nexthink',
+    //     name: 'Nexthink',
-        baseUrl: 'https://docs.nexthink.com',
+    //     contentBaseURL: 'https://docs.nexthink.com',
-        tests: [{ name: 'Home', url: '/', screenshot: { waitForTOCScrolling: false } }],
+    //     tests: [
-    },
+    //         {
+    //             name: 'Home',
+    //             url: '/',
+    //             screenshot: { waitForTOCScrolling: false },
+    //             run: waitForCookiesDialog,
+    //         },
+    //     ],
+    // },
     {
         name: 'asiksupport-stg.dto.kemkes.go.id',
-        baseUrl: 'https://asiksupport-stg.dto.kemkes.go.id',
+        contentBaseURL: 'https://asiksupport-stg.dto.kemkes.go.id',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'jasons-tutorials.gitbook.io',
-        baseUrl: 'https://jasons-tutorials.gitbook.io',
+        contentBaseURL: 'https://jasons-tutorials.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'faq.deltaemulator.com',
-        baseUrl: 'https://faq.deltaemulator.com',
+        contentBaseURL: 'https://faq.deltaemulator.com',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.dify.ai',
-        baseUrl: 'https://docs.dify.ai',
+        contentBaseURL: 'https://docs.dify.ai',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'seeddao.gitbook.io',
-        baseUrl: 'https://seeddao.gitbook.io',
+        contentBaseURL: 'https://seeddao.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'faq.altstore.io',
-        baseUrl: 'https://faq.altstore.io',
+        contentBaseURL: 'https://faq.altstore.io',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'support.audacityteam.org',
-        baseUrl: 'https://support.audacityteam.org',
+        contentBaseURL: 'https://support.audacityteam.org',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.gmgn.ai',
-        baseUrl: 'https://docs.gmgn.ai',
+        contentBaseURL: 'https://docs.gmgn.ai',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.spicychat.ai',
-        baseUrl: 'https://docs.spicychat.ai',
+        contentBaseURL: 'https://docs.spicychat.ai',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.portainer.io',
-        baseUrl: 'https://docs.portainer.io',
+        contentBaseURL: 'https://docs.portainer.io',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.chirptoken.io',
-        baseUrl: 'https://docs.chirptoken.io',
+        contentBaseURL: 'https://docs.chirptoken.io',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.dexscreener.com',
-        baseUrl: 'https://docs.dexscreener.com',
+        contentBaseURL: 'https://docs.dexscreener.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.pancakeswap.finance',
-        baseUrl: 'https://docs.pancakeswap.finance',
+        contentBaseURL: 'https://docs.pancakeswap.finance',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'book.character.ai',
-        baseUrl: 'https://book.character.ai',
+        contentBaseURL: 'https://book.character.ai',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
-    },
-    {
-        name: 'docs.tradeonnova.io',
-        baseUrl: 'https://docs.tradeonnova.io',
-        tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'azcoiner.gitbook.io',
-        baseUrl: 'https://azcoiner.gitbook.io',
+        contentBaseURL: 'https://azcoiner.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.midas.app',
-        baseUrl: 'https://docs.midas.app',
+        contentBaseURL: 'https://docs.midas.app',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.keeper.io',
-        baseUrl: 'https://docs.keeper.io',
+        contentBaseURL: 'https://docs.keeper.io',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'adiblar.gitbook.io',
-        baseUrl: 'https://adiblar.gitbook.io',
+        contentBaseURL: 'https://adiblar.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.gradient.network',
-        baseUrl: 'https://docs.gradient.network',
+        contentBaseURL: 'https://docs.gradient.network',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'mygate-network.gitbook.io',
-        baseUrl: 'https://mygate-network.gitbook.io',
+        contentBaseURL: 'https://mygate-network.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'treasurenft.gitbook.io',
-        baseUrl: 'https://treasurenft.gitbook.io',
+        contentBaseURL: 'https://treasurenft.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'browndust2.gitbook.io',
-        baseUrl: 'https://browndust2.gitbook.io',
+        contentBaseURL: 'https://browndust2.gitbook.io',
         tests: [{ name: 'Home', url: '/', screenshot: { waitForTOCScrolling: false } }],
     },
     {
         name: 'junookyo.gitbook.io',
-        baseUrl: 'https://junookyo.gitbook.io',
+        contentBaseURL: 'https://junookyo.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'meshnet.nordvpn.com',
-        baseUrl: 'https://meshnet.nordvpn.com',
+        contentBaseURL: 'https://meshnet.nordvpn.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'manual.bubble.io',
-        baseUrl: 'https://manual.bubble.io',
+        contentBaseURL: 'https://manual.bubble.io',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.tickettool.xyz',
-        baseUrl: 'https://docs.tickettool.xyz',
+        contentBaseURL: 'https://docs.tickettool.xyz',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'wiki.redmodding.org',
-        baseUrl: 'https://wiki.redmodding.org',
+        contentBaseURL: 'https://wiki.redmodding.org',
-        tests: [{ name: 'Home', url: '/' }],
-    },
-    {
-        name: 'docs.cherry-ai.com',
-        baseUrl: 'https://docs.cherry-ai.com',
         tests: [{ name: 'Home', url: '/' }],
     },
+    // {
+    //     name: 'docs.cherry-ai.com',
+    //     contentBaseURL: 'https://docs.cherry-ai.com',
+    //     tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
+    // },
     {
         name: 'docs.snyk.io',
-        baseUrl: 'https://docs.snyk.io',
+        contentBaseURL: 'https://docs.snyk.io',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.realapp.link',
-        baseUrl: 'https://docs.realapp.link',
+        contentBaseURL: 'https://docs.realapp.link',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.plaza.finance',
-        baseUrl: 'https://docs.plaza.finance',
+        contentBaseURL: 'https://docs.plaza.finance',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.publicai.io',
-        baseUrl: 'https://docs.publicai.io',
+        contentBaseURL: 'https://docs.publicai.io',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'hyperliquid.gitbook.io',
-        baseUrl: 'https://hyperliquid.gitbook.io',
+        contentBaseURL: 'https://hyperliquid.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.umbraco.com',
-        baseUrl: 'https://docs.umbraco.com',
+        contentBaseURL: 'https://docs.umbraco.com',
-        tests: [{ name: 'Home', url: '/welcome', screenshot: { waitForTOCScrolling: false } }],
+        tests: [
+            {
+                name: 'Home',
+                url: '/welcome',
+                run: waitForCookiesDialog,
+                screenshot: { waitForTOCScrolling: false },
+            },
+        ],
     },
     {
         name: 'sosovalue-white-paper.gitbook.io',
-        baseUrl: 'https://sosovalue-white-paper.gitbook.io',
+        contentBaseURL: 'https://sosovalue-white-paper.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.revrobotics.com',
-        baseUrl: 'https://docs.revrobotics.com',
+        contentBaseURL: 'https://docs.revrobotics.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'chartschool.stockcharts.com',
-        baseUrl: 'https://chartschool.stockcharts.com',
+        contentBaseURL: 'https://chartschool.stockcharts.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.soniclabs.com',
-        baseUrl: 'https://docs.soniclabs.com',
+        contentBaseURL: 'https://docs.soniclabs.com',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.meshchain.ai',
-        baseUrl: 'https://docs.meshchain.ai',
+        contentBaseURL: 'https://docs.meshchain.ai',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.thousandeyes.com',
-        baseUrl: 'https://docs.thousandeyes.com',
+        contentBaseURL: 'https://docs.thousandeyes.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.raydium.io',
-        baseUrl: 'https://docs.raydium.io',
+        contentBaseURL: 'https://docs.raydium.io',
         tests: [{ name: 'Home', url: '/' }],
     },
     {
         name: 'docs.fluentbit.io',
-        baseUrl: 'https://docs.fluentbit.io',
+        contentBaseURL: 'https://docs.fluentbit.io',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
+    },
+    {
+        name: 'run-ai-docs.nvidia.com',
+        contentBaseURL: 'https://run-ai-docs.nvidia.com',
+        skip: process.env.ARGOS_BUILD_NAME !== 'customers-v2',
+        tests: [
+            { name: 'Home', url: '/' },
+            { name: 'OG Image', url: '/~gitbook/ogimage/h17zQIFwy3MaafVNmItO', mode: 'image' },
+        ],
     },
 ];
 

packages/gitbook/e2e/internal.spec.ts

@@ -12,12 +12,14 @@ import {
     VISITOR_TOKEN_COOKIE,
     getVisitorAuthCookieName,
     getVisitorAuthCookieValue,
-} from '@/lib/visitor-token';
+} from '@/lib/visitors';
 
+import { getSiteAPIToken } from '../tests/utils';
 import {
     type TestsCase,
     allDeprecatedThemePresets,
     allLocales,
+    allSearchStyles,
     allSidebarBackgroundStyles,
     allThemeModes,
     allThemes,
@@ -26,12 +28,13 @@ import {
     headerLinks,
     runTestCases,
     waitForCookiesDialog,
+    waitForNotFound,
 } from './util';
 
 const testCases: TestsCase[] = [
     {
         name: 'GitBook Site (Single Variant)',
-        baseUrl: 'https://gitbook-open-e2e-sites.gitbook.io/gitbook-doc/',
+        contentBaseURL: 'https://gitbook-open-e2e-sites.gitbook.io/gitbook-doc/',
         tests: [
             {
                 name: 'Home',
@@ -84,7 +87,7 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'GitBook Site (Multi Variants)',
-        baseUrl: 'https://gitbook-open-e2e-sites.gitbook.io/multi-variants/',
+        contentBaseURL: 'https://gitbook-open-e2e-sites.gitbook.io/multi-variants/',
         tests: [
             {
                 name: 'Variants dropdown',
@@ -108,24 +111,24 @@ const testCases: TestsCase[] = [
                 name: 'Customized variant titles are displayed',
                 url: '',
                 run: async (page) => {
-                    const spaceDrowpdown = page
+                    const spaceDropdown = page
                         .locator('[data-testid="space-dropdown-button"]')
                         .locator('visible=true');
-                    await spaceDrowpdown.click();
+                    await spaceDropdown.click();
 
                     const variantSelectionDropdown = page.locator(
-                        'css=[data-testid="space-dropdown-button"] + div'
+                        'css=[data-testid="dropdown-menu"]'
                     );
                     // the customized space title
                     await expect(
-                        variantSelectionDropdown.getByRole('link', {
+                        variantSelectionDropdown.getByRole('menuitem', {
                             name: 'Multi-Variants',
                         })
                     ).toBeVisible();
 
                     // the NON-customized space title
                     await expect(
-                        variantSelectionDropdown.getByRole('link', {
+                        variantSelectionDropdown.getByRole('menuitem', {
                             name: 'RFCs',
                         })
                     ).toBeVisible();
@@ -135,28 +138,31 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'GitBook Site (Navigation when switching variant)',
-        baseUrl: 'https://gitbook-open-e2e-sites.gitbook.io/',
+        contentBaseURL: 'https://gitbook-open-e2e-sites.gitbook.io/',
         tests: [
             {
                 name: 'Keep navigation path/route when switching variant (Public)',
                 url: 'api-multi-versions/reference/api-reference/pets',
                 screenshot: false,
                 run: async (page) => {
-                    const spaceDrowpdown = await page
+                    const spaceDropdown = await page
                         .locator('[data-testid="space-dropdown-button"]')
                         .locator('visible=true');
-                    await spaceDrowpdown.click();
+                    await spaceDropdown.click();
 
+                    const variantSelectionDropdown = page.locator(
+                        'css=[data-testid="dropdown-menu"]'
+                    );
                     // Click the second variant in the dropdown
-                    await page
+                    await variantSelectionDropdown
-                        .getByRole('link', {
+                        .getByRole('menuitem', {
                             name: '2.0',
                         })
                         .click();
 
                     // It should keep the current page path, i.e "reference/api-reference/pets" when navigating to the new variant
-                    await page.waitForURL(
+                    await page.waitForURL((url) =>
-                        'https://gitbook-open-e2e-sites.gitbook.io/api-multi-versions/2.0/reference/api-reference/pets?fallback=true'
+                        url.pathname.includes('api-multi-versions/2.0/reference/api-reference/pets')
                     );
                 },
             },
@@ -165,28 +171,34 @@ const testCases: TestsCase[] = [
                 url: 'api-multi-versions-share-links/8tNo6MeXg7CkFMzSSz81/reference/api-reference/pets',
                 screenshot: false,
                 run: async (page) => {
-                    const spaceDrowpdown = await page
+                    const spaceDropdown = await page
                         .locator('[data-testid="space-dropdown-button"]')
                         .locator('visible=true');
-                    await spaceDrowpdown.click();
+                    await spaceDropdown.click();
+
+                    const variantSelectionDropdown = page.locator(
+                        'css=[data-testid="dropdown-menu"]'
+                    );
 
                     // Click the second variant in the dropdown
-                    await page
+                    await variantSelectionDropdown
-                        .getByRole('link', {
+                        .getByRole('menuitem', {
                             name: '2.0',
                         })
                         .click();
 
                     // It should keep the current page path, i.e "reference/api-reference/pets" when navigating to the new variant
-                    await page.waitForURL(
+                    await page.waitForURL((url) =>
-                        'https://gitbook-open-e2e-sites.gitbook.io/api-multi-versions-share-links/8tNo6MeXg7CkFMzSSz81/2.0/reference/api-reference/pets?fallback=true'
+                        url.pathname.includes(
+                            'api-multi-versions-share-links/8tNo6MeXg7CkFMzSSz81/2.0/reference/api-reference/pets'
+                        )
                     );
                 },
             },
             {
                 name: 'Keep navigation path/route when switching variant (VA)',
                 screenshot: false,
-                url: (() => {
+                url: () => {
                     const privateKey = 'c26190fc-74b2-4b54-9fc7-df9941104953';
                     const token = jwt.sign(
                         {
@@ -198,23 +210,29 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `api-multi-versions-va/reference/api-reference/pets?jwt_token=${token}`;
-                })(),
+                },
                 run: async (page) => {
-                    const spaceDrowpdown = await page
+                    const spaceDropdown = await page
                         .locator('[data-testid="space-dropdown-button"]')
                         .locator('visible=true');
-                    await spaceDrowpdown.click();
+                    await spaceDropdown.click();
+
+                    const variantSelectionDropdown = page.locator(
+                        'css=[data-testid="dropdown-menu"]'
+                    );
 
                     // Click the second variant in the dropdown
-                    await page
+                    await variantSelectionDropdown
-                        .getByRole('link', {
+                        .getByRole('menuitem', {
                             name: '2.0',
                         })
                         .click();
 
                     // It should keep the current page path, i.e "reference/api-reference/pets" when navigating to the new variant
-                    await page.waitForURL(
+                    await page.waitForURL((url) =>
-                        'https://gitbook-open-e2e-sites.gitbook.io/api-multi-versions-va/2.0/reference/api-reference/pets?fallback=true'
+                        url.pathname.includes(
+                            'api-multi-versions-va/2.0/reference/api-reference/pets'
+                        )
                     );
                 },
             },
@@ -222,7 +240,7 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'GitBook Site (Sections and Section Groups)',
-        baseUrl: 'https://gitbook-open-e2e-sites.gitbook.io/sections/',
+        contentBaseURL: 'https://gitbook-open-e2e-sites.gitbook.io/sections/',
         tests: [
             {
                 name: 'Site with sections and section groups',
@@ -244,16 +262,14 @@ const testCases: TestsCase[] = [
                     const sectionGroupDropdown = await page.getByText('Test Section Group 1');
                     await sectionGroupDropdown.hover();
                     await page.getByText('Section B').click();
-                    await page.waitForURL(
+                    await page.waitForURL((url) => url.pathname.includes('/sections/sections-4'));
-                        'https://gitbook-open-e2e-sites.gitbook.io/sections/sections-4'
-                    );
                 },
             },
         ],
     },
     {
         name: 'GitBook',
-        baseUrl: 'https://docs.gitbook.com',
+        contentBaseURL: 'https://gitbook.com/docs/',
         tests: [
             {
                 name: 'Home',
@@ -297,18 +313,30 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Versioning',
-        baseUrl: 'https://gitbook.gitbook.io/test-gitbook-open/',
+        contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
         tests: [
             {
                 name: 'Revision',
                 url: '~/revisions/S55pwsEr5UVoroaOiWnP/blocks/headings',
                 run: waitForCookiesDialog,
             },
+            {
+                name: 'Invalid revision',
+                url: '~/revisions/idnotfound/blocks/headings',
+                run: waitForNotFound,
+                screenshot: false,
+            },
+            {
+                name: 'Invalid change request',
+                url: '~/changes/idnotfound/blocks/headings',
+                run: waitForNotFound,
+                screenshot: false,
+            },
         ],
     },
     {
         name: 'PDF',
-        baseUrl: 'https://gitbook.gitbook.io/test-gitbook-open/',
+        contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
         tests: [
             {
                 name: 'PDF',
@@ -316,12 +344,132 @@ const testCases: TestsCase[] = [
                 screenshot: {
                     waitForTOCScrolling: false,
                 },
+                run: async (page) => {
+                    await expect(page.locator('[data-testid="print-button"]')).toBeVisible();
+                },
+            },
+        ],
+    },
+    {
+        name: 'Space PDF',
+        tests: [
+            {
+                name: 'Main content',
+                url: async () => {
+                    const data = await getSiteAPIToken(
+                        'https://gitbook.gitbook.io/test-gitbook-open/'
+                    );
+
+                    const searchParams = new URLSearchParams();
+                    searchParams.set('limit', '10');
+                    searchParams.set('token', data.apiToken);
+
+                    return `~space/${data.space}/~gitbook/pdf?${searchParams.toString()}`;
+                },
+                screenshot: false,
+                run: async (page) => {
+                    await expect(page.locator('[data-testid="print-button"]')).toBeVisible();
+                },
+            },
+            {
+                name: 'Change request',
+                url: async () => {
+                    const data = await getSiteAPIToken(
+                        'https://gitbook.gitbook.io/test-gitbook-open/'
+                    );
+
+                    const searchParams = new URLSearchParams();
+                    searchParams.set('limit', '10');
+                    searchParams.set('token', data.apiToken);
+
+                    return `~space/${data.space}/~/changes/HrtgUd5MlFusCMv1elA7/~gitbook/pdf?${searchParams.toString()}`;
+                },
+                screenshot: false,
+                run: async (page) => {
+                    await expect(page.locator('[data-testid="print-button"]')).toBeVisible();
+                },
+            },
+        ],
+    },
+    {
+        name: 'Site Preview',
+        skip: process.env.ARGOS_BUILD_NAME !== 'v2-vercel',
+        tests: [
+            {
+                name: 'Main content',
+                url: async () => {
+                    const data = await getSiteAPIToken(
+                        'https://gitbook.gitbook.io/test-gitbook-open/'
+                    );
+
+                    const searchParams = new URLSearchParams();
+                    searchParams.set('token', data.apiToken);
+
+                    return `url/preview/${data.site}/?${searchParams.toString()}`;
+                },
+                screenshot: false,
+                run: async (page) => {
+                    await expect(page.locator('[data-testid="table-of-contents"]')).toBeVisible();
+                },
+            },
+        ],
+    },
+    {
+        name: 'Markdown page',
+        skip: process.env.ARGOS_BUILD_NAME !== 'v2-vercel',
+        contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
+        tests: [
+            {
+                name: 'Text page',
+                url: 'text-page.md',
+                screenshot: false,
+                run: async (_page, response) => {
+                    expect(response?.status()).toBe(200);
+                    expect(response?.headers()['content-type']).toContain('text/markdown');
+                },
+            },
+        ],
+    },
+    {
+        name: 'Site subdirectory (proxy)',
+        skip: process.env.ARGOS_BUILD_NAME !== 'v2-vercel',
+        contentBaseURL: 'https://nextjs-gbo-proxy.vercel.app/documentation/',
+        tests: [
+            {
+                name: 'Main',
+                url: '',
+                fullPage: true,
+            },
+        ],
+    },
+    {
+        name: 'Site subdirectory (proxy) with VA',
+        skip: process.env.ARGOS_BUILD_NAME !== 'v2-vercel',
+        contentBaseURL: 'https://nextjs-gbo-proxy-va.vercel.app/va/docs/',
+        tests: [
+            {
+                name: 'Main',
+                url: () => {
+                    const privateKey =
+                        'rqSfA6x7eAKx1qDRCDq9aCXwivpUvQ8YkXeDdFvCCUa9QchIcM7pF1iJ4o7AGOU49spmOWjKoIPtX0pVUVQ81w==';
+                    const token = jwt.sign(
+                        {
+                            name: 'gitbook-open-tests',
+                        },
+                        privateKey,
+                        {
+                            expiresIn: '24h',
+                        }
+                    );
+                    return `?jwt_token=${token}`;
+                },
+                fullPage: true,
             },
         ],
     },
     {
         name: 'Content tests',
-        baseUrl: 'https://gitbook.gitbook.io/test-gitbook-open/',
+        contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
         tests: [
             {
                 name: 'Text',
@@ -338,7 +486,7 @@ const testCases: TestsCase[] = [
                 url: 'blocks/block-images',
                 run: waitForCookiesDialog,
                 fullPage: true,
-                screenshot: { threshold: 0.8 },
+                screenshot: { threshold: 0.9 },
             },
             {
                 name: 'Images (with zoom)',
@@ -349,7 +497,6 @@ const testCases: TestsCase[] = [
                     await zoomImage.first().click();
                     await expect(page.getByTestId('zoom-image-modal')).toBeVisible();
                 },
-                fullPage: true,
                 screenshot: { threshold: 0.8 },
             },
             {
@@ -384,7 +531,12 @@ const testCases: TestsCase[] = [
             {
                 name: 'Integration Blocks',
                 url: 'blocks/integrations',
-                run: waitForCookiesDialog,
+                run: async (page) => {
+                    await waitForCookiesDialog(page);
+                    const mermaidIframe = page.locator('iframe[title*="mermaid"]').contentFrame();
+                    await expect(mermaidIframe.getByText('Mermaid', { exact: true })).toBeVisible();
+                    await expect(mermaidIframe.getByText('Diagram', { exact: true })).toBeVisible();
+                },
             },
             {
                 name: 'Tables',
@@ -484,7 +636,7 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Page options',
-        baseUrl: 'https://gitbook.gitbook.io/test-gitbook-open/',
+        contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
         tests: [
             {
                 name: 'Hidden',
@@ -518,7 +670,7 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Customization',
-        baseUrl: 'https://gitbook.gitbook.io/test-gitbook-open/',
+        contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
         tests: allThemeModes.flatMap((themeMode) => [
             {
                 name: `Without header - Theme mode ${themeMode}`,
@@ -600,6 +752,23 @@ const testCases: TestsCase[] = [
                         run: waitForCookiesDialog,
                     })),
                 ]),
+                ...allSearchStyles.flatMap((searchStyle) => ({
+                    name: `Theme ${theme} – Search ${searchStyle} – Mode ${themeMode}`,
+                    url: getCustomizationURL({
+                        styling: {
+                            theme,
+                            search: searchStyle,
+                        },
+                        header: {
+                            links: headerLinks,
+                        },
+                        themes: {
+                            default: themeMode,
+                            toggeable: false,
+                        },
+                    }),
+                    run: waitForCookiesDialog,
+                })),
             ]),
             // Deprecated header themes
             ...allDeprecatedThemePresets.flatMap((preset) => [
@@ -652,7 +821,7 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Ads',
-        baseUrl: 'https://gitbook.gitbook.io/test-gitbook-open/',
+        contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
         tests: [
             {
                 name: 'Without previewed ads',
@@ -663,7 +832,7 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Shared space navigation (first site)',
-        baseUrl: 'https://gitbook-open-e2e-sites.gitbook.io/shared-space-uno/',
+        contentBaseURL: 'https://gitbook-open-e2e-sites.gitbook.io/shared-space-uno/',
         tests: [
             {
                 name: 'Navigation to shared space',
@@ -684,7 +853,7 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Shared space navigation (second site)',
-        baseUrl: 'https://gitbook-open-e2e-sites.gitbook.io/shared-space-dos/',
+        contentBaseURL: 'https://gitbook-open-e2e-sites.gitbook.io/shared-space-dos/',
         tests: [
             {
                 name: 'Navigation to shared space',
@@ -704,7 +873,7 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Site Redirects',
-        baseUrl: 'https://gitbook-open-e2e-sites.gitbook.io/gitbook-doc/',
+        contentBaseURL: 'https://gitbook-open-e2e-sites.gitbook.io/gitbook-doc/',
         tests: [
             {
                 name: 'Redirect to SSO page',
@@ -716,9 +885,38 @@ const testCases: TestsCase[] = [
             },
         ],
     },
+    {
+        name: 'Content Redirects',
+        contentBaseURL: 'https://gitbook-open-e2e-sites.gitbook.io/gitbook-doc/',
+        tests: [
+            {
+                name: 'Redirect to new location',
+                url: '/content-editor/editing-content/inline/redirect-test',
+                run: async (page) => {
+                    await expect(page.locator('h1')).toHaveText('Redirect test');
+                },
+                screenshot: false,
+            },
+        ],
+    },
+    {
+        name: 'Site Redirects with sections',
+        contentBaseURL: 'https://gitbook-open-e2e-sites.gitbook.io/sections/',
+        tests: [
+            {
+                // This test that a redirect that incudes a section path works
+                name: 'Redirect to Quickstart page',
+                url: 'sections-2/redirect-test',
+                run: async (page) => {
+                    await expect(page.locator('h1')).toHaveText('Quickstart');
+                },
+                screenshot: false,
+            },
+        ],
+    },
     {
         name: 'Share links',
-        baseUrl: 'https://gitbook.gitbook.io/gbo-tests-share-links/',
+        contentBaseURL: 'https://gitbook.gitbook.io/gbo-tests-share-links/',
         tests: [
             {
                 name: 'Valid link',
@@ -738,11 +936,11 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Visitor Auth - Space',
-        baseUrl: 'https://gitbook.gitbook.io/gbo-va-space/',
+        contentBaseURL: 'https://gitbook.gitbook.io/gbo-va-space/',
         tests: [
             {
                 name: 'First',
-                url: (() => {
+                url: () => {
                     const privateKey = '70b844d0-c519-4532-8586-5970ce48c537';
                     const token = jwt.sign(
                         {
@@ -754,7 +952,7 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `first?jwt_token=${token}`;
-                })(),
+                },
                 run: async (page) => {
                     await expect(
                         page.getByRole('heading', { level: 1, name: 'first' })
@@ -764,7 +962,7 @@ const testCases: TestsCase[] = [
             },
             {
                 name: 'Second',
-                url: (() => {
+                url: () => {
                     const privateKey = '70b844d0-c519-4532-8586-5970ce48c537';
                     const token = jwt.sign(
                         {
@@ -776,7 +974,7 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `second?jwt_token=${token}`;
-                })(),
+                },
                 run: async (page) => {
                     await expect(
                         page.getByRole('heading', { level: 1, name: 'second' })
@@ -788,11 +986,11 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Visitor Auth - Collection',
-        baseUrl: 'https://gitbook.gitbook.io/gbo-va-collection/',
+        contentBaseURL: 'https://gitbook.gitbook.io/gbo-va-collection/',
         tests: [
             {
                 name: 'Root',
-                url: (() => {
+                url: () => {
                     const privateKey = 'af5688dc-f0b6-4146-9b1d-6d834c62c980';
                     const token = jwt.sign(
                         {
@@ -804,12 +1002,12 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `?jwt_token=${token}`;
-                })(),
+                },
                 run: waitForCookiesDialog,
             },
             {
                 name: 'Primary (Space A)',
-                url: (() => {
+                url: () => {
                     const privateKey = 'af5688dc-f0b6-4146-9b1d-6d834c62c980';
                     const token = jwt.sign(
                         {
@@ -820,13 +1018,16 @@ const testCases: TestsCase[] = [
                             expiresIn: '24h',
                         }
                     );
+
+                    // Test that when accessing the non-canonical URL, we are redirected to the canonical URL
+                    // with the jwt token in the query string
                     return `spacea?jwt_token=${token}`;
-                })(),
+                },
                 run: waitForCookiesDialog,
             },
             {
                 name: 'Space B',
-                url: (() => {
+                url: () => {
                     const privateKey = 'af5688dc-f0b6-4146-9b1d-6d834c62c980';
                     const token = jwt.sign(
                         {
@@ -838,12 +1039,12 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `spaceb?jwt_token=${token}`;
-                })(),
+                },
                 run: waitForCookiesDialog,
             },
             {
                 name: 'Space C',
-                url: (() => {
+                url: () => {
                     const privateKey = 'af5688dc-f0b6-4146-9b1d-6d834c62c980';
                     const token = jwt.sign(
                         {
@@ -855,18 +1056,18 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `spacec?jwt_token=${token}`;
-                })(),
+                },
                 run: waitForCookiesDialog,
             },
         ],
     },
     {
         name: 'Visitor Auth - Space (custom domain)',
-        baseUrl: 'https://test.gitbook.community/',
+        contentBaseURL: 'https://test.gitbook.community/',
         tests: [
             {
                 name: 'Root',
-                url: (() => {
+                url: () => {
                     const privateKey = '19c8166f-c436-4ed1-a24e-60954b804021';
                     const token = jwt.sign(
                         {
@@ -878,12 +1079,12 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `?jwt_token=${token}`;
-                })(),
+                },
                 run: waitForCookiesDialog,
             },
             {
                 name: 'First',
-                url: (() => {
+                url: () => {
                     const privateKey = '19c8166f-c436-4ed1-a24e-60954b804021';
                     const token = jwt.sign(
                         {
@@ -895,7 +1096,7 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `first?jwt_token=${token}`;
-                })(),
+                },
                 run: async (page) => {
                     await expect(
                         page.getByRole('heading', { level: 1, name: 'first' })
@@ -905,7 +1106,7 @@ const testCases: TestsCase[] = [
             },
             {
                 name: 'Custom page',
-                url: (() => {
+                url: () => {
                     const privateKey = '19c8166f-c436-4ed1-a24e-60954b804021';
                     const token = jwt.sign(
                         {
@@ -917,12 +1118,12 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `custom-page?jwt_token=${token}`;
-                })(),
+                },
                 run: waitForCookiesDialog,
             },
             {
                 name: 'Inner page',
-                url: (() => {
+                url: () => {
                     const privateKey = '19c8166f-c436-4ed1-a24e-60954b804021';
                     const token = jwt.sign(
                         {
@@ -934,14 +1135,14 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `custom-page/inner-page?jwt_token=${token}`;
-                })(),
+                },
                 run: waitForCookiesDialog,
             },
         ],
     },
     {
         name: 'Visitor Auth - Site (redirects to fallback/auth URL)',
-        baseUrl: 'https://gitbook-open-e2e-sites.gitbook.io/va-site-redirects-fallback/',
+        contentBaseURL: 'https://gitbook-open-e2e-sites.gitbook.io/va-site-redirects-fallback/',
         tests: [
             {
                 name: 'Redirect to fallback on invalid token pulled from cookie',
@@ -973,7 +1174,7 @@ const testCases: TestsCase[] = [
             {
                 name: 'Show error message when invalid token is passed to url',
                 screenshot: false,
-                url: (() => {
+                url: () => {
                     const token = jwt.sign(
                         {
                             name: 'gitbook-open-tests',
@@ -984,7 +1185,7 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `?jwt_token=${token}`;
-                })(),
+                },
                 run: async (page) => {
                     await expect(page.locator('pre')).toContainText(
                         'Error while validating the JWT token. Reason: The token signature is invalid.'
@@ -995,7 +1196,7 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Languages',
-        baseUrl: 'https://gitbook.gitbook.io/test-gitbook-open/',
+        contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
         tests: allLocales.map((locale) => ({
             name: locale,
             url: getCustomizationURL({
@@ -1011,7 +1212,7 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'SEO',
-        baseUrl: 'https://gitbook.gitbook.io/test-gitbook-open/',
+        contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
         tests: [
             {
                 name: 'Index by default',
@@ -1062,11 +1263,11 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Adaptive Content - VA',
-        baseUrl: 'https://gitbook-open-e2e-sites.gitbook.io/adaptive-content-va/',
+        contentBaseURL: 'https://gitbook-open-e2e-sites.gitbook.io/adaptive-content-va/',
         tests: [
             {
                 name: 'isAlphaUser',
-                url: (() => {
+                url: () => {
                     const privateKey = 'afe09cdf-0f43-480a-b54c-8b1f62f174f9';
                     const token = jwt.sign(
                         {
@@ -1079,7 +1280,7 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `?jwt_token=${token}`;
-                })(),
+                },
                 run: async (page) => {
                     const alphaUserPage = page
                         .locator('a[class*="group\\/toclink"]')
@@ -1093,7 +1294,7 @@ const testCases: TestsCase[] = [
             },
             {
                 name: 'isBetaUser',
-                url: (() => {
+                url: () => {
                     const privateKey = 'afe09cdf-0f43-480a-b54c-8b1f62f174f9';
                     const token = jwt.sign(
                         {
@@ -1106,7 +1307,7 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `?jwt_token=${token}`;
-                })(),
+                },
                 run: async (page) => {
                     const alphaUserPage = page
                         .locator('a[class*="group\\/toclink"]')
@@ -1120,7 +1321,7 @@ const testCases: TestsCase[] = [
             },
             {
                 name: 'isAlphaUser & isBetaUser',
-                url: (() => {
+                url: () => {
                     const privateKey = 'afe09cdf-0f43-480a-b54c-8b1f62f174f9';
                     const token = jwt.sign(
                         {
@@ -1134,7 +1335,7 @@ const testCases: TestsCase[] = [
                         }
                     );
                     return `?jwt_token=${token}`;
-                })(),
+                },
                 run: async (page) => {
                     const alphaUserPage = page
                         .locator('a[class*="group\\/toclink"]')
@@ -1150,7 +1351,7 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Adaptive Content - Public',
-        baseUrl: 'https://gitbook-open-e2e-sites.gitbook.io/adaptive-content-public/',
+        contentBaseURL: 'https://gitbook-open-e2e-sites.gitbook.io/adaptive-content-public/',
         tests: [
             {
                 name: 'No custom cookie',
@@ -1293,7 +1494,7 @@ const testCases: TestsCase[] = [
     },
     {
         name: 'Tables',
-        baseUrl: 'https://gitbook.gitbook.io/test-gitbook-open/',
+        contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
         tests: [
             {
                 name: 'Default table',