---
title: Configuration
description: Configure a Geistdocs site through local adapter files and package APIs
type: reference
summary: Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
prerequisites:
  - /docs/getting-started
related:
  - /docs/migration
  - /docs/provider
  - /docs/env
  - /docs/versioned-docs
  - /docs/proxy
---

# Configuration



Configure Geistdocs through user-owned files in the generated project. Runtime features come from `@vercel/geistdocs`, while your local files control content, branding, routing adapters, and opt-in customization.

<CopyPrompt text="Review this Geistdocs project configuration. Explain what each export in geistdocs.tsx does, identify which features are enabled, and suggest safe customizations that do not require editing package internals.">
  Review this Geistdocs project configuration. Explain what each export in `geistdocs.tsx` does, identify which features are enabled, and suggest safe customizations that do not require editing package internals.
</CopyPrompt>

## Configuration files

| File                                       | Purpose                                                                                                                      |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `geistdocs.tsx`                            | Site-level settings, including logo, nav, GitHub repo, AI prompt, agent-readiness metadata, translations, and feature flags. |
| `source.config.ts`                         | Configures Fumadocs collections with the package-provided schema, Markdown plugins, and syntax theme.                        |
| `lib/geistdocs/config.tsx`                 | Converts `geistdocs.tsx` exports into the package config using `defineConfig`.                                               |
| `source.config.ts`                         | Configures Fumadocs collections with package-safe schemas and Markdown processing.                                           |
| `lib/geistdocs/source.ts`                  | Connects Fumadocs content collections to the package source adapter.                                                         |
| `components/geistdocs/mdx-components.tsx`  | Adds or overrides MDX components.                                                                                            |
| `components/geistdocs/docs-layout.tsx`     | Customizes the package-backed docs layout, including optional sidebar content.                                               |
| `app/[lang]/docs/[[...slug]]/page.tsx`     | Configures the package docs page renderer.                                                                                   |
| `app/[lang]/agents.md/route.ts`            | Configures the agent-readiness entry point.                                                                                  |
| `app/[lang]/.well-known/mcp.json/route.ts` | Configures MCP server discovery.                                                                                             |
| `app/[lang]/llms.txt/route.ts`             | Configures the all-docs Markdown endpoint.                                                                                   |
| `app/[lang]/llms.mdx/[[...slug]]/route.ts` | Configures single-page Markdown responses.                                                                                   |
| `proxy.ts`                                 | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks.                              |
| `content/docs/meta.json`                   | Controls sidebar order and section labels.                                                                                   |

## `geistdocs.tsx`

The root `geistdocs.tsx` file is the primary configuration surface:

```tsx title="geistdocs.tsx"
export const Logo = () => <span>My Docs</span>;

export const github = {
  owner: "my-org",
  repo: "my-repo",
  branch: "main",
  editPath: "content/docs/{path}",
};

export const nav = [
  { label: "Docs", href: "/docs" },
  { label: "GitHub", href: "https://github.com/my-org/my-repo" },
];

export const title = "My Documentation";

export const prompt =
  "You are a helpful assistant that answers questions about My Documentation.";

export const suggestions = [
  "How do I get started?",
  "How do I deploy?",
];

export const agent = {
  product: {
    name: "My Product",
    description: "My Product helps teams build and deploy applications.",
  },
};

export const translations = {
  en: { displayName: "English" },
};

export const basePath: string | undefined = undefined;
export const siteId: string | undefined = undefined;
```

## `defineConfig`

`lib/geistdocs/config.tsx` converts your root exports into a package config. Most projects only need the generated defaults:

```tsx title="lib/geistdocs/config.tsx"
import { defineConfig } from "@vercel/geistdocs/config";
import {
  agent,
  basePath,
  github,
  Logo,
  nav,
  prompt,
  siteId,
  suggestions,
  title,
  translations,
} from "@/geistdocs";

export const config = defineConfig({
  title,
  agent,
  defaultLanguage: "en",
  logo: <Logo />,
  github,
  nav,
  basePath,
  siteId,
  translations,
  ai: {
    prompt,
    suggestions,
  },
});
```

Advanced sites can add `content` and `versions` metadata so local adapters and custom UI share one configuration object:

