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

105 lines
2.7 KiB
TypeScript

import {
transformerNotationDiff,
transformerNotationFocus,
transformerNotationHighlight,
transformerNotationWordHighlight
} from "@shikijs/transformers";
import {
defineGeistdocsSourceConfig,
geistShikiTheme,
geistdocsFrontmatterSchema,
geistdocsMetaSchema
} from "@vercel/geistdocs/source-config";
import { defineDocs } from "fumadocs-mdx/config";
import type { ShikiTransformer } from "shiki";
import { z } from "zod";
import rehypeStripHeadingJsx from "./lib/rehype-strip-heading-jsx";
const transformerAddLanguage: ShikiTransformer = {
name: "add-language-attribute",
pre(node) {
if (this.options.lang) {
node.properties["data-language"] = this.options.lang;
}
}
};
// You can customise Zod schemas for frontmatter and `meta.json` here
// see https://fumadocs.dev/docs/mdx/collections
export const docs = defineDocs({
dir: "content/docs",
docs: {
schema: geistdocsFrontmatterSchema,
postprocess: {
includeProcessedMarkdown: true
}
},
meta: {
schema: geistdocsMetaSchema
}
});
export const { docs: blogDocs, meta: blogMeta } = defineDocs({
dir: "content/blog",
docs: {
schema: geistdocsFrontmatterSchema
.extend({
description: z.string(),
date: z.string(),
tag: z.string(),
ogImage: z
.string()
.startsWith("/images/blog/")
.endsWith("x-card.png")
.optional()
})
.strict()
}
});
export const { docs: externalBlogDocs, meta: externalBlogMeta } = defineDocs({
dir: "content/external-blog",
docs: {
schema: geistdocsFrontmatterSchema.extend({
description: z.string(),
date: z.string(),
isExternal: z.literal(true),
href: z.string()
})
}
});
export const { docs: openapiDocs, meta: openapiMeta } = defineDocs({
dir: "content/openapi"
});
export const { docs: extraDocs, meta: extraMeta } = defineDocs({
dir: "content/extra",
docs: {
schema: geistdocsFrontmatterSchema.extend({
description: z.string()
})
}
});
export default defineGeistdocsSourceConfig({
mdxOptions: {
rehypePlugins: [rehypeStripHeadingJsx],
rehypeCodeOptions: {
// defineGeistdocsSourceConfig sets these at runtime; repeated here to
// satisfy the fumadocs RehypeCodeOptions type, which requires themes.
themes: {
light: geistShikiTheme,
dark: geistShikiTheme
},
transformers: [
transformerNotationHighlight({ matchAlgorithm: "v3" }),
transformerNotationWordHighlight({ matchAlgorithm: "v3" }),
transformerNotationDiff({ matchAlgorithm: "v3" }),
transformerNotationFocus({ matchAlgorithm: "v3" }),
transformerAddLanguage
]
}
}
});