Merge branch 'main' into cloudflare-deployment-docs

Author: LZylstra

.env.example

@@ -1,7 +1,16 @@
-ALGOLIA_API_KEY=algolia_api_key
-ALGOLIA_APPLICATION_ID=algolia_application_id
+TYPESENSE_URL=https://your-cluster.a1.typesense.net
+TYPESENSE_PUBLIC_API_KEY=your_search_only_api_key
+TYPESENSE_PRIVATE_API_KEY=typesense_private_api_key_required_for_indexing_only
+# Optional. Overrides the branch-derived read alias.
+# TYPESENSE_COLLECTION=directus-docs
 DIRECTUS_URL=https://marketing-directus-url.com
 GOOGLE_TAG_MANAGER_ID=GTM-PTLT3GH
-NUXT_UI_PRO_LICENSE=nuxt_ui_pro_license_key_needed_to_build
 POSTHOG_API_HOST=https://directus.io/ingest
 POSTHOG_API_KEY=phc_secret_key_here
+NUXT_PUBLIC_SITE_URL=https://directus.com
+NUXT_PUBLIC_OG_BASE_URL=https://og.directus.com
+# Required outside local OG worker dev.
+# NUXT_OG_SIGNING_SECRET=shared_secret_from_website_og_worker
+# OG_SIGNING_SECRET=shared_secret_from_website_og_worker
+# Optional. Fine-grained PAT, public repos read-only. Required for code search and raises GitHub raw rate limits.
+# GITHUB_TOKEN=github_pat_...

.githooks/pre-commit

@@ -0,0 +1,9 @@
+#!/bin/sh
+set -e
+
+if ! command -v pnpm >/dev/null 2>&1; then
+	echo "warning: pnpm not found; skipping stable ID hook" >&2
+	exit 0
+fi
+
+pnpm stable-ids:ensure --staged

.githooks/pre-push

@@ -0,0 +1,13 @@
+#!/bin/sh
+set -e
+
+if ! git fetch origin main --quiet; then
+	echo "warning: failed to fetch origin/main; using local ref for redirect check" >&2
+fi
+
+if git diff --quiet origin/main...HEAD -- content redirects.json content.config.ts; then
+	exit 0
+fi
+
+echo "Checking redirects for docs changes..."
+pnpm redirects:check

.github/workflows/search-index.yml

