@vercel/geistdocs 1.3.0-canary.41d37f1 → 1.3.0-canary.5af98bc

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 (51) hide show
  1. package/dist/cli/index.js +2 -2
  2. package/dist/components/code-block.d.ts.map +1 -1
  3. package/dist/components/code-block.js +5 -1
  4. package/dist/components/copy-prompt.d.ts +11 -0
  5. package/dist/components/copy-prompt.d.ts.map +1 -0
  6. package/dist/components/copy-prompt.js +58 -0
  7. package/dist/internal/page-actions-client.d.ts +1 -2
  8. package/dist/internal/page-actions-client.d.ts.map +1 -1
  9. package/dist/internal/page-actions-client.js +12 -6
  10. package/dist/internal/provider-client.d.ts +9 -0
  11. package/dist/internal/provider-client.d.ts.map +1 -0
  12. package/dist/internal/provider-client.js +23 -0
  13. package/dist/internal/sidebar.d.ts.map +1 -1
  14. package/dist/internal/sidebar.js +4 -3
  15. package/dist/internal/table-of-contents.d.ts +9 -0
  16. package/dist/internal/table-of-contents.d.ts.map +1 -0
  17. package/dist/internal/table-of-contents.js +5 -0
  18. package/dist/layout.d.ts +2 -7
  19. package/dist/layout.d.ts.map +1 -1
  20. package/dist/layout.js +25 -43
  21. package/dist/mdx.d.ts.map +1 -1
  22. package/dist/mdx.js +2 -0
  23. package/dist/pages/docs.d.ts.map +1 -1
  24. package/dist/pages/docs.js +15 -9
  25. package/dist/sidebar.d.ts +11 -0
  26. package/dist/sidebar.d.ts.map +1 -0
  27. package/dist/sidebar.js +16 -0
  28. package/package.json +9 -1
  29. package/template/_gitignore +28 -0
  30. package/template/app/styles/geistdocs.css +1 -0
  31. package/template/components/geistdocs/mobile-docs-bar.tsx +2 -6
  32. package/template/content/docs/ask-ai.mdx +4 -0
  33. package/template/content/docs/configuration.mdx +75 -72
  34. package/template/content/docs/deployment.mdx +6 -0
  35. package/template/content/docs/edit-on-github.mdx +4 -0
  36. package/template/content/docs/env.mdx +4 -0
  37. package/template/content/docs/feedback.mdx +4 -0
  38. package/template/content/docs/getting-started.mdx +64 -43
  39. package/template/content/docs/index.mdx +57 -59
  40. package/template/content/docs/internationalization.cn.mdx +7 -9
  41. package/template/content/docs/internationalization.mdx +9 -4
  42. package/template/content/docs/llms-txt.mdx +4 -0
  43. package/template/content/docs/md.mdx +4 -0
  44. package/template/content/docs/meta.json +2 -2
  45. package/template/content/docs/open-in-chat.mdx +4 -0
  46. package/template/content/docs/provider.mdx +4 -0
  47. package/template/content/docs/rss.mdx +4 -0
  48. package/template/content/docs/syntax.cn.mdx +2 -2
  49. package/template/content/docs/syntax.mdx +5 -1
  50. package/template/content/docs/theme-aware-image.mdx +4 -0
  51. package/template/package.json +1 -1
@@ -1 +1,29 @@
1
+ # dependencies
2
+ node_modules
3
+
4
+ # generated content
5
+ .source
6
+
7
+ # test and build output
8
+ coverage
9
+ .next
10
+ out
11
+ build
12
+ dist
13
+ *.tsbuildinfo
14
+
15
+ # local environment
16
+ .env*.local
1
17
  .vercel
18
+
19
+ # logs
20
+ npm-debug.log*
21
+ yarn-debug.log*
22
+ yarn-error.log*
23
+ pnpm-debug.log*
24
+
25
+ # system files
26
+ .DS_Store
27
+
28
+ # Turborepo
29
+ .turbo
@@ -3,6 +3,7 @@
3
3
  @import "fumadocs-ui/css/preset.css";
4
4
  @import "tw-animate-css";
5
5
 
6
+ @source "../../node_modules/@vercel/geistdocs/dist/**/*.js";
6
7
  @source "../../node_modules/streamdown/dist/*.js";
7
8
 
8
9
  @custom-variant dark (&:is(.dark *));