```tsx title="lib/geistdocs/config.tsx"
export const config = defineConfig({
  // ...
  content: [
    { id: "docs", label: "Docs", dir: "content/docs", route: "/docs" },
    {
      id: "cookbook",
      label: "Cookbook",
      dir: "content/cookbook",
      route: "/cookbook",
    },
  ],
  versions: {
    current: "v6",
    items: [
      { id: "v6", label: "v6 latest" },
      { id: "v5", label: "v5", href: "https://v5.example.com/:path*" },
    ],
  },
});
```

Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.

## `source.config.ts`

Use the source-config-safe package export in `source.config.ts`. This file is evaluated by `fumadocs-mdx` during install and build, so it should avoid imports from runtime component entry points such as `@vercel/geistdocs/mdx`.

```ts title="source.config.ts"
import {
  defineGeistdocsSourceConfig,
  geistdocsFrontmatterSchema,
  geistdocsMetaSchema,
} from "@vercel/geistdocs/source-config";
import { defineDocs } from "fumadocs-mdx/config";

export const docs = defineDocs({
  dir: "content/docs",
  docs: {
    schema: geistdocsFrontmatterSchema,
    postprocess: {
      includeProcessedMarkdown: true,
    },
  },
  meta: {
    schema: geistdocsMetaSchema,
  },
});

export default defineGeistdocsSourceConfig();
```

To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/"` in `createSource`. Root-mounted docs need explicit `markdownRoutes`; Geistdocs does not infer a broad `/*path` mapping because it can capture homepages and non-docs app routes.

## Page actions

Page actions appear below the table of contents. They are enabled by default and can be disabled through `defineConfig` in `lib/geistdocs/config.tsx`:

```tsx title="lib/geistdocs/config.tsx"
export const config = defineConfig({
  // ...
  pageActions: {
    editSource: false,
    scrollTop: true,
    copyPage: true,
    askAI: true,
    openInChat: false,
  },
  feedback: {
    enabled: false,
  },
});
```

`github.editPath` controls the file path used by the "Edit this page on GitHub" action. Use `{path}` where the page path should be inserted. For monorepos, include the app directory, such as `apps/docs/content/docs/{path}`.

## Page visibility

Use frontmatter to control whether a page appears in package-owned machine-readable surfaces:

```mdx title="content/docs/internal-note.mdx"
---
title: Internal note
description: Hidden from public indexes
internal: true
---
```

`internal: true` excludes a page from `llms.txt`, `sitemap.md`, search, and chat. `noindex: true` adds `robots: noindex` metadata and excludes the page from `sitemap.md`. Use `excludeFrom` for per-surface control:

```mdx
---
title: Draft guide
excludeFrom:
  - chat
  - search
---
```

Optional `tags`, `keywords`, and `canonical` frontmatter are also recognized by the package runtime.

## User-owned adapters

Adapter files are safe to edit. Package updates do not overwrite them.

For example, add a custom MDX component:

```tsx title="components/geistdocs/mdx-components.tsx"
import { createMdxComponents } from "@vercel/geistdocs/mdx";
import type { MDXComponents } from "mdx/types";

const ProductCard = ({ name }: { name: string }) => <div>{name}</div>;

export const getMDXComponents = (components?: MDXComponents): MDXComponents =>
  createMdxComponents({
    ProductCard,
    ...components,
  });
```

Then use it in MDX:

```mdx
<ProductCard name="My product" />
```

## Docs page adapter

`createDocsPage` accepts hooks for route-specific behavior:

```tsx title="app/[lang]/docs/[[...slug]]/page.tsx"
const docsPage = createDocsPage({
  config,
  source: geistdocsSource,
  getPageUrl: ({ page }) => page.url,
  openGraph: {
    images: true,
  },
  metadata: ({ metadata }) => metadata,
  mdx: ({ link }) => getMDXComponents({ a: link }),
});
```

Use `getPageUrl` when the public route differs from the source URL, such as `/v5/docs`. Set `openGraph.images` to `true` only when your site includes the Geistdocs OG route. Use `metadata` to set canonical URLs, `robots`, or custom Open Graph fields for a specific route.

## Package-owned runtime

Do not edit files inside `node_modules/@vercel/geistdocs`. Update the package instead:

```bash title="Terminal"
pnpm exec geistdocs update
```

If a release adds an optional prop or config field, opt into it by editing the relevant local adapter file. Existing adapters should keep compiling unless a release includes a breaking API change.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)