Files
9150c662ea docs: Migrate docs site to @vercel/geistdocs package (#13320)
## Description

Migrates `apps/docs` from locally-vendored geistdocs components to the
published
[`@vercel/geistdocs`](https://www.npmjs.com/package/@vercel/geistdocs)
package (1.8.2), following the [official migration
guide](https://preview.geistdocs.com/docs/migration). Site-specific
content, routes, and product UI stay local as thin package-backed
adapters.

**~127 files, +2.2k/−14.4k lines** (net −12.2k).

### Adopted from the package

- Docs page via `createDocsPage` (MobileDocsBar, page actions, built-in
feedback with `siteId: "turborepo"`)
- Docs/home layouts, provider (search dialog, Ask AI shell, toaster),
OSS-variant navbar
- Search + Ask AI chat routes (AI SDK v6; optional
`GEISTDOCS_CHAT_PROXY_URL` proxy mode)
- Markdown surfaces: per-page `llms.mdx`, `sitemap.md`, **new
`agents.md`** (with a new agent-readiness config in `geistdocs.tsx`)
- `createProxy`: markdown negotiation, `.md` URL rewrites, **new
AI-agent UA rewrites**, md-tracking aligned to the package event shape
- MDX component defaults + design tokens via package `styles.css`
- GitHub edit links now point at the monorepo path
(`apps/docs/content/docs/{path}`)

### Kept custom (deliberate deviations)

- **Curated `/llms.txt` index + `/llms-full.txt`** — the package route
is a full corpus, which would change the public contract
- **HMAC-signed OG images** (injected via the `metadata` callback), OG
routes, rss/feed.xml, robots, Redis crawler sitemap, binaries/version +
remote-cache APIs
- **Four-column footer** (Fides "Cookie Preferences" link; the package
footer is a slim bar without link sections)
- `VersionWarning` banner via the package `sidebarTop` slot;
`RemoteCacheCounter` moved from TOC header to page-action extras (no
TOC-header hook exists)
- `PackageManagerTabs`, reactflow diagram system, heading-badge rehype
pipeline, shiki notation transformers
- Blog / showcase / homepage / devtools / extra / openapi sections
unchanged

### Version alignment

- `next` 16.2.9 → **16.2.6** (the package peer-pins next exactly)
- `fumadocs-core`/`ui` → **16.2.2**, `fumadocs-mdx` → **14.0.4**
(package pins)
- `fumadocs-openapi` → **10.2.7** (10.3+ peers fumadocs ^16.5,
incompatible)
- Removed ~20 dependencies owned by deleted vendored code (`ai@5`,
`@ai-sdk/react@2`, dexie, jotai, streamdown, cmdk, vaul, recharts, …)

### Repo-level change

- **`.npmrc`: added `hoist-pattern[]=tailwindcss`** — this repo's
explicit hoist list disables pnpm's default hoisting, which broke the
package CSS's internal `@import "tailwindcss"` resolution.

### Palette translation

The package remaps Tailwind's default `gray`/`blue`/`red`/`green`/…
scales to Geist `--ds-*` tokens (much lighter at the same step). Site
components written against Tailwind defaults (blog back-link/dates,
version banner, devtools error banner, green file trees) were translated
to the equivalent Geist steps; `dark:` variants dropped since Geist
tokens are theme-aware.

### Behavior changes to review

- Ask AI: history no longer persisted in IndexedDB; the hand-rolled
Upstash rate limiting on `/api/chat` is gone (package gateway route has
none)
- Navbar is the package OSS variant (Vercel OSS products dropdown; no
Turborepo logo asset exists upstream yet)
- Sidebar is the generic package renderer; shadcn radius scale shifted
slightly to the package's fixed scale
- Generated `agents.md` describes `/llms.txt` as a full-content surface,
though this site keeps it as an index

## Testing Instructions

```sh
cd apps/docs
fnm use 24
rm -rf .next
OG_IMAGE_SECRET=local-dev-secret pnpm dev
```

Verified locally (node 24): `check-types` (TS6), `check-openapi`, full
`next build` + `next start`; curled `/docs`, `/docs.md`, `Accept:
text/markdown` negotiation, agent-UA rewrite, `/llms.txt` (still the
index), `/llms-full.txt`, `/sitemap.md`, `/agents.md`, search API, blog,
showcase, terms, devtools, openapi; HTML greps confirm page actions,
signed `og:image`, markdown alternates, edit-source URLs, and
RemoteCacheCounter. `check-links` flags 2 pre-existing broken content
links (zero content changes in this PR).

---------

Co-authored-by: Anthony Shew <[email protected]>
2026-07-10 06:34:42 -06:00

109 lines
2.6 KiB
TypeScript

import { createSource } from "@vercel/geistdocs/source";
import {
type MetaData,
type PageData,
type Source,
loader
} from "fumadocs-core/source";
import { openapiPlugin } from "fumadocs-openapi/server";
import {
blogDocs,
blogMeta,
docs,
externalBlogDocs,
externalBlogMeta,
extraDocs,
extraMeta,
openapiDocs,
openapiMeta
} from "@/.source/server";
import { basePath } from "@/geistdocs";
import { createSignedDocsOgUrl } from "@/lib/og/sign";
import { config } from "./config";
export const geistdocsSource = createSource({
docs,
config,
id: "docs",
label: "Docs"
});
export const source = geistdocsSource.source;
/**
* Full LLM-ready markdown for a docs page (frontmatter + processed body +
* footer links to /sitemap.md, /llms.txt and /agents.md).
*/
export const getLLMText = geistdocsSource.getPageMarkdown;
/**
* Signed OG image URL for a docs page. The site keeps HMAC-signed OG URLs
* (see lib/og/sign.ts) instead of the package's unsigned `getPageImage`.
*/
export const getPageImage = (page: { slugs: string[] }) => {
const segments = [...page.slugs, "image.png"];
return {
segments,
url: createSignedDocsOgUrl(segments, basePath)
};
};
// Helper function to create source from doc and meta arrays with proper typing
function createLocalSource<
TPage extends PageData & { info: { path: string; fullPath: string } },
TMeta extends MetaData & { info: { path: string; fullPath: string } }
>(
pages: TPage[],
metas: TMeta[]
): Source<{ pageData: TPage; metaData: TMeta }> {
const files: Array<
| { type: "page"; path: string; absolutePath: string; data: TPage }
| { type: "meta"; path: string; absolutePath: string; data: TMeta }
> = [];
for (const entry of pages) {
files.push({
type: "page",
path: entry.info.path,
absolutePath: entry.info.fullPath,
data: entry
});
}
for (const entry of metas) {
files.push({
type: "meta",
path: entry.info.path,
absolutePath: entry.info.fullPath,
data: entry
});
}
return { files };
}
// Blog loaders
export const blog = loader({
baseUrl: "/blog",
source: createLocalSource(blogDocs, blogMeta)
});
export const externalBlog = loader({
baseUrl: "/blog",
source: createLocalSource(externalBlogDocs, externalBlogMeta)
});
// OpenAPI loaders
export const openapiPages = loader({
baseUrl: "/docs/openapi",
source: createLocalSource(openapiDocs, openapiMeta),
plugins: [openapiPlugin()]
});
// Extra pages (terms, governance, etc.)
export const extraPages = loader({
baseUrl: "/",
source: createLocalSource(extraDocs ?? [], extraMeta ?? [])
});