@vercel/geistdocs 1.3.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/dist/assets/logos/logo-svelte-kit.d.ts +0 -3
  2. package/dist/assets/logos/logo-svelte-kit.d.ts.map +1 -1
  3. package/dist/assets/logos/logo-svelte-kit.js +2 -5
  4. package/dist/cli/index.js +1 -1
  5. package/dist/config.d.ts +6 -0
  6. package/dist/config.d.ts.map +1 -1
  7. package/dist/routes/agents.d.ts.map +1 -1
  8. package/dist/routes/agents.js +14 -29
  9. package/dist/routes/discovery.d.ts +14 -0
  10. package/dist/routes/discovery.d.ts.map +1 -0
  11. package/dist/routes/discovery.js +74 -0
  12. package/dist/routes/mcp.d.ts +26 -0
  13. package/dist/routes/mcp.d.ts.map +1 -0
  14. package/dist/routes/mcp.js +31 -0
  15. package/dist/source.d.ts +1 -1
  16. package/dist/source.d.ts.map +1 -1
  17. package/dist/source.js +4 -1
  18. package/docs/agents.md +44 -0
  19. package/docs/llms.txt +2965 -0
  20. package/docs/manifest.json +194 -0
  21. package/docs/pages/agent-readiness.md +141 -0
  22. package/docs/pages/ask-ai.md +143 -0
  23. package/docs/pages/configuration.md +278 -0
  24. package/docs/pages/deployment.md +53 -0
  25. package/docs/pages/edit-on-github.md +53 -0
  26. package/docs/pages/env.md +62 -0
  27. package/docs/pages/feedback.md +91 -0
  28. package/docs/pages/getting-started.md +116 -0
  29. package/docs/pages/index.md +99 -0
  30. package/docs/pages/internationalization.md +124 -0
  31. package/docs/pages/llms-txt.md +88 -0
  32. package/docs/pages/md.md +84 -0
  33. package/docs/pages/migration.md +376 -0
  34. package/docs/pages/open-in-chat.md +82 -0
  35. package/docs/pages/provider.md +76 -0
  36. package/docs/pages/proxy.md +180 -0
  37. package/docs/pages/rss.md +110 -0
  38. package/docs/pages/syntax.md +413 -0
  39. package/docs/pages/theme-aware-image.md +59 -0
  40. package/docs/pages/versioned-docs.md +230 -0
  41. package/docs/sitemap.md +25 -0
  42. package/package.json +12 -2
  43. package/template/AGENTS.md +10 -3
  44. package/template/app/[lang]/.well-known/mcp.json/route.ts +8 -0
  45. package/template/content/docs/agent-readiness.mdx +44 -8
  46. package/template/content/docs/configuration.mdx +1 -0
  47. package/template/content/docs/index.mdx +1 -1
  48. package/template/content/docs/llms-txt.mdx +1 -1
  49. package/template/content/docs/migration.mdx +12 -2
  50. package/template/package.json +1 -1
