Fix 404 for embed root page

Going to `/~gitbook/embed/page/` should load the space's root page, but returns a 404 instead. This fixes that.

.github/CONTRIBUTING.md

@@ -54,10 +54,9 @@ After forking this repository, you'll want to [create a branch](https://docs.git
 #### 3. Install dependencies and run the project locally
 
 ##### Prerequisites:
-- Node.js (Version: >=20.6)
-  - Use `nvm` for easy Node management
-- [Bun](https://bun.sh/) (Version: >=1.2.15)
-  - We use a text-based lockfile which isn't supported below 1.2.15
+
+- [Node.js](https://nodejs.org/en) (see "engines" in `package.json`)
+- [Bun](https://bun.sh/) (see "packageManager" in `package.json`)
 
 ##### Setup steps:
 

.github/workflows/ci.yaml

@@ -4,8 +4,9 @@ on:
     push:
         branches:
             - main
+            - changeset-release/main
 env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
     format:
         runs-on: ubuntu-latest
@@ -41,7 +42,7 @@ jobs:
         name: Build (Open Source)
         timeout-minutes: 6
         env:
-            NPM_TOKEN_READONLY: ''
+            BUN_NPM_TOKEN: ''
         steps:
             - name: Checkout
               uses: actions/checkout@v4

.github/workflows/deploy-preview.yaml

@@ -5,7 +5,7 @@ on:
       branches:
         - main
 env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
     deploy-v2-vercel:
         name: Deploy v2 to Vercel (preview)

.github/workflows/deploy-production.yaml

@@ -4,7 +4,7 @@ on:
         branches:
             - main
 env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
     deploy-v2-vercel:
         name: Deploy v2 to Vercel (production)

.github/workflows/deploy-staging.yaml

@@ -4,7 +4,7 @@ on:
         branches:
             - main
 env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
     deploy-v2-vercel:
         name: Deploy v2 to Vercel (staging)

.github/workflows/publish.yaml

@@ -6,7 +6,7 @@ on:
             - main
 
 env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
     
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
@@ -14,30 +14,38 @@ jobs:
     publish:
         name: Publish
         runs-on: ubuntu-latest
+        permissions:
+            id-token: write
+            pull-requests: write
+            contents: write
         steps:
             - name: Checkout Repo
               uses: actions/checkout@v3
               with:
                   # This makes Actions fetch all Git history so that Changesets can generate changelogs with the correct commits
                   fetch-depth: 0
+            - name: Setup Node
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 22
+                  registry-url: 'https://registry.npmjs.org'
+            # Ensure npm 11.5.1 or later is installed
+            - name: Update npm
+              run: npm install -g npm@latest
             - name: Setup Bun
               uses: ./.github/composite/setup-bun
             - name: Install dependencies
               run: bun install --frozen-lockfile
               env:
                   PUPPETEER_SKIP_DOWNLOAD: 1
-            - name: Create Release Pull Request or Publish to npm
+            - name: Create Release Pull Request
               id: changesets
               uses: changesets/action@v1
               with:
-                  publish: npm run release
-                  version: npm run changeset-version
+                  publish: bun run publish-all-packages
+                  version: bun run changeset-version
               env:
                   # Using a PAT instead of GITHUB_TOKEN because we need to run workflows when releases are created
                   # https://github.com/orgs/community/discussions/26875#discussioncomment-3253761
                   GITHUB_TOKEN: ${{ secrets.GH_PERSONAL_TOKEN }}
-                  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-                  NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
-                  CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-                  CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 

.gitignore

@@ -25,3 +25,7 @@ yarn-error.log*
 
 # TypeScript
 *.tsbuildinfo
+.npmrc
+
+# Bun pack artifacts
+packages/*/*.tgz

.nvmrc

@@ -1 +1 @@
-v20.6
+v22.3

README.md

@@ -35,7 +35,7 @@ To run a local version of this project, please follow these simple steps.
 
 ### Prerequisites
 
-- Node.js (Version: >=20.6)
+- Node.js (Version: >= 22.3)
     - Use nvm for easy Node management
 - [Bun](https://bun.sh/) (Version: >=1.2.15)
   - We use a text-based lockfile which isn't supported below 1.2.15
@@ -90,7 +90,7 @@ If you are GitBook staff, you'll need our NPM token in your local environment.
 ```
 .env.local
 
-NPM_TOKEN_READONLY=xxx
+BUN_NPM_TOKEN=xxx
 ```
 
 and then reinstall dependencies.

bunfig.toml

@@ -1,2 +1,2 @@
 [install.scopes]
-"gitbook" = { token = "$NPM_TOKEN_READONLY", url = "https://registry.npmjs.org" }
+"gitbook" = { token = "$BUN_NPM_TOKEN", url = "https://registry.npmjs.org" }

package.json

@@ -1,17 +1,22 @@
 {
     "name": "gitbook",
     "version": "0.1.0",
+    "engines": {
+        "node": "^22.3.0"
+    },
     "devDependencies": {
         "@biomejs/biome": "^1.9.4",
         "@changesets/cli": "^2.29.7",
-        "turbo": "^2.5.8",
+        "turbo": "^2.6.1",
         "vercel": "^39.4.2"
     },
-    "packageManager": "bun@1.2.15",
+    "packageManager": "bun@1.3.2",
     "overrides": {
         "@codemirror/state": "6.4.1",
-        "react": "^19.0.0",
-        "react-dom": "^19.0.0",
+        "@types/react": "catalog:",
+        "@types/react-dom": "catalog:",
+        "react": "catalog:",
+        "react-dom": "catalog:",
         "esbuild": "0.24.2"
     },
     "private": true,
@@ -27,17 +32,28 @@
         "e2e-customers": "turbo run e2e-customers",
         "changeset": "changeset",
         "changeset-version": "changeset version && bun run format && bun update",
-        "release": "turbo run release && bun run publish-all-packages",
-        "publish-all-packages": "for dir in packages/*; do (cd \"$dir\" && bun publish || true); done && changeset tag",
+        "publish-all-packages": "turbo run publish-to-npm --continue=dependencies-successful",
         "download:env": "op read op://gitbook-x-dev/gitbook-open/.env.local >> .env.local",
         "clean": "turbo run clean"
     },
     "workspaces": {
         "packages": ["packages/*"],
         "catalog": {
-            "@gitbook/api": "0.143.2",
+            "@tsconfig/strictest": "^2.0.6",
+            "@tsconfig/node20": "^20.1.6",
+            "@gitbook/api": "0.150.0",
+            "@scalar/api-client-react": "^1.3.46",
+            "@types/react": "^19.0.0",
+            "@types/react-dom": "^19.0.0",
+            "assert-never": "^1.4.0",
             "bidc": "^0.0.2",
-            "tsdown": "^0.15.6"
+            "bun-types": "^1.1.20",
+            "classnames": "^2.5.1",
+            "react": "^19.0.0",
+            "react-dom": "^19.0.0",
+            "tsdown": "^0.15.6",
+            "typescript": "^5.5.3",
+            "usehooks-ts": "^3.1.1"
         }
     },
     "patchedDependencies": {

packages/browser-types/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @gitbook/browser-types
 
+## 0.1.3
+
+### Patch Changes
+
+- 10995e0: Use NPM Trusted publishing for publishing the package.
+- Updated dependencies [10995e0]
+  - @gitbook/icons@0.3.4
+
+## 0.1.2
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+- Updated dependencies [6142d6b]
+  - @gitbook/icons@0.3.3
+
 ## 0.1.1
 
 ### Patch Changes

packages/browser-types/package.json

@@ -8,21 +8,29 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "0.1.1",
+    "sideEffects": false,
+    "version": "0.1.3",
     "dependencies": {
         "@gitbook/api": "catalog:",
         "@gitbook/icons": "workspace:"
     },
     "devDependencies": {
-        "typescript": "^5.5.3"
+        "bun-types": "catalog:",
+        "tsdown": "catalog:",
+        "typescript": "catalog:"
     },
     "scripts": {
-        "build": "tsc",
-        "typecheck": "tsc --noEmit"
+        "build": "tsdown",
+        "typecheck": "tsc --noEmit",
+        "dev": "bun run build -- --watch ./src",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
     "files": ["dist", "README.md", "CHANGELOG.md"],
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
     }
 }

packages/cache-tags/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @gitbook/cache-tags
 
+## 0.3.4
+
+### Patch Changes
+
+- 10995e0: Use NPM Trusted publishing for publishing the package.
+
+## 0.3.3
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+
 ## 0.3.2
 
 ### Patch Changes

packages/cache-tags/package.json

@@ -4,26 +4,32 @@
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
-            "development": "./src/index.ts",
             "default": "./dist/index.js"
         }
     },
-    "version": "0.3.2",
+    "sideEffects": false,
+    "version": "0.3.4",
     "dependencies": {
         "@gitbook/api": "catalog:",
-        "assert-never": "^1.2.1"
+        "assert-never": "catalog:"
     },
     "devDependencies": {
-        "typescript": "^5.5.3"
+        "bun-types": "catalog:",
+        "tsdown": "catalog:",
+        "typescript": "catalog:"
     },
     "scripts": {
-        "build": "tsc",
+        "build": "tsdown",
         "typecheck": "tsc --noEmit",
-        "dev": "tsc -w"
+        "dev": "bun run build -- --watch ./src",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
-    "files": ["dist", "src", "README.md", "CHANGELOG.md"],
+    "files": ["dist", "README.md", "CHANGELOG.md"],
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
     }
 }

packages/colors/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @gitbook/colors
 
+## 0.4.3
+
+### Patch Changes
+
+- 10995e0: Use NPM Trusted publishing for publishing the package.
+
+## 0.4.2
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+
 ## 0.4.1
 
 ### Patch Changes

packages/colors/package.json

@@ -4,22 +4,28 @@
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
-            "development": "./src/index.ts",
             "default": "./dist/index.js"
         }
     },
-    "version": "0.4.1",
+    "sideEffects": false,
+    "version": "0.4.3",
     "devDependencies": {
-        "typescript": "^5.5.3"
+        "bun-types": "catalog:",
+        "tsdown": "catalog:",
+        "typescript": "catalog:"
     },
     "scripts": {
-        "build": "tsc",
+        "build": "tsdown",
         "typecheck": "tsc --noEmit",
-        "dev": "tsc -w"
+        "dev": "bun run build -- --watch ./src",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
-    "files": ["dist", "src", "README.md", "CHANGELOG.md"],
+    "files": ["dist", "README.md", "CHANGELOG.md"],
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
     }
 }

packages/embed/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @gitbook/embed
 
+## 0.1.5
+
+### Patch Changes
+
+- 10995e0: Use NPM Trusted publishing for publishing the package.
+- Updated dependencies [10995e0]
+  - @gitbook/icons@0.3.4
+
+## 0.1.4
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+- Updated dependencies [6142d6b]
+  - @gitbook/icons@0.3.3
+
 ## 0.1.3
 
 ### Patch Changes

packages/embed/package.json

@@ -12,19 +12,21 @@
             "default": "./dist/react/index.js"
         }
     },
-    "version": "0.1.3",
+    "sideEffects": false,
+    "version": "0.1.5",
     "dependencies": {
         "@gitbook/api": "catalog:",
         "@gitbook/icons": "workspace:",
         "bidc": "catalog:"
     },
     "peerDependencies": {
-        "react": "^18.0.0"
+        "react": "*"
     },
     "devDependencies": {
+        "@types/react": "catalog:",
         "tsdown": "catalog:",
-        "typescript": "^5.5.3",
-        "react": "^19.0.0"
+        "typescript": "catalog:",
+        "react": "catalog:"
     },
     "scripts": {
         "build": "bun run build-lib && bun run build-standalone",
@@ -32,11 +34,15 @@
         "build-standalone": "bun build src/standalone/index.ts --bundle --minify --outdir=standalone",
         "clean": "rm -rf ./dist",
         "typecheck": "tsc --noEmit",
-        "dev": "bun run build -- --watch ./src"
+        "dev": "bun run build -- --watch ./src",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
     "files": ["dist", "README.md", "CHANGELOG.md"],
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
     }
 }

packages/embed/src/react/GitBookFrame.tsx

@@ -1,4 +1,6 @@
-import React from 'react';
+'use client';
+
+import { useEffect, useMemo, useRef, useState } from 'react';
 import type {
     GetFrameURLOptions,
     GitBookEmbeddableConfiguration,
@@ -17,19 +19,19 @@ export type GitBookFrameProps = {
 export function GitBookFrame(props: GitBookFrameProps) {
     const { className, visitor, buttons, welcomeMessage, suggestions, tools } = props;
 
-    const frameRef = React.useRef<HTMLIFrameElement>(null);
+    const frameRef = useRef<HTMLIFrameElement>(null);
     const gitbook = useGitBook();
-    const [gitbookFrame, setGitbookFrame] = React.useState<GitBookFrameClient | null>(null);
+    const [gitbookFrame, setGitbookFrame] = useState<GitBookFrameClient | null>(null);
 
-    const frameURL = React.useMemo(() => gitbook.getFrameURL({ visitor }), [gitbook, visitor]);
+    const frameURL = useMemo(() => gitbook.getFrameURL({ visitor }), [gitbook, visitor]);
 
-    React.useEffect(() => {
+    useEffect(() => {
         if (frameRef.current) {
             setGitbookFrame(gitbook.createFrame(frameRef.current));
         }
     }, [gitbook]);
 
-    React.useEffect(() => {
+    useEffect(() => {
         gitbookFrame?.configure({
             buttons,
             welcomeMessage,

packages/embed/tsdown.config.ts

@@ -2,8 +2,12 @@ import { defineConfig } from 'tsdown';
 
 export default defineConfig([
     {
-        entry: ['src/index.ts', 'src/react/index.ts'],
-        dts: true,
-        format: ['esm'],
+        entry: 'src/index.ts',
+        outDir: 'dist',
+    },
+    {
+        entry: 'src/react/index.ts',
+        outDir: 'dist/react',
+        unbundle: true,
     },
 ]);

packages/emoji-codepoints/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @gitbook/emoji-codepoints
 
+## 0.2.2
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+
 ## 0.2.1
 
 ### Patch Changes

packages/emoji-codepoints/package.json

@@ -1,19 +1,15 @@
 {
     "name": "@gitbook/emoji-codepoints",
     "description": "Optimized mapping of codepoints to the fully qualified emoji codepoints",
-    "version": "0.2.1",
+    "version": "0.2.2",
     "private": true,
     "exports": "./dist/index.ts",
-    "dependencies": {},
+    "sideEffects": false,
     "devDependencies": {
-        "emoji-assets": "^8.0.0"
+        "emoji-assets": "^9.0.0"
     },
     "scripts": {
         "generate": "bun ./build.ts",
         "clean": "rm -rf ./dist"
-    },
-    "publishConfig": {
-        "access": "public",
-        "registry": "https://registry.npmjs.org/"
     }
 }

packages/expr/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @gitbook/expr
 
+## 1.2.4
+
+### Patch Changes
+
+- 10995e0: Use NPM Trusted publishing for publishing the package.
+- 10995e0: Use NPM dependency for eval-estree-expression
+
+## 1.2.3
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+
 ## 1.2.2
 
 ### Patch Changes

packages/expr/package.json

@@ -1,42 +1,47 @@
 {
     "name": "@gitbook/expr",
     "description": "Safely evaluate & parse user-defined GitBook expressions.",
-    "version": "1.2.2",
+    "version": "1.2.4",
     "type": "module",
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
-            "import": "./dist/index.js",
             "default": "./dist/index.js"
         }
     },
     "sideEffects": false,
     "dependencies": {
-        "eval-estree-expression": "github:jonschlinkert/eval-estree-expression#9cf28d2",
         "acorn": "^8.14.0",
         "acorn-loose": "8.4.0",
         "acorn-walk": "^8.3.4",
+        "assert-never": "catalog:",
         "escodegen": "^2.1.0",
-        "assert-never": "^1.2.1"
+        "eval-estree-expression": "github:jonschlinkert/eval-estree-expression#fb0246a"
     },
     "devDependencies": {
-        "bun-types": "^1.1.20",
-        "tsdown": "catalog:",
+        "@tsconfig/strictest": "catalog:",
+        "@tsconfig/node20": "catalog:",
+        "@types/escodegen": "^0.0.10",
         "@types/estree": "^1.0.6",
-        "@babel/types": "^7.26.0",
         "@types/json-schema": "^7.0.15",
-        "@types/escodegen": "^0.0.10"
+        "bun-types": "catalog:",
+        "tsdown": "catalog:",
+        "typescript": "catalog:"
     },
     "scripts": {
         "build": "tsdown",
         "typecheck": "tsc --noEmit",
         "unit": "bun test",
         "clean": "rm -rf ./dist",
-        "dev": "bun run build -- --watch ./src"
+        "dev": "bun run build -- --watch ./src",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
     "files": ["dist", "README.md", "CHANGELOG.md"],
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
     }
 }

packages/fonts/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @gitbook/fonts
 
+## 0.1.3
+
+### Patch Changes
+
+- 10995e0: Use NPM Trusted publishing for publishing the package.
+
+## 0.1.2
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+
 ## 0.1.1
 
 ### Patch Changes

packages/fonts/package.json

@@ -4,32 +4,38 @@
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
-            "development": "./src/index.ts",
             "default": "./dist/index.js"
         }
     },
-    "version": "0.1.1",
+    "sideEffects": false,
+    "version": "0.1.3",
     "dependencies": {
         "@gitbook/api": "catalog:"
     },
     "devDependencies": {
-        "google-font-metadata": "^6.0.3",
-        "typescript": "^5.5.3"
+        "bun-types": "catalog:",
+        "google-font-metadata": "^6.0.7",
+        "tsdown": "catalog:",
+        "typescript": "catalog:"
     },
     "scripts": {
         "generate": "bun ./bin/generate.js",
-        "build": "tsc --project tsconfig.build.json",
+        "build": "tsdown",
         "typecheck": "tsc --noEmit",
-        "dev": "tsc -w",
+        "dev": "bun run build -- --watch ./src",
         "clean": "rm -rf ./dist && rm -rf ./src/data",
-        "unit": "bun test"
+        "unit": "bun test",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
-    "files": ["dist", "src", "bin", "README.md", "CHANGELOG.md"],
+    "files": ["dist", "bin", "README.md", "CHANGELOG.md"],
     "engines": {
         "node": ">=20.0.0"
     },
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
     }
 }

packages/fonts/src/__snapshots__/getDefaultFont.test.ts.snap

@@ -1,57 +1,57 @@
-// Bun Snapshot v1, https://goo.gl/fbAQLP
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
 
 exports[`getDefaultFont should return correct object for Latin text 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hjp-Ek-_0ew.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hjp-Ek-_0ew.woff",
 }
 `;
 
 exports[`getDefaultFont should return correct object for Cyrillic text 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZthjp-Ek-_0ewmM.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZthjp-Ek-_0ewmM.woff",
 }
 `;
 
 exports[`getDefaultFont should return correct object for Greek text 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZxhjp-Ek-_0ewmM.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZxhjp-Ek-_0ewmM.woff",
 }
 `;
 
 exports[`getDefaultFont should handle mixed script text 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZthjp-Ek-_0ewmM.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZthjp-Ek-_0ewmM.woff",
 }
 `;
 
 exports[`getDefaultFont should handle different font weights: regular 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hjp-Ek-_0ew.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hjp-Ek-_0ew.woff",
 }
 `;
 
 exports[`getDefaultFont should handle different font weights: bold 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuFuYAZ9hjp-Ek-_0ew.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuFuYAZ9hjp-Ek-_0ew.woff",
 }
 `;
 
 exports[`getDefaultFont should handle different fonts: inter 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hjp-Ek-_0ew.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hjp-Ek-_0ew.woff",
 }
 `;
 
 exports[`getDefaultFont should handle different fonts: roboto 1`] = `
 {
   "font": "Roboto",
-  "url": "https://fonts.gstatic.com/s/roboto/v32/KFOmCnqEu92Fr1Mu4mxMKTU1Kg.woff",
+  "url": "https://fonts.gstatic.com/s/roboto/v49/KFOMCnqEu92Fr1ME7kSn66aGLdTylUAMQXC89YmC2DPNWubEbVmUiAz0klQm_20.woff",
 }
 `;

packages/fonts/tsconfig.build.json

@@ -1,4 +0,0 @@
-{
-    "extends": "./tsconfig.json",
-    "exclude": ["node_modules", "src/**/*.test.ts"]
-}

packages/gitbook/CHANGELOG.md

@@ -1,5 +1,80 @@
 # gitbook
 
+## 0.20.0
+
+### Minor Changes
+
+- 1d92dc1: Update site layout and blocks with container queries and better transitions
+
+### Patch Changes
+
+- 8fdc5c8: Fix webframe height issue
+- 9022d87: Add breadcrumbs to search results
+- 0c01832: SearchInput fixes — Translate Clear button, Bold theme color, "Esc" keyboard shortcut
+- 1d1f0a7: Fix search container shadow
+- 2aa4f2e: Update dropdown menu styling
+- a49781e: Printable collapsed code block
+- 7d6a316: Revert contentref anchor title
+- e27986b: Reword "Everywhere" search scope to "All docs"
+- 758b34d: Move the "Ask <query>" to the bottom of search results if query is not a question
+- 0ae7cfd: Improve AI Search branding
+- f9f8011: Add alt text support to card covers
+- ebbb476: Improve ancestor label in references
+- 1b0613e: Tweak language dropdown styling
+- 3355960: Fix ToggeableLinkItem display
+- c31e564: Fix icon resolution for page group
+- 55c0b03: Support translations and generic variants together
+- 3876f70: Edgeless Assistant window on `depth: flat` sites
+- 683bb8f: Add confirmation to "Copy MCP URL" page action
+- 4534ea8: Implement unique title tags for sections & variants
+- 6d56df7: Treat pages without visible TOC items as `no-toc`
+- 8606f22: Add padding to TOC page group items
+- 3676d64: Update search scope UI
+- c32d449: Fix OpenAPI path display
+- 8ce7322: Add OpenAPI servers selection
+- 2c3066e: Improve OAuth2 scopes handling in OpenAPI
+- 6b1c9fe: Fix opacity of ScrollContainer buttons on bold themes
+- Updated dependencies [b4a021a]
+- Updated dependencies [a512c90]
+- Updated dependencies [df1966d]
+- Updated dependencies [b45feaf]
+- Updated dependencies [10995e0]
+- Updated dependencies [f9f8011]
+- Updated dependencies [10995e0]
+- Updated dependencies [8ce7322]
+- Updated dependencies [2c3066e]
+  - @gitbook/react-openapi@1.5.3
+  - @gitbook/openapi-parser@3.0.5
+  - @gitbook/react-contentkit@0.7.8
+  - @gitbook/browser-types@0.1.3
+  - @gitbook/cache-tags@0.3.4
+  - @gitbook/react-math@0.6.4
+  - @gitbook/colors@0.4.3
+  - @gitbook/embed@0.1.5
+  - @gitbook/fonts@0.1.3
+  - @gitbook/icons@0.3.4
+  - @gitbook/expr@1.2.4
+
+## 0.19.2
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+- 75543b1: Update minimum Node version in .npmrc
+- 511f1cf: Add scroll margin to Expandable
+- Updated dependencies [6142d6b]
+  - @gitbook/emoji-codepoints@0.2.2
+  - @gitbook/react-contentkit@0.7.7
+  - @gitbook/openapi-parser@3.0.4
+  - @gitbook/browser-types@0.1.2
+  - @gitbook/react-openapi@1.5.2
+  - @gitbook/cache-tags@0.3.3
+  - @gitbook/react-math@0.6.3
+  - @gitbook/colors@0.4.2
+  - @gitbook/fonts@0.1.2
+  - @gitbook/icons@0.3.3
+  - @gitbook/expr@1.2.3
+
 ## 0.19.1
 
 ### Patch Changes

packages/gitbook/e2e/customers.spec.ts

@@ -112,11 +112,11 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://adiblar.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
-    {
-        name: 'docs.gradient.network',
-        contentBaseURL: 'https://docs.gradient.network',
-        tests: [{ name: 'Home', url: '/' }],
-    },
+    // {
+    //     name: 'docs.gradient.network',
+    //     contentBaseURL: 'https://docs.gradient.network',
+    //     tests: [{ name: 'Home', url: '/' }],
+    // },
     // {
     //     name: 'mygate-network.gitbook.io',
     //     contentBaseURL: 'https://mygate-network.gitbook.io',
@@ -172,11 +172,6 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://docs.realapp.link',
         tests: [{ name: 'Home', url: '/' }],
     },
-    {
-        name: 'docs.plaza.finance',
-        contentBaseURL: 'https://docs.plaza.finance',
-        tests: [{ name: 'Home', url: '/' }],
-    },
     {
         name: 'docs.publicai.io',
         contentBaseURL: 'https://docs.publicai.io',

packages/gitbook/e2e/internal.spec.ts

@@ -33,6 +33,7 @@ import {
     headerLinks,
     runTestCases,
     waitForCookiesDialog,
+    waitForCoverImages,
     waitForNotFound,
 } from './util';
 
@@ -159,20 +160,20 @@ const searchTestCases: Test[] = [
             await expect(page.getByTestId('ai-chat-input')).toBeFocused();
         },
     },
-    {
-        name: 'Ask - AI Mode: Assistant - Button',
-        url: getCustomizationURL({
-            ai: {
-                mode: CustomizationAIMode.Assistant,
-            },
-        }),
-        screenshot: false,
-        run: async (page) => {
-            await page.getByTestId('ai-chat-button').click();
-            await expect(page.getByTestId('ai-chat')).toBeVisible();
-            await expect(page.getByTestId('ai-chat-input')).toBeFocused();
-        },
-    },
+    // {
+    //     name: 'Ask - AI Mode: Assistant - Button',
+    //     url: getCustomizationURL({
+    //         ai: {
+    //             mode: CustomizationAIMode.Assistant,
+    //         },
+    //     }),
+    //     screenshot: false,
+    //     run: async (page) => {
+    //         await page.getByTestId('ai-chat-button').click();
+    //         await expect(page.getByTestId('ai-chat')).toBeVisible();
+    //         await expect(page.getByTestId('ai-chat-input')).toBeFocused();
+    //     },
+    // },
     {
         name: 'Ask - AI Mode: Assistant - URL query (Initial)',
         url: `${getCustomizationURL({
@@ -228,6 +229,58 @@ const testCases: TestsCase[] = [
                     );
                 },
             },
+            {
+                name: 'Expandable TOC navigation',
+                url: '',
+                run: async (page) => {
+                    await waitForCookiesDialog(page);
+
+                    // Verify "Navigation" link is not visible initially
+                    const navigationLink = page.getByRole('link', { name: 'Navigation' });
+                    await expect(navigationLink).not.toBeVisible();
+
+                    // Find and click the chevron element that is next to "Editor" in the TOC
+                    // It is a span inside the link
+                    const editorChevron = page
+                        .getByRole('link', { name: 'Editor' })
+                        .locator('span');
+                    await editorChevron.click();
+
+                    // Verify "Navigation" link becomes visible after expansion
+                    await expect(navigationLink).toBeVisible();
+                },
+            },
+            {
+                name: 'Expandable nested TOC navigation',
+                url: '',
+                screenshot: false,
+                run: async (page) => {
+                    await waitForCookiesDialog(page);
+
+                    // Verify "Spaces" link is not visible initially
+                    const navigationLink = page.getByRole('link', { name: 'Spaces' });
+                    await expect(navigationLink).not.toBeVisible();
+
+                    // Find and click the chevron element that is next to "Editor" in the TOC
+                    // It is a span inside the link
+                    const editorChevron = page
+                        .getByRole('link', { name: 'Editor' })
+                        .locator('span');
+                    await editorChevron.click();
+
+                    // At this stage the link should still not be visible
+                    await expect(navigationLink).not.toBeVisible();
+
+                    // Then we click 'Content Structure' chevron to expand further
+                    const contentStructureChevron = page
+                        .getByRole('link', { name: 'Content Structure' })
+                        .locator('span');
+                    await contentStructureChevron.click();
+
+                    // Verify "Spaces" link becomes visible after expansion
+                    await expect(navigationLink).toBeVisible();
+                },
+            },
             ...searchTestCases,
             {
                 name: 'Not found',
@@ -285,6 +338,37 @@ const testCases: TestsCase[] = [
                     ).toBeVisible();
                 },
             },
+            {
+                name: 'Switch variant with alternate link in metadata',
+                url: 'rfcs',
+                run: async (page) => {
+                    const spaceDropdown = page
+                        .locator('[data-testid="space-dropdown-button"]')
+                        .locator('visible=true');
+                    await spaceDropdown.click();
+
+                    const variantSelectionDropdown = page.locator(
+                        'css=[data-testid="dropdown-menu"]'
+                    );
+
+                    // Click the variant space called 'Multi-Variants' for which
+                    // there is an alternate link in the current (RFC variant) page metadata
+                    await variantSelectionDropdown
+                        .getByRole('menuitem', {
+                            name: 'Multi-Variants',
+                        })
+                        .click();
+
+                    // It should navigate to the alternate link defined in the metadata (a completely different page)
+                    await page.waitForURL((url) =>
+                        url.pathname.includes('multi-variants/reference/api-reference/pets')
+                    );
+                    // Verify we are on the correct page by checking the h1
+                    await expect(
+                        page.getByRole('heading', { level: 1, name: 'Pets' })
+                    ).toBeVisible();
+                },
+            },
         ],
     },
     {
@@ -727,7 +811,10 @@ const testCases: TestsCase[] = [
                 url: 'blocks/integrations',
                 run: async (page) => {
                     await waitForCookiesDialog(page);
-                    const mermaidIframe = page.locator('iframe[title*="mermaid"]').contentFrame();
+                    const mermaidIframe = page
+                        .locator('iframe[title*="mermaid"]')
+                        .first()
+                        .contentFrame();
                     await expect(mermaidIframe.getByText('Mermaid', { exact: true })).toBeVisible();
                     await expect(mermaidIframe.getByText('Diagram', { exact: true })).toBeVisible();
                 },
@@ -851,7 +938,10 @@ const testCases: TestsCase[] = [
             {
                 name: 'With cover',
                 url: 'page-options/page-with-cover',
-                run: waitForCookiesDialog,
+                run: async (page) => {
+                    await waitForCookiesDialog(page);
+                    await waitForCoverImages(page);
+                },
             },
             {
                 name: 'With cover for dark mode',
@@ -866,12 +956,18 @@ const testCases: TestsCase[] = [
             {
                 name: 'With hero cover',
                 url: 'page-options/page-with-hero-cover',
-                run: waitForCookiesDialog,
+                run: async (page) => {
+                    await waitForCookiesDialog(page);
+                    await waitForCoverImages(page);
+                },
             },
             {
                 name: 'With cover and no TOC',
                 url: 'page-options/page-with-cover-and-no-toc',
-                run: waitForCookiesDialog,
+                run: async (page) => {
+                    await waitForCookiesDialog(page);
+                    await waitForCoverImages(page);
+                },
                 screenshot: {
                     waitForTOCScrolling: false,
                 },
@@ -1454,10 +1550,7 @@ const testCases: TestsCase[] = [
                     locale,
                 },
             }),
-            run: async (page) => {
-                const dialog = page.getByTestId('cookies-dialog');
-                await expect(dialog).toBeVisible();
-            },
+            run: waitForCookiesDialog,
         })),
     },
     {

packages/gitbook/e2e/util.ts

@@ -143,7 +143,10 @@ export const headerLinks: CustomizationHeaderItem[] = [
 
 export async function waitForCookiesDialog(page: Page) {
     const dialog = page.getByTestId('cookies-dialog');
-    await expect(dialog).toBeVisible();
+    await expect(dialog).toBeVisible({
+        // Cookies dialog may take some times to appear
+        timeout: 10_000,
+    });
 }
 
 export async function waitForNotFound(_page: Page, response: Response | null) {
@@ -151,6 +154,13 @@ export async function waitForNotFound(_page: Page, response: Response | null) {
     expect(response?.status()).toBe(404);
 }
 
+export async function waitForCoverImages(page: Page) {
+    // Wait for cover images to exist (not the shimmer placeholder)
+    await expect(page.locator('img[alt="Page cover"]').first()).toBeVisible({
+        timeout: 10_000,
+    });
+}
+
 /**
  * Transform test cases into Playwright tests and run it.
  */

packages/gitbook/open-next.config.ts

@@ -7,7 +7,8 @@ export default {
             converter: 'edge',
             proxyExternalRequest: 'fetch',
             queue: () => import('./openNext/queue/middleware').then((m) => m.default),
-            incrementalCache: () => import('./openNext/incrementalCache').then((m) => m.default),
+            incrementalCache: () =>
+                import('./openNext/incrementalCache/server').then((m) => m.default),
             tagCache: () => import('./openNext/tagCache/middleware').then((m) => m.default),
         },
     },
@@ -18,7 +19,8 @@ export default {
             converter: 'edge',
             proxyExternalRequest: 'fetch',
             queue: () => import('./openNext/queue/middleware').then((m) => m.default),
-            incrementalCache: () => import('./openNext/incrementalCache').then((m) => m.default),
+            incrementalCache: () =>
+                import('./openNext/incrementalCache/middleware').then((m) => m.default),
             tagCache: () => import('./openNext/tagCache/middleware').then((m) => m.default),
         },
     },

packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc

@@ -1,15 +1,13 @@
 {
     "main": "default.js",
     "name": "gitbook-open-v2-server",
+    "keep_names": false,
     "compatibility_date": "2025-04-14",
     "compatibility_flags": [
         "nodejs_compat",
         "allow_importable_env",
         "global_fetch_strictly_public"
     ],
-    "observability": {
-        "enabled": true
-    },
     "vars": {
         "NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE": "true"
     },

packages/gitbook/openNext/customWorkers/doWrangler.jsonc

@@ -2,14 +2,12 @@
     "main": "do.js",
     "name": "gitbook-open-v2-do",
     "compatibility_date": "2025-04-14",
+    "keep_names": false,
     "compatibility_flags": [
         "nodejs_compat",
         "allow_importable_env",
         "global_fetch_strictly_public"
     ],
-    "observability": {
-        "enabled": true
-    },
     "env": {
         "preview": {
             "vars": {

packages/gitbook/openNext/customWorkers/middlewareWrangler.jsonc

@@ -2,6 +2,7 @@
     "main": "middleware.js",
     "name": "gitbook-open-v2",
     "compatibility_date": "2025-04-14",
+    "keep_names": false,
     "compatibility_flags": [
         "nodejs_compat",
         "allow_importable_env",
@@ -11,9 +12,6 @@
         "directory": "../../.open-next/assets",
         "binding": "ASSETS"
     },
-    "observability": {
-        "enabled": true
-    },
     "vars": {
         "NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE": "true"
     },

packages/gitbook/openNext/incrementalCache/incrementalCache.ts

@@ -7,8 +7,6 @@ import type {
 } from '@opennextjs/aws/types/overrides.js';
 import { getCloudflareContext } from '@opennextjs/cloudflare';
 
-import { withRegionalCache } from '@opennextjs/cloudflare/overrides/incremental-cache/regional-cache';
-
 import type { DurableObjectNamespace, Rpc } from '@cloudflare/workers-types';
 
 export const BINDING_NAME = 'NEXT_INC_CACHE_R2_BUCKET';
@@ -23,7 +21,7 @@ export type KeyOptions = {
  * It is very similar to the `R2IncrementalCache` in the `@opennextjs/cloudflare` package, but it has an additional
  * R2WriteBuffer Durable Object to handle writes to R2. Given how we set up cache, we often end up writing to the same key too fast.
  */
-class GitbookIncrementalCache implements IncrementalCache {
+export class GitbookIncrementalCache implements IncrementalCache {
     name = 'GitbookIncrementalCache';
 
     async get<CacheType extends CacheEntryType = 'cache'>(
@@ -137,12 +135,3 @@ class GitbookIncrementalCache implements IncrementalCache {
         );
     }
 }
-
-export default withRegionalCache(new GitbookIncrementalCache(), {
-    mode: 'long-lived',
-    // We can do it because we use our own logic to invalidate the cache
-    bypassTagCacheOnCacheHit: true,
-    defaultLongLivedTtlSec: 60 * 60 * 24 /* 24 hours */,
-    // We don't want to update the cache entry on every cache hit
-    shouldLazilyUpdateOnCacheHit: false,
-});

packages/gitbook/openNext/incrementalCache/middleware.ts

@@ -0,0 +1,11 @@
+import { withRegionalCache } from '@opennextjs/cloudflare/overrides/incremental-cache/regional-cache';
+import { GitbookIncrementalCache } from './incrementalCache';
+
+export default withRegionalCache(new GitbookIncrementalCache(), {
+    mode: 'long-lived',
+    // We can do it because we use our own logic to invalidate the cache
+    bypassTagCacheOnCacheHit: true,
+    defaultLongLivedTtlSec: 60 * 60 * 24 /* 24 hours */,
+    // We don't want to update the cache entry on every cache hit
+    shouldLazilyUpdateOnCacheHit: false,
+});

packages/gitbook/openNext/incrementalCache/server.ts

@@ -0,0 +1,12 @@
+import { withRegionalCache } from '@opennextjs/cloudflare/overrides/incremental-cache/regional-cache';
+import { GitbookIncrementalCache } from './incrementalCache';
+
+export default withRegionalCache(new GitbookIncrementalCache(), {
+    mode: 'long-lived',
+    // Because of a race condition, the middleware may have populated the cache entry before `cache.match` had time to run on the server.
+    // TODO: We should bypass the incremental cache entirely when the interceptor has caught the request. Should be done in OpenNext.
+    bypassTagCacheOnCacheHit: false,
+    defaultLongLivedTtlSec: 60 * 60 * 24 /* 24 hours */,
+    // We don't want to update the cache entry on every cache hit
+    shouldLazilyUpdateOnCacheHit: false,
+});

packages/gitbook/package.json

@@ -1,22 +1,25 @@
 {
     "name": "gitbook",
-    "version": "0.19.1",
+    "version": "0.20.0",
     "private": true,
     "dependencies": {
+        "@cloudflare/workers-types": "^4.20251011.0",
         "@gitbook/api": "catalog:",
         "@gitbook/browser-types": "workspace:*",
         "@gitbook/cache-tags": "workspace:*",
         "@gitbook/colors": "workspace:*",
         "@gitbook/emoji-codepoints": "workspace:*",
         "@gitbook/expr": "workspace:*",
+        "@gitbook/embed": "workspace:*",
         "@gitbook/fonts": "workspace:*",
         "@gitbook/icons": "workspace:*",
         "@gitbook/openapi-parser": "workspace:*",
         "@gitbook/react-contentkit": "workspace:*",
         "@gitbook/react-math": "workspace:*",
         "@gitbook/react-openapi": "workspace:*",
-        "@modelcontextprotocol/sdk": "^1.17.5",
-        "@opennextjs/cloudflare": "^1.9.2",
+        "@modelcontextprotocol/sdk": "1.17.5",
+        "@opennextjs/aws": "^3.8.5",
+        "@opennextjs/cloudflare": "^1.11.0",
         "@radix-ui/react-checkbox": "^1.0.4",
         "@radix-ui/react-dropdown-menu": "^2.1.12",
         "@radix-ui/react-hover-card": "^1.1.15",
@@ -28,19 +31,15 @@
         "@tailwindcss/typography": "^0.5.16",
         "@tusbar/cache-control": "^1.0.2",
         "ai": "^4.2.2",
-        "assert-never": "^1.2.1",
+        "assert-never": "catalog:",
         "bidc": "catalog:",
-        "bun-types": "^1.1.20",
-        "classnames": "^2.5.1",
+        "classnames": "catalog:",
         "direction": "^2.0.1",
         "event-iterator": "^2.0.0",
-        "framer-motion": "^10.16.14",
         "image-size": "^2.0.2",
         "js-cookie": "^3.0.5",
         "jsontoxml": "^1.0.1",
         "jwt-decode": "^4.0.0",
-        "katex": "^0.16.9",
-        "mathjax": "^3.2.2",
         "mcp-handler": "^1.0.2",
         "mdast-util-from-markdown": "^2.0.2",
         "mdast-util-frontmatter": "^2.0.1",
@@ -49,7 +48,7 @@
         "memoizee": "^0.4.17",
         "micromark-extension-frontmatter": "^2.0.0",
         "micromark-extension-gfm": "^3.0.0",
-        "motion": "^12.23.12",
+        "motion": "^12.23.24",
         "next": "15.4.0",
         "next-themes": "^0.4.6",
         "nuqs": "^2.2.3",
@@ -58,6 +57,8 @@
         "openapi-types": "^12.1.3",
         "p-map": "^7.0.3",
         "quick-lru": "^7.0.1",
+        "react": "catalog:",
+        "react-dom": "catalog:",
         "react-hotkeys-hook": "^4.4.1",
         "rehype-sanitize": "^6.0.0",
         "rehype-stringify": "^10.0.1",
@@ -73,7 +74,7 @@
         "unist-util-remove": "^4.0.0",
         "unist-util-visit": "^5.0.0",
         "url-join": "^5.0.0",
-        "usehooks-ts": "^3.1.0",
+        "usehooks-ts": "catalog:",
         "warn-once": "^0.1.1",
         "zod": "^3",
         "zustand": "^5.0.3"
@@ -81,6 +82,7 @@
     "devDependencies": {
         "@argos-ci/playwright": "^5.0.9",
         "@playwright/test": "^1.54.2",
+        "@scalar/api-client-react": "catalog:",
         "@tailwindcss/postcss": "^4.1.11",
         "@types/js-cookie": "^3.0.6",
         "@types/jsontoxml": "^1.0.5",
@@ -89,9 +91,10 @@
         "@types/node": "^20",
         "@types/object-hash": "^3.0.6",
         "@types/parse-cache-control": "^1.0.4",
-        "@types/react": "18.3.13",
-        "@types/react-dom": "18.3.1",
+        "@types/react": "catalog:",
+        "@types/react-dom": "catalog:",
         "@types/rison": "^0.0.9",
+        "bun-types": "catalog:",
         "deepmerge": "^4.3.1",
         "env-cmd": "^10.1.0",
         "jsonwebtoken": "^9.0.2",
@@ -99,8 +102,9 @@
         "stylelint": "^16.16.0",
         "tailwindcss": "^4.1.11",
         "ts-essentials": "^10.0.1",
-        "typescript": "^5.5.3",
-        "vercel": "^39.3.0"
+        "typescript": "catalog:",
+        "vercel": "^39.3.0",
+        "wrangler": "^4.43.0"
     },
     "scripts": {
         "generate": "./scripts/generate.sh",

packages/gitbook/src/app/utils.ts

@@ -19,7 +19,7 @@ export type RouteLayoutParams = {
 };
 
 export type RouteParams = RouteLayoutParams & {
-    pagePath: string;
+    pagePath?: string[];
 };
 
 /**
@@ -80,8 +80,10 @@ export async function getDynamicSiteContext(params: RouteLayoutParams) {
  * Get the decoded page path from the params.
  */
 export function getPagePathFromParams(params: RouteParams) {
-    const decoded = decodeURIComponent(params.pagePath);
-    return decoded;
+    if (!params.pagePath || params.pagePath.length === 0) {
+        return '';
+    }
+    return params.pagePath.map((part) => decodeURIComponent(part)).join('/');
 }
 
 function getSiteURLFromParams(params: RouteLayoutParams) {

packages/gitbook/src/components/AI/useAI.tsx

@@ -1,14 +1,14 @@
 'use client';
 
 import { CustomizationAIMode } from '@gitbook/api';
-import { Icon, type IconName, IconStyle } from '@gitbook/icons';
+import { Icon, type IconName } from '@gitbook/icons';
 import * as React from 'react';
 import type { ReactNode } from 'react';
 
 import { tString, useLanguage } from '@/intl/client';
 import type { GitBookAssistant } from '@gitbook/browser-types';
 import { useAIChatController, useAIChatState } from '.';
-import { AIChatIcon, getAIChatName } from '../AIChat';
+import { AIChatIcon, AISearchIcon, getAIChatName } from '../AIChat';
 import { useIntegrationAssistants } from '../Integrations';
 import { useSearch } from '../Search/useSearch';
 
@@ -104,16 +104,7 @@ export function useAI(): AIContext {
         assistants.push({
             id: 'gitbook-ai-search',
             label: tString(language, 'ai_chat_context_badge'),
-            icon: (
-                <div className="relative">
-                    <Icon icon="search" className="size-4" />
-                    <Icon
-                        icon="sparkle"
-                        iconStyle={IconStyle.Solid}
-                        className="absolute top-[2.5px] left-[2.6px] size-2"
-                    />
-                </div>
-            ),
+            icon: <AISearchIcon />,
             open: (query?: string) => {
                 if (query) {
                     setSearchState((prev) =>

packages/gitbook/src/components/AIChat/AIChat.tsx

@@ -2,6 +2,7 @@
 
 import { t, tString, useLanguage } from '@/intl/client';
 import type { TranslationLanguage } from '@/intl/translations';
+import { tcls } from '@/lib/tailwind';
 import { Icon } from '@gitbook/icons';
 import React from 'react';
 import { useHotkeys } from 'react-hotkeys-hook';
@@ -65,16 +66,17 @@ export function AIChat(props: { trademark: boolean }) {
         }
     }, [chat.opened, trackEvent]);
 
-    if (!chat.opened) {
-        return null;
-    }
-
     return (
         <div
             data-testid="ai-chat"
-            className="ai-chat inset-y-0 right-0 z-40 mx-auto flex max-w-3xl animate-present scroll-mt-36 px-4 py-4 transition-all duration-300 sm:px-6 lg:fixed lg:w-80 lg:animate-enter-from-right lg:pr-4 lg:pl-0 xl:w-96"
+            className={tcls(
+                'ai-chat inset-y-0 right-0 z-40 mx-auto flex max-w-3xl scroll-mt-36 px-4 py-4 transition-[width,opacity,margin,display] transition-discrete duration-300 sm:px-6 lg:fixed lg:w-80 depth-flat:lg:p-0 lg:pr-4 lg:pl-0 xl:w-96',
+                chat.opened
+                    ? 'lg:starting:ml-0 lg:starting:w-0 lg:starting:opacity-0'
+                    : 'hidden lg:ml-0 lg:w-0! lg:opacity-0'
+            )}
         >
-            <EmbeddableFrame className="relative circular-corners:rounded-3xl rounded-corners:rounded-md depth-subtle:shadow-lg shadow-tint ring-1 ring-tint-subtle">
+            <EmbeddableFrame className="relative shrink-0 circular-corners:rounded-3xl rounded-corners:rounded-md border border-tint-subtle depth-subtle:shadow-lg shadow-tint transition-all duration-300 lg:w-76 depth-flat:lg:rounded-none depth-flat:lg:border-y-0 depth-flat:lg:border-r-0 xl:w-92">
                 <EmbeddableFrameHeader>
                     <AIChatDynamicIcon trademark={trademark} />
                     <EmbeddableFrameHeaderMain>

packages/gitbook/src/components/AIChat/AIChatButton.tsx

@@ -23,7 +23,7 @@ export function AIChatButton(props: {
             iconOnly={!showLabel}
             size="medium"
             variant="header"
-            className="h-9 px-2.5 max-md:[&_.button-content]:hidden"
+            className="h-9 px-2.5 @max-2xl:[&_.button-content]:hidden"
             label={
                 <div className="flex items-center gap-2">
                     {t(language, 'ai_chat_ask', assistant.label)}

packages/gitbook/src/components/AIChat/AIChatIcon.tsx

@@ -1,5 +1,5 @@
 import { tcls } from '@/lib/tailwind';
-import { Icon } from '@gitbook/icons';
+import { Icon, IconStyle } from '@gitbook/icons';
 import type React from 'react';
 
 interface AIChatIconProps extends React.SVGProps<SVGSVGElement> {
@@ -9,17 +9,18 @@ interface AIChatIconProps extends React.SVGProps<SVGSVGElement> {
     trademark?: boolean;
 }
 
-export const AIChatIcon = ({
+export function AIChatIcon({
     className = 'size-4',
     size,
     trademark = true,
     state = 'default',
     ...props
-}: AIChatIconProps) => {
+}: AIChatIconProps) {
     if (!trademark) {
         return (
             <Icon
                 icon="sparkle"
+                {...props}
                 className={tcls(
                     className,
                     (state === 'thinking' || state === 'working') &&
@@ -163,4 +164,36 @@ export const AIChatIcon = ({
             </g>
         </svg>
     );
-};
+}
+
+export function AISearchIcon({
+    className = 'size-4',
+    state = 'default',
+}: Pick<AIChatIconProps, 'className' | 'state'>) {
+    return (
+        <div
+            className={tcls(
+                'relative',
+                state === 'intro' && 'animate-[fadeIn_1s_both,orbit_1s_cubic-bezier(0.16,1,0.3,1)]',
+                state === 'thinking' || state === 'working'
+                    ? 'animate-[fadeIn_1s_both,orbit_1s_ease-out,orbit_2s_1s_infinite_forwards_linear]'
+                    : ''
+            )}
+        >
+            <Icon icon="search" className={className} />
+            <Icon
+                icon="sparkle"
+                iconStyle={IconStyle.Solid}
+                className={tcls(
+                    'absolute top-[15.7%] left-[15.6%] size-[50%]',
+                    state === 'thinking' || state === 'working'
+                        ? 'animate-[spin_2s_infinite_forwards_cubic-bezier(0.16,1,0.3,1)]'
+                        : '',
+                    state === 'intro'
+                        ? 'animate-[spin_2s_.5s_forwards_cubic-bezier(0.16,1,0.3,1)]'
+                        : ''
+                )}
+            />
+        </div>
+    );
+}

packages/gitbook/src/components/AIChat/AIChatMessages.tsx

@@ -11,7 +11,7 @@ import { AIChatFollowupSuggestions } from './AiChatFollowupSuggestions';
 export function AIChatMessages(props: {
     chat: AIChatState;
     chatController: AIChatController;
-    lastUserMessageRef?: React.RefObject<HTMLDivElement>;
+    lastUserMessageRef?: React.RefObject<HTMLDivElement | null>;
 }) {
     const { chat, chatController, lastUserMessageRef } = props;
 
@@ -81,11 +81,19 @@ export function AIChatMessages(props: {
     );
 }
 
-function HoldMessage() {
+export function HoldMessage({
+    breakLines = false,
+    className = '',
+}: { breakLines?: boolean; className?: string }) {
     const language = useLanguage();
 
     return (
-        <div className="animate-[heightIn_500ms_4500ms_ease_both] py-2 text-tint-subtle">
+        <div
+            className={tcls(
+                'animate-[heightIn_500ms_4500ms_ease_both] overflow-hidden py-2 text-tint-subtle',
+                className
+            )}
+        >
             {tString(language, 'ai_chat_hold_message_1')
                 .split(' ')
                 .map((word, index) => (
@@ -99,6 +107,7 @@ function HoldMessage() {
                         {word}{' '}
                     </span>
                 ))}
+            {breakLines ? <br /> : null}
             {tString(language, 'ai_chat_hold_message_2')
                 .split(' ')
                 .map((word, index) => (

packages/gitbook/src/components/AdminToolbar/AdminToolbarClient.tsx

@@ -167,10 +167,10 @@ function ChangeRequestToolbar(props: ToolbarViewProps) {
                     icon="comment"
                 />
 
-                {/* Open production site */}
+                {/* Open published/live site */}
                 {site.urls.published ? (
                     <ToolbarButton
-                        title="Open production site"
+                        title="Open live site"
                         href={getToolbarHref({
                             href: site.urls.published,
                             siteId: site.id,
@@ -249,7 +249,7 @@ function RevisionToolbar(props: ToolbarViewProps) {
                 />
                 {site.urls.published ? (
                     <ToolbarButton
-                        title="Open production site"
+                        title="Open live site"
                         href={getToolbarHref({
                             href: site.urls.published,
                             siteId: site.id,

packages/gitbook/src/components/AdminToolbar/HideToolbarButton.tsx

@@ -35,6 +35,7 @@ export function HideToolbarButton(props: HideToolbarButtonProps) {
         }
         setOpen(false);
     };
+    // @ts-expect-error wrong type for ref
     useOnClickOutside(ref, handleClickOutsideArcMenu);
 
     // Close arc menu on scroll

packages/gitbook/src/components/AdminToolbar/Toolbar.tsx

@@ -6,7 +6,7 @@ import {
     useReducedMotion,
     useSpring,
 } from 'motion/react';
-import React from 'react';
+import React, { isValidElement } from 'react';
 import { AnimatedLogo } from './AnimatedLogo';
 import { useToolbarControls } from './ToolbarControlsContext';
 
@@ -291,6 +291,10 @@ function ToolbarButtonWrapper(props: {
         x: springX,
     };
 
+    if (!isValidElement<{ motionValues: typeof motionValues }>(child)) {
+        return null;
+    }
+
     return React.cloneElement(child, {
         motionValues,
     });

packages/gitbook/src/components/AdminToolbar/useMagnificationEffect.ts

@@ -136,7 +136,7 @@ const calculateSpacing = (
 
 export function useMagnificationEffect(props: {
     childrenCount: number;
-    containerRef: React.RefObject<HTMLElement>;
+    containerRef: React.RefObject<HTMLElement | null>;
     config?: MagnificationConfig;
 }) {
     const { childrenCount, containerRef, config } = props;

packages/gitbook/src/components/DocumentView/Block.tsx

@@ -6,6 +6,7 @@ import {
     SkeletonImage,
     SkeletonParagraph,
     SkeletonSmall,
+    SkeletonUpdate,
 } from '@/components/primitives';
 import type { ClassValue } from '@/lib/tailwind';
 
@@ -34,6 +35,8 @@ import { Stepper } from './Stepper';
 import { StepperStep } from './StepperStep';
 import { Table } from './Table';
 import { Tabs } from './Tabs';
+import { Update } from './Update';
+import { Updates } from './Updates';
 
 export interface BlockProps<Block extends DocumentBlock> extends DocumentContextProps {
     block: Block;
@@ -105,6 +108,10 @@ export function Block<T extends DocumentBlock>(props: BlockProps<T>) {
                 return <Stepper {...props} block={block} />;
             case 'stepper-step':
                 return <StepperStep {...props} block={block} />;
+            case 'updates':
+                return <Updates {...props} block={block} />;
+            case 'update':
+                return <Update {...props} block={block} />;
             case 'if':
                 // If block should be processed by the API.
                 return null;
@@ -165,10 +172,13 @@ export function BlockSkeleton(props: { block: DocumentBlock; style: ClassValue }
         case 'images':
         case 'drawing':
             return <SkeletonImage id={id} style={style} />;
+        case 'updates':
+            return <SkeletonUpdate id={id} style={style} />;
         case 'image':
         case 'code-line':
         case 'tabs-item':
         case 'column':
+        case 'update':
             throw new Error(`Blocks (${block.type}) should be directly rendered by parent`);
         default:
             return nullIfNever(block);

packages/gitbook/src/components/DocumentView/BlockContentRef.tsx

@@ -1,9 +1,18 @@
-import { type DocumentBlockContentRef, SiteInsightsLinkPosition } from '@gitbook/api';
+import {
+    type ContentRef,
+    type DocumentBlockContentRef,
+    SiteInsightsLinkPosition,
+} from '@gitbook/api';
 
-import { Card } from '@/components/primitives';
-import { type ResolvedContentRef, resolveContentRef } from '@/lib/references';
+import { Card, type CardProps } from '@/components/primitives';
+import {
+    type ResolvedContentRef,
+    resolveContentRef,
+    resolveContentRefFallback,
+} from '@/lib/references';
 
 import type { BlockProps } from './Block';
+import { NotFoundRefHoverCard } from './NotFoundRefHoverCard';
 
 export async function BlockContentRef(props: BlockProps<DocumentBlockContentRef>) {
     const { block, context, style } = props;
@@ -16,51 +25,45 @@ export async function BlockContentRef(props: BlockProps<DocumentBlockContentRef>
         : null;
 
     if (!resolved) {
-        return null;
+        const fallback = resolveContentRefFallback(block.data.ref);
+        if (!fallback) {
+            return null;
+        }
+        return (
+            <NotFoundRefHoverCard context={context}>
+                <BlockContentRefCard
+                    contentRef={block.data.ref}
+                    resolved={fallback}
+                    style={style}
+                />
+            </NotFoundRefHoverCard>
+        );
     }
 
-    const isContentInOtherSpace =
-        context.contentContext?.space &&
-        'space' in block.data.ref &&
-        context.contentContext.space.id !== block.data.ref.space;
-    const kind = block?.data?.ref?.kind;
-    if ((resolved.active && kind === 'space') || isContentInOtherSpace) {
-        return <SpaceRefCard {...props} resolved={resolved} />;
-    }
+    return <BlockContentRefCard contentRef={block.data.ref} resolved={resolved} style={style} />;
+}
 
+function BlockContentRefCard(
+    props: {
+        resolved: ResolvedContentRef;
+        contentRef: ContentRef;
+    } & Omit<CardProps, 'href' | 'title'>
+) {
+    const { ref, resolved, contentRef, ...rest } = props;
     return (
         <Card
+            ref={ref}
             leadingIcon={resolved.icon ? resolved.icon : null}
             href={resolved.href}
             title={resolved.text}
-            style={style}
             insights={{
                 type: 'link_click',
                 link: {
-                    target: block.data.ref,
+                    target: contentRef,
                     position: SiteInsightsLinkPosition.Content,
                 },
             }}
-        />
-    );
-}
-
-async function SpaceRefCard(
-    props: { resolved: ResolvedContentRef } & BlockProps<DocumentBlockContentRef>
-) {
-    const { context, style, resolved } = props;
-    const spaceId = context.contentContext?.space.id;
-
-    if (!spaceId) {
-        return null;
-    }
-
-    return (
-        <Card
-            href={resolved.href}
-            title={resolved.text}
-            postTitle={resolved.subText}
-            style={style}
+            {...rest}
         />
     );
 }

packages/gitbook/src/components/DocumentView/Blocks.tsx

@@ -51,11 +51,13 @@ type UnwrappedBlocksProps<TBlock extends DocumentBlock> = DocumentContextProps &
  * Ideally we'd rely on the block type to determine if it can be full width, but
  * the block's `fullWidth` property does not differentiate between `undefined` and `false`.
  * So instead we hardcode a list of blocks that can be full width. */
-const FULL_WIDTH_BLOCKS = [
+const FULL_WIDTH_BLOCKS: DocumentBlock['type'][] = [
     'table',
     'tabs',
     'integration',
-    'openapi',
+    'openapi-operation',
+    'openapi-schemas',
+    'openapi-webhook',
     'images',
     'embed',
     'columns',
@@ -64,6 +66,8 @@ const FULL_WIDTH_BLOCKS = [
     'hint',
 ];
 
+const LIST_BLOCKS: DocumentBlock['type'][] = ['list-ordered', 'list-tasks', 'list-unordered'];
+
 /**
  * Renders a list of blocks without a wrapper element.
  */
@@ -85,10 +89,11 @@ export function UnwrappedBlocks<TBlock extends DocumentBlock>(props: UnwrappedBl
                 key={node.key || `${node.type}-${index}`}
                 block={node}
                 style={[
-                    'mx-auto page-width-wide:mx-0 w-full decoration-primary/6 print:break-inside-avoid',
+                    'mx-auto page-width-wide:mx-0 w-full decoration-primary/6',
                     node.data && 'fullWidth' in node.data && node.data.fullWidth
                         ? 'max-w-screen-xl'
                         : 'max-w-3xl',
+                    !LIST_BLOCKS.includes(node.type) && 'print:break-inside-avoid',
                     FULL_WIDTH_BLOCKS.includes(node.type) && 'page-width-wide:max-w-full',
                     blockStyle,
                 ]}

packages/gitbook/src/components/DocumentView/CodeBlock/ClientCodeBlock.tsx

@@ -1,11 +1,14 @@
 'use client';
 
 import type { DocumentBlockCode } from '@gitbook/api';
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
 
 import { useAdaptiveVisitor } from '@/components/Adaptive';
 import { useInViewportListener } from '@/components/hooks/useInViewportListener';
 import { useScrollListener } from '@/components/hooks/useScrollListener';
+import { Button } from '@/components/primitives';
+import { t, useLanguage } from '@/intl/client';
+import { tcls } from '@/lib/tailwind';
 import { useDebounceCallback } from 'usehooks-ts';
 import type { BlockProps } from '../Block';
 import { type InlineExpressionVariables, useEvaluateInlineExpression } from '../InlineExpression';
@@ -16,14 +19,17 @@ import { plainHighlight } from './plain-highlight';
 type ClientBlockProps = Pick<BlockProps<DocumentBlockCode>, 'block' | 'style'> & {
     inlines: RenderedInline[];
     inlineExprVariables: InlineExpressionVariables;
+    mode: BlockProps<DocumentBlockCode>['context']['mode'];
 };
 
+export const CODE_BLOCK_DEFAULT_COLLAPSED_LINE_COUNT = 10;
+
 /**
  * Render a code-block client-side by loading the highlighter asynchronously.
  * It allows us to defer some load to avoid blocking the rendering of the whole page with block highlighting.
  */
 export function ClientCodeBlock(props: ClientBlockProps) {
-    const { block, style, inlines, inlineExprVariables } = props;
+    const { block, mode, style, inlines, inlineExprVariables } = props;
     const blockRef = useRef<HTMLDivElement>(null);
     const isInViewportRef = useRef(false);
     const [isInViewport, setIsInViewport] = useState(false);
@@ -113,13 +119,84 @@ export function ClientCodeBlock(props: ClientBlockProps) {
         setLines(null);
     }, [isInViewport, block, inlines, evaluateInlineExpression]);
 
-    return (
+    const expandable = block.data.expandable;
+
+    const numberOfLinesOfCode = lines?.length ?? plainLines.length;
+    const collapsedLineCount =
+        block.data.collapsedLineCount || CODE_BLOCK_DEFAULT_COLLAPSED_LINE_COUNT;
+    const isExpandable = Boolean(
+        expandable && mode !== 'print' && numberOfLinesOfCode > collapsedLineCount
+    );
+
+    const codeBlockBodyId = useId();
+
+    const renderer = (
         <CodeBlockRenderer
             ref={blockRef}
             aria-busy={highlighting}
             block={block}
             style={style}
             lines={lines ?? plainLines}
+            id={codeBlockBodyId}
         />
     );
+
+    return isExpandable ? (
+        <CodeBlockExpandable
+            lines={lines ?? plainLines}
+            controls={codeBlockBodyId}
+            collapsedLineCount={collapsedLineCount}
+        >
+            {renderer}
+        </CodeBlockExpandable>
+    ) : (
+        renderer
+    );
+}
+
+function CodeBlockExpandable(props: {
+    children: React.ReactNode;
+    lines: HighlightLine[];
+    collapsedLineCount: number;
+    controls?: string;
+}) {
+    const { children, controls, lines = [], collapsedLineCount } = props;
+    const [isExpanded, setIsExpanded] = useState(false);
+    const language = useLanguage();
+    return (
+        <div className="group/codeblock-expandable relative">
+            <div
+                className={tcls(
+                    isExpanded
+                        ? '[&_pre]:after:opacity-0'
+                        : '[&_pre]:h-[calc(2rem+var(--line-count)*var(--line-height))] [&_pre]:overflow-y-hidden [&_pre]:after:opacity-100',
+                    '[&_pre]:after:pointer-events-none [&_pre]:after:absolute [&_pre]:after:inset-0 [&_pre]:after:z-1 [&_pre]:after:bg-gradient-to-t [&_pre]:after:from-0% [&_pre]:after:from-tint-2 [&_pre]:after:to-70% [&_pre]:after:to-transparent [&_pre]:after:content-[""]'
+                )}
+                style={
+                    {
+                        '--line-count': collapsedLineCount,
+                        '--line-height': '1.25rem',
+                    } as React.CSSProperties
+                }
+            >
+                {children}
+            </div>
+            <div className="pointer-events-none absolute bottom-0 flex w-full justify-center">
+                <Button
+                    icon={isExpanded ? 'chevron-up' : 'chevron-down'}
+                    size="xsmall"
+                    variant="blank"
+                    type="button"
+                    onClick={() => setIsExpanded(!isExpanded)}
+                    className="pointer-events-auto z-1 my-2 text-primary text-sm opacity-0 focus:opacity-11 group-hover/codeblock-expandable:opacity-11"
+                    aria-expanded={isExpanded}
+                    aria-controls={controls}
+                >
+                    {isExpanded
+                        ? t(language, 'code_block_expanded')
+                        : t(language, 'code_block_collapsed', lines.length)}
+                </Button>
+            </div>
+        </div>
+    );
 }

packages/gitbook/src/components/DocumentView/CodeBlock/CodeBlock.tsx

@@ -50,7 +50,7 @@ export async function CodeBlock(props: BlockProps<DocumentBlockCode>) {
             return { inline, body };
         });
 
-    if (!isEstimatedOffscreen && !hasInlineExpression) {
+    if (!isEstimatedOffscreen && !hasInlineExpression && !block.data.expandable) {
         // In v2, we render the code block server-side
         const lines = await highlight(block, richInlines);
         return <CodeBlockRenderer block={block} style={style} lines={lines} />;
@@ -73,6 +73,7 @@ export async function CodeBlock(props: BlockProps<DocumentBlockCode>) {
                 style={style}
                 inlines={richInlines}
                 inlineExprVariables={variables}
+                mode={context.mode}
             />
         </React.Suspense>
     );

packages/gitbook/src/components/DocumentView/CodeBlock/CodeBlockRenderer.tsx

@@ -12,6 +12,7 @@ import type { HighlightLine, HighlightToken } from './highlight';
 type CodeBlockRendererProps = Pick<BlockProps<DocumentBlockCode>, 'block' | 'style'> & {
     lines: HighlightLine[];
     'aria-busy'?: boolean;
+    id?: string;
 };
 
 /**
@@ -23,11 +24,12 @@ export const CodeBlockRenderer = forwardRef(function CodeBlockRenderer(
 ) {
     const { block, style, lines, 'aria-busy': ariaBusy } = props;
 
-    const id = useId();
     const withLineNumbers = Boolean(block.data.lineNumbers) && block.nodes.length > 1;
     const withWrap = block.data.overflow === 'wrap';
     const title = block.data.title;
 
+    const id = useId();
+    const codeId = props.id || id;
     return (
         <div
             ref={ref}
@@ -42,7 +44,7 @@ export const CodeBlockRenderer = forwardRef(function CodeBlockRenderer(
                 ) : null}
             </div>
             <CopyCodeButton
-                codeId={id}
+                codeId={codeId}
                 style="z-2 mt-2 mr-2 self-start justify-self-end leading-none opacity-0 backdrop-blur-md [grid-area:2/1] group-hover/codeblock:opacity-11"
             />
             <pre
@@ -53,7 +55,7 @@ export const CodeBlockRenderer = forwardRef(function CodeBlockRenderer(
                 )}
             >
                 <code
-                    id={id}
+                    id={codeId}
                     className={tcls(
                         'inline-grid min-w-full grid-cols-[auto_1fr] [count-reset:line] print:whitespace-pre-wrap',
                         withWrap && 'whitespace-pre-wrap'

packages/gitbook/src/components/DocumentView/Columns/Columns.tsx

@@ -80,6 +80,7 @@ export function Column(props: {
         <div
             className={tcls(
                 'flex flex-col',
+                '@container/column',
                 (verticalAlignment === VerticalAlignment.Top || !verticalAlignment) &&
                     'justify-start',
                 verticalAlignment === VerticalAlignment.Middle && 'justify-center',

packages/gitbook/src/components/DocumentView/Drawing.tsx

@@ -31,6 +31,7 @@ export async function Drawing(props: BlockProps<DocumentBlockDrawing>) {
                 alt="Drawing"
                 sizes={imageBlockSizes}
                 zoom
+                loading="lazy"
             />
         </Caption>
     );

packages/gitbook/src/components/DocumentView/Embed.tsx

@@ -60,6 +60,7 @@ export async function Embed(props: BlockProps<gitbookAPI.DocumentBlockEmbed>) {
                                 sources={{ light: { src: embed.icon } }}
                                 sizes={[{ width: 20 }]}
                                 resize={context.contentContext.imageResizer}
+                                loading="lazy"
                             />
                         ) : null
                     }

packages/gitbook/src/components/DocumentView/Expandable/Details.tsx

@@ -17,29 +17,34 @@ export function Details(props: {
 }) {
     const { children, id, className } = props;
 
-    const detailsRef = React.useRef<HTMLDetailsElement>(null);
+    const ref = React.useRef<HTMLDetailsElement>(null);
 
     const [openFromHash, setOpenFromHash] = React.useState(false);
 
     const hash = useHash();
+
     /**
      * Open the details element if the url hash refers to the id of the details element
      * or the id of some element contained within the details element.
      */
     React.useEffect(() => {
-        if (!hash || !detailsRef.current) {
+        if (!hash || !ref.current) {
             return;
         }
+
         if (hash === id) {
             setOpenFromHash(true);
+            return;
         }
+
         const activeElement = document.getElementById(hash);
-        setOpenFromHash(Boolean(activeElement && detailsRef.current?.contains(activeElement)));
+        const isOpen = Boolean(activeElement && ref.current.contains(activeElement));
+        setOpenFromHash(isOpen);
     }, [hash, id]);
 
     return (
         <details
-            ref={detailsRef}
+            ref={ref}
             id={id}
             open={props.open || openFromHash}
             className={tcls(

packages/gitbook/src/components/DocumentView/Expandable/Expandable.tsx

@@ -25,7 +25,11 @@ export function Expandable(props: BlockProps<DocumentBlockExpandable>) {
     id = context.getId ? context.getId(id) : id;
 
     return (
-        <Details id={id} open={context.mode === 'print'} className={style}>
+        <Details
+            id={id}
+            open={context.mode === 'print'}
+            className={tcls('scroll-mt-(--content-scroll-margin)', style)}
+        >
             <summary
                 className={tcls(
                     'cursor-pointer',
@@ -47,7 +51,7 @@ export function Expandable(props: BlockProps<DocumentBlockExpandable>) {
                     className={tcls(
                         'inline-block',
                         'size-3',
-                        'mr-2',
+                        'mr-3',
                         'mb-1',
                         'transition-transform',
                         'shrink-0',
@@ -92,7 +96,7 @@ export function Expandable(props: BlockProps<DocumentBlockExpandable>) {
                 document={document}
                 ancestorBlocks={[...ancestorBlocks, block]}
                 context={context}
-                style={['px-10', 'pb-5', 'space-y-4']}
+                style="space-y-4 px-10 pb-5"
             />
         </Details>
     );

packages/gitbook/src/components/DocumentView/File.tsx

@@ -1,10 +1,12 @@
 import { type DocumentBlockFile, SiteInsightsLinkPosition } from '@gitbook/api';
 
+import { t } from '@/intl/translate';
 import { getSimplifiedContentType } from '@/lib/files';
 import { resolveContentRef } from '@/lib/references';
-import { tcls } from '@/lib/tailwind';
 
-import { Link } from '../primitives';
+import { getSpaceLanguage } from '@/intl/server';
+import { Button, Link } from '../primitives';
+import { DownloadButton } from '../primitives/DownloadButton';
 import type { BlockProps } from './Block';
 import { Caption } from './Caption';
 import { FileIcon } from './FileIcon';
@@ -12,67 +14,70 @@ import { FileIcon } from './FileIcon';
 export async function File(props: BlockProps<DocumentBlockFile>) {
     const { block, context } = props;
 
-    const contentRef = context.contentContext
-        ? await resolveContentRef(block.data.ref, context.contentContext)
-        : null;
+    if (!context.contentContext) {
+        return null;
+    }
+
+    const contentRef = await resolveContentRef(block.data.ref, context.contentContext);
     const file = contentRef?.file;
 
     if (!file) {
         return null;
     }
 
+    const language = getSpaceLanguage(context.contentContext);
     const contentType = getSimplifiedContentType(file.contentType);
+    const insights = {
+        type: 'link_click' as const,
+        link: {
+            target: block.data.ref,
+            position: SiteInsightsLinkPosition.Content,
+        },
+    };
 
     return (
         <Caption {...props} withBorder>
-            <Link
-                href={file.downloadURL}
-                download={file.name}
-                insights={{
-                    type: 'link_click',
-                    link: {
-                        target: block.data.ref,
-                        position: SiteInsightsLinkPosition.Content,
-                    },
-                }}
-                className={tcls('group/file', 'flex', 'flex-row', 'items-center', 'px-5', 'py-3')}
-            >
-                <div
-                    className={tcls(
-                        'min-w-14',
-                        'mr-5',
-                        'pr-5',
-                        'flex',
-                        'flex-col',
-                        'items-center',
-                        'gap-1',
-                        'border-r',
-                        'border-tint-subtle'
-                    )}
-                >
-                    <div>
-                        <FileIcon
-                            contentType={contentType}
-                            className={tcls('size-5', 'text-primary')}
-                        />
+            <div className="flex flex-wrap items-center gap-5 px-5 py-3">
+                <div className="flex min-w-14 flex-col items-center gap-1 border-tint-subtle border-r pr-5">
+                    <FileIcon contentType={contentType} className="size-5 text-primary" />
+                    <div className="text-hint text-xs">{getHumanFileSize(file.size)}</div>
+                </div>
+                <div className="min-w-24 flex-1">
+                    <div className="text-base">
+                        <Link
+                            href={file.downloadURL}
+                            target="_blank"
+                            insights={insights}
+                            className="hover:underline"
+                        >
+                            {file.name}
+                        </Link>
                     </div>
-                    <div
-                        className={tcls(
-                            'text-xs',
-                            'text-tint',
-                            'group-hover/file:text-tint-strong'
-                        )}
+                    <div className="text-sm opacity-9 dark:opacity-8">{contentType}</div>
+                </div>
+                <div className="flex shrink-0 flex-wrap gap-2">
+                    <DownloadButton
+                        icon="download"
+                        size="xsmall"
+                        variant="secondary"
+                        downloadUrl={file.downloadURL}
+                        filename={file.name}
+                        insights={insights}
                     >
-                        {getHumanFileSize(file.size)}
-                    </div>
+                        {t(language, 'download')}
+                    </DownloadButton>
+                    <Button
+                        icon="arrow-up-right-from-square"
+                        size="xsmall"
+                        variant="secondary"
+                        href={file.downloadURL}
+                        target="_blank"
+                        insights={insights}
+                    >
+                        {t(language, 'open')}
+                    </Button>
                 </div>
-                <div>
-                    <div className={tcls('text-base')}>{file.name}</div>
-                    <div className={tcls('text-sm', 'opacity-9', 'dark:opacity-8')}>
-                        {contentType}
-                    </div>
-                </div>
-            </Link>
+            </div>
         </Caption>
     );
 }

packages/gitbook/src/components/DocumentView/FileIcon.tsx

@@ -9,7 +9,7 @@ export function FileIcon(props: { contentType: SimplifiedFileType | null; classN
     const { contentType, className } = props;
 
     switch (contentType) {
-        case 'pdf':
+        case 'PDF':
             return <Icon icon="file-pdf" className={className} />;
         case 'image':
             return <Icon icon="file-image" className={className} />;

packages/gitbook/src/components/DocumentView/HashLinkButton.tsx

@@ -1,6 +1,7 @@
 import { type ClassValue, tcls } from '@/lib/tailwind';
 import type { DocumentBlockHeading, DocumentBlockTabs } from '@gitbook/api';
 import { Icon } from '@gitbook/icons';
+import { Link } from '../primitives';
 import { getBlockTextStyle } from './spacing';
 
 /**
@@ -28,6 +29,8 @@ export function HashLinkButton(props: {
                 'h-[1em]',
                 'border-0',
                 'opacity-0',
+                'site-background',
+                'rounded',
                 'group-hover/hash:opacity-[0]',
                 'group-focus/hash:opacity-[0]',
                 'md:group-hover/hash:opacity-[1]',
@@ -35,10 +38,10 @@ export function HashLinkButton(props: {
                 className
             )}
         >
-            <a
+            <Link
                 href={`#${id}`}
                 aria-label={label}
-                className={tcls('inline-flex', 'h-full', 'items-start', textStyle.lineHeight)}
+                className={tcls('inline-flex h-full items-start', textStyle.lineHeight)}
             >
                 <Icon
                     icon="hashtag"
@@ -52,7 +55,7 @@ export function HashLinkButton(props: {
                         iconClassName
                     )}
                 />
-            </a>
+            </Link>
         </div>
     );
 }

