Docs Updates #6 - Add Typesense docs search

[bryantgillespie]

Changes

• Replace Algolia search with a Typesense-backed docs search palette.
• Add direct browser search via public Typesense key, grouped page results, section chips, highlights, matched headings, and preference-aware ranking.
• Add docs indexing pipeline for Typesense: markdown chunking, schema creation, synonym sync, import validation, blue/green alias swaps.
• Add GitHub Actions workflow to index production on main and preview aliases for same-repo PRs.
• Add Typesense env docs, alias parsing, branch alias resolution, and focused search tests.

Potential Risks

• Requires valid TYPESENSE_URL, TYPESENSE_PUBLIC_API_KEY, and TYPESENSE_PRIVATE_API_KEY secrets/env vars before search/indexing works.
• PR preview indexing only runs for same-repo PRs; fork PRs won't get preview indexes.
• OpenAPI/API reference indexing is explicitly deferred, so API search coverage depends on existing markdown content only.
• Browser queries hit Typesense directly, so public key permissions must stay search-only.

Review Notes

• Search UI behavior is mostly in DocsSearchPalette.vue, useDocsSearch.ts, and app/utils/searchResults.ts.
• Index behavior is mostly in scripts/index-docs.ts and scripts/index-docs-chunker.ts.
• Validated with pnpm test:search: 5 files, 12 tests passed.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	May 26, 2026 8:10pm

[Copilot]

Pull request overview

Replaces the existing Algolia-based docs search with a Typesense-backed search palette and adds an end-to-end indexing pipeline (chunking, synonyms, and blue/green alias swaps) plus CI automation to keep production and PR preview indexes up to date.

Changes:

• Add a Typesense-powered search UI (command palette + preview pane) with grouped results, section chips, and preference-aware ranking.
• Add a Typesense indexing script with Markdown chunking, synonym sync, import validation, and blue/green alias swapping.
• Add supporting tests, Vitest/Nuxt test setup, and a GitHub Actions workflow for indexing on main and same-repo PRs.

Reviewed changes

Copilot reviewed 31 out of 33 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
vitest.config.ts	Adds Nuxt Vitest configuration (happy-dom).
tests/shared/parseTypesenseUrl.test.ts	Tests Typesense URL parsing behavior.
tests/services/typesenseService.test.ts	Tests multi_search facet merging behavior.
tests/scripts/index-docs-chunker.test.ts	Tests Markdown chunking output quality on real content pages.
tests/lib/typesenseAlias.test.ts	Tests branch alias/slug helpers and env precedence.
tests/components/DocsSearchPalette.test.ts	Tests palette behavior (section cycling, preview, actions).
shared/utils/parseTypesenseUrl.ts	Adds Typesense URL parsing helper for both browser and scripts.
server/utils/contentToMarkdown.ts	Introduces Markdown/directive rewriting utility (currently unused).
server/data/synonyms.ts	Adds editorial synonym definitions for Typesense.
server/api/search/debug/[...slug].get.ts	Adds a dev-only endpoint to inspect indexed chunks for a page.
scripts/tsconfig.json	Updates scripts TS config for repo path aliases and TS options.
scripts/nuxt-shims.d.ts	Adds ambient Nuxt auto-import shims for scripts typechecking.
scripts/index-docs.ts	Adds Typesense indexing pipeline (schema, synonyms, import, alias swap).
scripts/index-docs-chunker.ts	Adds Markdown chunking + document shaping for Typesense indexing.
README.md	Updates documentation from Algolia to Typesense + indexing instructions.
package.json	Adds index:docs + test:search scripts and new deps (Typesense, remark, vitest, etc).
nuxt.config.ts	Removes Algolia module/CSS and adds public runtime config for Typesense.
lib/typesenseAlias.ts	Adds branch-to-alias resolution for prod/preview collections.
app/utils/transformAlgoliaSearchItems.ts	Removes Algolia-specific hit transformation utility.
app/utils/searchResults.ts	Adds Typesense result shaping (group flattening, highlighting, sort_by builder).
app/services/typesenseService.ts	Adds Typesense search client (search + multi_search refinement facet merging).
app/composables/useSearchOverlay.ts	Switches search overlay to mount the new palette.
app/composables/useDocsSearch.ts	Adds client-side search composable (debounce, personalization, facets).
app/components/HomeHero.vue	Updates home hero search trigger styling/icon and opens new overlay.
app/components/DocsSearchTrigger.vue	Replaces Algolia trigger with a button that opens the new overlay.
app/components/DocsSearchPreview.vue	Adds preview pane for highlighted result.
app/components/DocsSearchPalette.vue	Adds the main command palette UI, grouping, chips, preview, and navigation.
app/assets/css/algolia.css	Removes Algolia DocSearch styling.
app/app.config.ts	Switches search backend flag from algolia to typesense.
.nuxtrc	Pins Nuxt test-utils setup metadata.
.github/workflows/search-index.yml	Adds CI workflow to index Typesense on main and same-repo PRs.
.env.example	Updates example env vars from Algolia to Typesense.

Comments suppressed due to low confidence (1)

scripts/tsconfig.json:22

• scripts/nuxt-shims.d.ts won't be included in this TS project because the tsconfig "include" glob only matches "/*.ts" (not "/*.d.ts"). If these ambient declarations are needed for typecheck:scripts, update the include pattern (or add a "files" entry) so the shim is actually picked up; otherwise consider removing the shim file to avoid confusion.

		"skipLibCheck": true
	},
	"include": ["**/*.ts"]
}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.