@vercel/geistdocs 1.11.4 → 1.13.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.
- package/dist/cli/index.js +1 -1
- package/dist/controls.d.ts.map +1 -1
- package/dist/controls.js +7 -5
- package/dist/home-layout.d.ts.map +1 -1
- package/dist/home-layout.js +2 -7
- package/dist/internal/page-actions-client.d.ts +7 -3
- package/dist/internal/page-actions-client.d.ts.map +1 -1
- package/dist/internal/page-actions-client.js +82 -67
- package/dist/internal/provider-client.d.ts.map +1 -1
- package/dist/internal/provider-client.js +1 -1
- package/dist/internal/sidebar-responsive.d.ts +3 -0
- package/dist/internal/sidebar-responsive.d.ts.map +1 -0
- package/dist/internal/sidebar-responsive.js +10 -0
- package/dist/internal/sidebar-tree.d.ts +23 -0
- package/dist/internal/sidebar-tree.d.ts.map +1 -0
- package/dist/internal/sidebar-tree.js +115 -0
- package/dist/internal/sidebar.d.ts +2 -5
- package/dist/internal/sidebar.d.ts.map +1 -1
- package/dist/internal/sidebar.js +282 -44
- package/dist/internal/table-of-contents.d.ts +2 -1
- package/dist/internal/table-of-contents.d.ts.map +1 -1
- package/dist/internal/table-of-contents.js +1 -1
- package/dist/internal/ui/button.d.ts.map +1 -1
- package/dist/internal/ui/button.js +4 -4
- package/dist/internal/ui/dropdown-menu.js +4 -4
- package/dist/internal/ui/popover.js +1 -1
- package/dist/internal/ui/sheet.d.ts.map +1 -1
- package/dist/internal/ui/sheet.js +2 -2
- package/dist/layout.d.ts.map +1 -1
- package/dist/layout.js +1 -6
- package/dist/mdx.d.ts +1 -0
- package/dist/mdx.d.ts.map +1 -1
- package/dist/mobile-docs-bar.d.ts.map +1 -1
- package/dist/mobile-docs-bar.js +3 -3
- package/dist/navbar.js +1 -1
- package/dist/pages/docs.d.ts +3 -1
- package/dist/pages/docs.d.ts.map +1 -1
- package/dist/pages/docs.js +16 -10
- package/dist/source-config.d.ts +1 -0
- package/dist/source-config.d.ts.map +1 -1
- package/dist/source-config.js +1 -0
- package/dist/source.d.ts +1 -0
- package/dist/source.d.ts.map +1 -1
- package/dist/source.js +21 -2
- package/dist/versions.d.ts.map +1 -1
- package/dist/versions.js +3 -3
- package/docs/agents.md +2 -2
- package/docs/llms.txt +203 -32
- package/docs/manifest.json +10 -9
- package/docs/pages/configuration.md +9 -2
- package/docs/pages/getting-started.md +2 -0
- package/docs/pages/guides/nested-navigation.md +174 -13
- package/docs/pages/syntax.md +2 -1
- package/docs/sitemap.md +1 -1
- package/package.json +1 -1
- package/source-config.js +1 -0
- package/template/app/styles/geistdocs.css +8 -6
- package/template/content/docs/configuration.mdx +9 -2
- package/template/content/docs/getting-started.mdx +2 -0
- package/template/content/docs/guides/nested-navigation.mdx +174 -12
- package/template/content/docs/syntax.mdx +2 -1
- package/template/package.json +1 -1
- package/theme.css +150 -0
|
@@ -11,6 +11,7 @@ related:
|
|
|
11
11
|
- /docs/migration
|
|
12
12
|
- /docs/provider
|
|
13
13
|
- /docs/env
|
|
14
|
+
- /docs/guides/nested-navigation
|
|
14
15
|
- /docs/versioned-docs
|
|
15
16
|
- /docs/proxy
|
|
16
17
|
---
|
|
@@ -40,6 +41,8 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
|
|
|
40
41
|
| `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
|
|
41
42
|
| `content/docs/meta.json` | Controls sidebar order and section labels. |
|
|
42
43
|
|
|
44
|
+
Read [Configure sidebar navigation](/docs/guides/nested-navigation) for page ordering, titled separators, folder indexes, nested folders, and custom navigation links.
|
|
45
|
+
|
|
43
46
|
## `geistdocs.tsx`
|
|
44
47
|
|
|
45
48
|
The root `geistdocs.tsx` file is the primary configuration surface:
|
|
@@ -178,7 +181,7 @@ To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/
|
|
|
178
181
|
|
|
179
182
|
## Page actions
|
|
180
183
|
|
|
181
|
-
|
|
184
|
+
Content actions appear in the **Copy page** menu beside the page title. **Scroll to top** and **Give feedback** remain below the table of contents so they stay available while you read. These actions are enabled by default and can be disabled through `defineConfig` in `lib/geistdocs/config.tsx`:
|
|
182
185
|
|
|
183
186
|
```tsx title="lib/geistdocs/config.tsx"
|
|
184
187
|
export const config = defineConfig({
|
|
@@ -262,10 +265,14 @@ const docsPage = createDocsPage({
|
|
|
262
265
|
},
|
|
263
266
|
metadata: ({ metadata }) => metadata,
|
|
264
267
|
mdx: ({ link }) => getMDXComponents({ a: link }),
|
|
268
|
+
tableOfContent: {
|
|
269
|
+
header: <div className="mb-3">Above the table of contents</div>,
|
|
270
|
+
footer: <div className="mt-3">Below the table of contents</div>,
|
|
271
|
+
},
|
|
265
272
|
});
|
|
266
273
|
```
|
|
267
274
|
|
|
268
|
-
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.
|
|
275
|
+
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. The `tableOfContent.header` and `tableOfContent.footer` slots render immediately above and below the table of contents.
|
|
269
276
|
|
|
270
277
|
## Package-owned runtime
|
|
271
278
|
|
|
@@ -90,6 +90,8 @@ Use `content/docs/meta.json` to control page order and groups:
|
|
|
90
90
|
}
|
|
91
91
|
```
|
|
92
92
|
|
|
93
|
+
Page and folder entries use names without extensions. A value such as `---Guides---` creates a non-clickable separator label. Read [Configure sidebar navigation](/docs/guides/nested-navigation) to add folder landing pages, deeply nested folders, custom links, and `defaultOpen` behavior.
|
|
94
|
+
|
|
93
95
|
## Configure the site
|
|
94
96
|
|
|
95
97
|
Use `geistdocs.tsx` to customize the site shell:
|
|
@@ -1,23 +1,184 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
3
|
-
description:
|
|
2
|
+
title: Configure sidebar navigation
|
|
3
|
+
description: Organize Geistdocs pages with ordered groups, separators, folder indexes, and nested navigation
|
|
4
4
|
type: guide
|
|
5
|
+
summary: Configure sidebar order, section labels, folder landing pages, and deeply nested page trees with meta.json files.
|
|
5
6
|
url: /docs/guides/nested-navigation
|
|
6
7
|
source: apps/template/content/docs/guides/nested-navigation.mdx
|
|
8
|
+
prerequisites:
|
|
9
|
+
- /docs/getting-started
|
|
10
|
+
related:
|
|
11
|
+
- /docs/configuration
|
|
12
|
+
- /docs/syntax
|
|
7
13
|
---
|
|
8
14
|
|
|
9
|
-
#
|
|
15
|
+
# Configure sidebar navigation
|
|
10
16
|
|
|
11
|
-
|
|
12
|
-
automatically from the page tree. This page lives under the **Guides** folder,
|
|
13
|
-
so the breadcrumb above reads _Guides_.
|
|
17
|
+
Use `meta.json` files to organize the Geistdocs sidebar without changing layout components. Each `meta.json` controls the pages and folders in its own directory, so the same pattern works at every nesting level.
|
|
14
18
|
|
|
15
|
-
##
|
|
19
|
+
## Start with the content tree
|
|
16
20
|
|
|
17
|
-
|
|
18
|
-
rendered on the server from the page's URL and the sidebar tree, so it is
|
|
19
|
-
present in the initial HTML — the page title never shifts once the page
|
|
20
|
-
hydrates.
|
|
21
|
+
Directories become sidebar folders, and `.mdx` files become pages. The examples on this page use the following content tree:
|
|
21
22
|
|
|
22
|
-
|
|
23
|
-
|
|
23
|
+
```text
|
|
24
|
+
content/docs/
|
|
25
|
+
├── index.mdx
|
|
26
|
+
├── getting-started.mdx
|
|
27
|
+
├── architecture.mdx
|
|
28
|
+
├── api-reference.mdx
|
|
29
|
+
├── changelog.mdx
|
|
30
|
+
├── meta.json
|
|
31
|
+
└── guides/
|
|
32
|
+
├── index.mdx
|
|
33
|
+
├── quickstarts.mdx
|
|
34
|
+
├── meta.json
|
|
35
|
+
└── integrations/
|
|
36
|
+
├── nextjs.mdx
|
|
37
|
+
├── sveltekit.mdx
|
|
38
|
+
├── meta.json
|
|
39
|
+
└── advanced/
|
|
40
|
+
├── index.mdx
|
|
41
|
+
├── caching.mdx
|
|
42
|
+
├── security.mdx
|
|
43
|
+
└── meta.json
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Every page needs a frontmatter `title`. Add a `description` to summarize the page. For a regular page, the frontmatter title becomes its sidebar label. Folder landing pages use the folder behavior described below.
|
|
47
|
+
|
|
48
|
+
## Order top-level pages and add separators
|
|
49
|
+
|
|
50
|
+
Add page and folder names to the root `pages` array without file extensions:
|
|
51
|
+
|
|
52
|
+
```json title="content/docs/meta.json"
|
|
53
|
+
{
|
|
54
|
+
"title": "My Product Documentation",
|
|
55
|
+
"root": true,
|
|
56
|
+
"pages": [
|
|
57
|
+
"index",
|
|
58
|
+
"getting-started",
|
|
59
|
+
"---Guides---",
|
|
60
|
+
"guides",
|
|
61
|
+
"---Internals---",
|
|
62
|
+
"architecture",
|
|
63
|
+
"api-reference",
|
|
64
|
+
"---Resources---",
|
|
65
|
+
"..."
|
|
66
|
+
]
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
This configuration produces three labeled groups after the two introductory pages:
|
|
71
|
+
|
|
72
|
+
- `---Guides---` adds a non-clickable **Guides** separator before the `guides` folder.
|
|
73
|
+
- `---Internals---` adds an **Internals** separator before the architecture and API reference pages.
|
|
74
|
+
- `---Resources---` adds a **Resources** separator before pages inserted by `...`.
|
|
75
|
+
|
|
76
|
+
The `...` entry inserts every page or folder that is not named elsewhere in the array. Place it where the remaining items should appear. Without `...`, unnamed items do not appear in that folder's sidebar navigation.
|
|
77
|
+
|
|
78
|
+
On desktop, top-level folders open as dedicated sidebar sections. On mobile, Geistdocs renders the same page tree as expandable nested navigation. Both layouts use the same `meta.json` files.
|
|
79
|
+
|
|
80
|
+
## Add a folder landing page
|
|
81
|
+
|
|
82
|
+
Create `index.mdx` inside a nested directory when the folder needs its own landing page:
|
|
83
|
+
|
|
84
|
+
```mdx title="content/docs/guides/index.mdx"
|
|
85
|
+
---
|
|
86
|
+
title: Guides
|
|
87
|
+
description: Follow task-focused guides for My Product.
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
Choose a guide based on the workflow you want to complete.
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Then order the folder's child pages in its `meta.json`:
|
|
94
|
+
|
|
95
|
+
```json title="content/docs/guides/meta.json"
|
|
96
|
+
{
|
|
97
|
+
"title": "Guides",
|
|
98
|
+
"pages": ["quickstarts", "integrations"]
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Leave `index` out of a nested folder's `pages` array to use `index.mdx` as the folder landing page. In the desktop section view, Geistdocs exposes a top-level folder index as **Overview**. For a nested folder, the folder label links to its index while the disclosure control expands its children.
|
|
103
|
+
|
|
104
|
+
If you include `index` explicitly in `pages`, Geistdocs treats it as a regular child page instead of the folder landing page.
|
|
105
|
+
|
|
106
|
+
## Configure deeply nested folders
|
|
107
|
+
|
|
108
|
+
Add another `meta.json` inside each nested directory. For the `integrations` folder from the example tree, group framework pages separately from advanced topics:
|
|
109
|
+
|
|
110
|
+
```json title="content/docs/guides/integrations/meta.json"
|
|
111
|
+
{
|
|
112
|
+
"title": "Integrations",
|
|
113
|
+
"defaultOpen": true,
|
|
114
|
+
"pages": [
|
|
115
|
+
"---Frameworks---",
|
|
116
|
+
"nextjs",
|
|
117
|
+
"sveltekit",
|
|
118
|
+
"---Advanced---",
|
|
119
|
+
"advanced"
|
|
120
|
+
]
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
The `advanced` directory can define another level:
|
|
125
|
+
|
|
126
|
+
```json title="content/docs/guides/integrations/advanced/meta.json"
|
|
127
|
+
{
|
|
128
|
+
"title": "Advanced Integrations",
|
|
129
|
+
"pages": ["caching", "security"]
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Because `advanced/index.mdx` exists and is not listed in `pages`, **Advanced Integrations** links to `/docs/guides/integrations/advanced`. Its child pages resolve to:
|
|
134
|
+
|
|
135
|
+
- `/docs/guides/integrations/advanced/caching`
|
|
136
|
+
- `/docs/guides/integrations/advanced/security`
|
|
137
|
+
|
|
138
|
+
Set `defaultOpen` to `true` when a folder should start expanded. Geistdocs also opens the folders that contain the active page, unless a folder explicitly sets `defaultOpen` to `false`.
|
|
139
|
+
|
|
140
|
+
## Add a badge to a page
|
|
141
|
+
|
|
142
|
+
Add a short `badge` value to page frontmatter to show status or availability beside its sidebar label:
|
|
143
|
+
|
|
144
|
+
```yaml title="content/docs/guides/new-api.mdx"
|
|
145
|
+
---
|
|
146
|
+
title: New API
|
|
147
|
+
description: Use the new API in your application.
|
|
148
|
+
badge: Beta
|
|
149
|
+
---
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Geistdocs renders the badge in desktop and mobile navigation. Badges also appear on folder landing pages because their sidebar items use the folder's `index.mdx` frontmatter. Keep badge text short so the page label has enough room to remain readable.
|
|
153
|
+
|
|
154
|
+
## Add links to the navigation
|
|
155
|
+
|
|
156
|
+
The `pages` array can include internal and external links alongside content files:
|
|
157
|
+
|
|
158
|
+
```json title="content/docs/meta.json"
|
|
159
|
+
{
|
|
160
|
+
"pages": [
|
|
161
|
+
"index",
|
|
162
|
+
"[Status](/status)",
|
|
163
|
+
"external:[GitHub](https://github.com/my-org/my-repo)"
|
|
164
|
+
]
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Use `[Label](/path)` for an internal link. Prefix an external link with `external:` so Geistdocs opens it in a new tab and shows the external-link indicator.
|
|
169
|
+
|
|
170
|
+
## Check breadcrumbs for nested pages
|
|
171
|
+
|
|
172
|
+
Geistdocs builds breadcrumbs from the same page tree. A page at `content/docs/guides/integrations/advanced/caching.mdx` receives the folder path **Guides**, **Integrations**, and **Advanced Integrations** before its page title.
|
|
173
|
+
|
|
174
|
+
Breadcrumbs render on the server from the page URL and sidebar tree, so they are present in the initial HTML. Top-level pages have no folder ancestors and do not render a breadcrumb.
|
|
175
|
+
|
|
176
|
+
## Troubleshoot missing navigation items
|
|
177
|
+
|
|
178
|
+
Check these rules when a page or folder does not appear where expected:
|
|
179
|
+
|
|
180
|
+
- Match each `pages` entry to a file or directory name without its extension.
|
|
181
|
+
- Add a `meta.json` to every folder that needs custom ordering, separators, `defaultOpen` behavior, or a title override.
|
|
182
|
+
- Add `...` when unlisted files and folders should remain visible.
|
|
183
|
+
- Leave `index` out of a nested folder's `pages` array when it should act as the folder landing page.
|
|
184
|
+
- Keep separator labels between three hyphens on each side, such as `---Internals---`.
|
package/docs/pages/syntax.md
CHANGED
|
@@ -25,10 +25,11 @@ Every MDX file should include frontmatter at the top:
|
|
|
25
25
|
---
|
|
26
26
|
title: Page Title
|
|
27
27
|
description: A brief description of the page content
|
|
28
|
+
badge: Beta
|
|
28
29
|
---
|
|
29
30
|
```
|
|
30
31
|
|
|
31
|
-
The `title` property is required and is used for the page heading and navigation. The `description` is used for SEO and page previews.
|
|
32
|
+
The `title` property is required and is used for the page heading and navigation. The `description` is used for SEO and page previews. The optional `badge` appears beside the page label in desktop and mobile sidebar navigation.
|
|
32
33
|
|
|
33
34
|
## Basic Markdown
|
|
34
35
|
|
package/docs/sitemap.md
CHANGED
|
@@ -16,11 +16,11 @@ Use it to choose focused page files from `docs/pages/` before reading the full `
|
|
|
16
16
|
- [.md Extension](pages/md.md) | URL: /docs/md | Type: conceptual | Summary: Access any documentation page as raw Markdown by appending .md or .mdx to the URL for AI tool consumption.
|
|
17
17
|
- [Agent readiness](pages/agent-readiness.md) | URL: /docs/agent-readiness | Type: guide | Summary: Generate /agents.md and /.well-known/mcp.json from Geistdocs config so agents can find docs, Markdown surfaces, API specs, and MCP endpoints.
|
|
18
18
|
- [Ask AI](pages/ask-ai.md) | URL: /docs/ask-ai | Type: conceptual | Summary: An AI-powered chat assistant with context-aware search, persistent history, and suggested prompts for your documentation.
|
|
19
|
+
- [Configure sidebar navigation](pages/guides/nested-navigation.md) | URL: /docs/guides/nested-navigation | Type: guide | Summary: Configure sidebar order, section labels, folder landing pages, and deeply nested page trees with meta.json files.
|
|
19
20
|
- [Edit on GitHub](pages/edit-on-github.md) | URL: /docs/edit-on-github | Type: integration | Summary: A direct link on every documentation page that lets readers propose changes through GitHub pull requests.
|
|
20
21
|
- [Feedback](pages/feedback.md) | URL: /docs/feedback | Type: integration | Summary: An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
|
|
21
22
|
- [Internationalization](pages/internationalization.md) | URL: /docs/internationalization | Type: guide | Summary: Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
|
|
22
23
|
- [llms.txt](pages/llms-txt.md) | URL: /docs/llms-txt | Type: conceptual | Summary: A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
|
|
23
|
-
- [Nested navigation](pages/guides/nested-navigation.md) | URL: /docs/guides/nested-navigation | Type: guide
|
|
24
24
|
- [Open in Chat](pages/open-in-chat.md) | URL: /docs/open-in-chat | Type: conceptual | Summary: Transfer documentation context to AI chat platforms like ChatGPT, Claude, Cursor, and v0 with a single click.
|
|
25
25
|
- [RSS](pages/rss.md) | URL: /docs/rss | Type: conceptual | Summary: An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
|
|
26
26
|
- [Theme-Aware Image](pages/theme-aware-image.md) | URL: /docs/theme-aware-image | Type: reference | Summary: A component that swaps images based on the active theme, built on top of Next.js Image.
|
package/package.json
CHANGED
package/source-config.js
CHANGED
|
@@ -17,18 +17,20 @@
|
|
|
17
17
|
}
|
|
18
18
|
|
|
19
19
|
/* Align docs content with navbar on mobile */
|
|
20
|
-
#nd-page {
|
|
21
|
-
@apply max-md:px-6;
|
|
22
|
-
}
|
|
23
|
-
|
|
24
20
|
/*
|
|
25
21
|
* On mobile the sticky MobileDocsBar abuts the navbar via a negative top
|
|
26
22
|
* margin, which would otherwise overlap and clip the page breadcrumb rendered
|
|
27
23
|
* above it. Hide the breadcrumb on mobile so the bar sits flush under the
|
|
28
24
|
* navbar; it stays visible on desktop, where the bar is hidden.
|
|
29
25
|
*/
|
|
30
|
-
|
|
31
|
-
|
|
26
|
+
@container (max-width: 960px) {
|
|
27
|
+
#nd-page {
|
|
28
|
+
@apply px-6;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
#nd-page > .text-fd-muted-foreground:first-child {
|
|
32
|
+
@apply hidden;
|
|
33
|
+
}
|
|
32
34
|
}
|
|
33
35
|
|
|
34
36
|
/* TOC and footer links use gray-1000 */
|
|
@@ -9,6 +9,7 @@ related:
|
|
|
9
9
|
- /docs/migration
|
|
10
10
|
- /docs/provider
|
|
11
11
|
- /docs/env
|
|
12
|
+
- /docs/guides/nested-navigation
|
|
12
13
|
- /docs/versioned-docs
|
|
13
14
|
- /docs/proxy
|
|
14
15
|
---
|
|
@@ -38,6 +39,8 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
|
|
|
38
39
|
| `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
|
|
39
40
|
| `content/docs/meta.json` | Controls sidebar order and section labels. |
|
|
40
41
|
|
|
42
|
+
Read [Configure sidebar navigation](/docs/guides/nested-navigation) for page ordering, titled separators, folder indexes, nested folders, and custom navigation links.
|
|
43
|
+
|
|
41
44
|
## `geistdocs.tsx`
|
|
42
45
|
|
|
43
46
|
The root `geistdocs.tsx` file is the primary configuration surface:
|
|
@@ -176,7 +179,7 @@ To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/
|
|
|
176
179
|
|
|
177
180
|
## Page actions
|
|
178
181
|
|
|
179
|
-
|
|
182
|
+
Content actions appear in the **Copy page** menu beside the page title. **Scroll to top** and **Give feedback** remain below the table of contents so they stay available while you read. These actions are enabled by default and can be disabled through `defineConfig` in `lib/geistdocs/config.tsx`:
|
|
180
183
|
|
|
181
184
|
```tsx title="lib/geistdocs/config.tsx"
|
|
182
185
|
export const config = defineConfig({
|
|
@@ -260,10 +263,14 @@ const docsPage = createDocsPage({
|
|
|
260
263
|
},
|
|
261
264
|
metadata: ({ metadata }) => metadata,
|
|
262
265
|
mdx: ({ link }) => getMDXComponents({ a: link }),
|
|
266
|
+
tableOfContent: {
|
|
267
|
+
header: <div className="mb-3">Above the table of contents</div>,
|
|
268
|
+
footer: <div className="mt-3">Below the table of contents</div>,
|
|
269
|
+
},
|
|
263
270
|
});
|
|
264
271
|
```
|
|
265
272
|
|
|
266
|
-
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.
|
|
273
|
+
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. The `tableOfContent.header` and `tableOfContent.footer` slots render immediately above and below the table of contents.
|
|
267
274
|
|
|
268
275
|
## Package-owned runtime
|
|
269
276
|
|
|
@@ -88,6 +88,8 @@ Use `content/docs/meta.json` to control page order and groups:
|
|
|
88
88
|
}
|
|
89
89
|
```
|
|
90
90
|
|
|
91
|
+
Page and folder entries use names without extensions. A value such as `---Guides---` creates a non-clickable separator label. Read [Configure sidebar navigation](/docs/guides/nested-navigation) to add folder landing pages, deeply nested folders, custom links, and `defaultOpen` behavior.
|
|
92
|
+
|
|
91
93
|
## Configure the site
|
|
92
94
|
|
|
93
95
|
Use `geistdocs.tsx` to customize the site shell:
|
|
@@ -1,19 +1,181 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
3
|
-
description:
|
|
2
|
+
title: Configure sidebar navigation
|
|
3
|
+
description: Organize Geistdocs pages with ordered groups, separators, folder indexes, and nested navigation
|
|
4
|
+
badge: Beta
|
|
4
5
|
type: guide
|
|
6
|
+
summary: Configure sidebar order, section labels, folder landing pages, and deeply nested page trees with meta.json files.
|
|
7
|
+
prerequisites:
|
|
8
|
+
- /docs/getting-started
|
|
9
|
+
related:
|
|
10
|
+
- /docs/configuration
|
|
11
|
+
- /docs/syntax
|
|
5
12
|
---
|
|
6
13
|
|
|
7
|
-
|
|
8
|
-
automatically from the page tree. This page lives under the **Guides** folder,
|
|
9
|
-
so the breadcrumb above reads _Guides_.
|
|
14
|
+
Use `meta.json` files to organize the Geistdocs sidebar without changing layout components. Each `meta.json` controls the pages and folders in its own directory, so the same pattern works at every nesting level.
|
|
10
15
|
|
|
11
|
-
##
|
|
16
|
+
## Start with the content tree
|
|
12
17
|
|
|
13
|
-
|
|
14
|
-
rendered on the server from the page's URL and the sidebar tree, so it is
|
|
15
|
-
present in the initial HTML — the page title never shifts once the page
|
|
16
|
-
hydrates.
|
|
18
|
+
Directories become sidebar folders, and `.mdx` files become pages. The examples on this page use the following content tree:
|
|
17
19
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
+
```text
|
|
21
|
+
content/docs/
|
|
22
|
+
├── index.mdx
|
|
23
|
+
├── getting-started.mdx
|
|
24
|
+
├── architecture.mdx
|
|
25
|
+
├── api-reference.mdx
|
|
26
|
+
├── changelog.mdx
|
|
27
|
+
├── meta.json
|
|
28
|
+
└── guides/
|
|
29
|
+
├── index.mdx
|
|
30
|
+
├── quickstarts.mdx
|
|
31
|
+
├── meta.json
|
|
32
|
+
└── integrations/
|
|
33
|
+
├── nextjs.mdx
|
|
34
|
+
├── sveltekit.mdx
|
|
35
|
+
├── meta.json
|
|
36
|
+
└── advanced/
|
|
37
|
+
├── index.mdx
|
|
38
|
+
├── caching.mdx
|
|
39
|
+
├── security.mdx
|
|
40
|
+
└── meta.json
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Every page needs a frontmatter `title`. Add a `description` to summarize the page. For a regular page, the frontmatter title becomes its sidebar label. Folder landing pages use the folder behavior described below.
|
|
44
|
+
|
|
45
|
+
## Order top-level pages and add separators
|
|
46
|
+
|
|
47
|
+
Add page and folder names to the root `pages` array without file extensions:
|
|
48
|
+
|
|
49
|
+
```json title="content/docs/meta.json"
|
|
50
|
+
{
|
|
51
|
+
"title": "My Product Documentation",
|
|
52
|
+
"root": true,
|
|
53
|
+
"pages": [
|
|
54
|
+
"index",
|
|
55
|
+
"getting-started",
|
|
56
|
+
"---Guides---",
|
|
57
|
+
"guides",
|
|
58
|
+
"---Internals---",
|
|
59
|
+
"architecture",
|
|
60
|
+
"api-reference",
|
|
61
|
+
"---Resources---",
|
|
62
|
+
"..."
|
|
63
|
+
]
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
This configuration produces three labeled groups after the two introductory pages:
|
|
68
|
+
|
|
69
|
+
- `---Guides---` adds a non-clickable **Guides** separator before the `guides` folder.
|
|
70
|
+
- `---Internals---` adds an **Internals** separator before the architecture and API reference pages.
|
|
71
|
+
- `---Resources---` adds a **Resources** separator before pages inserted by `...`.
|
|
72
|
+
|
|
73
|
+
The `...` entry inserts every page or folder that is not named elsewhere in the array. Place it where the remaining items should appear. Without `...`, unnamed items do not appear in that folder's sidebar navigation.
|
|
74
|
+
|
|
75
|
+
On desktop, top-level folders open as dedicated sidebar sections. On mobile, Geistdocs renders the same page tree as expandable nested navigation. Both layouts use the same `meta.json` files.
|
|
76
|
+
|
|
77
|
+
## Add a folder landing page
|
|
78
|
+
|
|
79
|
+
Create `index.mdx` inside a nested directory when the folder needs its own landing page:
|
|
80
|
+
|
|
81
|
+
```mdx title="content/docs/guides/index.mdx"
|
|
82
|
+
---
|
|
83
|
+
title: Guides
|
|
84
|
+
description: Follow task-focused guides for My Product.
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
Choose a guide based on the workflow you want to complete.
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Then order the folder's child pages in its `meta.json`:
|
|
91
|
+
|
|
92
|
+
```json title="content/docs/guides/meta.json"
|
|
93
|
+
{
|
|
94
|
+
"title": "Guides",
|
|
95
|
+
"pages": ["quickstarts", "integrations"]
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Leave `index` out of a nested folder's `pages` array to use `index.mdx` as the folder landing page. In the desktop section view, Geistdocs exposes a top-level folder index as **Overview**. For a nested folder, the folder label links to its index while the disclosure control expands its children.
|
|
100
|
+
|
|
101
|
+
If you include `index` explicitly in `pages`, Geistdocs treats it as a regular child page instead of the folder landing page.
|
|
102
|
+
|
|
103
|
+
## Configure deeply nested folders
|
|
104
|
+
|
|
105
|
+
Add another `meta.json` inside each nested directory. For the `integrations` folder from the example tree, group framework pages separately from advanced topics:
|
|
106
|
+
|
|
107
|
+
```json title="content/docs/guides/integrations/meta.json"
|
|
108
|
+
{
|
|
109
|
+
"title": "Integrations",
|
|
110
|
+
"defaultOpen": true,
|
|
111
|
+
"pages": [
|
|
112
|
+
"---Frameworks---",
|
|
113
|
+
"nextjs",
|
|
114
|
+
"sveltekit",
|
|
115
|
+
"---Advanced---",
|
|
116
|
+
"advanced"
|
|
117
|
+
]
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
The `advanced` directory can define another level:
|
|
122
|
+
|
|
123
|
+
```json title="content/docs/guides/integrations/advanced/meta.json"
|
|
124
|
+
{
|
|
125
|
+
"title": "Advanced Integrations",
|
|
126
|
+
"pages": ["caching", "security"]
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Because `advanced/index.mdx` exists and is not listed in `pages`, **Advanced Integrations** links to `/docs/guides/integrations/advanced`. Its child pages resolve to:
|
|
131
|
+
|
|
132
|
+
- `/docs/guides/integrations/advanced/caching`
|
|
133
|
+
- `/docs/guides/integrations/advanced/security`
|
|
134
|
+
|
|
135
|
+
Set `defaultOpen` to `true` when a folder should start expanded. Geistdocs also opens the folders that contain the active page, unless a folder explicitly sets `defaultOpen` to `false`.
|
|
136
|
+
|
|
137
|
+
## Add a badge to a page
|
|
138
|
+
|
|
139
|
+
Add a short `badge` value to page frontmatter to show status or availability beside its sidebar label:
|
|
140
|
+
|
|
141
|
+
```yaml title="content/docs/guides/new-api.mdx"
|
|
142
|
+
---
|
|
143
|
+
title: New API
|
|
144
|
+
description: Use the new API in your application.
|
|
145
|
+
badge: Beta
|
|
146
|
+
---
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Geistdocs renders the badge in desktop and mobile navigation. Badges also appear on folder landing pages because their sidebar items use the folder's `index.mdx` frontmatter. Keep badge text short so the page label has enough room to remain readable.
|
|
150
|
+
|
|
151
|
+
## Add links to the navigation
|
|
152
|
+
|
|
153
|
+
The `pages` array can include internal and external links alongside content files:
|
|
154
|
+
|
|
155
|
+
```json title="content/docs/meta.json"
|
|
156
|
+
{
|
|
157
|
+
"pages": [
|
|
158
|
+
"index",
|
|
159
|
+
"[Status](/status)",
|
|
160
|
+
"external:[GitHub](https://github.com/my-org/my-repo)"
|
|
161
|
+
]
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Use `[Label](/path)` for an internal link. Prefix an external link with `external:` so Geistdocs opens it in a new tab and shows the external-link indicator.
|
|
166
|
+
|
|
167
|
+
## Check breadcrumbs for nested pages
|
|
168
|
+
|
|
169
|
+
Geistdocs builds breadcrumbs from the same page tree. A page at `content/docs/guides/integrations/advanced/caching.mdx` receives the folder path **Guides**, **Integrations**, and **Advanced Integrations** before its page title.
|
|
170
|
+
|
|
171
|
+
Breadcrumbs render on the server from the page URL and sidebar tree, so they are present in the initial HTML. Top-level pages have no folder ancestors and do not render a breadcrumb.
|
|
172
|
+
|
|
173
|
+
## Troubleshoot missing navigation items
|
|
174
|
+
|
|
175
|
+
Check these rules when a page or folder does not appear where expected:
|
|
176
|
+
|
|
177
|
+
- Match each `pages` entry to a file or directory name without its extension.
|
|
178
|
+
- Add a `meta.json` to every folder that needs custom ordering, separators, `defaultOpen` behavior, or a title override.
|
|
179
|
+
- Add `...` when unlisted files and folders should remain visible.
|
|
180
|
+
- Leave `index` out of a nested folder's `pages` array when it should act as the folder landing page.
|
|
181
|
+
- Keep separator labels between three hyphens on each side, such as `---Internals---`.
|
|
@@ -23,10 +23,11 @@ Every MDX file should include frontmatter at the top:
|
|
|
23
23
|
---
|
|
24
24
|
title: Page Title
|
|
25
25
|
description: A brief description of the page content
|
|
26
|
+
badge: Beta
|
|
26
27
|
---
|
|
27
28
|
```
|
|
28
29
|
|
|
29
|
-
The `title` property is required and is used for the page heading and navigation. The `description` is used for SEO and page previews.
|
|
30
|
+
The `title` property is required and is used for the page heading and navigation. The `description` is used for SEO and page previews. The optional `badge` appears beside the page label in desktop and mobile sidebar navigation.
|
|
30
31
|
|
|
31
32
|
## Basic Markdown
|
|
32
33
|
|
package/template/package.json
CHANGED
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
"@streamdown/code": "^1.0.1",
|
|
19
19
|
"@vercel/agent-readability": "^0.2.1",
|
|
20
20
|
"@vercel/analytics": "^1.6.1",
|
|
21
|
-
"@vercel/geistdocs": "1.
|
|
21
|
+
"@vercel/geistdocs": "1.13.0",
|
|
22
22
|
"@vercel/speed-insights": "^1.3.1",
|
|
23
23
|
"ai": "^6.0.132",
|
|
24
24
|
"class-variance-authority": "^0.7.1",
|