@@ -0,0 +1,99 @@
1
+ ---
2
+ title: Overview
3
+ description: Learn how Geistdocs packages the CLI, runtime, and template for documentation sites
4
+ type: overview
5
+ summary: Geistdocs is a packaged documentation system for creating Next.js and Fumadocs sites with shared runtime features.
6
+ url: /docs
7
+ source: apps/template/content/docs/index.mdx
8
+ related:
9
+ - /docs/getting-started
10
+ - /docs/migration
11
+ - /docs/configuration
12
+ ---
13
+
14
+ # Overview
15
+
16
+ Geistdocs is a packaged documentation system built with Next.js, Fumadocs, and shared Vercel documentation patterns. Use it to create a docs site with local content files and package-managed runtime features.
17
+
18
+ Help me understand this Geistdocs project. Explain how the `@vercel/geistdocs` package, local adapter files, and `content/docs` folder work together, then suggest the first files I should edit for my documentation site.
19
+
20
+ ## How Geistdocs works
21
+
22
+ Geistdocs has three main parts:
23
+
24
+ - `@vercel/geistdocs`: The npm package that provides the CLI, runtime components, route helpers, MDX components, page actions, and bundled template.
25
+ - Local adapter files: The files in your generated project that connect your configuration, content source, routes, and UI customization to the package.
26
+ - Platform services: Hosted endpoints at `geistdocs.com` for optional translation, feedback, and markdown tracking features.
27
+
28
+ ```mermaid
29
+ flowchart TB
30
+ subgraph Package["@vercel/geistdocs package"]
31
+ cli["CLI: init, update, translate"]
32
+ runtime["Runtime: layout, routes, MDX, controls"]
33
+ bundledTemplate["Bundled template snapshot"]
34
+ end
35
+
36
+ subgraph Site["Generated docs site"]
37
+ config["geistdocs.tsx"]
38
+ adapters["app/, components/geistdocs/, lib/geistdocs/"]
39
+ content["content/docs/*.mdx"]
40
+ end
41
+
42
+ subgraph Platform["Geistdocs platform"]
43
+ translate["/translate"]
44
+ feedback["/feedback"]
45
+ tracking["/md-tracking"]
46
+ end
47
+
48
+ cli --> bundledTemplate
49
+ bundledTemplate --> Site
50
+ adapters --> runtime
51
+ content --> adapters
52
+ cli --> translate
53
+ runtime --> feedback
54
+ runtime --> tracking
55
+ ```
56
+
57
+ ## What you edit
58
+
59
+ Most projects start by editing these files:
60
+
61
+ - `content/docs`: Write and organize your docs.
62
+ - `content/docs/meta.json`: Control sidebar order and groups.
63
+ - `geistdocs.tsx`: Configure the logo, nav, GitHub repo, title, AI prompt, translations, and feature flags.
64
+ - `components/geistdocs/mdx-components.tsx`: Add or override MDX components.
65
+ - `app/[lang]/docs/[[...slug]]/page.tsx`: Configure docs page behavior, such as custom render hooks.
66
+ - `proxy.ts`: Add site-specific request logic before or after package-managed markdown negotiation.
67
+
68
+ ## What the package owns
69
+
70
+ The package owns shared behavior such as docs rendering, page actions, search, Ask AI, markdown routes, `llms.txt`, and reusable MDX components. Updating `@vercel/geistdocs` gives your project package-level fixes and features without overwriting user-owned adapter files.
71
+
72
+ Ask AI uses AI SDK v6 through package-managed client and server code. Generated projects include `ai` v6 and `@ai-sdk/react` v3 so the package chat UI and `createChatRoute` use the supported AI SDK APIs.
73
+
74
+ Advanced projects can use package APIs for versioned docs, multiple content sources, custom page metadata, and custom proxy hooks while keeping runtime behavior in `@vercel/geistdocs`.
75
+
76
+ ## Included features
77
+
78
+ - MDX documentation with custom components
79
+ - Local content in `content/docs`
80
+ - Search and Ask AI
81
+ - Page actions, including feedback, copy page, open in chat, and edit on GitHub
82
+ - Agent-readiness metadata with `/agents.md` and `/.well-known/mcp.json`
83
+ - Raw Markdown routes for AI tools
84
+ - `llms.txt`
85
+ - Versioned docs and multiple content sources
86
+ - Proxy hooks for custom request logic
87
+ - RSS feed
88
+ - Theme-aware images
89
+ - Internationalized routes
90
+ - CLI commands for init, update, and translation
91
+
92
+ ## Next steps
93
+
94
+ - Follow [Getting Started](/docs/getting-started) to create and run a project.
95
+ - Read [Migration guide](/docs/migration) to move an existing docs site to package-backed Geistdocs.
96
+ - Read [Configuration](/docs/configuration) to customize the generated site.
97
+ - Read [Versioned docs](/docs/versioned-docs) to configure multiple docs versions.
98
+ - Read [Proxy and markdown routes](/docs/proxy) to add custom request logic.
99
+ - Read [Syntax](/docs/syntax) to write content with MDX components.
@@ -0,0 +1,124 @@
1
+ ---
2
+ title: Internationalization
3
+ description: Add multi-language support to your documentation site
4
+ type: guide
5
+ summary: Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
6
+ url: /docs/internationalization
7
+ source: apps/template/content/docs/internationalization.mdx
8
+ prerequisites:
9
+ - /docs/getting-started
10
+ related:
11
+ - /docs/configuration
12
+ ---
13
+
14
+ # Internationalization
15
+
16
+ Geistdocs supports internationalization (i18n) out of the box using Fumadocs' language-aware routing. You can serve documentation in multiple languages with automatic translation via the Geistdocs CLI.
17
+
18
+ Help me add a new language to this Geistdocs project. Update `translations` in `geistdocs.tsx`, run the Geistdocs translate command for `content/docs`, and explain how localized routes are generated.
19
+
20
+ ## How it works
21
+
22
+ The i18n system uses dynamic routing with a `[lang]` URL segment. The default language (English) doesn't show in URLs, while other languages get a prefix:
23
+
24
+ - `/docs/getting-started` - English (default)
25
+ - `/cn/docs/getting-started` - Chinese
26
+
27
+ Users can switch languages using the language selector in the navigation bar.
28
+
29
+ ## Translating Content
30
+
31
+ Use the Geistdocs CLI to automatically translate your MDX files:
32
+
33
+ ```bash
34
+ pnpm translate
35
+ ```
36
+
37
+ The CLI reads your target locales from `geistdocs.tsx`. If no locales are found in the config, you'll be prompted to enter them manually.
38
+
39
+ Translations are generated using the Geistdocs platform and saved alongside your original file with the locale suffix (e.g., `introduction.cn.mdx`).
40
+
41
+ ### Command Options
42
+
43
+ You can pass options directly to customize the translation behavior:
44
+
45
+ ```bash
46
+ # Translate all MDX files (uses default pattern)
47
+ pnpm translate
48
+
49
+ # Translate files matching a specific glob pattern
50
+ pnpm translate "content/docs/**/*.mdx"
51
+
52
+ # Use a custom config file
53
+ pnpm translate "content/**/*.mdx" --config custom-config.tsx
54
+
55
+ # Use a custom translation API URL
56
+ pnpm translate --url "https://custom-api.example.com/translate"
57
+ ```
58
+
59
+ | Option | Description |
60
+ | ----------- | -------------------------------------------------------- |
61
+ | `--config` | Path to config file with translations (default: `geistdocs.tsx`) |
62
+ | `--url` | Custom translation API URL (can also use `GEISTDOCS_TRANSLATE_URL` env var) |
63
+
64
+ Pass the glob pattern as the command argument. If you omit it, Geistdocs uses `content/docs/**/*.mdx`.
65
+
66
+ The CLI automatically excludes files that already have a locale suffix (e.g., `getting-started.cn.mdx`) to avoid translating already-translated content.
67
+
68
+ ### Batch Processing
69
+
70
+ When translating multiple files, the CLI automatically batches them into groups of 10. Progress is displayed as each batch completes, and a 1-second delay is added between batches to avoid rate limiting.
71
+
72
+ ## Configuration
73
+
74
+ Configure supported languages in `geistdocs.tsx`:
75
+
76
+ ```typescript title="geistdocs.tsx"
77
+ export const translations = {
78
+ en: {
79
+ displayName: "English",
80
+ },
81
+ cn: {
82
+ displayName: "中文",
83
+ search: "搜尋文檔",
84
+ },
85
+ };
86
+ ```
87
+
88
+ The first locale in the `translations` object is treated as your default/source language and is excluded from translation targets.
89
+
90
+ ### Adding a New Language
91
+
92
+ To add a new language:
93
+
94
+ 1. Add a new key to the `translations` object with the language code
95
+ 2. Add translations for UI elements like `displayName` and `search`
96
+ 3. Run `pnpm translate "content/**/*.mdx"` to generate translated content
97
+
98
+ The language selector will automatically include your new language.
99
+
100
+ ## Content Organization
101
+
102
+ Translated files are saved alongside the original with a locale suffix:
103
+
104
+ ```
105
+ content/docs/
106
+ ├── getting-started.mdx # English (default)
107
+ ├── getting-started.cn.mdx # Chinese
108
+ ├── getting-started.fr.mdx # French
109
+ └── getting-started.es.mdx # Spanish
110
+ ```
111
+
112
+ Fumadocs automatically serves the correct file based on the URL path.
113
+
114
+ ## Translating UI Elements
115
+
116
+ The `translations` object in `geistdocs.tsx` controls UI text like search placeholders, navigation labels, and error messages. Add translations for each language you support.
117
+
118
+ If you don't provide a translation for a specific element, it falls back to English.
119
+
120
+ ## Language Detection
121
+
122
+ The language is determined by the URL path. There's no automatic detection based on browser settings - users must explicitly choose their language using the language selector.
123
+
124
+ This approach gives users full control and ensures they see the language they expect.
@@ -0,0 +1,88 @@
1
+ ---
2
+ title: llms.txt
3
+ description: A single file containing all your documentation in plain text for AI consumption
4
+ type: conceptual
5
+ summary: A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
6
+ url: /docs/llms-txt
7
+ source: apps/template/content/docs/llms-txt.mdx
8
+ related:
9
+ - /docs/agent-readiness
10
+ - /docs/md
11
+ - /docs/ask-ai
12
+ - /docs/proxy
13
+ ---
14
+
15
+ # llms.txt
16
+
17
+ Geistdocs implements the [llms.txt standard](https://llmstxt.org/), a convention for exposing documentation as one AI-readable text file. Language models and coding agents can use `/llms.txt` to retrieve broad documentation context.
18
+
19
+ Help me verify this Geistdocs site's AI-readable docs. Check `/llms.txt` and a few `.mdx` page URLs, then explain whether an AI assistant can retrieve the full documentation context.
20
+
21
+ ## What it is
22
+
23
+ The `/llms.txt` endpoint returns all configured documentation pages as Markdown in a single response. Each page is separated by blank lines so AI tools can parse the complete documentation set. When agent metadata is configured, page-level Markdown also links agents to `/agents.md` for API and MCP discovery.
24
+
25
+ ### Access
26
+
27
+ ```
28
+ https://yourdomain.com/llms.txt
29
+ ```
30
+
31
+ Returns all documentation pages concatenated together as Markdown.
32
+
33
+ ## How it works
34
+
35
+ The package route helper:
36
+
37
+ 1. Fetches pages from one or more source bundles.
38
+ 2. Processes each page to extract clean Markdown.
39
+ 3. Combines the pages into a single response.
40
+ 4. Returns the response as `text/markdown`.
41
+
42
+ Pages are joined with double newlines (`\n\n`) for clear separation.
43
+
44
+ ## Use cases
45
+
46
+ This feature enables:
47
+
48
+ - **AI Training** - Provide your docs as context for AI assistants
49
+ - **Search Indexing** - Feed your entire documentation to search systems
50
+ - **Content Analysis** - Analyze patterns and content across all docs
51
+ - **Bulk Processing** - Process all documentation at once
52
+ - **LLM Context** - Give language models complete documentation context
53
+
54
+ ## Configure sources
55
+
56
+ Generated projects use one documentation source:
57
+
58
+ ```ts title="app/[lang]/llms.txt/route.ts"
59
+ import { createLlmsRoute } from "@vercel/geistdocs/routes/llms";
60
+ import { geistdocsSource } from "@/lib/geistdocs/source";
61
+
62
+ export const { GET, revalidate } = createLlmsRoute({
63
+ source: geistdocsSource,
64
+ });
65
+ ```
66
+
67
+ Sites with multiple content sections or versions can pass `sources`:
68
+
69
+ ```ts title="app/[lang]/llms.txt/route.ts"
70
+ export const { GET, revalidate } = createLlmsRoute({
71
+ sources: [docsSource, cookbookSource],
72
+ });
73
+ ```
74
+
75
+ Use `filterPage` to exclude pages from `/llms.txt`, such as internal or preview-only docs:
76
+
77
+ ```ts title="app/[lang]/llms.txt/route.ts"
78
+ export const { GET, revalidate } = createLlmsRoute({
79
+ source: geistdocsSource,
80
+ filterPage: (page) => !page.url.includes("/internal"),
81
+ });
82
+ ```
83
+
84
+ ## The llms.txt standard
85
+
86
+ The llms.txt standard is a simple convention that makes documentation more accessible to AI tools. It's similar in spirit to `robots.txt` but designed for language models instead of search crawlers.
87
+
88
+ Learn more at [llmstxt.org](https://llmstxt.org/)
@@ -0,0 +1,84 @@
1
+ ---
2
+ title: .md Extension
3
+ description: Access documentation pages as raw Markdown by appending .md or .mdx to any URL
4
+ type: conceptual
5
+ summary: Access any documentation page as raw Markdown by appending .md or .mdx to the URL for AI tool consumption.
6
+ url: /docs/md
7
+ source: apps/template/content/docs/md.mdx
8
+ related:
9
+ - /docs/agent-readiness
10
+ - /docs/llms-txt
11
+ - /docs/proxy
12
+ ---
13
+
14
+ # .md Extension
15
+
16
+ Geistdocs lets AI tools and language models access documentation pages as plain Markdown. Append `.md` or `.mdx` to a documentation URL to get the processed Markdown content for that page.
17
+
18
+ Help me test raw Markdown routes in this Geistdocs project. Fetch a docs page with `.mdx` appended, compare it to the rendered page, and explain how AI tools can use it.
19
+
20
+ ## How it works
21
+
22
+ When you add `.md` or `.mdx` to a documentation URL, Geistdocs returns the page content as Markdown instead of rendered HTML. AI tools can use that response as focused context for one page.
23
+
24
+ ### Example
25
+
26
+ ```
27
+ # Normal page
28
+ https://yourdomain.com/docs/getting-started
29
+
30
+ # Markdown version
31
+ https://yourdomain.com/docs/getting-started.mdx
32
+ ```
33
+
34
+ The `.mdx` version returns:
35
+
36
+ - The page title as an H1 heading
37
+ - The full processed Markdown content
38
+ - No HTML, styling, or navigation
39
+
40
+ ## Use cases
41
+
42
+ This feature is particularly useful for:
43
+
44
+ - **AI Chat Tools** - Tools like ChatGPT, Claude, and Cursor can fetch and read your docs
45
+ - **LLM Context** - Provides clean text for language model prompts
46
+ - **Documentation Analysis** - Extract content for processing or analysis
47
+ - **Content Migration** - Export documentation in a clean format
48
+
49
+ ## Implementation
50
+
51
+ The package proxy routes `.md` and `.mdx` requests to the package-backed markdown route handler:
52
+
53
+ ```ts title="proxy.ts"
54
+ const proxy = createProxy({
55
+ config: geistdocsConfig,
56
+ markdownRoutes: [
57
+ { from: "/docs/*path", to: "/[lang]/llms.mdx/*path" },
58
+ ],
59
+ });
60
+ ```
61
+
62
+ The destination route uses `createDocsMarkdownRoute` to process the page and return Markdown with a `text/markdown` content type:
63
+
64
+ ```ts title="app/[lang]/llms.mdx/[[...slug]]/route.ts"
65
+ import { createDocsMarkdownRoute } from "@vercel/geistdocs/routes/llms";
66
+ import { geistdocsSource } from "@/lib/geistdocs/source";
67
+
68
+ export const { GET, generateStaticParams, revalidate } =
69
+ createDocsMarkdownRoute({
70
+ sources: [geistdocsSource],
71
+ });
72
+ ```
73
+
74
+ Read [Proxy and markdown routes](/docs/proxy) to configure additional route families such as `/cookbook` or `/v5/docs`.
75
+
76
+ ## Response Format
77
+
78
+ The response includes:
79
+
80
+ - Content-Type: `text/markdown`
81
+ - The page title as a level 1 heading
82
+ - Processed Markdown content from Fumadocs
83
+
84
+ All MDX components are processed and converted to plain Markdown equivalents.