@@ -1,5 +1,6 @@
1
1
  "use client";
2
2
 
3
+ import { useGeistdocsSidebar } from "@vercel/geistdocs/sidebar";
3
4
  import type { TableOfContents } from "fumadocs-core/toc";
4
5
  import { useState } from "react";
5
6
  import { IconFileText } from "@/components/geistcn-fallbacks/geistcn-assets/icons/icon-file-text";
@@ -9,9 +10,7 @@ import {
9
10
  SheetContent,
10
11
  SheetDescription,
11
12
  SheetHeader,
12
- SheetTitle,
13
13
  } from "@/components/ui/sheet";
14
- import { useSidebarContext } from "@/hooks/geistdocs/use-sidebar";
15
14
  import { cn } from "@/lib/utils";
16
15
 
17
16
  interface MobileDocsBarProps {
@@ -19,7 +18,7 @@ interface MobileDocsBarProps {
19
18
  }
20
19
 
21
20
  export const MobileDocsBar = ({ toc }: MobileDocsBarProps) => {
22
- const { setIsOpen: setSidebarOpen } = useSidebarContext();
21
+ const { setIsOpen: setSidebarOpen } = useGeistdocsSidebar();
23
22
  const [tocOpen, setTocOpen] = useState(false);
24
23
 
25
24
  return (
@@ -47,9 +46,6 @@ export const MobileDocsBar = ({ toc }: MobileDocsBarProps) => {
47
46
  <Sheet onOpenChange={setTocOpen} open={tocOpen}>
48
47
  <SheetContent className="w-72 gap-0" side="right">
49
48
  <SheetHeader>
50
- <SheetTitle className="px-4 pt-4 font-medium text-sm">
51
- On this page
52
- </SheetTitle>
53
49
  <SheetDescription className="sr-only">
54
50
  Table of contents for the current page.
55
51
  </SheetDescription>
@@ -13,6 +13,10 @@ related:
13
13
 
14
14
  The Ask AI feature provides an intelligent chat assistant built directly into your documentation. Users can ask questions about your docs and get instant, context-aware answers powered by AI. The assistant can search through your documentation, understand context, and provide helpful responses.
15
15
 
16
+ <CopyPrompt text="Help me configure Ask AI for this Geistdocs site. Check my AI prompt, suggestions, environment variables, and search route, then recommend improvements for the assistant experience.">
17
+ Help me configure Ask AI for this Geistdocs site. Check my AI prompt, suggestions, environment variables, and search route, then recommend improvements for the assistant experience.
18
+ </CopyPrompt>
19
+
16
20
  ## How It Works
17
21
 
18
22
  The AI chat assistant is available in two ways:
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  title: Configuration
3
- description: Customize your Geistdocs site without modifying source files
3
+ description: Configure a Geistdocs site through local adapter files and package APIs
4
4
  type: reference
5
- summary: Customize your Geistdocs site through the geistdocs.tsx configuration file without modifying source code.
5
+ summary: Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
6
6
  prerequisites:
7
7
  - /docs/getting-started
8
8
  related:
@@ -10,106 +10,109 @@ related:
10
10
  - /docs/env
11
11
  ---
12
12
 
13
- While Geistdocs is fully open source, composable and copy-pasteable, it's preferable to customize your site without modifying the source code. This makes it easier to update Geistdocs in the future while preserving your customizations.
13
+ 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.
14
14
 
15
- To enable this, Geistdocs uses a root-level configuration file that lets you customize your documentation site without touching the source code.
15
+ <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.">
16
+ 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.
17
+ </CopyPrompt>
16
18
 
17
- ## Configuration File
19
+ ## Configuration files
18
20
 
19
- The `geistdocs.tsx` file in your project root contains all customization options:
21
+ | File | Purpose |
22
+ | --- | --- |
23
+ | `geistdocs.tsx` | Site-level settings, including logo, nav, GitHub repo, AI prompt, translations, and feature flags. |
24
+ | `lib/geistdocs/config.tsx` | Converts `geistdocs.tsx` exports into the package config using `defineConfig`. |
25
+ | `lib/geistdocs/source.ts` | Connects Fumadocs content collections to the package source adapter. |
26
+ | `components/geistdocs/mdx-components.tsx` | Adds or overrides MDX components. |
27
+ | `app/[lang]/docs/[[...slug]]/page.tsx` | Configures the package docs page renderer. |
28
+ | `content/docs/meta.json` | Controls sidebar order and section labels. |
29
+
30
+ ## `geistdocs.tsx`
31
+
32
+ The root `geistdocs.tsx` file is the primary configuration surface:
20
33
 
21
34
  ```tsx title="geistdocs.tsx"
22
- import { BookHeartIcon } from "lucide-react";
35
+ export const Logo = () => <span>My Docs</span>;
23
36
 
24
- export const Logo = () => (
25
- <div className="flex items-center gap-2">
26
- <BookHeartIcon className="size-5" />
27
- <p className="font-semibold text-xl tracking-tight">Geistdocs</p>
28
- </div>
29
- );
37
+ export const github = {
38
+ owner: "my-org",
39
+ repo: "my-repo",
40
+ };
30
41
 
31
42
  export const nav = [
32
- {
33
- label: "Docs",
34
- href: "/docs",
35
- },
43
+ { label: "Docs", href: "/docs" },
44
+ { label: "GitHub", href: "https://github.com/my-org/my-repo" },
36
45
  ];
37
46
 
38
- export const suggestions = [
39
- "What is Vercel?",
40
- "What can I deploy with Vercel?",
41
- "What is Fluid Compute?",
42
- "How much does Vercel cost?",
43
- ];
44
-
45
- export const title = "Geistdocs Documentation";
47
+ export const title = "My Documentation";
46
48
 
47
49
  export const prompt =
48
- "You are a helpful assistant specializing in answering questions about Geistdocs, a modern documentation template built with Next.js and Fumadocs.";
49
- ```
50
+ "You are a helpful assistant that answers questions about My Documentation.";
50
51
 
51
- ## Configuration Options
52
-
53
- ### `Logo`
52
+ export const suggestions = [
53
+ "How do I get started?",
54
+ "How do I deploy?",
55
+ ];
54
56
 
55
- Customize the logo component displayed in your site header:
57
+ export const translations = {
58
+ en: { displayName: "English" },
59
+ };
56
60
 
57
- ```tsx title="geistdocs.tsx"
58
- export const Logo = () => (
59
- <div className="flex items-center gap-2">
60
- <YourIcon className="size-5" />
61
- <p className="font-semibold text-xl tracking-tight">Your Brand</p>
62
- </div>
63
- );
61
+ export const basePath: string | undefined = undefined;
62
+ export const siteId: string | undefined = undefined;
64
63
  ```
65
64
 
66
- ### `nav`
65
+ ## Page actions
67
66
 
68
- Define navigation links shown in the header:
67
+ Page actions appear below the table of contents. They are enabled by default and can be disabled through `defineConfig` in `lib/geistdocs/config.tsx`:
69
68
 
70
- ```tsx title="geistdocs.tsx"
71
- export const nav = [
72
- {
73
- label: "Documentation",
74
- href: "/docs",
69
+ ```tsx title="lib/geistdocs/config.tsx"
70
+ export const config = defineConfig({
71
+ // ...
72
+ pageActions: {
73
+ editSource: false,
74
+ scrollTop: true,
75
+ copyPage: true,
76
+ askAI: true,
77
+ openInChat: false,
75
78
  },
76
- {
77
- label: "API Reference",
78
- href: "/api",
79
+ feedback: {
80
+ enabled: false,
79
81
  },
80
- {
81
- label: "GitHub",
82
- href: "https://github.com/your-org/your-repo",
83
- },
84
- ];
82
+ });
85
83
  ```
86
84
 
87
- ### `suggestions`
85
+ ## User-owned adapters
88
86
 
89
- Configure suggested questions for the AI assistant:
87
+ Adapter files are safe to edit. Package updates do not overwrite them.
90
88
 
91
- ```tsx title="geistdocs.tsx"
92
- export const suggestions = [
93
- "How do I get started?",
94
- "What are the key features?",
95
- "How do I deploy my site?",
96
- "Where can I get help?",
97
- ];
98
- ```
89
+ For example, add a custom MDX component:
99
90
 
100
- ### `title`
91
+ ```tsx title="components/geistdocs/mdx-components.tsx"
92
+ import { createMdxComponents } from "@vercel/geistdocs/mdx";
93
+ import type { MDXComponents } from "mdx/types";
101
94
 
102
- Set the main title for your documentation site:
95
+ const ProductCard = ({ name }: { name: string }) => <div>{name}</div>;
103
96
 
104
- ```tsx title="geistdocs.tsx"
105
- export const title = "Your Product Documentation";
97
+ export const getMDXComponents = (components?: MDXComponents): MDXComponents =>
98
+ createMdxComponents({
99
+ ProductCard,
100
+ ...components,
101
+ });
106
102
  ```
107
103
 
108
- ### `prompt`
104
+ Then use it in MDX:
109
105
 
110
- Customize the system prompt for the AI assistant to match your documentation context:
106
+ ```mdx
107
+ <ProductCard name="My product" />
108
+ ```
111
109
 
112
- ```tsx title="geistdocs.tsx"
113
- export const prompt =
114
- "You are a helpful assistant specializing in answering questions about Your Product, a platform for building amazing applications.";
110
+ ## Package-owned runtime
111
+
112
+ Do not edit files inside `node_modules/@vercel/geistdocs`. Update the package instead:
113
+
114
+ ```bash title="Terminal"
115
+ pnpm exec geistdocs update
115
116
  ```
117
+
118
+ 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.
@@ -10,6 +10,12 @@ related:
10
10
  - /docs/configuration
11
11
  ---
12
12
 
13
+ Deploy a Geistdocs site to Vercel as a Next.js app. Make sure your package dependency, environment variables, and production URL are configured before shipping.
14
+
15
+ <CopyPrompt text="Help me deploy this Geistdocs project to Vercel. Check the package scripts, required environment variables, and Vercel project settings, then give me a deploy checklist for production.">
16
+ Help me deploy this Geistdocs project to Vercel. Check the package scripts, required environment variables, and Vercel project settings, then give me a deploy checklist for production.
17
+ </CopyPrompt>
18
+
13
19
  ## Prerequisites
14
20
 
15
21
  Before deploying, you need:
@@ -9,6 +9,10 @@ related:
9
9
 
10
10
  The "Edit on GitHub" feature provides a direct link for readers to propose changes to your documentation. This link appears in the table of contents sidebar on every documentation page, making it easy for users to contribute fixes, improvements, or updates.
11
11
 
12
+ <CopyPrompt text="Help me configure Edit on GitHub for this Geistdocs site. Check the github owner and repo in geistdocs.tsx, verify the generated edit URL for this page, and tell me how to disable the action if needed.">
13
+ Help me configure Edit on GitHub for this Geistdocs site. Check the `github` owner and repo in `geistdocs.tsx`, verify the generated edit URL for this page, and tell me how to disable the action if needed.
14
+ </CopyPrompt>
15
+
12
16
  ## How It Works
13
17
 
14
18
  When users click the "Edit this page on GitHub" link, they are taken directly to the source file in your GitHub repository. From there, they can:
@@ -12,6 +12,10 @@ related:
12
12
 
13
13
  Geistdocs has functionality that requires specific environment variables to be set.
14
14
 
15
+ <CopyPrompt text="Review this Geistdocs project and help me configure the required environment variables. Check whether AI_GATEWAY_API_KEY and NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL are needed for the features I enabled, then tell me where to set them locally and on Vercel.">
16
+ Review this Geistdocs project and help me configure the required environment variables. Check whether `AI_GATEWAY_API_KEY` and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` are needed for the features I enabled, then tell me where to set them locally and on Vercel.
17
+ </CopyPrompt>
18
+
15
19
  ## `AI_GATEWAY_API_KEY`
16
20
 
17
21
  The API key for the AI gateway. This is used to power the AI chat functionality.
@@ -12,6 +12,10 @@ related:
12
12
 
13
13
  The Feedback feature allows readers to share their thoughts about your documentation pages through an interactive widget. Feedback is automatically posted to a centralized GitHub repository as issues, making it easy to track, label, and respond to user input.
14
14
 
15
+ <CopyPrompt text="Help me configure feedback for this Geistdocs project. Check whether feedback is enabled, what siteId label is used, and how feedback is sent to the Geistdocs platform and GitHub issues.">
16
+ Help me configure feedback for this Geistdocs project. Check whether feedback is enabled, what `siteId` label is used, and how feedback is sent to the Geistdocs platform and GitHub issues.
17
+ </CopyPrompt>
18
+
15
19
  ## How It Works
16
20
 
17
21
  The feedback widget appears in the table of contents sidebar on every documentation page. When users click "Give feedback", they can:
@@ -1,86 +1,107 @@
1
1
  ---
2
2
  title: Getting Started
3
- description: A comprehensive guide to getting started with Geistdocs
3
+ description: Create a Geistdocs project and start writing documentation
4
4
  type: guide
5
- summary: Set up a new Geistdocs project, configure environment variables, and create your first documentation page.
5
+ summary: Create a Geistdocs project, run it locally, and edit your first documentation page.
6
6
  related:
7
- - /docs/env
7
+ - /docs/configuration
8
8
  - /docs/syntax
9
9
  - /docs/deployment
10
10
  ---
11
11
 
12
- This guide will walk you through everything you need to know to set up and customize your documentation site.
12
+ Create a Geistdocs site with the package CLI, then edit the generated content and configuration files. The generated project includes these docs so you can use them as a reference while you build.
13
13
 
14
- ## Prerequisites
14
+ <CopyPrompt text="Create a Geistdocs project with pnpm dlx @vercel/geistdocs init --name my-docs. Then open my-docs, run pnpm dev, and explain which files I should edit first: geistdocs.tsx, content/docs, content/docs/meta.json, and components/geistdocs/mdx-components.tsx.">
15
+ Create a Geistdocs project with `pnpm dlx @vercel/geistdocs init --name my-docs`. Then open `my-docs`, run `pnpm dev`, and explain which files I should edit first: `geistdocs.tsx`, `content/docs`, `content/docs/meta.json`, and `components/geistdocs/mdx-components.tsx`.
16
+ </CopyPrompt>
15
17
 
16
- Before you begin, make sure you have:
18
+ ## Prerequisites
17
19
 
18
- - **Node.js 18+** installed on your system
19
- - **pnpm** (recommended) or your favorite npm package manager
20
- - A **GitHub account** for repository hosting
21
- - Basic familiarity with **MDX**, **Next.js**, and **React**
20
+ Before you begin, install:
22
21
 
23
- ## Installation
22
+ - Node.js 18 or later
23
+ - pnpm, npm, or another package manager
24
+ - Git
24
25
 
25
- ### 1. Create a New Project
26
+ ## Create a project
26
27
 
27
- Create a new project using the Geistdocs CLI:
28
+ Run the Geistdocs CLI from an empty parent folder:
28
29
 
29
30
  ```bash title="Terminal"
30
- npx @vercel/geistdocs init
31
+ pnpm dlx @vercel/geistdocs init --name my-docs
31
32
  ```
32
33
 
33
- This will clone the Geistdocs `template` app into a new directory. It will prompt you for a project name, then install all dependencies and delete the Geistdocs website content.
34
-
35
- ### 2. Configure Environment Variables
36
-
37
- Copy the example environment file:
34
+ You can also use npm:
38
35
 
39
36
  ```bash title="Terminal"
40
- cp .env.example .env.local
37
+ npx @vercel/geistdocs init --name my-docs
41
38
  ```
42
39
 
43
- Then edit the environment variables in the `.env.local` file. You can learn more about the environment variables in the [Environment Variables](/docs/env) section.
40
+ The CLI copies the template bundled in the package, rewrites the generated app to depend on the same `@vercel/geistdocs` version, installs dependencies, copies `.env.example` to `.env.local`, and initializes Git.
44
41
 
45
- ### 3. Start Development Server
42
+ ## Start the development server
46
43
 
47
- Run the development server:
44
+ Open the generated project and start Next.js:
48
45
 
49
46
  ```bash title="Terminal"
47
+ cd my-docs
50
48
  pnpm dev
51
49
  ```
52
50
 
53
- Open [http://localhost:3000](http://localhost:3000) in your browser to see your documentation site.
51
+ Open `http://localhost:3000` in your browser.
54
52
 
55
- ### 4. Create a New Page
53
+ ## Edit your first page
56
54
 
57
- Create a new file in `content/docs/`:
55
+ Docs live in `content/docs`. Edit the overview page:
58
56
 
59
- ````mdx title="content/docs/my-first-page.mdx"
57
+ ```mdx title="content/docs/index.mdx"
60
58
  ---
61
- title: My First Page
62
- description: This is my first documentation page
59
+ title: Overview
60
+ description: Learn how to use my project.
63
61
  ---
64
62
 
65
- # My First Page
63
+ My project helps developers build with clear documentation.
64
+
65
+ ## Start here
66
+
67
+ Add the first workflow you want readers to complete.
68
+ ```
69
+
70
+ Add more pages by creating new `.mdx` files in `content/docs`.
66
71
 
67
- Welcome to my documentation! This page will be available at `/docs/my-first-page`.
72
+ ## Update the sidebar
68
73
 
69
- ## Features
74
+ Use `content/docs/meta.json` to control page order and groups:
70
75
 
71
- - Easy to write with Markdown
72
- - Full React component support
73
- - Automatic navigation generation
76
+ ```json title="content/docs/meta.json"
77
+ {
78
+ "title": "Documentation",
79
+ "root": true,
80
+ "pages": ["index", "getting-started", "---Guides---", "deploy"]
81
+ }
82
+ ```
83
+
84
+ ## Configure the site
85
+
86
+ Use `geistdocs.tsx` to customize the site shell:
87
+
88
+ ```tsx title="geistdocs.tsx"
89
+ export const title = "My Documentation";
74
90
 
75
- ## Code Example
91
+ export const nav = [
92
+ { label: "Docs", href: "/docs" },
93
+ { label: "GitHub", href: "https://github.com/my-org/my-repo" },
94
+ ];
95
+ ```
96
+
97
+ Read [Configuration](/docs/configuration) for the full configuration surface.
76
98
 
77
- ```typescript
78
- const greeting = (name: string): string => {
79
- return `Hello, ${name}!`;
80
- };
99
+ ## Update Geistdocs
81
100
 
82
- console.log(greeting("World"));
101
+ For package-based projects, `geistdocs update` updates the `@vercel/geistdocs` package version. It does not overwrite your local content or adapter files.
102
+
103
+ ```bash title="Terminal"
104
+ pnpm exec geistdocs update
83
105
  ```
84
- ````
85
106
 
86
- Learn more about the available syntax in the [Syntax](/docs/syntax) section.
107
+ Review and test dependency changes before committing.
@@ -1,87 +1,85 @@
1
1
  ---
2
2
  title: Overview
3
- description: A modern documentation template for spinning up Vercel documentation microsites quickly and consistently
3
+ description: Learn how Geistdocs packages the CLI, runtime, and template for documentation sites
4
4
  type: overview
5
- summary: A production-ready documentation template built with Next.js and Fumadocs for creating consistent documentation microsites.
5
+ summary: Geistdocs is a packaged documentation system for creating Next.js and Fumadocs sites with shared runtime features.
6
6
  related:
7
7
  - /docs/getting-started
8
8
  - /docs/configuration
9
9
  ---
10
10
 
11
- Geistdocs is a production-ready documentation template built with Next.js 16 and Fumadocs. It's designed as an internal Vercel template for creating documentation microsites with a consistent look, feel, and feature set across projects.
11
+ 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.
12
12
 
13
- ## Overview
13
+ <CopyPrompt text="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.">
14
+ 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.
15
+ </CopyPrompt>
14
16
 
15
- This template provides everything you need to build beautiful, functional documentation sites with minimal setup. It combines the power of MDX for content authoring with modern features like AI-powered chat, GitHub Discussions integration, and advanced search capabilities.
17
+ ## How Geistdocs works
16
18
 
17
- ## Use Cases
19
+ Geistdocs has three main parts:
18
20
 
19
- This template is ideal for:
20
-
21
- - **Product documentation** - Feature guides, tutorials, and references
22
- - **API documentation** - Endpoint documentation with code examples
23
- - **Developer tools** - CLI tools, SDKs, and framework documentation
24
- - **Internal wikis** - Team knowledge bases and guides
25
- - **Project documentation** - Open source project documentation
26
-
27
- ## What's Included
28
-
29
- Geistdocs is comprised of three main parts:
30
-
31
- - `template` - The template you'll use to create your docs site.
32
- - `platform` - The backend your docs site will use to handle feedback and translations.
33
- - `cli` - The CLI for creating and managing your docs site.
21
+ - `@vercel/geistdocs`: The npm package that provides the CLI, runtime components, route helpers, MDX components, page actions, and bundled template.
22
+ - Local adapter files: The files in your generated project that connect your configuration, content source, routes, and UI customization to the package.
23
+ - Platform services: Hosted endpoints at `geistdocs.com` for optional translation, feedback, and markdown tracking features.
34
24
 
35
25
  ```mermaid
36
26
  flowchart TB
37
- subgraph User["Developer Workflow"]
38
- init["npx @vercel/geistdocs init"]
39
- translate["npx @vercel/geistdocs translate"]
40
- docs["Your Docs Site"]
41
- end
42
-
43
- subgraph CLI["packages/cli"]
44
- initCmd["init command"]
45
- translateCmd["translate command"]
27
+ subgraph Package["@vercel/geistdocs package"]
28
+ cli["CLI: init, update, translate"]
29
+ runtime["Runtime: layout, routes, MDX, controls"]
30
+ bundledTemplate["Bundled template snapshot"]
46
31
  end
47
32
 
48
- subgraph Template["apps/template"]
33
+ subgraph Site["Generated docs site"]
34
+ config["geistdocs.tsx"]
35
+ adapters["app/, components/geistdocs/, lib/geistdocs/"]
49
36
  content["content/docs/*.mdx"]
50
- localeContent["content/docs/*.locale.mdx"]
51
- config["geistdocs.tsx\n(locale config)"]
52
- feedback["Feedback Component"]
53
37
  end
54
38
 
55
- subgraph Platform["apps/platform"]
56
- translateAPI["/translate API"]
57
- feedbackAPI["/feedback API"]
39
+ subgraph Platform["Geistdocs platform"]
40
+ translate["/translate"]
41
+ feedback["/feedback"]
42
+ tracking["/md-tracking"]
58
43
  end
59
44
 
60
- subgraph External["External Services"]
61
- aigateway["Vercel AI Gateway"]
62
- github["vercel/feedback\n(GitHub Issues)"]
63
- end
45
+ cli --> bundledTemplate
46
+ bundledTemplate --> Site
47
+ adapters --> runtime
48
+ content --> adapters
49
+ cli --> translate
50
+ runtime --> feedback
51
+ runtime --> tracking
52
+ ```
64
53
 
65
- init --> initCmd
66
- initCmd -->|"Downloads template"| Template
54
+ ## What you edit
67
55
 
68
- translate --> translateCmd
69
- translateCmd -->|"Reads locales from"| config
70
- translateCmd -->|"Reads source files"| content
71
- translateCmd -->|"POST /translate"| translateAPI
72
- translateAPI --> aigateway
73
- translateAPI -->|"Returns translations"| translateCmd
74
- translateCmd -->|"Writes translated files"| localeContent
56
+ Most projects start by editing these files:
75
57
 
76
- docs --> feedback
77
- feedback -->|"POST /feedback"| feedbackAPI
78
- feedbackAPI -->|"Creates issue"| github
79
- ```
58
+ - `content/docs`: Write and organize your docs.
59
+ - `content/docs/meta.json`: Control sidebar order and groups.
60
+ - `geistdocs.tsx`: Configure the logo, nav, GitHub repo, title, AI prompt, translations, and feature flags.
61
+ - `components/geistdocs/mdx-components.tsx`: Add or override MDX components.
62
+ - `app/[lang]/docs/[[...slug]]/page.tsx`: Configure docs page behavior, such as custom render hooks.
63
+
64
+ ## What the package owns
65
+
66
+ 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.
67
+
68
+ ## Included features
80
69
 
81
- ## Support
70
+ - MDX documentation with custom components
71
+ - Local content in `content/docs`
72
+ - Search and Ask AI
73
+ - Page actions, including feedback, copy page, open in chat, and edit on GitHub
74
+ - Raw Markdown routes for AI tools
75
+ - `llms.txt`
76
+ - RSS feed
77
+ - Theme-aware images
78
+ - Internationalized routes
79
+ - CLI commands for init, update, and translation
82
80
 
83
- For issues, questions, or contributions:
81
+ ## Next steps
84
82
 
85
- - Check the documentation pages for detailed guides
86
- - Use the built-in feedback widget to report issues
87
- - Ask questions using the AI chat assistant
83
+ - Follow [Getting Started](/docs/getting-started) to create and run a project.
84
+ - Read [Configuration](/docs/configuration) to customize the generated site.
85
+ - Read [Syntax](/docs/syntax) to write content with MDX components.