@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.
- package/dist/cli/index.js +2 -2
- package/dist/components/code-block.d.ts.map +1 -1
- package/dist/components/code-block.js +5 -1
- package/dist/components/copy-prompt.d.ts +11 -0
- package/dist/components/copy-prompt.d.ts.map +1 -0
- package/dist/components/copy-prompt.js +58 -0
- package/dist/internal/page-actions-client.d.ts +1 -2
- package/dist/internal/page-actions-client.d.ts.map +1 -1
- package/dist/internal/page-actions-client.js +12 -6
- package/dist/internal/provider-client.d.ts +9 -0
- package/dist/internal/provider-client.d.ts.map +1 -0
- package/dist/internal/provider-client.js +23 -0
- package/dist/internal/sidebar.d.ts.map +1 -1
- package/dist/internal/sidebar.js +4 -3
- package/dist/internal/table-of-contents.d.ts +9 -0
- package/dist/internal/table-of-contents.d.ts.map +1 -0
- package/dist/internal/table-of-contents.js +5 -0
- package/dist/layout.d.ts +2 -7
- package/dist/layout.d.ts.map +1 -1
- package/dist/layout.js +25 -43
- package/dist/mdx.d.ts.map +1 -1
- package/dist/mdx.js +2 -0
- package/dist/pages/docs.d.ts.map +1 -1
- package/dist/pages/docs.js +15 -9
- package/dist/sidebar.d.ts +11 -0
- package/dist/sidebar.d.ts.map +1 -0
- package/dist/sidebar.js +16 -0
- package/package.json +9 -1
- package/template/_gitignore +28 -0
- package/template/app/styles/geistdocs.css +1 -0
- package/template/components/geistdocs/mobile-docs-bar.tsx +2 -6
- package/template/content/docs/ask-ai.mdx +4 -0
- package/template/content/docs/configuration.mdx +75 -72
- package/template/content/docs/deployment.mdx +6 -0
- package/template/content/docs/edit-on-github.mdx +4 -0
- package/template/content/docs/env.mdx +4 -0
- package/template/content/docs/feedback.mdx +4 -0
- package/template/content/docs/getting-started.mdx +64 -43
- package/template/content/docs/index.mdx +57 -59
- package/template/content/docs/internationalization.cn.mdx +7 -9
- package/template/content/docs/internationalization.mdx +9 -4
- package/template/content/docs/llms-txt.mdx +4 -0
- package/template/content/docs/md.mdx +4 -0
- package/template/content/docs/meta.json +2 -2
- package/template/content/docs/open-in-chat.mdx +4 -0
- package/template/content/docs/provider.mdx +4 -0
- package/template/content/docs/rss.mdx +4 -0
- package/template/content/docs/syntax.cn.mdx +2 -2
- package/template/content/docs/syntax.mdx +5 -1
- package/template/content/docs/theme-aware-image.mdx +4 -0
- package/template/package.json +1 -1
package/template/_gitignore
CHANGED
|
@@ -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
|
|
@@ -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 } =
|
|
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:
|
|
3
|
+
description: Configure a Geistdocs site through local adapter files and package APIs
|
|
4
4
|
type: reference
|
|
5
|
-
summary:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
19
|
+
## Configuration files
|
|
18
20
|
|
|
19
|
-
|
|
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
|
-
|
|
35
|
+
export const Logo = () => <span>My Docs</span>;
|
|
23
36
|
|
|
24
|
-
export const
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
49
|
-
```
|
|
50
|
+
"You are a helpful assistant that answers questions about My Documentation.";
|
|
50
51
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
52
|
+
export const suggestions = [
|
|
53
|
+
"How do I get started?",
|
|
54
|
+
"How do I deploy?",
|
|
55
|
+
];
|
|
54
56
|
|
|
55
|
-
|
|
57
|
+
export const translations = {
|
|
58
|
+
en: { displayName: "English" },
|
|
59
|
+
};
|
|
56
60
|
|
|
57
|
-
|
|
58
|
-
export const
|
|
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
|
-
|
|
65
|
+
## Page actions
|
|
67
66
|
|
|
68
|
-
|
|
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
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
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
|
-
|
|
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
|
-
|
|
85
|
+
## User-owned adapters
|
|
88
86
|
|
|
89
|
-
|
|
87
|
+
Adapter files are safe to edit. Package updates do not overwrite them.
|
|
90
88
|
|
|
91
|
-
|
|
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
|
-
|
|
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
|
-
|
|
95
|
+
const ProductCard = ({ name }: { name: string }) => <div>{name}</div>;
|
|
103
96
|
|
|
104
|
-
|
|
105
|
-
|
|
97
|
+
export const getMDXComponents = (components?: MDXComponents): MDXComponents =>
|
|
98
|
+
createMdxComponents({
|
|
99
|
+
ProductCard,
|
|
100
|
+
...components,
|
|
101
|
+
});
|
|
106
102
|
```
|
|
107
103
|
|
|
108
|
-
|
|
104
|
+
Then use it in MDX:
|
|
109
105
|
|
|
110
|
-
|
|
106
|
+
```mdx
|
|
107
|
+
<ProductCard name="My product" />
|
|
108
|
+
```
|
|
111
109
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
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:
|
|
3
|
+
description: Create a Geistdocs project and start writing documentation
|
|
4
4
|
type: guide
|
|
5
|
-
summary:
|
|
5
|
+
summary: Create a Geistdocs project, run it locally, and edit your first documentation page.
|
|
6
6
|
related:
|
|
7
|
-
- /docs/
|
|
7
|
+
- /docs/configuration
|
|
8
8
|
- /docs/syntax
|
|
9
9
|
- /docs/deployment
|
|
10
10
|
---
|
|
11
11
|
|
|
12
|
-
|
|
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
|
-
|
|
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
|
-
|
|
18
|
+
## Prerequisites
|
|
17
19
|
|
|
18
|
-
|
|
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
|
-
|
|
22
|
+
- Node.js 18 or later
|
|
23
|
+
- pnpm, npm, or another package manager
|
|
24
|
+
- Git
|
|
24
25
|
|
|
25
|
-
|
|
26
|
+
## Create a project
|
|
26
27
|
|
|
27
|
-
|
|
28
|
+
Run the Geistdocs CLI from an empty parent folder:
|
|
28
29
|
|
|
29
30
|
```bash title="Terminal"
|
|
30
|
-
|
|
31
|
+
pnpm dlx @vercel/geistdocs init --name my-docs
|
|
31
32
|
```
|
|
32
33
|
|
|
33
|
-
|
|
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
|
-
|
|
37
|
+
npx @vercel/geistdocs init --name my-docs
|
|
41
38
|
```
|
|
42
39
|
|
|
43
|
-
|
|
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
|
-
|
|
42
|
+
## Start the development server
|
|
46
43
|
|
|
47
|
-
|
|
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
|
|
51
|
+
Open `http://localhost:3000` in your browser.
|
|
54
52
|
|
|
55
|
-
|
|
53
|
+
## Edit your first page
|
|
56
54
|
|
|
57
|
-
|
|
55
|
+
Docs live in `content/docs`. Edit the overview page:
|
|
58
56
|
|
|
59
|
-
|
|
57
|
+
```mdx title="content/docs/index.mdx"
|
|
60
58
|
---
|
|
61
|
-
title:
|
|
62
|
-
description:
|
|
59
|
+
title: Overview
|
|
60
|
+
description: Learn how to use my project.
|
|
63
61
|
---
|
|
64
62
|
|
|
65
|
-
|
|
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
|
-
|
|
72
|
+
## Update the sidebar
|
|
68
73
|
|
|
69
|
-
|
|
74
|
+
Use `content/docs/meta.json` to control page order and groups:
|
|
70
75
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
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
|
-
|
|
78
|
-
const greeting = (name: string): string => {
|
|
79
|
-
return `Hello, ${name}!`;
|
|
80
|
-
};
|
|
99
|
+
## Update Geistdocs
|
|
81
100
|
|
|
82
|
-
|
|
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
|
-
|
|
107
|
+
Review and test dependency changes before committing.
|
|
@@ -1,87 +1,85 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Overview
|
|
3
|
-
description:
|
|
3
|
+
description: Learn how Geistdocs packages the CLI, runtime, and template for documentation sites
|
|
4
4
|
type: overview
|
|
5
|
-
summary:
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
17
|
+
## How Geistdocs works
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
Geistdocs has three main parts:
|
|
18
20
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
-
|
|
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
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
|
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["
|
|
56
|
-
|
|
57
|
-
|
|
39
|
+
subgraph Platform["Geistdocs platform"]
|
|
40
|
+
translate["/translate"]
|
|
41
|
+
feedback["/feedback"]
|
|
42
|
+
tracking["/md-tracking"]
|
|
58
43
|
end
|
|
59
44
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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
|
-
|
|
66
|
-
initCmd -->|"Downloads template"| Template
|
|
54
|
+
## What you edit
|
|
67
55
|
|
|
68
|
-
|
|
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
|
-
|
|
77
|
-
|
|
78
|
-
|
|
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
|
-
|
|
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
|
-
|
|
81
|
+
## Next steps
|
|
84
82
|
|
|
85
|
-
-
|
|
86
|
-
-
|
|
87
|
-
-
|
|
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.
|