@@ -0,0 +1,76 @@
+name: Search Index
+
+on:
+  push:
+    branches:
+      - main
+    paths: &index-paths
+      - 'content/**'
+      - 'scripts/index-docs.ts'
+      - 'scripts/index-docs-chunker.ts'
+      - 'shared/utils/parseTypesenseUrl.ts'
+      - 'shared/utils/docsSections.ts'
+      - 'app/utils/slugify.ts'
+      - 'server/data/synonyms.ts'
+      - 'lib/typesenseAlias.ts'
+      - 'pnpm-lock.yaml'
+      - '.github/workflows/search-index.yml'
+  pull_request:
+    branches:
+      - main
+    paths: *index-paths
+  workflow_dispatch:
+
+concurrency:
+  group: search-index-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  preview-index:
+    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    env:
+      TYPESENSE_URL: ${{ secrets.TYPESENSE_URL }}
+      TYPESENSE_PUBLIC_API_KEY: ${{ secrets.TYPESENSE_PUBLIC_API_KEY }}
+      TYPESENSE_PRIVATE_API_KEY: ${{ secrets.TYPESENSE_PRIVATE_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Index preview collection
+        run: pnpm index:docs
+
+  prod-index:
+    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    env:
+      TYPESENSE_URL: ${{ secrets.TYPESENSE_URL }}
+      TYPESENSE_PUBLIC_API_KEY: ${{ secrets.TYPESENSE_PUBLIC_API_KEY }}
+      TYPESENSE_PRIVATE_API_KEY: ${{ secrets.TYPESENSE_PRIVATE_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Index production collection
+        run: pnpm index:docs

.gitignore

@@ -27,3 +27,5 @@ logs
 .vercel
 
 .vscode
+
+.claude/scheduled_tasks.lock

.nuxtrc

@@ -0,0 +1 @@
+setups.@nuxt/test-utils="4.0.3"

CLAUDE.md

@@ -62,7 +62,7 @@ Reusable content fragments live in `/content/_partials/` and are included via th
 
 ### Modules & Integrations
 
-Nuxt modules: `@nuxt/ui-pro`, `@nuxt/content`, `@nuxtjs/seo`, `@nuxtjs/algolia` (conditional on env vars), `@vueuse/nuxt`, `@nuxt/scripts`. Custom PostHog module in `/modules/posthog/`.
+Nuxt modules: `@nuxt/ui-pro`, `@nuxt/content`, `@nuxtjs/robots`, `@nuxtjs/sitemap`, `@nuxtjs/algolia` (conditional on env vars), `@vueuse/nuxt`, `@nuxt/scripts`. Custom PostHog module in `/modules/posthog/`.
 
 ## Code Style
 

README.md

@@ -13,7 +13,7 @@ Welcome! This is the repo for [Directus' documentation](https://docs.directus.io
 
 ### Requirements
 
-- Node.js 22
+- Node.js 22.18 or later
 - pnpm
 
 ### Install Dependencies
@@ -47,6 +47,48 @@ pnpm dev
 pnpm build
 ```
 
+### Repository Tooling
+
+The repository includes scripts that keep docs routes stable when files move and that index the docs into Typesense.
+
+```bash
+pnpm stable-ids:ensure  # Add missing stableId frontmatter
+pnpm stable-ids:check   # Validate stableId frontmatter
+pnpm redirects:sync     # Update redirects.json for moved pages
+pnpm redirects:check    # Check redirect coverage without writing files
+pnpm index:docs         # Build the search index in Typesense
+pnpm typecheck:scripts  # Type check repository scripts
+```
+
+`pnpm install` configures `.githooks` for the repository when no custom `core.hooksPath` is set. The pre-commit hook can add missing `stableId` values to staged docs files. The pre-push hook checks redirects when docs content, redirect configuration, or content configuration changes.
+
+## ✍️ Authoring Content
+
+Pages live as Markdown files under `content/`. Frontmatter fields are validated by the schema in `content.config.ts`.
+
+### Framework Guides
+
+Framework guides live under `content/frameworks/<framework>/`. The numeric prefix on filenames (`01.`, `02.`, …) controls sidebar sort order only — it has no semantic meaning, renumber freely.
+
+The `section` frontmatter field controls grouping on the `/frameworks/<framework>` hub page:
+
+- `section: start-here` — appears in the "Start Here" block at the top.
+- `section: guides` (or unset) — appears in the "Guides" block below.
+
+Minimal frontmatter for a new framework guide:
+
+```yaml
+---
+title: Fetch Data from Directus with Foo
+description: Learn how to integrate Directus in your Foo app.
+section: start-here
+technologies:
+  - foo
+navigation:
+  title: Data Fetching
+---
+```
+
 ## ☁️ Deploying the Docs
 
 The documentation automatically deploys to Vercel when changes are merged into the main branch. Simply:
@@ -68,9 +110,45 @@ The documentation automatically deploys to Vercel when changes are merged into t
 - [GitHub Issues](https://github.com/directus/docs/issues) (Report Bugs)
 - [Roadmap](https://roadmap.directus.io) (Roadmap & Feature Requests)
 
-## Making changes to Algolia Search
+## 🔍 Search
+
+Search is powered by [Typesense](https://typesense.org). The browser palette (`UCommandPalette`-based) lives at `app/components/DocsSearchPalette.vue` and queries Typesense directly via `app/services/typesenseService.ts`. The official `typesense` npm client is used by the indexer only.
+
+### Indexing
+
+The indexer at `scripts/index-docs.ts` walks `/content`, chunks each Markdown page, attaches synonyms, and pushes everything to Typesense. OpenAPI indexing is deferred to a later branch. Run it locally with:
+
+```bash
+pnpm index:docs
+```
+
+CI runs the same command on every push to `main` (production index) and on every PR commit (per-branch preview index). See `.github/workflows/search-index.yml`.
+
+### Collection naming
+
+Indexes use a blue/green slot pattern with a stable alias:
+
+- `main` -> alias `directus-docs`, slots `directus-docs-a` / `directus-docs-b`
+- Branch `bry/foo` -> alias `directus-docs-preview-bry-foo`, slots `...-a` / `...-b`
+- Local branch runs use the same branch-derived alias as CI
+
+Each indexer run writes to whichever slot the alias is not currently pointing at, swaps the alias, then deletes the previous slot.
+
+For one-off writes, override the index target with `TYPESENSE_INDEX_TARGET=...`.
+
+The browser reads from `TYPESENSE_COLLECTION` when set. Otherwise it derives the same branch alias as the indexer. The app reads the alias, never the `-a` / `-b` slot name.
+
+### Ranking
+
+Section boosts and personalization live in `buildPersonalizedSortBy` in `app/composables/useDocsSearch.ts`. The same `sectionPriority` array drives both the Typesense `_eval` boost order and the chip-bar render order in the palette.
+
+### Synonyms
+
+Search synonyms live in `server/data/synonyms.ts` and are pushed to Typesense on every indexer run. Two formats: `multiway` (equivalent terms) and `oneway` (directional shorthand -> canonical, e.g. `db -> database`). Header comment in the file explains both.
+
+### Search-friendly content
 
-The docs make use of the Algolia Crawler to index the content. The crawler is found at the bottom left in the Algolia dashboard under `Data Sources > Crawler > directus`. To make changes on how the crawler works, go to the `Editor` tab and make your changes. By default the crawler runs once a day but you can also manually run it. In order to tweak the ranking of search results, go to the `Search > Configure > Index > Configuration > Ranking and Sorting` tab.
+Write H2s and first paragraphs so they work as standalone search results.
 
 <br />