Skip to content

refactor(docs): migrate chat-sdk.dev to @vercel/geistdocs#686

Merged
molebox merged 5 commits into
mainfrom
docs/migrate-to-geistdocs
Jul 9, 2026
Merged

refactor(docs): migrate chat-sdk.dev to @vercel/geistdocs#686
molebox merged 5 commits into
mainfrom
docs/migrate-to-geistdocs

Conversation

@molebox

@molebox molebox commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Migrates apps/docs from locally-copied geistdocs runtime code to the published @vercel/geistdocs package (1.8.2), following the official migration guide. Net −8,400 lines.

Package-backed now

  • Docs page + layouts: createDocsPage, GeistdocsDocsLayout, GeistdocsHomeLayout (JSON-LD + sr-only markdown hints preserved via renderTop)
  • Navbar (OSS product switcher via navbarOssProducts), footer, provider, search dialog, page actions (edit source, feedback, copy page, Ask AI, open-in-chat, scroll top)
  • /api/search → createSearchRoute, /api/chat → createChatRoute (AI SDK v6; AI Gateway default, optional GEISTDOCS_CHAT_PROXY_URL)
  • llms.mdx → createDocsMarkdownRoute, sitemap.md → createSitemapMarkdownRoute (now includes an Adapters section)
  • New: /agents.md via createAgentsRoute, backed by a new agent readiness config
  • proxy.ts → createProxy with explicit markdownRoutes for /docs → llms.mdx and /adapters → adapters.mdx (adds AI-agent UA rewrites)
  • CSS: @vercel/geistdocs/styles.css + slim local overrides (shadcn tokens for remaining components/ui, body tint, prose inline code, #nd-* tweaks); code blocks now use the geist Shiki theme
  • Icons/logos from @vercel/geistdocs/assets/*; feedback via the package action (same geistdocs.com endpoint + siteId)

Kept local by design

  • Curated /llms.txt index + /llms-full.txt corpus — the published AGENTS.md/SKILL.md artifacts and integration tests reference this exact contract
  • The adapters section (README fetching, OG images, JSON-LD, feature matrices, adapters.mdx markdown route) — now rendered inside the package docs layout
  • RSS and OG image routes (app-owned per the migration guide)
  • Skipped /.well-known/mcp.json: no MCP servers configured, and the proxy matcher must keep excluding .well-known for the served agent-skills files

Cleanup

  • Deleted local copies: components/geistdocs/* chrome, components/ai-elements/*, chat hooks/persistence, feedback server actions, unused shadcn primitives, geistcn logo/icon fallbacks covered by package assets
  • Removed 13 now-unused deps (ai@5, @ai-sdk/react@2, dexie, jotai, cmdk, vaul, mermaid, nanoid, react-player, use-stick-to-bottom, @orama/tokenizers, dexie-react-hooks, next-themes)
  • Updated docs-llms.test.ts proxy assertions to the createProxy markdown-route shape

Behavior changes to be aware of

  • Code blocks use the geist Shiki theme instead of GitHub light/dark
  • Ask AI history is no longer persisted in IndexedDB (package owns the panel)
  • Adapters sidebar uses the standard geistdocs tree rendering instead of the bespoke grouped sidebar
  • Per-page markdown output appends the standard geistdocs footer links (/sitemap.md, /llms.txt, /agents.md)

Test plan

  • pnpm validate green (knip + check + typecheck + test + build)
  • Smoke-tested against next build && next start: /, /docs, /adapters, /agents.md, /llms.txt, /llms-full.txt, /sitemap.md, page-level .md URLs for both docs and adapters, Accept: text/markdown negotiation, search API, JSON-LD, sr-only markdown hints, edit-source URLs (apps/docs/content/docs/{path}), OSS navbar, page actions
  • Verified compiled CSS chunks contain the home grid, Shiki palette, and geist utilities (note: stale turbopack dev caches from before this change can serve incomplete CSS — rm -rf apps/docs/.next fixes it)

Checklist

  • All commits are signed and verified
  • All commits are signed off for the DCO (git commit -s)
  • pnpm validate passes
  • Changeset added (or N/A — docs app + tests only, no package behavior change)
  • Documentation updated (or N/A)

@molebox
refactor(docs): migrate chat-sdk.dev to @vercel/geistdocs
7ec7971 
Replace the locally-copied geistdocs runtime in apps/docs with the
published @vercel/geistdocs package, keeping site-specific content,
custom sections, and established public contracts local.

Package-backed now: docs page + layouts (createDocsPage,
GeistdocsDocsLayout/HomeLayout), navbar/footer/provider, search
(createSearchRoute), Ask AI (createChatRoute, AI SDK v6), per-page
markdown (createDocsMarkdownRoute), sitemap.md
(createSitemapMarkdownRoute, now with an Adapters section), a new
/agents.md surface (createAgentsRoute), proxy (createProxy with
explicit markdownRoutes for /docs and /adapters), MDX defaults,
design tokens/styles, and icon/logo assets.

Kept local by design: the curated /llms.txt index and /llms-full.txt
corpus (referenced by the published SKILL.md artifacts and tests), the
adapters section (README fetching, OG images, JSON-LD, feature
matrices, adapters.mdx markdown route), RSS, and the OG image route.

Also: removes 13 now-unused dependencies (ai@5, @ai-sdk/react@2,
dexie, jotai, cmdk, vaul, mermaid, etc.), slims the local CSS to
overrides on top of @vercel/geistdocs/styles.css, and updates the
docs-llms integration test to assert on the new proxy shape.

Signed-off-by: molebox <rich@vercel.com>
@molebox molebox requested a review from a team as a code owner July 8, 2026 12:21
@vercel

vercel Bot commented Jul 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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

Project Deployment Actions Updated (UTC)
chat Ready Ready Preview, Comment, Open in v0 Jul 9, 2026 1:25pm
chat-sdk-nextjs-chat Ready Ready Preview, Comment, Open in v0 Jul 9, 2026 1:25pm

@molebox
fix(docs): restore dark-mode elevated background scale
b3e0214 
The @vercel/geistdocs stylesheet inverts the dark background tokens
(background-100 becomes pure black over a near-black background-200),
which flattened elevated surfaces on the homepage: the Chat SDK Core
code window blended into the page and the active code-showcase tab had
no visible state. Restore the site's original dark values (elevated
background-100 over pure-black background-200) in the local override
layer.

Signed-off-by: molebox <rich@vercel.com>
@molebox
chore(docs): bump @vercel/geistdocs to 1.9.0
965cc99 
Brings the Ask AI panel z-index fix (paints below the search command
menu) and adds the Turborepo logo to the navbar OSS products dropdown,
matching the new package default (we keep an explicit list because the
package default includes chat-sdk.dev itself).

Signed-off-by: molebox <rich@vercel.com>
@molebox
Merge remote-tracking branch 'origin/main' into docs/migrate-to-geist…
42b2a1e 
…docs

Signed-off-by: molebox <rich@vercel.com>

# Conflicts:
#	apps/docs/app/api/chat/route.ts
@molebox

molebox commented Jul 9, 2026

Copy link
Copy Markdown
Contributor Author

Merged main to resolve the conflict in apps/docs/app/api/chat/route.ts.

Main's #687 switched the old custom chat route's model to xai/grok-4.5; this branch replaces that route with createChatRoute from @vercel/geistdocs, which currently hardcodes openai/gpt-4.1-mini (no model option as of 1.9.0). Resolution keeps the package-backed route, so the Ask AI model reverts to gpt-4.1-mini until geistdocs exposes a model option — the docs/guide content changes from #687 (grok-4.5 in code samples and pages) merge through untouched.

Follow-up: propose a model option for createChatRoute upstream in vercel/geistdocs so sites can pin their own model.

@molebox

molebox commented Jul 9, 2026

Copy link
Copy Markdown
Contributor Author

Upstream PR for the Ask AI model regression: vercel/geistdocs#142 adds a model option to createChatRoute (defaults to the current openai/gpt-4.1-mini).

Plan: once that lands and a release is cut, bump @vercel/geistdocs here and pass model: "xai/grok-4.5" in app/api/chat/route.ts to restore #687's intent before merging.

@molebox
chore(docs): bump @vercel/geistdocs to 1.10.0 and set Ask AI model
6e3b373 
1.10.0 adds the createChatRoute model option (vercel/geistdocs#142).
Pass xai/grok-4.5 to restore the model set in #687, which the
package-backed chat route had reverted to its hardcoded default.

Signed-off-by: molebox <rich@vercel.com>
@molebox

molebox commented Jul 9, 2026

Copy link
Copy Markdown
Contributor Author

geistdocs 1.10.0 is out with the model option (vercel/geistdocs#142). Bumped the package and set model: "xai/grok-4.5" in app/api/chat/route.ts (6e3b373) — the Ask AI model regression from the #687 conflict is resolved. No open follow-ups on this PR.

@molebox molebox merged commit 1dff451 into main Jul 9, 2026
17 checks passed
@molebox molebox deleted the docs/migrate-to-geistdocs branch July 9, 2026 13:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@bensabic bensabic bensabic approved these changes
@christopherkindl christopherkindl christopherkindl approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@molebox @bensabic @christopherkindl