@vercel/geistdocs 1.3.1 → 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.
- package/dist/cli/index.js +1 -1
- package/dist/config.d.ts +6 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/routes/agents.d.ts.map +1 -1
- package/dist/routes/agents.js +14 -29
- package/dist/routes/discovery.d.ts +14 -0
- package/dist/routes/discovery.d.ts.map +1 -0
- package/dist/routes/discovery.js +74 -0
- package/dist/routes/mcp.d.ts +26 -0
- package/dist/routes/mcp.d.ts.map +1 -0
- package/dist/routes/mcp.js +31 -0
- package/dist/source.d.ts +1 -1
- package/dist/source.d.ts.map +1 -1
- package/dist/source.js +4 -1
- package/docs/agents.md +44 -0
- package/docs/llms.txt +2965 -0
- package/docs/manifest.json +194 -0
- package/docs/pages/agent-readiness.md +141 -0
- package/docs/pages/ask-ai.md +143 -0
- package/docs/pages/configuration.md +278 -0
- package/docs/pages/deployment.md +53 -0
- package/docs/pages/edit-on-github.md +53 -0
- package/docs/pages/env.md +62 -0
- package/docs/pages/feedback.md +91 -0
- package/docs/pages/getting-started.md +116 -0
- package/docs/pages/index.md +99 -0
- package/docs/pages/internationalization.md +124 -0
- package/docs/pages/llms-txt.md +88 -0
- package/docs/pages/md.md +84 -0
- package/docs/pages/migration.md +376 -0
- package/docs/pages/open-in-chat.md +82 -0
- package/docs/pages/provider.md +76 -0
- package/docs/pages/proxy.md +180 -0
- package/docs/pages/rss.md +110 -0
- package/docs/pages/syntax.md +413 -0
- package/docs/pages/theme-aware-image.md +59 -0
- package/docs/pages/versioned-docs.md +230 -0
- package/docs/sitemap.md +25 -0
- package/package.json +12 -2
- package/template/AGENTS.md +10 -3
- package/template/app/[lang]/.well-known/mcp.json/route.ts +8 -0
- package/template/content/docs/agent-readiness.mdx +44 -8
- package/template/content/docs/configuration.mdx +1 -0
- package/template/content/docs/index.mdx +1 -1
- package/template/content/docs/llms-txt.mdx +1 -1
- package/template/content/docs/migration.mdx +12 -2
- package/template/package.json +1 -1
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Proxy and markdown routes
|
|
3
|
+
description: Add custom request logic while keeping Geistdocs markdown negotiation in the package
|
|
4
|
+
type: reference
|
|
5
|
+
summary: Configure createProxy with before and after hooks, markdown route mappings, and a static Next.js matcher.
|
|
6
|
+
url: /docs/proxy
|
|
7
|
+
source: apps/template/content/docs/proxy.mdx
|
|
8
|
+
prerequisites:
|
|
9
|
+
- /docs/configuration
|
|
10
|
+
related:
|
|
11
|
+
- /docs/migration
|
|
12
|
+
- /docs/md
|
|
13
|
+
- /docs/llms-txt
|
|
14
|
+
- /docs/versioned-docs
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
# Proxy and markdown routes
|
|
18
|
+
|
|
19
|
+
The Geistdocs proxy handles markdown negotiation, AI-agent rewrites, request tracking, and i18n fallback. Add site-specific request logic with hooks instead of copying the package proxy implementation.
|
|
20
|
+
|
|
21
|
+
Review this Geistdocs `proxy.ts` file. Check that `export const config` is static, custom logic is inside `createProxy` `before` or `after` hooks, and `markdownRoutes` cover every public docs route family.
|
|
22
|
+
|
|
23
|
+
## Basic proxy
|
|
24
|
+
|
|
25
|
+
Generated projects use `createProxy` with the default `/docs` markdown route:
|
|
26
|
+
|
|
27
|
+
```ts title="proxy.ts"
|
|
28
|
+
import { createProxy } from "@vercel/geistdocs/proxy";
|
|
29
|
+
import { config as geistdocsConfig } from "@/lib/geistdocs/config";
|
|
30
|
+
import { trackMdRequest } from "@/lib/geistdocs/md-tracking";
|
|
31
|
+
|
|
32
|
+
const proxy = createProxy({
|
|
33
|
+
config: geistdocsConfig,
|
|
34
|
+
trackMarkdownRequest: trackMdRequest,
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
export const config = {
|
|
38
|
+
matcher: [
|
|
39
|
+
"/((?!api(?:/|$)|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
|
|
40
|
+
],
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
export default proxy;
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Keep `export const config` as a static object. Next.js reads proxy matchers at build time and does not support calling a helper for this export.
|
|
47
|
+
|
|
48
|
+
## Custom request logic
|
|
49
|
+
|
|
50
|
+
Use `before` for logic that should run before Geistdocs markdown handling. Return a `Response` to stop processing.
|
|
51
|
+
|
|
52
|
+
```ts title="proxy.ts"
|
|
53
|
+
import { createProxy } from "@vercel/geistdocs/proxy";
|
|
54
|
+
import { NextResponse } from "next/server";
|
|
55
|
+
import { config as geistdocsConfig } from "@/lib/geistdocs/config";
|
|
56
|
+
|
|
57
|
+
const proxy = createProxy({
|
|
58
|
+
config: geistdocsConfig,
|
|
59
|
+
before: async ({ request, defaultLanguage }) => {
|
|
60
|
+
if (request.nextUrl.pathname === "/") {
|
|
61
|
+
return NextResponse.rewrite(
|
|
62
|
+
new URL(`/${defaultLanguage}/home`, request.url)
|
|
63
|
+
);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
return null;
|
|
67
|
+
},
|
|
68
|
+
});
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Use `after` for logic that should run after markdown handling but before the i18n fallback:
|
|
72
|
+
|
|
73
|
+
```ts title="proxy.ts"
|
|
74
|
+
const proxy = createProxy({
|
|
75
|
+
config: geistdocsConfig,
|
|
76
|
+
after: async ({ request }) => {
|
|
77
|
+
const session = await getSessionFromReq(request);
|
|
78
|
+
|
|
79
|
+
if (!session) {
|
|
80
|
+
return null;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
return refreshSession(request, session);
|
|
84
|
+
},
|
|
85
|
+
});
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Markdown route mappings
|
|
89
|
+
|
|
90
|
+
Define `content` sections in `lib/geistdocs/config.tsx` to infer standard Markdown route mappings from each section route. The package still serves `/llms.txt` and individual page Markdown through route helpers; the proxy uses these mappings for `.md`, `.mdx`, `Accept: text/markdown`, and AI-agent requests.
|
|
91
|
+
|
|
92
|
+
Geistdocs does not infer Markdown mappings for `content` sections with `route: "/"`. A root catch-all such as `/*path` can make a homepage or other application routes look like documentation. Use explicit `markdownRoutes` for root-mounted docs.
|
|
93
|
+
|
|
94
|
+
```tsx title="lib/geistdocs/config.tsx"
|
|
95
|
+
export const config = defineConfig({
|
|
96
|
+
// ...
|
|
97
|
+
content: [{ id: "docs", label: "Docs", dir: "content/docs", route: "/docs" }],
|
|
98
|
+
});
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Use `markdownRoutes` when you need to override the inferred mappings:
|
|
102
|
+
|
|
103
|
+
```ts title="proxy.ts"
|
|
104
|
+
const proxy = createProxy({
|
|
105
|
+
config: geistdocsConfig,
|
|
106
|
+
markdownRoutes: [
|
|
107
|
+
{ from: "/docs/*path", to: "/[lang]/llms.mdx/*path" },
|
|
108
|
+
{ from: "/cookbook/*path", to: "/[lang]/llms.mdx/cookbook/*path" },
|
|
109
|
+
{ from: "/v5/docs/*path", to: "/[lang]/v5/llms.mdx/*path" },
|
|
110
|
+
],
|
|
111
|
+
});
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
With these mappings:
|
|
115
|
+
|
|
116
|
+
| Request | Rewritten destination |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| `/docs/getting-started.md` | `/en/llms.mdx/getting-started` |
|
|
119
|
+
| `/cookbook/install.mdx` | `/en/llms.mdx/cookbook/install` |
|
|
120
|
+
| `/v5/docs/intro` with `Accept: text/markdown` | `/en/v5/llms.mdx/intro` |
|
|
121
|
+
|
|
122
|
+
Use `[lang]` in the destination when your markdown route is nested under `app/[lang]`. Use `*path` or `:path*` to insert the matched wildcard path.
|
|
123
|
+
|
|
124
|
+
## Root-mounted docs
|
|
125
|
+
|
|
126
|
+
For docs served from the site root, set the source `baseUrl` and config route to `/`:
|
|
127
|
+
|
|
128
|
+
```ts title="lib/geistdocs/source.ts"
|
|
129
|
+
export const geistdocsSource = createSource({
|
|
130
|
+
docs,
|
|
131
|
+
config,
|
|
132
|
+
baseUrl: "/",
|
|
133
|
+
});
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
```tsx title="lib/geistdocs/config.tsx"
|
|
137
|
+
export const config = defineConfig({
|
|
138
|
+
// ...
|
|
139
|
+
content: [{ id: "docs", label: "Docs", dir: "content/docs", route: "/" }],
|
|
140
|
+
});
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
If the whole site is documentation and there is no separate homepage, you can map all root paths to page-level Markdown:
|
|
144
|
+
|
|
145
|
+
```ts title="proxy.ts"
|
|
146
|
+
const proxy = createProxy({
|
|
147
|
+
config: geistdocsConfig,
|
|
148
|
+
markdownRoutes: [{ from: "/*path", to: "/[lang]/llms.mdx/*path" }],
|
|
149
|
+
});
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
If a homepage or app routes also live at `/`, do not use a broad `/*path` mapping. Enumerate each docs route family instead:
|
|
153
|
+
|
|
154
|
+
```ts title="proxy.ts"
|
|
155
|
+
const proxy = createProxy({
|
|
156
|
+
config: geistdocsConfig,
|
|
157
|
+
markdownRoutes: [
|
|
158
|
+
{ from: "/api-reference/*path", to: "/[lang]/llms.mdx/api-reference/*path" },
|
|
159
|
+
{ from: "/guides/*path", to: "/[lang]/llms.mdx/guides/*path" },
|
|
160
|
+
{ from: "/concepts/*path", to: "/[lang]/llms.mdx/concepts/*path" },
|
|
161
|
+
],
|
|
162
|
+
});
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## Hook context
|
|
166
|
+
|
|
167
|
+
Both `before` and `after` receive the same context:
|
|
168
|
+
|
|
169
|
+
| Property | Type | Description |
|
|
170
|
+
| --- | --- | --- |
|
|
171
|
+
| `request` | `NextRequest` | The incoming request. |
|
|
172
|
+
| `context` | `NextFetchEvent` | The proxy event, including `waitUntil`. |
|
|
173
|
+
| `defaultLanguage` | `string` | The configured default language. |
|
|
174
|
+
| `languages` | `string[]` | All configured languages. |
|
|
175
|
+
|
|
176
|
+
## Next steps
|
|
177
|
+
|
|
178
|
+
- Read [.md extension](/docs/md) to understand single-page Markdown responses.
|
|
179
|
+
- Read [Migration guide](/docs/migration) to move existing middleware behavior into `createProxy` hooks.
|
|
180
|
+
- Read [Versioned docs](/docs/versioned-docs) to map multiple public route families.
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: RSS
|
|
3
|
+
description: Keep users updated with an automatically generated RSS feed for your documentation
|
|
4
|
+
type: conceptual
|
|
5
|
+
summary: An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
|
|
6
|
+
url: /docs/rss
|
|
7
|
+
source: apps/template/content/docs/rss.mdx
|
|
8
|
+
related:
|
|
9
|
+
- /docs/env
|
|
10
|
+
- /docs/configuration
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# RSS
|
|
14
|
+
|
|
15
|
+
The RSS feature provides an automatically generated RSS 2.0 feed for your documentation. This allows users to subscribe to updates and stay informed when new content is published or existing pages are modified.
|
|
16
|
+
|
|
17
|
+
Help me verify the RSS feed for this Geistdocs site. Check the `/rss.xml` route, confirm the production URL environment variable is set, and explain how page metadata affects feed items.
|
|
18
|
+
|
|
19
|
+
## How it works
|
|
20
|
+
|
|
21
|
+
Geistdocs automatically generates an RSS feed that includes:
|
|
22
|
+
|
|
23
|
+
- All published documentation pages
|
|
24
|
+
- Page titles and descriptions
|
|
25
|
+
- Direct links to each page
|
|
26
|
+
- Last modified dates
|
|
27
|
+
- Author information
|
|
28
|
+
|
|
29
|
+
The feed is regenerated on each request, ensuring subscribers always receive the most current information about your documentation.
|
|
30
|
+
|
|
31
|
+
## Accessing the Feed
|
|
32
|
+
|
|
33
|
+
The RSS feed is available at:
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
https://your-domain.com/rss.xml
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Users can subscribe to this URL using:
|
|
40
|
+
|
|
41
|
+
- RSS readers (Feedly, Inoreader, NewsBlur)
|
|
42
|
+
- Email services (Blogtrottr, Kill the Newsletter)
|
|
43
|
+
- Browser extensions
|
|
44
|
+
- News aggregators
|
|
45
|
+
|
|
46
|
+
### RSS Button
|
|
47
|
+
|
|
48
|
+
An RSS button appears in the navigation bar so readers can discover and subscribe to your feed. Clicking the button opens the RSS XML in a new tab.
|
|
49
|
+
|
|
50
|
+
## Feed Format
|
|
51
|
+
|
|
52
|
+
The RSS feed follows the RSS 2.0 specification and includes:
|
|
53
|
+
|
|
54
|
+
### Channel Metadata
|
|
55
|
+
|
|
56
|
+
```xml
|
|
57
|
+
<channel>
|
|
58
|
+
<title>Your Documentation Title</title>
|
|
59
|
+
<link>https://your-domain.com</link>
|
|
60
|
+
<language>en</language>
|
|
61
|
+
<image>https://your-domain.com/banner.png</image>
|
|
62
|
+
<copyright>All rights reserved [Year], [Your Organization]</copyright>
|
|
63
|
+
</channel>
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Item Format
|
|
67
|
+
|
|
68
|
+
Each documentation page appears as an item:
|
|
69
|
+
|
|
70
|
+
```xml
|
|
71
|
+
<item>
|
|
72
|
+
<guid>page-url</guid>
|
|
73
|
+
<title>Page Title</title>
|
|
74
|
+
<description>Page description</description>
|
|
75
|
+
<link>https://your-domain.com/docs/page-url</link>
|
|
76
|
+
<pubDate>Thu, 12 Nov 2025 00:00:00 GMT</pubDate>
|
|
77
|
+
<author>
|
|
78
|
+
<name>Your Organization</name>
|
|
79
|
+
</author>
|
|
80
|
+
</item>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Configuration
|
|
84
|
+
|
|
85
|
+
The RSS feed requires the `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` environment variable to be set, which you can read more about in the [Environment Variables](/docs/env) section.
|
|
86
|
+
|
|
87
|
+
It also requires a `title` exported from the Geistdocs configuration file, which you can read more about in the [Configuration](/docs/configuration) section.
|
|
88
|
+
|
|
89
|
+
## Features
|
|
90
|
+
|
|
91
|
+
### Automatic Updates
|
|
92
|
+
|
|
93
|
+
The feed automatically includes:
|
|
94
|
+
|
|
95
|
+
- Newly created pages
|
|
96
|
+
- Updated page content (using last modified dates)
|
|
97
|
+
- Changed titles or descriptions
|
|
98
|
+
- All pages from your documentation source
|
|
99
|
+
|
|
100
|
+
### Last Modified Dates
|
|
101
|
+
|
|
102
|
+
Pages use their `lastModified` frontmatter field or fall back to the current date:
|
|
103
|
+
|
|
104
|
+
```mdx title="content/docs/example.mdx"
|
|
105
|
+
---
|
|
106
|
+
title: Example Page
|
|
107
|
+
description: An example documentation page
|
|
108
|
+
lastModified: 2025-11-12
|
|
109
|
+
---
|
|
110
|
+
```
|
|
@@ -0,0 +1,413 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Syntax
|
|
3
|
+
description: Learn about the supported markdown syntax and formatting options
|
|
4
|
+
type: reference
|
|
5
|
+
summary: Supported MDX syntax including text formatting, code blocks, line highlighting, and Mermaid diagrams.
|
|
6
|
+
url: /docs/syntax
|
|
7
|
+
source: apps/template/content/docs/syntax.mdx
|
|
8
|
+
prerequisites:
|
|
9
|
+
- /docs/getting-started
|
|
10
|
+
related:
|
|
11
|
+
- /docs/configuration
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# Syntax
|
|
15
|
+
|
|
16
|
+
Geistdocs supports MDX, a superset of Markdown that allows you to use JSX components within your documentation. This guide covers all the formatting options available.
|
|
17
|
+
|
|
18
|
+
Help me write a Geistdocs MDX page. Use this page as a syntax reference and create an example page with frontmatter, headings, links, a code block, a `Callout`, and a `CopyPrompt` component.
|
|
19
|
+
|
|
20
|
+
## Frontmatter
|
|
21
|
+
|
|
22
|
+
Every MDX file should include frontmatter at the top:
|
|
23
|
+
|
|
24
|
+
```yaml
|
|
25
|
+
---
|
|
26
|
+
title: Page Title
|
|
27
|
+
description: A brief description of the page content
|
|
28
|
+
---
|
|
29
|
+
```
|
|
30
|
+
|
|
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
|
+
|
|
33
|
+
## Basic Markdown
|
|
34
|
+
|
|
35
|
+
### Text Formatting
|
|
36
|
+
|
|
37
|
+
You can style text using standard Markdown syntax:
|
|
38
|
+
|
|
39
|
+
- **Bold text** with `**double asterisks**`
|
|
40
|
+
- _Italic text_ with `*single asterisks*`
|
|
41
|
+
- ~~Strikethrough~~ with `~~double tildes~~`
|
|
42
|
+
- `Inline code` with `` `backticks` ``
|
|
43
|
+
|
|
44
|
+
### Headings
|
|
45
|
+
|
|
46
|
+
Use `#` symbols to create headings:
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
# Heading 1
|
|
50
|
+
|
|
51
|
+
## Heading 2
|
|
52
|
+
|
|
53
|
+
### Heading 3
|
|
54
|
+
|
|
55
|
+
#### Heading 4
|
|
56
|
+
|
|
57
|
+
##### Heading 5
|
|
58
|
+
|
|
59
|
+
###### Heading 6
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Headings automatically generate anchor links for navigation and deep linking.
|
|
63
|
+
|
|
64
|
+
### Lists
|
|
65
|
+
|
|
66
|
+
Create unordered lists with `-`, `*`, or `+`:
|
|
67
|
+
|
|
68
|
+
- First item
|
|
69
|
+
- Second item
|
|
70
|
+
- Nested item
|
|
71
|
+
- Another nested item
|
|
72
|
+
- Third item
|
|
73
|
+
|
|
74
|
+
Create ordered lists with numbers:
|
|
75
|
+
|
|
76
|
+
1. First step
|
|
77
|
+
2. Second step
|
|
78
|
+
3. Third step
|
|
79
|
+
|
|
80
|
+
### Blockquotes
|
|
81
|
+
|
|
82
|
+
Use `>` to create blockquotes:
|
|
83
|
+
|
|
84
|
+
> This is a blockquote. You can use it to highlight important information or quotes from external sources.
|
|
85
|
+
|
|
86
|
+
### Links
|
|
87
|
+
|
|
88
|
+
Create links with `[text](url)`:
|
|
89
|
+
|
|
90
|
+
- [External link](https://vercel.com)
|
|
91
|
+
- [Internal link](/docs/getting-started)
|
|
92
|
+
|
|
93
|
+
### Images
|
|
94
|
+
|
|
95
|
+
Add images with ``:
|
|
96
|
+
|
|
97
|
+
```md
|
|
98
|
+

|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## GitHub Flavored Markdown
|
|
102
|
+
|
|
103
|
+
Geistdocs supports GFM extensions including tables, task lists, and autolinks.
|
|
104
|
+
|
|
105
|
+
### Tables
|
|
106
|
+
|
|
107
|
+
Create tables using pipes and dashes:
|
|
108
|
+
|
|
109
|
+
```md
|
|
110
|
+
| Feature | Description | Status |
|
|
111
|
+
| -------- | ----------------- | --------- |
|
|
112
|
+
| Markdown | Basic formatting | Supported |
|
|
113
|
+
| GFM | GitHub extensions | Supported |
|
|
114
|
+
| MDX | JSX in Markdown | Supported |
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
This renders as:
|
|
118
|
+
|
|
119
|
+
| Feature | Description | Status |
|
|
120
|
+
| -------- | ----------------- | --------- |
|
|
121
|
+
| Markdown | Basic formatting | Supported |
|
|
122
|
+
| GFM | GitHub extensions | Supported |
|
|
123
|
+
| MDX | JSX in Markdown | Supported |
|
|
124
|
+
|
|
125
|
+
### Task Lists
|
|
126
|
+
|
|
127
|
+
Create interactive task lists:
|
|
128
|
+
|
|
129
|
+
```md
|
|
130
|
+
- [x] Completed task
|
|
131
|
+
- [ ] Incomplete task
|
|
132
|
+
- [ ] Another task to do
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
This renders as:
|
|
136
|
+
|
|
137
|
+
- [x] Completed task
|
|
138
|
+
- [ ] Incomplete task
|
|
139
|
+
- [ ] Another task to do
|
|
140
|
+
|
|
141
|
+
### Autolinks
|
|
142
|
+
|
|
143
|
+
URLs are automatically converted to clickable links:
|
|
144
|
+
|
|
145
|
+
```md
|
|
146
|
+
https://vercel.com
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
This renders as:
|
|
150
|
+
|
|
151
|
+
https://vercel.com
|
|
152
|
+
|
|
153
|
+
## Code Blocks
|
|
154
|
+
|
|
155
|
+
Fenced code blocks support syntax highlighting for many languages.
|
|
156
|
+
|
|
157
|
+
### Basic Syntax Highlighting
|
|
158
|
+
|
|
159
|
+
Specify the language after the opening backticks:
|
|
160
|
+
|
|
161
|
+
````md
|
|
162
|
+
```typescript
|
|
163
|
+
const greet = (name: string): string => {
|
|
164
|
+
return `Hello, ${name}!`;
|
|
165
|
+
};
|
|
166
|
+
```
|
|
167
|
+
````
|
|
168
|
+
|
|
169
|
+
This renders as:
|
|
170
|
+
|
|
171
|
+
```typescript
|
|
172
|
+
const greet = (name: string): string => {
|
|
173
|
+
return `Hello, ${name}!`;
|
|
174
|
+
};
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### Titles
|
|
178
|
+
|
|
179
|
+
Add a title to your code block with the `title` attribute:
|
|
180
|
+
|
|
181
|
+
````md
|
|
182
|
+
```tsx title="components/button.tsx"
|
|
183
|
+
export const Button = ({ children }) => {
|
|
184
|
+
return <button type="button">{children}</button>;
|
|
185
|
+
};
|
|
186
|
+
```
|
|
187
|
+
````
|
|
188
|
+
|
|
189
|
+
This renders as:
|
|
190
|
+
|
|
191
|
+
```tsx title="components/button.tsx"
|
|
192
|
+
export const Button = ({ children }) => {
|
|
193
|
+
return <button type="button">{children}</button>;
|
|
194
|
+
};
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
### Line Numbers
|
|
198
|
+
|
|
199
|
+
Display line numbers by adding the `lineNumbers` attribute:
|
|
200
|
+
|
|
201
|
+
````md
|
|
202
|
+
```typescript lineNumbers
|
|
203
|
+
const numbers = [1, 2, 3, 4, 5];
|
|
204
|
+
const doubled = numbers.map((n) => n * 2);
|
|
205
|
+
console.log(doubled);
|
|
206
|
+
```
|
|
207
|
+
````
|
|
208
|
+
|
|
209
|
+
This renders as:
|
|
210
|
+
|
|
211
|
+
```typescript lineNumbers
|
|
212
|
+
const numbers = [1, 2, 3, 4, 5];
|
|
213
|
+
const doubled = numbers.map((n) => n * 2);
|
|
214
|
+
console.log(doubled);
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Line Highlighting
|
|
218
|
+
|
|
219
|
+
Highlight specific lines using the `[!code highlight]` comment:
|
|
220
|
+
|
|
221
|
+
````md
|
|
222
|
+
```typescript
|
|
223
|
+
const config = {
|
|
224
|
+
theme: "dark", // [ !code highlight]
|
|
225
|
+
language: "en",
|
|
226
|
+
};
|
|
227
|
+
```
|
|
228
|
+
````
|
|
229
|
+
|
|
230
|
+
Remove the space before `!` when using this syntax. This renders as:
|
|
231
|
+
|
|
232
|
+
```typescript
|
|
233
|
+
const config = {
|
|
234
|
+
theme: "dark", // [!code highlight]
|
|
235
|
+
language: "en",
|
|
236
|
+
};
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### Word Highlighting
|
|
240
|
+
|
|
241
|
+
Highlight specific words with `[!code word:term]`:
|
|
242
|
+
|
|
243
|
+
````md
|
|
244
|
+
```typescript
|
|
245
|
+
// [ !code word:config]
|
|
246
|
+
const config = {
|
|
247
|
+
theme: "dark",
|
|
248
|
+
};
|
|
249
|
+
|
|
250
|
+
console.log(config);
|
|
251
|
+
```
|
|
252
|
+
````
|
|
253
|
+
|
|
254
|
+
Remove the space before `!` when using this syntax. This renders as:
|
|
255
|
+
|
|
256
|
+
```typescript
|
|
257
|
+
// [!code word:config]
|
|
258
|
+
const config = {
|
|
259
|
+
theme: "dark",
|
|
260
|
+
};
|
|
261
|
+
|
|
262
|
+
console.log(config);
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### Diff Syntax
|
|
266
|
+
|
|
267
|
+
Show additions and deletions with `[!code ++]` and `[!code --]`:
|
|
268
|
+
|
|
269
|
+
````md
|
|
270
|
+
```typescript
|
|
271
|
+
const config = {
|
|
272
|
+
theme: "light", // [ !code --]
|
|
273
|
+
theme: "dark", // [ !code ++]
|
|
274
|
+
language: "en",
|
|
275
|
+
};
|
|
276
|
+
```
|
|
277
|
+
````
|
|
278
|
+
|
|
279
|
+
Remove the space before `!` when using this syntax. This renders as:
|
|
280
|
+
|
|
281
|
+
```typescript
|
|
282
|
+
const config = {
|
|
283
|
+
theme: "light", // [!code --]
|
|
284
|
+
theme: "dark", // [!code ++]
|
|
285
|
+
language: "en",
|
|
286
|
+
};
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
### Focus Lines
|
|
290
|
+
|
|
291
|
+
Draw attention to specific lines with `[!code focus]`:
|
|
292
|
+
|
|
293
|
+
````md
|
|
294
|
+
```typescript
|
|
295
|
+
const numbers = [1, 2, 3, 4, 5];
|
|
296
|
+
const sum = numbers.reduce((a, b) => a + b, 0); // [ !code focus]
|
|
297
|
+
console.log(sum);
|
|
298
|
+
```
|
|
299
|
+
````
|
|
300
|
+
|
|
301
|
+
Remove the space before `!` when using this syntax. This renders as:
|
|
302
|
+
|
|
303
|
+
```typescript
|
|
304
|
+
const numbers = [1, 2, 3, 4, 5];
|
|
305
|
+
const sum = numbers.reduce((a, b) => a + b, 0); // [!code focus]
|
|
306
|
+
console.log(sum);
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
## Mermaid Diagrams
|
|
310
|
+
|
|
311
|
+
Create diagrams and flowcharts using Mermaid syntax.
|
|
312
|
+
|
|
313
|
+
### Flowcharts
|
|
314
|
+
|
|
315
|
+
````md
|
|
316
|
+
```mermaid
|
|
317
|
+
graph TD;
|
|
318
|
+
A[Start] --> B{Is it working?};
|
|
319
|
+
B -->|Yes| C[Great!];
|
|
320
|
+
B -->|No| D[Debug];
|
|
321
|
+
D --> B;
|
|
322
|
+
```
|
|
323
|
+
````
|
|
324
|
+
|
|
325
|
+
This renders as:
|
|
326
|
+
|
|
327
|
+
```mermaid
|
|
328
|
+
graph TD;
|
|
329
|
+
A[Start] --> B{Is it working?};
|
|
330
|
+
B -->|Yes| C[Great!];
|
|
331
|
+
B -->|No| D[Debug];
|
|
332
|
+
D --> B;
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
### Sequence Diagrams
|
|
336
|
+
|
|
337
|
+
````md
|
|
338
|
+
```mermaid
|
|
339
|
+
sequenceDiagram
|
|
340
|
+
participant User
|
|
341
|
+
participant API
|
|
342
|
+
participant Database
|
|
343
|
+
User->>API: Request data
|
|
344
|
+
API->>Database: Query
|
|
345
|
+
Database-->>API: Results
|
|
346
|
+
API-->>User: Response
|
|
347
|
+
```
|
|
348
|
+
````
|
|
349
|
+
|
|
350
|
+
This renders as:
|
|
351
|
+
|
|
352
|
+
```mermaid
|
|
353
|
+
sequenceDiagram
|
|
354
|
+
participant User
|
|
355
|
+
participant API
|
|
356
|
+
participant Database
|
|
357
|
+
User->>API: Request data
|
|
358
|
+
API->>Database: Query
|
|
359
|
+
Database-->>API: Results
|
|
360
|
+
API-->>User: Response
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
### Architecture Diagrams
|
|
364
|
+
|
|
365
|
+
````md
|
|
366
|
+
```mermaid
|
|
367
|
+
graph TD;
|
|
368
|
+
subgraph Frontend
|
|
369
|
+
A[Web App]
|
|
370
|
+
B[Mobile App]
|
|
371
|
+
end
|
|
372
|
+
subgraph Backend
|
|
373
|
+
C[API Gateway]
|
|
374
|
+
D[Auth Service]
|
|
375
|
+
E[Data Service]
|
|
376
|
+
end
|
|
377
|
+
subgraph Storage
|
|
378
|
+
F[(Database)]
|
|
379
|
+
G[(Cache)]
|
|
380
|
+
end
|
|
381
|
+
A --> C
|
|
382
|
+
B --> C
|
|
383
|
+
C --> D
|
|
384
|
+
C --> E
|
|
385
|
+
E --> F
|
|
386
|
+
E --> G
|
|
387
|
+
```
|
|
388
|
+
````
|
|
389
|
+
|
|
390
|
+
This renders as:
|
|
391
|
+
|
|
392
|
+
```mermaid
|
|
393
|
+
graph TD;
|
|
394
|
+
subgraph Frontend
|
|
395
|
+
A[Web App]
|
|
396
|
+
B[Mobile App]
|
|
397
|
+
end
|
|
398
|
+
subgraph Backend
|
|
399
|
+
C[API Gateway]
|
|
400
|
+
D[Auth Service]
|
|
401
|
+
E[Data Service]
|
|
402
|
+
end
|
|
403
|
+
subgraph Storage
|
|
404
|
+
F[(Database)]
|
|
405
|
+
G[(Cache)]
|
|
406
|
+
end
|
|
407
|
+
A --> C
|
|
408
|
+
B --> C
|
|
409
|
+
C --> D
|
|
410
|
+
C --> E
|
|
411
|
+
E --> F
|
|
412
|
+
E --> G
|
|
413
|
+
```
|