packages/gitbook/src/components/DocumentView/Heading.tsx

@@ -36,7 +36,10 @@ export function Heading(props: BlockProps<DocumentBlockHeading>) {
             <HashLinkButton
                 id={id}
                 block={block}
-                className={tcls('-ml-6', 'pr-2')}
+                className={tcls(
+                    '-ml-6 pr-2',
+                    '[.flip-heading-hash_&]:order-last [.flip-heading-hash_&]:ml-1 [.flip-heading-hash_&]:pl-2'
+                )}
                 iconClassName={tcls('size-4')}
                 label="Direct link to heading"
             />

packages/gitbook/src/components/DocumentView/Hint.tsx

@@ -65,9 +65,9 @@ export function Hint({
             {hasHeading ? (
                 <Block
                     style={tcls(
-                        'w-full items-start py-4! pl-3 text-[1em] *:flex-none',
+                        'w-full items-start py-4! pl-3 text-[1em]! *:flex-none',
                         // Heading hash styles
-                        'flip-heading-hash pr-8',
+                        'flip-heading-hash pr-8 [&_.hash]:bg-transparent',
                         hintStyle.header
                     )}
                     ancestorBlocks={[...ancestorBlocks, block]}

packages/gitbook/src/components/DocumentView/Images.tsx

@@ -19,34 +19,42 @@ export function Images(props: BlockProps<DocumentBlockImages>) {
             className={tcls(
                 style,
                 'flex',
-                'flex-row',
-                'gap-3',
+                'w-full',
                 align === 'center' && 'justify-center',
                 align === 'right' && 'justify-end',
-                align === 'left' && 'justify-start',
-                hasMultipleImages && ['grid', 'grid-flow-col'],
-                withFrame && [
-                    'rounded-2xl',
-                    'border',
-                    'border-[rgb(234,235,238)]',
-                    'dark:border-[rgb(45,50,58)]',
-                    'relative',
-                    'overflow-hidden',
-                ]
+                align === 'left' && 'justify-start'
             )}
         >
-            {block.nodes.map((node: any, _i: number) => (
-                <ImageBlock
-                    key={node.key}
-                    block={node}
-                    document={document}
-                    style={[]}
-                    siblings={block.nodes.length}
-                    context={context}
-                    isEstimatedOffscreen={isEstimatedOffscreen}
-                    withFrame={withFrame}
-                />
-            ))}
+            <div
+                className={tcls(
+                    'flex',
+                    'flex-row',
+                    'gap-3',
+                    hasMultipleImages && ['grid', 'grid-flow-col'],
+                    withFrame && [
+                        'rounded-2xl',
+                        'border',
+                        'border-[rgb(234,235,238)]',
+                        'dark:border-[rgb(45,50,58)]',
+                        'relative',
+                        'overflow-hidden',
+                        'w-fit',
+                    ]
+                )}
+            >
+                {block.nodes.map((node: any, _i: number) => (
+                    <ImageBlock
+                        key={node.key}
+                        block={node}
+                        document={document}
+                        style={[]}
+                        siblings={block.nodes.length}
+                        context={context}
+                        isEstimatedOffscreen={isEstimatedOffscreen}
+                        withFrame={withFrame}
+                    />
+                ))}
+            </div>
         </div>
     );
 }
@@ -135,8 +143,7 @@ async function ImageBlock(props: {
                               }
                             : null,
                     }}
-                    priority={isEstimatedOffscreen ? 'lazy' : 'high'}
-                    preload
+                    loading={isEstimatedOffscreen ? 'lazy' : 'eager'}
                     zoom
                     inlineStyle={{
                         maxWidth: '100%',

packages/gitbook/src/components/DocumentView/InlineButton.tsx

@@ -1,31 +1,29 @@
-import { resolveContentRef } from '@/lib/references';
+import { resolveContentRef, resolveContentRefFallback } from '@/lib/references';
 import * as api from '@gitbook/api';
 import type { IconName } from '@gitbook/icons';
 import { Button } from '../primitives';
 import type { InlineProps } from './Inline';
+import { NotFoundRefHoverCard } from './NotFoundRefHoverCard';
 
 export async function InlineButton(props: InlineProps<api.DocumentInlineButton>) {
     const { inline, context } = props;
 
-    if (!context.contentContext) {
-        throw new Error('InlineButton requires a contentContext');
-    }
+    const resolved = context.contentContext
+        ? await resolveContentRef(inline.data.ref, context.contentContext)
+        : null;
 
-    const resolved = await resolveContentRef(inline.data.ref, context.contentContext);
+    const href = resolved?.href ?? resolveContentRefFallback(inline.data.ref)?.href;
 
-    if (!resolved) {
-        return null;
-    }
-
-    return (
+    const inlineElement = (
         // Set the leading to have some vertical space between adjacent buttons
         <span className="inline-button leading-12 [&:has(+.inline-button)]:mr-2">
             <Button
-                href={resolved.href}
+                href={href}
                 label={inline.data.label}
                 // TODO: use a variant specifically for user-defined buttons.
                 variant={inline.data.kind}
                 className="leading-normal"
+                disabled={href === undefined}
                 icon={inline.data.icon as IconName | undefined}
                 insights={{
                     type: 'link_click',
@@ -37,4 +35,10 @@ export async function InlineButton(props: InlineProps<api.DocumentInlineButton>)
             />
         </span>
     );
+
+    if (!resolved) {
+        return <NotFoundRefHoverCard context={context}>{inlineElement}</NotFoundRefHoverCard>;
+    }
+
+    return inlineElement;
 }

packages/gitbook/src/components/DocumentView/InlineIcon.tsx

@@ -1,4 +1,4 @@
-import type { DocumentInlineIcon, DocumentMarkColor } from '@gitbook/api';
+import type { DocumentInlineIcon } from '@gitbook/api';
 
 import { tcls } from '@/lib/tailwind';
 import { Icon, type IconName } from '@gitbook/icons';
@@ -7,16 +7,11 @@ import { textColorToStyle } from './utils/colors';
 
 export async function InlineIcon(props: InlineProps<DocumentInlineIcon>) {
     const { inline } = props;
-    const icon = inline.data.icon as IconName;
-    // @ts-expect-error remove this comment once API is updated
-    const color = inline.data.color
-        ? // @ts-expect-error remove "as DocumentMarkColor['data']['text']" once API is updated
-          (inline.data.color as DocumentMarkColor['data']['text'])
-        : undefined;
+    const { color, icon } = inline.data;
 
     return (
         <Icon
-            icon={icon}
+            icon={icon as IconName}
             className={tcls('inline size-[1em]', color ? textColorToStyle[color] : null)}
         />
     );

packages/gitbook/src/components/DocumentView/InlineImage.tsx

@@ -49,8 +49,7 @@ export async function InlineImage(props: InlineProps<DocumentInlineImage>) {
                           }
                         : null,
                 }}
-                priority="lazy"
-                preload
+                loading="lazy"
                 style={[size === 'line' ? ['max-h-lh', 'h-lh', 'w-auto'] : null]}
                 inline
                 zoom={!isInLink}

packages/gitbook/src/components/DocumentView/InlineLink/InlineLink.tsx

@@ -1,12 +1,17 @@
-import { type DocumentInlineLink, SiteInsightsLinkPosition } from '@gitbook/api';
+import { type ContentRef, type DocumentInlineLink, SiteInsightsLinkPosition } from '@gitbook/api';
 
 import { getSpaceLanguage, tString } from '@/intl/server';
 import { type TranslationLanguage, languages } from '@/intl/translations';
-import { type ResolvedContentRef, resolveContentRef } from '@/lib/references';
+import {
+    type ResolvedContentRef,
+    resolveContentRef,
+    resolveContentRefFallback,
+} from '@/lib/references';
 import { Icon } from '@gitbook/icons';
-import { HoverCard, HoverCardRoot, HoverCardTrigger, StyledLink } from '../../primitives';
+import { StyledLink } from '../../primitives';
 import type { InlineProps } from '../Inline';
 import { Inlines } from '../Inlines';
+import { NotFoundRefHoverCard } from '../NotFoundRefHoverCard';
 import { InlineLinkTooltip } from './InlineLinkTooltip';
 
 export async function InlineLink(props: InlineProps<DocumentInlineLink>) {
@@ -18,52 +23,75 @@ export async function InlineLink(props: InlineProps<DocumentInlineLink>) {
               resolveAnchorText: false,
           })
         : null;
+
     const { contentContext } = context;
 
-    const language = contentContext ? getSpaceLanguage(contentContext) : languages.en;
+    const inlinesElement = (
+        <Inlines
+            context={context}
+            document={document}
+            nodes={inline.nodes}
+            ancestorInlines={[...ancestorInlines, inline]}
+        />
+    );
 
-    if (!contentContext || !resolved) {
+    if (!resolved) {
+        const fallback = resolveContentRefFallback(inline.data.ref);
         return (
-            <HoverCardRoot>
-                <HoverCardTrigger>
-                    <span className="cursor-not-allowed underline">
-                        <Inlines
-                            context={context}
-                            document={document}
-                            nodes={inline.nodes}
-                            ancestorInlines={[...ancestorInlines, inline]}
-                        />
-                    </span>
-                </HoverCardTrigger>
-                <HoverCard className="flex flex-col gap-1 p-4">
-                    <div className="flex items-center gap-2">
-                        <Icon icon="ban" className="size-4 text-tint-subtle" />
-                        <h5 className="font-semibold">{tString(language, 'notfound_title')}</h5>
-                    </div>
-                    <p className="text-sm text-tint">{tString(language, 'notfound_link')}</p>
-                </HoverCard>
-            </HoverCardRoot>
+            <NotFoundRefHoverCard context={context}>
+                {fallback ? (
+                    <InlineLinkAnchor href={fallback.href} contentRef={inline.data.ref} isExternal>
+                        {inlinesElement}
+                    </InlineLinkAnchor>
+                ) : (
+                    <span className="cursor-not-allowed underline">{inlinesElement}</span>
+                )}
+            </NotFoundRefHoverCard>
         );
     }
-    const isExternal = inline.data.ref.kind === 'url';
-    const isMailto = resolved.href.startsWith('mailto:');
-    const content = (
-        <StyledLink
+    const anchorElement = (
+        <InlineLinkAnchor
             href={resolved.href}
+            contentRef={inline.data.ref}
+            isExternal={inline.data.ref.kind === 'url'}
+        >
+            {inlinesElement}
+        </InlineLinkAnchor>
+    );
+
+    if (context.withLinkPreviews) {
+        const language = contentContext ? getSpaceLanguage(contentContext) : languages.en;
+
+        return (
+            <InlineLinkTooltipWrapper inline={inline} language={language} resolved={resolved}>
+                {anchorElement}
+            </InlineLinkTooltipWrapper>
+        );
+    }
+
+    return anchorElement;
+}
+
+function InlineLinkAnchor(props: {
+    href: string;
+    contentRef: ContentRef;
+    isExternal?: boolean;
+    children: React.ReactNode;
+}) {
+    const { href, isExternal, contentRef, children } = props;
+    const isMailto = href.startsWith('mailto:');
+    return (
+        <StyledLink
+            href={href}
             insights={{
                 type: 'link_click',
                 link: {
-                    target: inline.data.ref,
+                    target: contentRef,
                     position: SiteInsightsLinkPosition.Content,
                 },
             }}
         >
-            <Inlines
-                context={context}
-                document={document}
-                nodes={inline.nodes}
-                ancestorInlines={[...ancestorInlines, inline]}
-            />
+            {children}
             {isMailto ? (
                 <Icon
                     icon="envelope"
@@ -77,16 +105,6 @@ export async function InlineLink(props: InlineProps<DocumentInlineLink>) {
             ) : null}
         </StyledLink>
     );
-
-    if (context.withLinkPreviews) {
-        return (
-            <InlineLinkTooltipWrapper inline={inline} language={language} resolved={resolved}>
-                {content}
-            </InlineLinkTooltipWrapper>
-        );
-    }
-
-    return content;
 }
 
 /**

packages/gitbook/src/components/DocumentView/InlineLink/InlineLinkTooltip.tsx

@@ -1,37 +1,9 @@
 'use client';
-import dynamic from 'next/dynamic';
-import React from 'react';
+import { tcls } from '@/lib/tailwind';
+import { Icon } from '@gitbook/icons';
+import { Fragment } from 'react';
+import { Button, HoverCard, HoverCardRoot, HoverCardTrigger, StyledLink } from '../../primitives';
 
-const LoadingValueContext = React.createContext<React.ReactNode>(null);
-
-// To avoid polluting the RSC payload with the tooltip implementation,
-// we lazily load it on the client side. This way, the tooltip is only loaded
-// when the user interacts with the link, and it doesn't block the initial render.
-
-const InlineLinkTooltipImpl = dynamic(
-    () => import('./InlineLinkTooltipImpl').then((mod) => mod.InlineLinkTooltipImpl),
-    {
-        // Disable server-side rendering for this component, it's only
-        // visible on user interaction.
-        ssr: false,
-        loading: () => {
-            // The fallback should be the children (the content of the link),
-            // but as next/dynamic is aiming for feature parity with React.lazy,
-            // it doesn't support passing children to the loading component.
-            // https://github.com/vercel/next.js/issues/7906
-            const children = React.useContext(LoadingValueContext);
-            return <>{children}</>;
-        },
-    }
-);
-
-/**
- * Tooltip for inline links. It's lazily loaded to avoid blocking the initial render
- * and polluting the RSC payload.
- *
- * The link text and href have already been rendered on the server for good SEO,
- * so we can be as lazy as possible with the tooltip.
- */
 export function InlineLinkTooltip(props: {
     isSamePage: boolean;
     isExternal: boolean;
@@ -45,28 +17,79 @@ export function InlineLinkTooltip(props: {
     openInNewTabLabel: string;
     children: React.ReactNode;
 }) {
-    const { children, ...rest } = props;
-    const [shouldLoad, setShouldLoad] = React.useState(false);
+    const { isSamePage, isExternal, openInNewTabLabel, target, breadcrumbs, children } = props;
 
-    // Once the browser is idle, we set shouldLoad to true.
-    // NOTE: to be slightly more performant, we could load when a link is hovered.
-    // But I found this was too much of a delay for the tooltip to appear.
-    // Loading on idle is a good compromise, as it allows the initial render to be fast,
-    // while still loading the tooltip in the background and not polluting the RSC payload.
-    React.useEffect(() => {
-        if ('requestIdleCallback' in window) {
-            (window as globalThis.Window).requestIdleCallback(() => setShouldLoad(true));
-        } else {
-            // fallback for old browsers
-            setTimeout(() => setShouldLoad(true), 2000);
-        }
-    }, []);
+    return (
+        <HoverCardRoot>
+            <HoverCardTrigger>{children}</HoverCardTrigger>
+            <HoverCard className="p-4">
+                <div className="flex items-start gap-4">
+                    <div className="flex flex-col">
+                        {breadcrumbs && breadcrumbs.length > 0 ? (
+                            <div className="mb-1 flex grow flex-wrap items-center gap-x-2 gap-y-0.5 font-semibold text-tint text-xs uppercase leading-tight tracking-wide">
+                                {breadcrumbs.map((crumb, index) => {
+                                    const Tag = crumb.href ? StyledLink : 'div';
 
-    return shouldLoad ? (
-        <LoadingValueContext.Provider value={children}>
-            <InlineLinkTooltipImpl {...rest}>{children}</InlineLinkTooltipImpl>
-        </LoadingValueContext.Provider>
-    ) : (
-        children
+                                    return (
+                                        <Fragment key={crumb.label}>
+                                            {index !== 0 ? (
+                                                <Icon
+                                                    icon="chevron-right"
+                                                    className="size-3 text-tint-subtle"
+                                                />
+                                            ) : null}
+                                            <Tag
+                                                className={tcls(
+                                                    'flex gap-1',
+                                                    crumb.href &&
+                                                        'links-default:text-tint no-underline hover:underline contrast-more:underline contrast-more:decoration-current'
+                                                )}
+                                                href={crumb.href ?? '#'}
+                                            >
+                                                {crumb.icon ? (
+                                                    <span className="mt-0.5 text-tint-subtle empty:hidden">
+                                                        {crumb.icon}
+                                                    </span>
+                                                ) : null}
+                                                {crumb.label}
+                                            </Tag>
+                                        </Fragment>
+                                    );
+                                })}
+                            </div>
+                        ) : null}
+                        <div
+                            className={tcls(
+                                'flex gap-2 leading-snug',
+                                isExternal && 'wrap-anywhere text-sm'
+                            )}
+                        >
+                            {target.icon ? (
+                                <div className="mt-1 text-tint-subtle empty:hidden">
+                                    {target.icon}
+                                </div>
+                            ) : null}
+                            <h5 className="font-semibold">{target.text}</h5>
+                        </div>
+                    </div>
+                    {!isSamePage && target.href ? (
+                        <Button
+                            className={tcls(
+                                '-mx-2 -my-2 ml-auto',
+                                breadcrumbs?.length === 0 ? 'place-self-center' : null
+                            )}
+                            variant="blank"
+                            href={target.href}
+                            target="_blank"
+                            label={openInNewTabLabel}
+                            size="small"
+                            icon="arrow-up-right-from-square"
+                            iconOnly={true}
+                        />
+                    ) : null}
+                </div>
+                {target.subText ? <p className="mt-1 text-sm text-tint">{target.subText}</p> : null}
+            </HoverCard>
+        </HoverCardRoot>
     );
 }

packages/gitbook/src/components/DocumentView/InlineLink/InlineLinkTooltipImpl.tsx

@@ -1,95 +0,0 @@
-'use client';
-import { tcls } from '@/lib/tailwind';
-import { Icon } from '@gitbook/icons';
-import { Fragment } from 'react';
-import { Button, HoverCard, HoverCardRoot, HoverCardTrigger, StyledLink } from '../../primitives';
-
-export function InlineLinkTooltipImpl(props: {
-    isSamePage: boolean;
-    isExternal: boolean;
-    breadcrumbs: Array<{ href?: string; label: string; icon?: React.ReactNode }>;
-    target: {
-        href: string;
-        text: string;
-        subText?: string;
-        icon?: React.ReactNode;
-    };
-    openInNewTabLabel: string;
-    children: React.ReactNode;
-}) {
-    const { isSamePage, isExternal, openInNewTabLabel, target, breadcrumbs, children } = props;
-
-    return (
-        <HoverCardRoot>
-            <HoverCardTrigger>{children}</HoverCardTrigger>
-            <HoverCard className="p-4">
-                <div className="flex items-start gap-4">
-                    <div className="flex flex-col">
-                        {breadcrumbs && breadcrumbs.length > 0 ? (
-                            <div className="mb-1 flex grow flex-wrap items-center gap-x-2 gap-y-0.5 font-semibold text-tint text-xs uppercase leading-tight tracking-wide">
-                                {breadcrumbs.map((crumb, index) => {
-                                    const Tag = crumb.href ? StyledLink : 'div';
-
-                                    return (
-                                        <Fragment key={crumb.label}>
-                                            {index !== 0 ? (
-                                                <Icon
-                                                    icon="chevron-right"
-                                                    className="size-3 text-tint-subtle"
-                                                />
-                                            ) : null}
-                                            <Tag
-                                                className={tcls(
-                                                    'flex gap-1',
-                                                    crumb.href &&
-                                                        'links-default:text-tint no-underline hover:underline contrast-more:underline contrast-more:decoration-current'
-                                                )}
-                                                href={crumb.href ?? '#'}
-                                            >
-                                                {crumb.icon ? (
-                                                    <span className="mt-0.5 text-tint-subtle empty:hidden">
-                                                        {crumb.icon}
-                                                    </span>
-                                                ) : null}
-                                                {crumb.label}
-                                            </Tag>
-                                        </Fragment>
-                                    );
-                                })}
-                            </div>
-                        ) : null}
-                        <div
-                            className={tcls(
-                                'flex gap-2 leading-snug',
-                                isExternal && 'wrap-anywhere text-sm'
-                            )}
-                        >
-                            {target.icon ? (
-                                <div className="mt-1 text-tint-subtle empty:hidden">
-                                    {target.icon}
-                                </div>
-                            ) : null}
-                            <h5 className="font-semibold">{target.text}</h5>
-                        </div>
-                    </div>
-                    {!isSamePage && target.href ? (
-                        <Button
-                            className={tcls(
-                                '-mx-2 -my-2 ml-auto',
-                                breadcrumbs?.length === 0 ? 'place-self-center' : null
-                            )}
-                            variant="blank"
-                            href={target.href}
-                            target="_blank"
-                            label={openInNewTabLabel}
-                            size="small"
-                            icon="arrow-up-right-from-square"
-                            iconOnly={true}
-                        />
-                    ) : null}
-                </div>
-                {target.subText ? <p className="mt-1 text-sm text-tint">{target.subText}</p> : null}
-            </HoverCard>
-        </HoverCardRoot>
-    );
-}

packages/gitbook/src/components/DocumentView/ListItem.tsx

@@ -32,8 +32,6 @@ export function ListItem(props: BlockProps<DocumentBlockListItem>) {
             ancestorBlocks={[...ancestorBlocks, block]}
             blockStyle={tcls(
                 'min-h-lh',
-                // flip heading hash icon if list item is a heading
-                'flip-heading-hash',
                 // remove margin-top for the first heading in a list
                 '[h2]:pt-0',
                 '[h3]:pt-0',

packages/gitbook/src/components/DocumentView/NotFoundRefHoverCard.tsx

@@ -0,0 +1,32 @@
+import { getSpaceLanguage, tString } from '@/intl/server';
+import { languages } from '@/intl/translations';
+import { Icon } from '@gitbook/icons';
+import type { DocumentContextProps } from '../DocumentView';
+import { HoverCard, HoverCardRoot, HoverCardTrigger } from '../primitives';
+
+/**
+ * Hover card displayed for a link not found.
+ */
+export function NotFoundRefHoverCard(
+    props: DocumentContextProps & {
+        children: React.ReactNode;
+    }
+) {
+    const {
+        context: { contentContext },
+        children,
+    } = props;
+    const language = contentContext ? getSpaceLanguage(contentContext) : languages.en;
+    return (
+        <HoverCardRoot>
+            <HoverCardTrigger>{children}</HoverCardTrigger>
+            <HoverCard className="flex flex-col gap-1 p-4">
+                <div className="flex items-center gap-2">
+                    <Icon icon="ban" className="size-4 text-tint-subtle" />
+                    <h5 className="font-semibold">{tString(language, 'notfound_title')}</h5>
+                </div>
+                <p className="text-sm text-tint">{tString(language, 'notfound_link')}</p>
+            </HoverCard>
+        </HoverCardRoot>
+    );
+}

packages/gitbook/src/components/DocumentView/OpenAPI/context.tsx

@@ -39,6 +39,9 @@ export function getOpenAPIContext(args: {
             chevronDown: <Icon icon="chevron-down" />,
             chevronRight: <Icon icon="chevron-right" />,
             plus: <Icon icon="plus" />,
+            copy: <Icon icon="copy" />,
+            check: <Icon icon="check" />,
+            lock: <Icon icon="lock" />,
         },
         renderCodeBlock: (codeProps) => <PlainCodeBlock {...codeProps} />,
         renderDocument: (documentProps) => (

packages/gitbook/src/components/DocumentView/OpenAPI/style.css

@@ -34,7 +34,7 @@
 
 .openapi-deprecated,
 .openapi-stability {
-    @apply py-0.5 px-1.5 min-w-[1.625rem] font-normal w-fit justify-center items-center ring-1 ring-inset ring-tint bg-tint rounded text-sm leading-[calc(max(1.20em,1.25rem))] before:content-none! after:!content-none;
+    @apply py-0.5 px-1.5 min-w-[1.625rem] font-normal w-fit justify-center items-center ring-1 ring-inset ring-tint bg-tint rounded straight-corners:rounded-none circular-corners:rounded-sm text-sm leading-[calc(max(1.20em,1.25rem))] before:content-none! after:!content-none;
 }
 
 .openapi-stability-alpha {
@@ -72,7 +72,7 @@
 }
 
 .openapi-markdown code {
-    @apply py-px px-1 min-w-[1.625rem] font-normal w-fit justify-center items-center ring-1 ring-inset ring-tint bg-tint rounded   text-sm leading-[calc(max(1.20em,1.25rem))] before:content-none! after:!content-none;
+    @apply py-px px-1 min-w-[1.625rem] font-normal w-fit justify-center items-center ring-1 ring-inset ring-tint bg-tint rounded straight-corners:rounded-none circular-corners:rounded-md text-sm leading-[calc(max(1.20em,1.25rem))] before:content-none! after:!content-none;
 }
 
 .openapi-markdown pre code {
@@ -95,7 +95,7 @@
 /* Method Tags */
 .openapi-method,
 .openapi-statuscode {
-    @apply rounded uppercase font-mono items-center shrink-0 font-semibold text-[0.813rem] px-1 py-0.5 mr-2 text-tint-12/8 leading-tight align-middle inline-flex ring-1 ring-inset ring-tint-12/1 dark:ring-tint-1/1 whitespace-nowrap;
+    @apply rounded straight-corners:rounded-none circular-corners:rounded-md uppercase font-mono items-center shrink-0 font-semibold text-[0.813rem] px-1 py-0.5 mr-2 text-tint-12/8 leading-tight align-middle inline-flex ring-1 ring-inset ring-tint-12/1 dark:ring-tint-1/1 whitespace-nowrap;
 }
 
 .openapi-method-get,
@@ -270,11 +270,11 @@
 }
 
 .openapi-schema-enum-value:first-child {
-    @apply rounded-l ml-0;
+    @apply rounded-l straight-corners:rounded-none circular-corners:rounded-l-md ml-0;
 }
 
 .openapi-schema-enum-value:last-child {
-    @apply rounded-r;
+    @apply rounded-r straight-corners:rounded-none circular-corners:rounded-r-md;
 }
 
 /* Schema Description */
@@ -308,7 +308,7 @@
 .openapi-schema-pattern code,
 .openapi-schema-enum-value code,
 .openapi-schema-default code {
-    @apply py-px px-1 min-w-[1.625rem] text-tint-strong font-normal w-fit justify-center items-center ring-1 ring-inset ring-tint-subtle bg-tint rounded text-xs leading-[calc(max(1.20em,1.25rem))] before:content-none! after:!content-none;
+    @apply py-px px-1 min-w-[1.625rem] text-tint-strong font-normal w-fit justify-center items-center ring-1 ring-inset ring-tint-subtle bg-tint rounded straight-corners:rounded-none circular-corners:rounded-md text-xs leading-[calc(max(1.20em,1.25rem))] before:content-none! after:!content-none;
 }
 
 /* Authentication */
@@ -325,16 +325,20 @@
     @apply prose *:!prose-sm *:text-tint;
 }
 
+.openapi-securities-oauth-content {
+    @apply flex flex-col gap-1 mt-1;
+}
+
 .openapi-securities-oauth-content.openapi-markdown code {
     @apply text-xs;
 }
 
 .openapi-securities-scopes ul {
-    @apply !my-0;
+    @apply !my-0 ml-4 pl-0;
 }
 
 .openapi-securities-url {
-    @apply ml-0.5 px-0.5 rounded hover:bg-tint transition-colors;
+    @apply ml-0.5 px-0.5 rounded straight-corners:rounded-none circular-corners:rounded-md hover:bg-tint dark:hover:bg-tint-hover transition-colors;
 }
 
 .openapi-securities-body {
@@ -394,15 +398,13 @@
     @apply text-left prose-sm text-sm leading-tight text-tint select-text prose-strong:font-semibold prose-strong:text-inherit;
 }
 
-.openapi-disclosure-group-trigger[aria-expanded="false"] {
-    .openapi-response-description.openapi-markdown {
-        @apply truncate;
-        @apply [&>*:not(:first-child)]:hidden *:truncate *:!p-0 *:!m-0;
-    }
+.openapi-disclosure-group-trigger[aria-expanded="false"] .openapi-response-description.openapi-markdown {
+    @apply truncate;
+    @apply [&>*:not(:first-child)]:hidden *:truncate *:!p-0 *:!m-0;
+}
 
-    .openapi-response-tab-content {
-        @apply basis-[60%]
-    }
+.openapi-disclosure-group-trigger[aria-expanded="false"] .openapi-response-tab-content {
+    @apply basis-[60%];
 }
 
 .openapi-response-body {
@@ -454,6 +456,10 @@
     @apply flex items-center font-mono text-[0.813rem] gap-1 h-fit *:truncate overflow-x-auto min-w-0 max-w-full font-normal text-tint-strong;
 }
 
+.openapi-codesample-header-content .openapi-path-title {
+    @apply block;
+}
+
 .openapi-codesample-header-content .openapi-path .openapi-path-variable {
     @apply text-[0.813rem];
 }
@@ -474,21 +480,26 @@
 }
 
 .openapi-path-variable {
-    @apply p-px min-w-[1.625rem] text-tint-strong font-normal w-fit justify-center items-center ring-1 ring-inset ring-tint bg-tint rounded text-sm leading-none before:content-none! after:!content-none;
+    @apply p-px min-w-[1.625rem] text-tint-strong font-normal w-fit justify-center items-center ring-1 ring-inset ring-tint bg-tint rounded straight-corners:rounded-none circular-corners:rounded-md text-sm leading-none before:content-none! after:!content-none;
 }
 
 .openapi-path-server {
-    @apply text-tint hidden md:inline;
+    @apply text-tint inline;
 }
 
-.openapi-path .openapi-method {
-    @apply m-0 mt-0.5 items-center flex px-1;
+.openapi-summary .openapi-path .openapi-method {
+    @apply m-0 items-center flex px-2 py-1 h-6;
 }
 
 .openapi-path-title {
-    @apply flex-1 relative font-normal text-left font-mono text-tint-strong/10;
-    @apply py-0.5 px-1 rounded hover:bg-tint transition-colors;
+    @apply flex-1 relative font-normal items-center gap-y-1 flex flex-wrap text-left overflow-x-auto font-mono text-tint-strong/10;
     @apply whitespace-nowrap md:whitespace-normal;
+    scrollbar-width: none;
+    -ms-overflow-style: none;
+}
+
+.openapi-path-title-row{
+    @apply flex flex-row items-center;
 }
 
 .openapi-path-title[data-deprecated="true"] {
@@ -515,7 +526,7 @@
 .openapi-panel,
 .openapi-codesample,
 .openapi-response-examples {
-    @apply border shrink min-h-40 overflow-hidden rounded-md straight-corners:rounded-none circular-corners:rounded-xl bg-tint-subtle border-tint-subtle shadow-sm;
+    @apply border shrink min-h-40 overflow-hidden rounded-lg straight-corners:rounded-none circular-corners:rounded-xl bg-tint-subtle border-tint-subtle shadow-sm;
 }
 
 .openapi-response-examples-panel {
@@ -592,18 +603,30 @@ body:has(.openapi-select-popover) {
 }
 
 .openapi-select > button {
-    @apply flex items-center font-normal cursor-pointer *:truncate gap-1.5 text-tint-strong rounded text-xs p-1.5 leading-none border border-tint-subtle bg-tint;
-    @apply hover:bg-tint-hover transition-all;
+    @apply flex items-center font-normal cursor-pointer *:truncate gap-1.5 p-1.5 border border-tint-subtle text-tint-strong rounded straight-corners:rounded-none circular-corners:rounded-md leading-none;
+    @apply hover:bg-tint dark:hover:bg-tint-hover transition-all;
+}
+
+.openapi-select:not(.openapi-select-unstyled) > button {
+    @apply border border-tint-subtle bg-tint text-xs;
+}
+
+.openapi-select-unstyled > button {
+    @apply p-1 *:truncate max-w-full;
 }
 
 .openapi-select > button[data-focused="true"] {
-    @apply outline-primary -outline-offset-1 outline outline-1;
+    @apply outline-primary -outline-offset-1 outline;
 }
 
 .openapi-select > button > span.react-aria-SelectValue {
     @apply shrink truncate flex items-center;
 }
 
+.openapi-select > button > .react-aria-SelectValue [slot="description"] {
+    display: none;
+}
+
 .openapi-select > button .openapi-markdown {
     @apply *:leading-none;
 }
@@ -613,7 +636,7 @@ body:has(.openapi-select-popover) {
 }
 
 .openapi-select-popover {
-    @apply min-w-32 z-10 max-w-[max(20rem,var(--trigger-width))] overflow-x-hidden max-h-52 overflow-y-auto p-1.5 border border-tint-subtle bg-tint-base backdrop-blur-xl rounded-md circular-corners:rounded-xl straight-corners:rounded-none;
+    @apply min-w-32 z-10 max-w-[max(20rem,var(--trigger-width))] overflow-x-hidden max-h-52 overflow-y-auto p-1.5 border border-tint-subtle bg-tint-base backdrop-blur-xl rounded-md straight-corners:rounded-none circular-corners:rounded-xl;
     @apply shadow-md shadow-tint-12/1 dark:shadow-tint-1/1;
 }
 
@@ -626,10 +649,18 @@ body:has(.openapi-select-popover) {
 }
 
 .openapi-select-item {
-    @apply text-sm flex items-center cursor-pointer px-1.5 overflow-hidden py-1 text-tint ring-0 border-none rounded !outline-none;
+    @apply text-sm flex items-center cursor-pointer px-1.5 overflow-hidden py-1 text-tint ring-0 border-none rounded straight-corners:rounded-none circular-corners:rounded-md !outline-none;
     @apply hover:bg-tint-hover hover:theme-gradient:bg-tint-12/1 hover:text-tint-strong contrast-more:hover:ring-1 contrast-more:hover:ring-inset contrast-more:hover:ring-current;
 }
 
+.openapi-select-item.openapi-select-item-column {
+    @apply flex flex-col gap-1 justify-start items-start;
+}
+
+.openapi-select-item [slot="description"] {
+    @apply text-xs text-tint-subtle;
+}
+
 .openapi-select button .openapi-markdown,
 .openapi-select-item .openapi-markdown {
     @apply text-[0.813rem] *:truncate *:!p-0 *:!m-0 [&>*:not(:first-child)]:hidden;
@@ -714,7 +745,7 @@ body:has(.openapi-select-popover) {
 }
 
 .openapi-tabs-tab {
-    @apply hover:bg-primary-hover whitespace-nowrap font-mono font-normal tabular-nums hover:text-primary cursor-pointer transition-all relative text-[0.813rem] text-tint px-1 border border-transparent rounded;
+    @apply hover:bg-primary-hover whitespace-nowrap font-mono font-normal tabular-nums hover:text-primary cursor-pointer transition-all relative text-[0.813rem] text-tint px-1 border border-transparent rounded straight-corners:rounded-none circular-corners:rounded-md;
 }
 
 .openapi-tabs-tab[aria-selected="true"] {
@@ -785,12 +816,12 @@ body:has(.openapi-select-popover) {
 }
 
 .openapi-schemas-disclosure > .openapi-disclosure-trigger {
-    @apply flex items-center font-mono transition-all font-normal text-tint-strong !text-sm hover:bg-tint-subtle relative flex-1 gap-2.5 p-5 truncate -outline-offset-1;
+    @apply flex items-center font-mono transition-all font-normal text-tint-strong !text-sm hover:bg-tint-subtle dark:hover:bg-tint-hover relative flex-1 gap-2.5 p-5 truncate -outline-offset-1;
 }
 
 .openapi-schemas-disclosure > .openapi-disclosure-trigger,
 .openapi-schemas-disclosure .openapi-disclosure-panel {
-    @apply straight-corners:!rounded-none;
+    @apply straight-corners:!rounded-none circular-corners:!rounded-md;
 }
 
 .openapi-disclosure-panel {
@@ -818,7 +849,7 @@ body:has(.openapi-select-popover) {
         .openapi-schema-alternatives .openapi-disclosure,
         .openapi-schemas-disclosure .openapi-schema.openapi-disclosure
     ) {
-    @apply rounded-xl;
+    @apply rounded-md circular-corners:rounded-xl straight-corners:rounded-none;
 }
 
 .openapi-disclosure .openapi-schemas-disclosure .openapi-schema.openapi-disclosure {
@@ -833,10 +864,10 @@ body:has(.openapi-select-popover) {
     @apply ring-1 shadow-sm;
 }
 
-.openapi-disclosure[data-expanded="true"]:not(.openapi-schemas-disclosure):not(:first-child) {
+.openapi-disclosure[data-expanded="true"]:not(.openapi-schemas-disclosure,.openapi-required-scopes):not(:first-child) {
     @apply mt-2;
 }
-.openapi-disclosure[data-expanded="true"]:not(.openapi-schemas-disclosure):not(:last-child) {
+.openapi-disclosure[data-expanded="true"]:not(.openapi-schemas-disclosure,.openapi-required-scopes):not(:last-child) {
     @apply mb-2;
 }
 
@@ -966,3 +997,43 @@ body:has(.openapi-select-popover) {
 .openapi-copy-button[data-disabled="true"] {
     @apply cursor-default;
 }
+
+.openapi-path-copy-button {
+    @apply p-1 flex rounded-md straight-corners:rounded-none;
+    @apply hover:bg-tint dark:hover:bg-tint-hover;
+}
+
+.openapi-path-copy-button-icon {
+    @apply size-6 opacity-0 transition-all hidden sm:flex;
+}
+
+.openapi-path:hover .openapi-path-copy-button-icon {
+    @apply opacity-100;
+}
+
+.openapi-path-copy-button-icon svg {
+    @apply text-tint size-4;
+}
+
+.openapi-required-scopes {
+    @apply border text-base rounded-md straight-corners:rounded-none circular-corners:rounded-md font-medium mx-0;
+}
+
+.openapi-required-scopes .openapi-required-scopes-header {
+    @apply flex items-center gap-3;
+}
+
+.openapi-required-scopes .openapi-required-scopes-header svg {
+    @apply size-3.5 text-tint-subtle rotate-none;
+}
+
+.openapi-required-scopes .openapi-disclosure-group-panel {
+    @apply px-3 pb-3;
+}
+.openapi-required-scopes .openapi-securities-scopes {
+    @apply ml-6 font-normal *:!text-[0.8125rem];
+}
+
+.openapi-required-scopes .openapi-required-scopes-description {
+    @apply text-xs !text-tint font-normal mb-2;
+}

packages/gitbook/src/components/DocumentView/Table/RecordCard.tsx

@@ -60,7 +60,7 @@ export async function RecordCard(
                 'overflow-hidden',
                 '[&_.heading>div:first-child]:hidden',
                 '[&_.heading>div]:text-[.8em]',
-                'md:[&_.heading>div]:text-[1em]',
+                '@xl:[&_.heading>div]:text-[1em]',
                 '[&_.blocks:first-child_.heading]:pt-0', // Remove padding-top on first heading in card
 
                 // On mobile, check if we can display the cover responsively or not:
@@ -69,10 +69,10 @@ export async function RecordCard(
                 lightCoverIsSquareOrPortrait || darkCoverIsSquareOrPortrait
                     ? [
                           lightCoverIsSquareOrPortrait
-                              ? 'grid-cols-[40%__1fr] min-[432px]:grid-cols-none min-[432px]:grid-rows-[auto_1fr]'
+                              ? '@sm:grid-cols-none grid-cols-[40%__1fr] @sm:grid-rows-[auto_1fr]'
                               : '',
                           darkCoverIsSquareOrPortrait
-                              ? 'dark:grid-cols-[40%__1fr] dark:min-[432px]:grid-cols-none dark:min-[432px]:grid-rows-[auto_1fr]'
+                              ? 'dark:@sm:grid-cols-none dark:grid-cols-[40%__1fr] dark:@sm:grid-rows-[auto_1fr]'
                               : '',
                       ].filter(Boolean)
                     : 'grid-rows-[auto_1fr]'
@@ -85,11 +85,13 @@ export async function RecordCard(
                         light: {
                             src: lightCover.href,
                             size: lightCover.file?.dimensions,
+                            alt: light.alt,
                         },
                         dark: darkCover
                             ? {
                                   src: darkCover.href,
                                   size: darkCover.file?.dimensions,
+                                  alt: dark.alt,
                               }
                             : null,
                     }}
@@ -110,18 +112,15 @@ export async function RecordCard(
                         'bg-tint-subtle',
                         lightCoverIsSquareOrPortrait || darkCoverIsSquareOrPortrait
                             ? [
-                                  lightCoverIsSquareOrPortrait
-                                      ? 'min-[432px]:aspect-video min-[432px]:h-auto'
-                                      : '',
+                                  lightCoverIsSquareOrPortrait ? '@sm:aspect-video @sm:h-auto' : '',
                                   darkCoverIsSquareOrPortrait
-                                      ? 'dark:min-[432px]:aspect-video dark:min-[432px]:h-auto'
+                                      ? 'dark:@sm:aspect-video dark:@sm:h-auto'
                                       : '',
                               ].filter(Boolean)
                             : ['h-auto', 'aspect-video'],
                         objectFits
                     )}
-                    priority={isOffscreen ? 'lazy' : 'high'}
-                    preload
+                    loading={isOffscreen ? 'lazy' : 'eager'}
                 />
             ) : null}
             <div

packages/gitbook/src/components/DocumentView/Table/RecordColumnValue.tsx

@@ -229,7 +229,7 @@ export async function RecordColumnValue<Tag extends React.ElementType = 'div'>(
                                                 },
                                             },
                                         }}
-                                        priority="lazy"
+                                        loading="lazy"
                                     />
                                 ) : (
                                     <FileIcon
@@ -404,7 +404,7 @@ export async function RecordColumnValue<Tag extends React.ElementType = 'div'>(
                                     size: image.file?.dimensions,
                                 },
                             }}
-                            priority="lazy"
+                            loading="lazy"
                         />
                         {image.text}
                     </StyledLink>

packages/gitbook/src/components/DocumentView/Table/ViewCards.tsx

@@ -15,8 +15,8 @@ export function ViewCards(props: TableViewProps<DocumentTableViewCards>) {
                 'inline-grid',
                 'gap-4',
                 'grid-cols-1',
-                'min-[432px]:grid-cols-2',
-                view.cardSize === 'large' ? 'md:grid-cols-2' : 'md:grid-cols-3',
+                '@sm:grid-cols-2',
+                view.cardSize === 'large' ? '@xl:grid-cols-2' : '@xl:grid-cols-3',
                 block.data.fullWidth ? 'large:flex-column' : null
             )}
         >

packages/gitbook/src/components/DocumentView/Table/utils.ts

@@ -21,6 +21,12 @@ export function getRecordValue<T extends number | string | boolean | string[] |
     return record.values[definitionId];
 }
 
+type RecordCardCover = {
+    contentRef: ContentRefFile | ContentRefURL | null;
+    objectFit?: CardsImageObjectFit;
+    alt?: string;
+};
+
 /**
  * Get the covers for a record card.
  * Returns both the light and dark covers with their content refs and optional object fit.
@@ -31,10 +37,7 @@ export function getRecordCardCovers(
     record: DocumentTableRecord,
     view: DocumentTableViewCards
 ): {
-    [key in 'light' | 'dark']: {
-        contentRef: ContentRefFile | ContentRefURL | null;
-        objectFit?: CardsImageObjectFit;
-    };
+    [key in 'light' | 'dark']: RecordCardCover;
 } {
     const lightValue = view.coverDefinition
         ? (getRecordValue(record, view.coverDefinition) as DocumentTableImageRecord | string[])
@@ -53,10 +56,9 @@ export function getRecordCardCovers(
 /**
  * Process a cover value and return the content ref and object fit.
  */
-function processCoverValue(value: DocumentTableImageRecord | string[] | null | undefined): {
-    contentRef: ContentRefFile | ContentRefURL | null;
-    objectFit?: CardsImageObjectFit;
-} {
+function processCoverValue(
+    value: DocumentTableImageRecord | string[] | null | undefined
+): RecordCardCover {
     if (!value) {
         return { contentRef: null };
     }
@@ -78,6 +80,7 @@ function processCoverValue(value: DocumentTableImageRecord | string[] | null | u
         return {
             contentRef: imageValue.ref,
             objectFit: imageValue.objectFit,
+            alt: imageValue.alt,
         };
     }
 

packages/gitbook/src/components/DocumentView/Tabs/DynamicTabs.tsx

@@ -1,12 +1,22 @@
 'use client';
 
-import React, { useCallback, useMemo } from 'react';
+import React, {
+    memo,
+    useCallback,
+    useMemo,
+    useRef,
+    useState,
+    type ComponentPropsWithRef,
+} from 'react';
 
-import { useHash, useIsMounted } from '@/components/hooks';
+import { NavigationStatusContext, useListOverflow } from '@/components/hooks';
+import { DropdownMenu, DropdownMenuItem } from '@/components/primitives';
+import { useLanguage } from '@/intl/client';
+import { tString } from '@/intl/translate';
 import { getLocalStorageItem, setLocalStorageItem } from '@/lib/browser';
-import { type ClassValue, tcls } from '@/lib/tailwind';
-import type { DocumentBlockTabs } from '@gitbook/api';
-import { HashLinkButton, hashLinkButtonWrapperStyles } from '../HashLinkButton';
+import { tcls } from '@/lib/tailwind';
+import { Icon } from '@gitbook/icons';
+import { useRouter } from 'next/navigation';
 
 interface TabsState {
     activeIds: {
@@ -46,16 +56,9 @@ const TITLES_MAX = 5;
 export interface TabsItem {
     id: string;
     title: string;
+    body: React.ReactNode;
 }
 
-type SelectorMapper<Type> = {
-    [Property in keyof Type]: Type[Property];
-};
-type TabsInput = {
-    id: string;
-    tabs: SelectorMapper<TabsItem>[];
-};
-
 interface TabsState {
     activeIds: {
         [tabsBlockId: string]: string;
@@ -66,16 +69,16 @@ interface TabsState {
 /**
  * Client side component for the tabs, taking care of interactions.
  */
-export function DynamicTabs(
-    props: TabsInput & {
-        tabsBody: React.ReactNode[];
-        style: ClassValue;
-        block: DocumentBlockTabs;
-    }
-) {
-    const { id, block, tabs, tabsBody, style } = props;
+export function DynamicTabs(props: {
+    id: string;
+    tabs: TabsItem[];
+    className?: string;
+}) {
+    const { id, tabs, className } = props;
+    const router = useRouter();
 
-    const hash = useHash();
+    const { onNavigationClick, hash } = React.useContext(NavigationStatusContext);
+    const [initialized, setInitialized] = useState(false);
     const [tabsState, setTabsState] = useTabsState();
     const activeState = useMemo(() => {
         const input = { id, tabs };
@@ -84,41 +87,99 @@ export function DynamicTabs(
         );
     }, [id, tabs, tabsState]);
 
+    // Track if the tab has been touched by the user.
+    const touchedRef = useRef(false);
+
     // To avoid issue with hydration, we only use the state from localStorage
-    // once the component has been mounted.
+    // once the component has been initialized (=mounted).
     // Otherwise because of  the streaming/suspense approach, tabs can be first-rendered at different time
     // and get stuck into an inconsistent state.
-    const mounted = useIsMounted();
-    const active = mounted ? activeState : tabs[0];
+    const active = initialized ? activeState : tabs[0];
 
-    /**
-     * When clicking to select a tab, we:
-     * - mark this specific ID as selected
-     * - store the ID to auto-select other tabs with the same title
-     */
-    const onSelectTab = React.useCallback(
-        (tab: TabsItem) => {
-            setTabsState((prev) => ({
-                activeIds: {
-                    ...prev.activeIds,
-                    [id]: tab.id,
-                },
-                activeTitles: tab.title
-                    ? prev.activeTitles
-                          .filter((t) => t !== tab.title)
-                          .concat([tab.title])
-                          .slice(-TITLES_MAX)
-                    : prev.activeTitles,
-            }));
+    // When clicking to select a tab, we:
+    // - update the URL hash
+    // - mark this specific ID as selected
+    // - store the ID to auto-select other tabs with the same title
+    const selectTab = useCallback(
+        (tabId: string, manual = true) => {
+            const tab = tabs.find((tab) => tab.id === tabId);
+
+            if (!tab) {
+                return;
+            }
+
+            if (manual) {
+                touchedRef.current = true;
+                const href = `#${tab.id}`;
+                if (window.location.hash !== href) {
+                    onNavigationClick(href);
+                    router.replace(href, { scroll: false });
+                }
+            }
+
+            setTabsState((prev) => {
+                if (prev.activeIds[id] === tab.id) {
+                    return prev;
+                }
+                return {
+                    activeIds: {
+                        ...prev.activeIds,
+                        [id]: tab.id,
+                    },
+                    activeTitles: tab.title
+                        ? prev.activeTitles
+                              .filter((t) => t !== tab.title)
+                              .concat([tab.title])
+                              .slice(-TITLES_MAX)
+                        : prev.activeTitles,
+                };
+            });
         },
-        [id, setTabsState]
+        [router, setTabsState, tabs, id]
     );
 
-    /**
-     * When the hash changes, we try to select the tab containing the targetted element.
-     */
-    React.useEffect(() => {
-        if (!hash) {
+    // When the hash changes, we try to select the tab containing the targetted element.
+    React.useLayoutEffect(() => {
+        setInitialized(true);
+
+        if (hash) {
+            // First check if the hash matches a tab ID.
+            const hashIsTab = tabs.some((tab) => tab.id === hash);
+            if (hashIsTab) {
+                selectTab(hash, false);
+                return;
+            }
+
+            // Then check if the hash matches an element inside a tab.
+            const activeElement = document.getElementById(hash);
+            if (!activeElement) {
+                return;
+            }
+
+            const tabPanel = activeElement.closest('[role="tabpanel"]');
+            if (!tabPanel) {
+                return;
+            }
+
+            selectTab(tabPanel.id, false);
+        }
+    }, [selectTab, tabs, hash]);
+
+    // Scroll to active element in the tab.
+    React.useLayoutEffect(() => {
+        // If there is no hash or active tab, nothing to scroll.
+        if (!hash || hash !== '' || !active) {
+            return;
+        }
+
+        // If the tab is touched, we don't want to scroll.
+        if (touchedRef.current) {
+            return;
+        }
+
+        // If the hash matches a tab, then the scroll is already done.
+        const hashIsTab = tabs.some((tab) => tab.id === hash);
+        if (hashIsTab) {
             return;
         }
 
@@ -127,143 +188,237 @@ export function DynamicTabs(
             return;
         }
 
-        const tabAncestor = activeElement.closest('[role="tabpanel"]');
-        if (!tabAncestor) {
-            return;
-        }
-
-        const tab = tabs.find((tab) => getTabPanelId(tab.id) === tabAncestor.id);
-        if (!tab) {
-            return;
-        }
-
-        onSelectTab(tab);
-    }, [hash, tabs, onSelectTab]);
+        activeElement.scrollIntoView({
+            block: 'start',
+            behavior: 'instant',
+        });
+    }, [active, tabs, hash]);
 
     return (
         <div
             className={tcls(
                 'rounded-lg',
                 'straight-corners:rounded-xs',
-                'ring-1',
-                'ring-inset',
-                'ring-tint-subtle',
-                'flex',
-                'flex-col',
-                'overflow-hidden',
-                style
+                'ring-1 ring-tint-subtle ring-inset',
+                'flex min-w-0 flex-col',
+                className
             )}
         >
-            <div
-                role="tablist"
-                className={tcls(
-                    'group/tabs',
-                    'inline-flex',
-                    'flex-row',
-                    'self-stretch',
-                    'after:flex-1',
-                    'after:bg-tint-12/1',
-                    // if last tab is selected, apply rounded to :after element
-                    '[&:has(button.active-tab:last-of-type):after]:rounded-bl-md'
-                )}
-            >
-                {tabs.map((tab) => (
-                    <div
-                        key={tab.id}
-                        className={tcls(
-                            hashLinkButtonWrapperStyles,
-                            'flex',
-                            'items-center',
-                            'gap-3.5',
-
-                            //prev from active-tab
-                            '[&:has(+_.active-tab)]:rounded-br-md',
-
-                            //next from active-tab
-                            '[.active-tab+&]:rounded-bl-md',
-
-                            //next from active-tab
-                            '[.active-tab_+_:after]:rounded-br-md',
-
-                            'after:transition-colors',
-                            'after:border-r',
-                            'after:absolute',
-                            'after:left-[unset]',
-                            'after:right-0',
-                            'after:border-tint',
-                            'after:top-[15%]',
-                            'after:h-[70%]',
-                            'after:w-px',
-
-                            'px-3.5',
-                            'py-2',
-
-                            'last:after:border-transparent',
-
-                            'text-tint',
-                            'bg-tint-12/1',
-                            'hover:text-tint-strong',
-                            'max-w-full',
-                            'truncate',
-
-                            active?.id === tab.id
-                                ? [
-                                      'shrink-0',
-                                      'active-tab',
-                                      'text-tint-strong',
-                                      'bg-transparent',
-                                      '[&.active-tab]:after:border-transparent',
-                                      '[:has(+_&.active-tab)]:after:border-transparent',
-                                      '[:has(&_+)]:after:border-transparent',
-                                  ]
-                                : null
-                        )}
-                    >
-                        <button
-                            type="button"
-                            role="tab"
-                            aria-selected={active?.id === tab.id}
-                            aria-controls={getTabPanelId(tab.id)}
-                            id={getTabButtonId(tab.id)}
-                            onClick={() => {
-                                onSelectTab(tab);
-                            }}
-                            className={tcls(
-                                'inline-block',
-                                'text-sm',
-                                'transition-[color]',
-                                'font-medium',
-                                'relative',
-                                'max-w-full',
-                                'truncate'
-                            )}
-                        >
-                            {tab.title}
-                        </button>
-
-                        <HashLinkButton
-                            id={getTabButtonId(tab.id)}
-                            block={block}
-                            label="Direct link to tab"
-                        />
-                    </div>
-                ))}
-            </div>
-            {tabs.map((tab, index) => (
-                <div
-                    key={tab.id}
-                    role="tabpanel"
-                    id={getTabPanelId(tab.id)}
-                    aria-labelledby={getTabButtonId(tab.id)}
-                    className={tcls('p-4', tab.id !== active?.id ? 'hidden' : null)}
-                >
-                    {tabsBody[index]}
-                </div>
+            <TabItemList tabs={tabs} activeTabId={active?.id ?? null} onSelect={selectTab} />
+            {tabs.map((tab) => (
+                <TabPanel key={tab.id} tab={tab} isActive={tab.id === active?.id} />
             ))}
         </div>
     );
 }
 
+const TabPanel = memo(function TabPanel(props: {
+    tab: TabsItem;
+    isActive: boolean;
+}) {
+    const { tab, isActive } = props;
+    return (
+        <div
+            role="tabpanel"
+            id={tab.id}
+            aria-labelledby={getTabButtonId(tab.id)}
+            className="scroll-mt-[calc(var(--content-scroll-margin)+var(--spacing)*20)]"
+        >
+            <div className="p-4" hidden={!isActive}>
+                {tab.body}
+            </div>
+        </div>
+    );
+});
+
+const TabItemList = memo(function TabItemList(props: {
+    tabs: TabsItem[];
+    activeTabId: string | null;
+    onSelect: (tabId: string) => void;
+}) {
+    const { tabs, activeTabId, onSelect } = props;
+    const { containerRef, itemRef, overflowing, isMeasuring } = useListOverflow();
+    const overflowingTabs = useMemo(
+        () =>
+            Array.from(overflowing, (id) => {
+                const tabId = getTabIdFromButtonId(id);
+                return tabs.find((tab) => tab.id === tabId);
+            }).filter((x) => x !== undefined),
+        [overflowing, tabs]
+    );
+    return (
+        <div
+            ref={containerRef}
+            role="tablist"
+            className={tcls(
+                'group/tabs',
+                'overflow-hidden',
+                'rounded-t-lg',
+                'straight-corners:rounded-t-xs',
+                'inline-flex',
+                'self-stretch',
+                'after:flex-1',
+                'after:bg-tint-12/1',
+                // if last tab is selected, apply rounded to :after element
+                '[&:has(button.active-tab:last-of-type):after]:rounded-bl-md'
+            )}
+        >
+            {/* When we measure, we add the menu at start to be sure everything's fit. */}
+            {isMeasuring ? (
+                <TabsDropdownMenu tabs={tabs} onSelect={onSelect} activeTabId={activeTabId} />
+            ) : null}
+            {tabs.map((tab) => {
+                // Hide overflowing tabs when not measuring.
+                if (overflowing.has(getTabButtonId(tab.id)) && !isMeasuring) {
+                    return null;
+                }
+                return (
+                    <TabItem
+                        key={tab.id}
+                        ref={itemRef}
+                        isActive={tab.id === activeTabId}
+                        tab={tab}
+                        onSelect={onSelect}
+                    />
+                );
+            })}
+            {/* Dropdown for overflowing tabs */}
+            {overflowingTabs.length > 0 && !isMeasuring ? (
+                <TabsDropdownMenu
+                    tabs={overflowingTabs}
+                    onSelect={onSelect}
+                    activeTabId={activeTabId}
+                />
+            ) : null}
+        </div>
+    );
+});
+
+function TabsDropdownMenu(props: {
+    tabs: TabsItem[];
+    activeTabId: string | null;
+    onSelect: (tabId: string) => void;
+}) {
+    const { tabs, onSelect, activeTabId } = props;
+    const language = useLanguage();
+    return (
+        <DropdownMenu
+            button={
+                <TabButton
+                    isActive={tabs.some((tab) => tab.id === activeTabId)}
+                    aria-label={tString(language, 'more')}
+                    className="shrink-0"
+                >
+                    <Icon icon="ellipsis" className="size-4" />
+                </TabButton>
+            }
+        >
+            {tabs.map((tab) => {
+                return (
+                    <DropdownMenuItem
+                        key={tab.id}
+                        onClick={() => onSelect(tab.id)}
+                        active={tab.id === activeTabId}
+                    >
+                        {tab.title}
+                    </DropdownMenuItem>
+                );
+            })}
+        </DropdownMenu>
+    );
+}
+
+/**
+ * Tab item that accepts a `tab` prop.
+ */
+const TabItem = memo(function TabItem(props: {
+    ref: React.Ref<HTMLButtonElement>;
+    isActive: boolean;
+    tab: TabsItem;
+    onSelect: (tabId: string) => void;
+}) {
+    const { ref, tab, isActive, onSelect } = props;
+    return (
+        <TabButton
+            ref={ref}
+            role="tab"
+            aria-selected={isActive}
+            aria-controls={tab.id}
+            id={getTabButtonId(tab.id)}
+            onClick={() => onSelect(tab.id)}
+        >
+            {tab.title}
+        </TabButton>
+    );
+});
+
+/**
+ * Generic tab button component, low-level.
+ */
+function TabButton(
+    props: Omit<ComponentPropsWithRef<'button'>, 'type'> & {
+        isActive?: boolean;
+    }
+) {
+    const { isActive, ...rest } = props;
+    return (
+        <div
+            className={tcls(
+                'relative',
+                'flex items-center',
+
+                //prev from active-tab
+                '[&:has(+_.active-tab)]:rounded-br-md',
+
+                //next from active-tab
+                '[.active-tab+&]:rounded-bl-md',
+
+                //next from active-tab
+                '[.active-tab_+_:after]:rounded-br-md',
+
+                'after:transition-colors',
+                'after:border-r',
+                'after:absolute',
+                'after:left-[unset]',
+                'after:right-0',
+                'after:border-tint',
+                'after:top-[15%]',
+                'after:h-[70%]',
+                'after:w-px',
+
+                'last:after:border-transparent',
+
+                'text-tint',
+                'bg-tint-12/1',
+                'hover:text-tint-strong',
+                'max-w-full',
+                'shrink-0',
+                'truncate',
+
+                props['aria-selected'] || props['aria-expanded'] || isActive
+                    ? [
+                          'active-tab',
+                          'text-tint-strong',
+                          'bg-transparent',
+                          '[&.active-tab]:after:border-transparent',
+                          '[:has(+_&.active-tab)]:after:border-transparent',
+                          '[:has(&_+)]:after:border-transparent',
+                      ]
+                    : null
+            )}
+        >
+            <button
+                {...rest}
+                type="button"
+                className={tcls(
+                    'relative inline-block max-w-full truncate px-3.5 py-2 font-medium text-sm transition-[color]',
+                    props.className
+                )}
+            />
+        </div>
+    );
+}
+
 /**
  * Get the ID for a tab button.
  */
@@ -272,17 +427,25 @@ function getTabButtonId(tabId: string) {
 }
 
 /**
- * Get the ID for a tab panel.
- * We use the ID of the tab itself as links can be pointing to this ID.
+ * Get the ID of a tab from a button ID.
  */
-function getTabPanelId(tabId: string) {
-    return tabId;
+function getTabIdFromButtonId(buttonId: string) {
+    if (buttonId.startsWith('tab-')) {
+        return buttonId.slice(4);
+    }
+    return buttonId;
 }
 
 /**
  * Get explicitly selected tab in a set of tabs.
  */
-function getTabBySelection(input: TabsInput, state: TabsState): TabsItem | null {
+function getTabBySelection(
+    input: {
+        id: string;
+        tabs: TabsItem[];
+    },
+    state: TabsState
+): TabsItem | null {
     const activeId = state.activeIds[input.id];
     return activeId ? (input.tabs.find((child) => child.id === activeId) ?? null) : null;
 }
@@ -290,7 +453,13 @@ function getTabBySelection(input: TabsInput, state: TabsState): TabsItem | null
 /**
  * Get the best selected tab in a set of tabs by taking only title into account.
  */
-function getTabByTitle(input: TabsInput, state: TabsState): TabsItem | null {
+function getTabByTitle(
+    input: {
+        id: string;
+        tabs: TabsItem[];
+    },
+    state: TabsState
+): TabsItem | null {
     return (
         input.tabs
             .map((item) => {

packages/gitbook/src/components/DocumentView/Tabs/Tabs.tsx

@@ -9,47 +9,40 @@ import { DynamicTabs, type TabsItem } from './DynamicTabs';
 export function Tabs(props: BlockProps<DocumentBlockTabs>) {
     const { block, ancestorBlocks, document, style, context } = props;
 
-    const tabs: TabsItem[] = [];
-    const tabsBody: React.ReactNode[] = [];
-
-    block.nodes.forEach((tab, index) => {
-        tabs.push({
-            id: tab.meta?.id ?? tab.key!,
-            title: tab.data.title ?? '',
-        });
-
-        tabsBody.push(
-            <Blocks
-                key={tab.key ?? index}
-                nodes={tab.nodes}
-                document={document}
-                ancestorBlocks={[...ancestorBlocks, block, tab]}
-                context={context}
-                blockStyle={tcls('flip-heading-hash')}
-                style={tcls('w-full', 'space-y-4')}
-            />
-        );
-    });
-
-    if (context.mode === 'print') {
-        // When printing, we display the tab, one after the other
-        return (
-            <>
-                {tabs.map((tab, index) => (
-                    <DynamicTabs
-                        key={tab.id}
-                        id={block.key!}
-                        block={block}
-                        tabs={[tab]}
-                        tabsBody={[tabsBody[index]]}
-                        style={style}
-                    />
-                ))}
-            </>
-        );
+    if (!block.key) {
+        throw new Error('Tabs block is missing a key');
     }
 
-    return (
-        <DynamicTabs id={block.key!} block={block} tabs={tabs} tabsBody={tabsBody} style={style} />
-    );
+    const id = block.key;
+
+    const tabs: TabsItem[] = block.nodes.map((tab) => {
+        if (!tab.key) {
+            throw new Error('Tab block is missing a key');
+        }
+
+        return {
+            id: tab.meta?.id ?? tab.key,
+            title: tab.data.title ?? '',
+            body: (
+                <Blocks
+                    key={tab.key}
+                    nodes={tab.nodes}
+                    document={document}
+                    ancestorBlocks={[...ancestorBlocks, block, tab]}
+                    context={context}
+                    blockStyle="flip-heading-hash"
+                    style="w-full space-y-4"
+                />
+            ),
+        };
+    });
+
+    // When printing, we display the tab, one after the other
+    if (context.mode === 'print') {
+        return tabs.map((tab) => {
+            return <DynamicTabs key={tab.id} id={id} tabs={[tab]} className={tcls(style)} />;
+        });
+    }
+
+    return <DynamicTabs id={id} tabs={tabs} className={tcls(style)} />;
 }

packages/gitbook/src/components/DocumentView/Update.tsx

@@ -0,0 +1,82 @@
+import { formatDateFull, formatDateShort, formatNumericDate } from '@/components/utils/dates';
+import { tcls } from '@/lib/tailwind';
+import type { DocumentBlockUpdate, DocumentBlockUpdates } from '@gitbook/api';
+import { assert } from 'ts-essentials';
+import type { BlockProps } from './Block';
+import { Blocks } from './Blocks';
+
+export function Update(props: BlockProps<DocumentBlockUpdate>) {
+    const { block, style, ancestorBlocks, ...contextProps } = props;
+
+    // Get the parent Updates block to retrieve properties from
+    const parentUpdates = ancestorBlocks.find(
+        (ancestor): ancestor is DocumentBlockUpdates => ancestor.type === 'updates'
+    );
+
+    if (!parentUpdates) {
+        assert(parentUpdates, 'Parent updates block should exist');
+        return null;
+    }
+
+    // Get the date for this Update block and parse it to a Date object
+    const date = block.data.date;
+    const parsedDate = parseISODate(date);
+
+    if (!parsedDate) {
+        assert(date, 'Date should exist on Update block');
+        return null;
+    }
+
+    // Then get the format from the parent Updates block and use that format
+    const dateFormat = parentUpdates.data?.format ?? 'full';
+    const displayDate = {
+        numeric: formatNumericDate(parsedDate),
+        full: formatDateFull(parsedDate),
+        short: formatDateShort(parsedDate),
+    }[dateFormat];
+
+    const isSticky = parentUpdates.data.sticky;
+
+    return (
+        <div
+            className={tcls(
+                'relative flex flex-col gap-2 md:flex-row md:gap-4 lg:gap-12 xl:gap-20',
+                style
+            )}
+        >
+            <div
+                className={tcls(
+                    'h-fit w-40 min-w-40 shrink-0',
+                    // Date is sticky on larger screens & if enabled on the parent Updates block
+                    isSticky && 'md:sticky md:top-[calc(var(--toc-top-offset)+8px)]!'
+                )}
+            >
+                <time
+                    // Adding a dateTime attribute for accessibility (and SEO)
+                    dateTime={date}
+                    className="inline-flex items-center font-medium text-neutral-10 text-sm tracking-wide"
+                >
+                    {displayDate}
+                </time>
+            </div>
+            <Blocks
+                {...contextProps}
+                nodes={block.nodes}
+                ancestorBlocks={[...ancestorBlocks, block]}
+                // Remove padding-top from headings when they're the first child (similar to column-first-of-type pattern)
+                style="[&>*:first-child]:!pt-0 flex-1 space-y-4"
+            />
+        </div>
+    );
+}
+
+/**
+ * Parse an ISO date string into a Date object.
+ */
+function parseISODate(value: string): Date | undefined {
+    if (!value) {
+        return undefined;
+    }
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? undefined : date;
+}

packages/gitbook/src/components/DocumentView/Updates.tsx

@@ -0,0 +1,16 @@
+import type { DocumentBlockUpdates } from '@gitbook/api';
+import type { BlockProps } from './Block';
+import { Blocks } from './Blocks';
+
+export function Updates(props: BlockProps<DocumentBlockUpdates>) {
+    const { block, style, ancestorBlocks, ...contextProps } = props;
+
+    return (
+        <Blocks
+            {...contextProps}
+            nodes={block.nodes}
+            ancestorBlocks={[...ancestorBlocks, block]}
+            style={[style, 'flex flex-col gap-20']}
+        />
+    );
+}

packages/gitbook/src/components/DocumentView/spacing.ts

@@ -19,19 +19,19 @@ export function getBlockTextStyle(block: DocumentBlock): {
             };
         case 'heading-1':
             return {
-                textSize: 'text-3xl font-semibold',
+                textSize: 'text-xl @xs:text-2xl @lg:text-3xl font-semibold',
                 lineHeight: 'leading-tight',
                 marginTop: 'column-first-of-type:pt-0 pt-[1em]',
             };
         case 'heading-2':
             return {
-                textSize: 'text-2xl font-semibold',
+                textSize: 'text-lg @xs:text-xl @lg:text-2xl font-semibold',
                 lineHeight: 'leading-snug',
                 marginTop: 'column-first-of-type:pt-0 pt-[0.75em]',
             };
         case 'heading-3':
             return {
-                textSize: 'text-xl font-semibold',
+                textSize: 'text-base @xs:text-lg @lg:text-xl font-semibold',
                 lineHeight: 'leading-snug',
                 marginTop: 'column-first-of-type:pt-0 pt-[0.5em]',
             };

packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx

@@ -17,7 +17,7 @@ export const EmbeddableFrame = React.forwardRef<HTMLDivElement, EmbeddableFrameP
             <div
                 {...divProps}
                 className={tcls(
-                    'flex h-full grow animate-fade-in-slow flex-col overflow-hidden bg-tint-base text-sm text-tint',
+                    'flex h-full grow flex-col overflow-hidden bg-tint-base text-sm text-tint',
                     divProps.className
                 )}
                 ref={ref}

packages/gitbook/src/components/Footer/Footer.tsx

@@ -29,112 +29,123 @@ export function Footer(props: { context: GitBookSiteContext }) {
             className={tcls(
                 'border-tint-subtle border-t',
                 // If the footer only contains a mode toggle, we only show it on smaller screens
-                mobileOnly ? 'xl:hidden' : null
+                mobileOnly ? '@7xl:hidden' : null
             )}
         >
-            <div className={tcls(CONTAINER_STYLE, 'px-4', 'py-8', 'lg:py-12', 'mx-auto')}>
+            <div className="motion-safe:transition-[padding] motion-safe:duration-300 lg:chat-open:pr-80 xl:chat-open:pr-96">
                 <div
                     className={tcls(
-                        'mx-auto grid max-w-3xl site-width-wide:max-w-screen-2xl justify-between gap-12 lg:max-w-none!',
-                        'grid-cols-[auto_auto]',
-                        'lg:grid-cols-[18rem_minmax(auto,48rem)_auto]',
-                        'xl:grid-cols-[18rem_minmax(auto,48rem)_14rem]',
-                        'lg:site-width-wide:grid-cols-[18rem_minmax(auto,80rem)_auto]',
-                        'xl:site-width-wide:grid-cols-[18rem_minmax(auto,80rem)_14rem]',
-                        'lg:page-no-toc:grid-cols-[minmax(auto,48rem)_auto]',
-                        'xl:page-no-toc:grid-cols-[14rem_minmax(auto,48rem)_14rem]',
-                        'lg:[body:has(.site-width-wide,.page-no-toc)_&]:grid-cols-[minmax(auto,90rem)_auto]',
-                        'xl:[body:has(.site-width-wide,.page-no-toc)_&]:grid-cols-[14rem_minmax(auto,90rem)_14rem]'
+                        CONTAINER_STYLE,
+                        'px-4',
+                        'py-8',
+                        '@4xl:py-12',
+                        'mx-auto',
+                        '@container/footer'
                     )}
                 >
-                    {
-                        // Footer Logo
-                        customization.footer.logo ? (
-                            <div className="col-start-1 row-start-1">
-                                <Image
-                                    alt="Logo"
-                                    resize={context.imageResizer}
-                                    sources={{
-                                        light: {
-                                            src: customization.footer.logo.light,
-                                        },
-                                        dark: customization.footer.logo.dark
-                                            ? {
-                                                  src: customization.footer.logo.dark,
-                                              }
-                                            : null,
-                                    }}
-                                    priority="lazy"
-                                    style={[
-                                        'w-auto',
-                                        'max-w-40',
-                                        'lg:max-w-64',
-                                        'max-h-10',
-                                        'lg:max-h-12',
-                                        'object-contain',
-                                        'object-left',
-                                        'rounded-sm',
-                                        'straight-corners:rounded-xs',
-                                    ]}
-                                    sizes={[
-                                        {
-                                            width: 320,
-                                        },
-                                    ]}
-                                />
-                            </div>
-                        ) : null
-                    }
-
-                    {
-                        // Theme Toggle
-                        customization.themes.toggeable ? (
-                            <div className="-col-start-2 row-start-1 flex items-start justify-end xl:hidden">
-                                <React.Suspense fallback={null}>
-                                    <ThemeToggler />
-                                </React.Suspense>
-                            </div>
-                        ) : null
-                    }
-
-                    {
-                        // Navigation groups (split into equal columns)
-                        customization.footer.groups?.length > 0 ? (
-                            <div
-                                className={tcls(
-                                    'col-span-2 lg:page-has-toc:col-span-1 lg:page-has-toc:col-start-2 xl:page-no-toc:col-span-1 xl:page-no-toc:col-start-2'
-                                )}
-                            >
-                                <div className="mx-auto flex max-w-3xl site-width-wide:max-w-screen-2xl flex-col gap-10 sm:flex-row sm:gap-6">
-                                    {partition(customization.footer.groups, FOOTER_COLUMNS).map(
-                                        (column, columnIndex) => (
-                                            <div
-                                                key={columnIndex}
-                                                className="flex flex-1 grow flex-col gap-10"
-                                            >
-                                                {column.map((group, groupIndex) => (
-                                                    <FooterLinksGroup
-                                                        key={groupIndex}
-                                                        group={group}
-                                                        context={context}
-                                                    />
-                                                ))}
-                                            </div>
-                                        )
-                                    )}
+                    <div
+                        className={tcls(
+                            'mx-auto flex @xs:grid @4xl:max-w-none! max-w-3xl site-width-wide:max-w-screen-2xl flex-col justify-between gap-12',
+                            'grid-cols-[auto_auto]',
+                            '@4xl:grid-cols-[18rem_minmax(auto,48rem)_auto]',
+                            '@7xl:grid-cols-[18rem_minmax(auto,48rem)_14rem]',
+                            '@4xl:site-width-wide:grid-cols-[18rem_minmax(auto,80rem)_auto]',
+                            '@7xl:site-width-wide:grid-cols-[18rem_minmax(auto,80rem)_14rem]',
+                            '@4xl:page-no-toc:grid-cols-[minmax(auto,48rem)_auto]',
+                            '@7xl:page-no-toc:grid-cols-[14rem_minmax(auto,48rem)_14rem]',
+                            '@4xl:[body:has(.site-width-wide,.page-no-toc)_&]:grid-cols-[minmax(auto,90rem)_auto]',
+                            '@7xl:[body:has(.site-width-wide,.page-no-toc)_&]:grid-cols-[14rem_minmax(auto,90rem)_14rem]'
+                        )}
+                    >
+                        {
+                            // Footer Logo
+                            customization.footer.logo ? (
+                                <div className="col-start-1 row-start-1">
+                                    <Image
+                                        alt="Logo"
+                                        resize={context.imageResizer}
+                                        sources={{
+                                            light: {
+                                                src: customization.footer.logo.light,
+                                            },
+                                            dark: customization.footer.logo.dark
+                                                ? {
+                                                      src: customization.footer.logo.dark,
+                                                  }
+                                                : null,
+                                        }}
+                                        loading="lazy"
+                                        style={[
+                                            'w-auto',
+                                            'max-w-40',
+                                            '@4xl:max-w-64',
+                                            'max-h-10',
+                                            '@4xl:max-h-12',
+                                            'object-contain',
+                                            'object-left',
+                                            'rounded-sm',
+                                            'straight-corners:rounded-xs',
+                                        ]}
+                                        sizes={[
+                                            {
+                                                width: 320,
+                                            },
+                                        ]}
+                                    />
                                 </div>
-                            </div>
-                        ) : null
-                    }
+                            ) : null
+                        }
 
-                    {
-                        // Legal
-                        customization.footer.copyright ? (
-                            <div className="order-last col-span-full flex w-full grow flex-col items-center gap-2 text-center text-tint text-xs">
-                                <p>{customization.footer.copyright}</p>
-                            </div>
-                        ) : null
-                    }
+                        {
+                            // Theme Toggle
+                            customization.themes.toggeable ? (
+                                <div className="-col-start-2 row-start-1 flex items-start @xs:justify-end xl:hidden">
+                                    <React.Suspense fallback={null}>
+                                        <ThemeToggler />
+                                    </React.Suspense>
+                                </div>
+                            ) : null
+                        }
+
+                        {
+                            // Navigation groups (split into equal columns)
+                            customization.footer.groups?.length > 0 ? (
+                                <div
+                                    className={tcls(
+                                        '@4xl:page-has-toc:col-span-1 @7xl:page-no-toc:col-span-1 col-span-2 @4xl:page-has-toc:col-start-2 @7xl:page-no-toc:col-start-2'
+                                    )}
+                                >
+                                    <div className="mx-auto flex max-w-3xl site-width-wide:max-w-screen-2xl @xl:flex-row flex-col @xl:gap-6 gap-10">
+                                        {partition(customization.footer.groups, FOOTER_COLUMNS).map(
+                                            (column, columnIndex) => (
+                                                <div
+                                                    key={columnIndex}
+                                                    className="flex flex-1 grow flex-col gap-10"
+                                                >
+                                                    {column.map((group, groupIndex) => (
+                                                        <FooterLinksGroup
+                                                            key={groupIndex}
+                                                            group={group}
+                                                            context={context}
+                                                        />
+                                                    ))}
+                                                </div>
+                                            )
+                                        )}
+                                    </div>
+                                </div>
+                            ) : null
+                        }
+
+                        {
+                            // Legal
+                            customization.footer.copyright ? (
+                                <div className="order-last col-span-full flex w-full grow flex-col items-center gap-2 text-center text-tint text-xs">
+                                    <p>{customization.footer.copyright}</p>
+                                </div>
+                            ) : null
+                        }
+                    </div>
                 </div>
             </div>
         </footer>

packages/gitbook/src/components/Header/CurrentContentIcon.tsx

@@ -51,6 +51,7 @@ export function CurrentContentIcon(
                           },
                       }
             }
+            preload
             {...imageProps}
         />
     );

packages/gitbook/src/components/Header/Header.tsx

@@ -3,6 +3,7 @@ import type { GitBookSiteContext } from '@/lib/context';
 import { CONTAINER_STYLE, HEADER_HEIGHT_DESKTOP } from '@/components/layout';
 import { getSpaceLanguage, t } from '@/intl/server';
 import { tcls } from '@/lib/tailwind';
+import type { SiteSpace } from '@gitbook/api';
 import { SearchContainer } from '../Search';
 import { SiteSectionTabs, encodeClientSiteSections } from '../SiteSections';
 import { HeaderLink } from './HeaderLink';
@@ -18,9 +19,12 @@ import { TranslationsDropdown } from './SpacesDropdown';
 export function Header(props: {
     context: GitBookSiteContext;
     withTopHeader?: boolean;
-    withVariants?: 'generic' | 'translations';
+    variants: {
+        generic: SiteSpace[];
+        translations: SiteSpace[];
+    };
 }) {
-    const { context, withTopHeader, withVariants } = props;
+    const { context, withTopHeader, variants } = props;
     const { siteSpace, siteSpaces, sections, customization } = context;
 
     const withSections = Boolean(
@@ -63,7 +67,7 @@ export function Header(props: {
                     'theme-bold:shadow-tint-12/2'
                 )}
             >
-                <div className="transition-[padding] duration-300 lg:chat-open:pr-80 xl:chat-open:pr-96">
+                <div className="transition-all duration-300 lg:chat-open:pr-80 xl:chat-open:pr-96">
                     <div
                         className={tcls(
                             'gap-4',
@@ -75,13 +79,19 @@ export function Header(props: {
                             'py-3',
                             'min-h-16',
                             'sm:h-16',
-                            CONTAINER_STYLE
+                            CONTAINER_STYLE,
+                            'transition-[max-width] duration-300',
+                            '@container/header'
                         )}
                     >
                         <div
                             className={tcls(
-                                'flex max-w-full lg:basis-72',
-                                'min-w-0 shrink items-center justify-start gap-2 lg:gap-4'
+                                'flex max-w-full',
+                                'min-w-0 shrink items-center justify-start gap-2 lg:gap-4',
+                                'search' in customization.styling &&
+                                    customization.styling.search === 'prominent'
+                                    ? 'lg:@2xl:basis-72'
+                                    : null
                             )}
                         >
                             <HeaderMobileMenu
@@ -91,8 +101,8 @@ export function Header(props: {
                                     'theme-bold:text-header-link',
                                     'hover:bg-tint-hover',
                                     'hover:theme-bold:bg-header-link/3',
-                                    withVariants === 'generic'
-                                        ? 'xl:hidden'
+                                    variants.generic.length > 1
+                                        ? 'lg:hidden'
                                         : 'page-no-toc:hidden lg:hidden'
                                 )}
                             />
@@ -104,36 +114,37 @@ export function Header(props: {
                                 'flex',
                                 'grow-0',
                                 'shrink-0',
-                                'md:basis-56',
+                                '@2xl:basis-56',
                                 'justify-self-end',
                                 'items-center',
                                 'gap-2',
+                                'transition-[margin] duration-300',
                                 'search' in customization.styling &&
                                     customization.styling.search === 'prominent'
                                     ? [
-                                          'md:grow-[0.8]',
-                                          'lg:basis-40',
-                                          'md:max-w-[40%]',
-                                          'lg:max-w-lg',
-                                          'lg:ml-[max(calc((100%-18rem-48rem)/2),1.5rem)]', // container (100%) - sidebar (18rem) - content (48rem)
-                                          'xl:ml-[max(calc((100%-18rem-48rem-14rem-3rem)/2),1.5rem)]', // container (100%) - sidebar (18rem) - content (48rem) - outline (14rem) - margin (3rem)
-                                          'md:mr-auto',
+                                          '@2xl:grow-[0.8]',
+                                          '@4xl:basis-40',
+                                          '@2xl:max-w-[40%]',
+                                          '@4xl:max-w-lg',
+                                          'lg:@2xl:ml-[max(calc((100%-18rem-48rem)/2),1.5rem)]', // container (100%) - sidebar (18rem) - content (48rem)
+                                          'not-chat-open:xl:ml-[max(calc((100%-18rem-48rem-14rem-3rem)/2),1.5rem)]', // container (100%) - sidebar (18rem) - content (48rem) - outline (14rem) - margin (3rem)
+                                          '@2xl:mr-auto',
                                           'order-last',
-                                          'md:order-[unset]',
+                                          '@2xl:order-[unset]',
                                       ]
                                     : ['order-last']
                             )}
                         >
                             <SearchContainer
                                 style={customization.styling.search}
-                                withVariants={withVariants === 'generic'}
+                                withVariants={variants.generic.length > 1}
                                 withSiteVariants={
                                     sections?.list.some(
                                         (s) =>
                                             s.object === 'site-section' && s.siteSpaces.length > 1
                                     ) ?? false
                                 }
-                                withSections={!!sections}
+                                withSections={sections ? sections.list.length > 1 : false}
                                 section={
                                     sections
                                         ? // Client-encode to avoid a serialisation issue that was causing the language selector to disappear
@@ -150,7 +161,7 @@ export function Header(props: {
                         </div>
 
                         {customization.header.links.length > 0 ||
-                        (!withSections && withVariants === 'translations') ? (
+                        (!withSections && variants.translations.length > 1) ? (
                             <HeaderLinks>
                                 {customization.header.links.length > 0 ? (
                                     <>
@@ -170,11 +181,15 @@ export function Header(props: {
                                         />
                                     </>
                                 ) : null}
-                                {!withSections && withVariants === 'translations' ? (
+                                {!withSections && variants.translations.length > 1 ? (
                                     <TranslationsDropdown
                                         context={context}
-                                        siteSpace={siteSpace}
-                                        siteSpaces={siteSpaces}
+                                        siteSpace={
+                                            variants.translations.find(
+                                                (space) => space.id === siteSpace.id
+                                            ) ?? siteSpace
+                                        }
+                                        siteSpaces={variants.translations}
                                         className="flex! theme-bold:text-header-link hover:theme-bold:bg-header-link/3"
                                     />
                                 ) : null}
@@ -187,14 +202,17 @@ export function Header(props: {
             {sections && withSections ? (
                 <div className="transition-[padding] duration-300 lg:chat-open:pr-80 xl:chat-open:pr-96">
                     <SiteSectionTabs sections={encodeClientSiteSections(context, sections)}>
-                        {withVariants === 'translations' ? (
-                            <div className="before:contents[] flex self-start py-2 before:mr-4 before:border-tint before:border-l">
-                                <TranslationsDropdown
-                                    context={context}
-                                    siteSpace={siteSpace}
-                                    siteSpaces={siteSpaces}
-                                />
-                            </div>
+                        {variants.translations.length > 1 ? (
+                            <TranslationsDropdown
+                                context={context}
+                                siteSpace={
+                                    variants.translations.find(
+                                        (space) => space.id === siteSpace.id
+                                    ) ?? siteSpace
+                                }
+                                siteSpaces={variants.translations}
+                                className="my-2 ml-2 self-start"
+                            />
                         ) : null}
                     </SiteSectionTabs>
                 </div>

packages/gitbook/src/components/Header/HeaderLinks.tsx

@@ -14,7 +14,7 @@ export async function HeaderLinks({ children, style }: HeaderLinksProps) {
         <div
             className={tcls(
                 styles.containerHeaderlinks,
-                'lg:[&>.button+.button]:-ml-2 z-20 ml-auto flex min-w-9 shrink grow items-center justify-end gap-x-4 lg:gap-x-6 xl:grow-0',
+                '@4xl:[&>.button+.button]:-ml-2 z-20 ml-auto flex min-w-9 shrink grow @7xl:grow-0 items-center justify-end @4xl:gap-x-6 gap-x-4',
                 style
             )}
         >

packages/gitbook/src/components/Header/HeaderLogo.tsx

@@ -3,6 +3,7 @@ import type { GitBookSiteContext } from '@/lib/context';
 import { Image } from '@/components/utils';
 import { tcls } from '@/lib/tailwind';
 
+import { resolveContentRef } from '@/lib/references';
 import { Link } from '../primitives';
 import { CurrentContentIcon } from './CurrentContentIcon';
 
@@ -18,9 +19,13 @@ export async function HeaderLogo(props: HeaderLogoProps) {
     const { context } = props;
     const { customization, linker } = context;
 
+    const primaryLink = customization.header.primaryLink
+        ? await resolveContentRef(customization.header.primaryLink, context)
+        : null;
+
     return (
         <Link
-            href={linker.toPathInSite('')}
+            href={primaryLink?.href ?? linker.toPathInSite('')}
             className={tcls('group/headerlogo', 'min-w-0', 'shrink', 'flex', 'items-center')}
         >
             {customization.header.logo ? (
@@ -46,7 +51,7 @@ export async function HeaderLogo(props: HeaderLogoProps) {
                             width: 260,
                         },
                     ]}
-                    priority="high"
+                    preload
                     style={tcls(
                         'overflow-hidden',
                         'shrink',

packages/gitbook/src/components/Header/SpacesDropdown.tsx

@@ -45,11 +45,12 @@ export function SpacesDropdown(props: {
             }
         >
             <SpacesDropdownMenuItems
-                slimSpaces={siteSpaces.map((space) => ({
-                    id: space.id,
-                    title: space.title,
-                    url: getSiteSpaceURL(context, space),
-                    isActive: space.id === siteSpace.id,
+                slimSpaces={siteSpaces.map((siteSp) => ({
+                    id: siteSp.id,
+                    title: siteSp.title,
+                    url: getSiteSpaceURL(context, siteSp),
+                    isActive: siteSp.id === siteSpace.id,
+                    spaceId: siteSp.space.id,
                 }))}
                 curPath={siteSpace.path}
             />

packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx

@@ -1,26 +1,39 @@
 'use client';
 
-import type { Space } from '@gitbook/api';
-
 import { joinPath } from '@/lib/paths';
-import { useCurrentPagePath } from '../hooks';
+import { useCurrentPageMetadata, useCurrentPagePath } from '../hooks';
 import { DropdownMenuItem } from '../primitives/DropdownMenu';
 
 interface VariantSpace {
-    id: Space['id'];
-    title: Space['title'];
+    id: string;
+    title: string;
     url: string;
     isActive: boolean;
+    spaceId: string;
 }
 
-// When switching to a different variant space, we reconstruct the URL by swapping the space path.
-function useVariantSpaceHref(variantSpaceUrl: string, currentSpacePath: string, active = false) {
+/**
+ * Return the href for a variant space, taking into account the current page path and metadata.
+ */
+function useVariantSpaceHref(variantSpace: VariantSpace, currentSpacePath: string, active = false) {
     const currentPathname = useCurrentPagePath();
+    const { metaLinks } = useCurrentPageMetadata();
+
+    // We first check if there is an alternate link for the variant space in the current page metadata.
+    const pageHasAlternateForVariant = metaLinks?.alternates.find(
+        (alt) => alt.space?.id === variantSpace.spaceId
+    );
+    if (pageHasAlternateForVariant) {
+        return pageHasAlternateForVariant.href;
+    }
+
+    // If there is no alternate link, we reconstruct the URL by swapping the space path.
 
     // We need to ensure that the variant space URL is not the same as the current space path.
     // If it is, we return only the variant space URL to redirect to the root of the variant space.
     // This is necessary in case the currentPathname is the same as the variantSpaceUrl,
     // otherwise we would redirect to the same space if the variant space that we are switching to is the default one.
+    const variantSpaceUrl = variantSpace.url;
     if (!active && currentPathname.startsWith(`${currentSpacePath}/`)) {
         return variantSpaceUrl;
     }
@@ -44,7 +57,7 @@ export function SpacesDropdownMenuItem(props: {
     currentSpacePath: string;
 }) {
     const { variantSpace, active, currentSpacePath } = props;
-    const variantHref = useVariantSpaceHref(variantSpace.url, currentSpacePath, active);
+    const variantHref = useVariantSpaceHref(variantSpace, currentSpacePath, active);
 
     return (
         <DropdownMenuItem key={variantSpace.id} href={variantHref} active={active}>

packages/gitbook/src/components/Header/headerLinks.module.css

@@ -1,4 +1,4 @@
-@media (max-width: 1279px) {
+@container header (width < 1280px) {
     .containerHeaderlinks {
         container-type: inline-size;
         container-name: headerlinks;

packages/gitbook/src/components/Insights/InsightsProvider.tsx

@@ -127,9 +127,16 @@ export function InsightsProvider(props: InsightsProviderProps) {
         }
     });
 
-    const flushBatchedEvents = useDebounceCallback(() => {
-        flushEventsSync();
-    }, 1500);
+    const flushBatchedEvents = useDebounceCallback(
+        () => {
+            flushEventsSync();
+        },
+        1500,
+        {
+            // We don't want to debounce indefinitely, after 1 minute we want to flush anyway
+            maxWait: 60000,
+        }
+    );
 
     // Flush pending events once the visitor session has been fetched
     React.useEffect(() => {