Skip to content

Commit 86250fc

Browse files
SoonIterCopilot
SoonIter
and
Copilot
authored
docs: improve conventional route documentation with better examples and best practices (#2995)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 3b26efc commit 86250fc

File tree

17 files changed

+382
-161
lines changed

17 files changed

+382
-161
lines changed

website/docs/en/guide/use-mdx/_Border.tsx renamed to website/docs/components/Border.tsx

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,13 @@ import type { ReactNode } from 'react';
22

33
export const Border = ({ children }: { children: ReactNode }) => {
44
return (
5-
<div style={{ border: '1px solid var(--rp-c-divider)', padding: '10px' }}>
5+
<div
6+
style={{
7+
border: '1px solid var(--rp-c-divider)',
8+
borderRadius: 'var(--rp-radius)',
9+
padding: '10px',
10+
}}
11+
>
612
{children}
713
</div>
814
);

‎website/docs/en/fragments/_button.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#### button
2+
3+
This is text from MDX

‎website/docs/en/fragments/file-structure.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
Here is a best practice file structure that includes [MDX fragments and React components](/guide/use-mdx/components#component), [custom themes](/guide/basic/custom-theme), [conventional routing](/guide/basic/conventional-route), and [internationalization](/guide/basic/i18n):
2+
3+
```tree
4+
├── docs
5+
│ ├── components # React components used in documentation
6+
│ │ └── Example.tsx
7+
│ ├── zh
8+
│ │ ├── fragments # zh document fragments
9+
│ │ │ └── example.mdx
10+
│ │ └── index.mdx
11+
│ └── en
12+
│ ├── fragments # en document fragments
13+
│ │ └── example.mdx
14+
│ └── index.mdx
15+
└── theme
16+
├── components # React components for theme
17+
│ └── DocFooter.tsx
18+
└── index.tsx
19+
```
20+
21+
```ts title="rspress.config.ts"
22+
import { defineConfig } from '@rspress/core';
23+
24+
export default defineConfig({
25+
route: {
26+
exclude: ['*/components/**/*', '*/fragments/**/*'], // Files in these directories won't be registered as routes
27+
},
28+
lang: 'en',
29+
locales: [
30+
{
31+
lang: 'zh',
32+
label: '中文',
33+
},
34+
{
35+
lang: 'en',
36+
label: 'English',
37+
},
38+
],
39+
});
40+
```
41+
42+
```json title="tsconfig.json"
43+
{
44+
"compilerOptions": {
45+
"lib": ["DOM", "ESNext"],
46+
"jsx": "react-jsx",
47+
"moduleResolution": "bundler",
48+
"paths": {
49+
"i18n": ["./i18n.json"],
50+
"@theme": ["./theme/index.tsx"]
51+
}
52+
},
53+
"include": ["docs", "theme", "rspress.config.ts"],
54+
"mdx": {
55+
"checkMdx": true
56+
}
57+
}
58+
```

‎website/docs/en/fragments/route-convention.mdx‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
import { Tabs, Tab } from '@theme';
2+
import { Border } from '../../components/Border';
3+
4+
In the [docs directory](/api/config/config-basic#root), MDX fragments or React components need to be excluded from routing through the [route.exclude](/api/config/config-basic#routeexclude) configuration. For convenience, files starting with "\_" are excluded by default via [route.excludeConvention](/api/config/config-basic#routeexcludeconvention).
5+
6+
You can also place components in adjacent directories outside the docs directory, for example:
7+
8+
```tree
9+
docs
10+
├── _button.mdx
11+
└── index.mdx
12+
components
13+
└── button.tsx
14+
```
15+
16+
<Tabs>
17+
<Tab label="docs/index.mdx">
18+
19+
```mdx
20+
import ButtonFragment from './_button.mdx';
21+
import Button from '../../components/button';
22+
23+
<ButtonFragment />
24+
<Button />
25+
```
26+
27+
</Tab>
28+
<Tab label="docs/_button.mdx">
29+
30+
```mdx file="./_button.mdx"
31+
32+
```
33+
34+
</Tab>
35+
<Tab label="components/button.tsx">
36+
37+
```tsx
38+
const Button = () => <button>This is a button from tsx</button>;
39+
export default Button;
40+
```
41+
42+
</Tab>
43+
</Tabs>
44+
45+
It will be rendered as:
46+
47+
<Border>
48+
49+
import Button from './_button.mdx';
50+
51+
<Button />
52+
<button>This is a button from tsx</button>
53+
54+
</Border>

‎website/docs/en/guide/basic/conventional-route.mdx‎

Lines changed: 74 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -13,20 +13,35 @@ Rspress automatically scans the root directory and all subdirectories, and maps
1313
```tree
1414
docs
1515
├── foo
16-
│ └── bar.md
17-
└── foo.md
16+
│ ├── bar.md
17+
│ └── index.md
18+
├── zoo.md
19+
└── index.md
1820
```
1921

20-
Then `bar.md` will be routed to `/foo/bar`, and `foo.md` will be routed to `/foo`.
22+
Then `bar.md` will be routed to `/foo/bar` and `/foo/index.md` will be routed to `/foo/`.
2123

2224
The specific mapping rules are as follows:
2325

24-
| file path | route path |
25-
| --------------- | ---------- |
26-
| `index.md` | `/` |
27-
| `/foo.md` | `/foo` |
28-
| `/foo/bar.md` | `/foo/bar` |
29-
| `/zoo/index.md` | `/zoo/` |
26+
| filepath | route path | `cleanUrl: false` path |
27+
| --------------- | ---------- | ---------------------- |
28+
| `index.md` | `/` | `/index.html` |
29+
| `/zoo.md` | `/zoo` | `/zoo.html` |
30+
| `/foo/index.md` | `/foo/` | `/foo/index.html` |
31+
| `/foo/bar.md` | `/foo/bar` | `/foo/bar.html` |
32+
33+
:::warning
34+
35+
Do not have files and folders with the same name, which will cause routing conflicts. For example, the following file structure is not allowed:
36+
37+
```tree
38+
docs
39+
├── foo
40+
│ └── index.md
41+
└── foo.md
42+
```
43+
44+
:::
3045

3146
## Component routing
3247

@@ -59,24 +74,63 @@ import { defineConfig } from '@rspress/core';
5974

6075
export default defineConfig({
6176
route: {
62-
// These files will be excluded from the routing (support glob pattern)
63-
exclude: ['component/**/*'],
64-
// These files will be included in the routing (support glob pattern)
77+
// These files will be registered as routes (supports glob pattern)
6578
include: ['other-dir/**/*'],
79+
// These files will not be registered as routes (supports glob pattern)
80+
exclude: ['components/**/*', 'fragments/**/*'],
6681
},
6782
});
6883
```
6984

7085
## Best practices
7186

72-
We recommend that you place documentation files in the `docs` directory to make your project more clear. For non-documentation content, such as custom components, util functions, etc., they can be maintained outside the `docs` directory. For example:
87+
We recommend that you place documentation files in the `docs` directory to make your project more clear. For non-documentation content, such as custom components, util functions, etc., they can be maintained outside the `docs` directory.
88+
89+
:::tip
90+
91+
If you want to place `.tsx` or `.mdx` files in the `docs` directory, you need to use `route.exclude` together, otherwise these files will be automatically registered as routes, which may cause some unexpected issues.
92+
93+
:::
94+
95+
Here is a best practice that uses `route.exclude` to make your project structure clearer:
7396

7497
```tree
75-
docs
76-
└── foo.mdx
77-
src
78-
├── components
79-
│ └── CustomComponent.tsx
80-
└── utils
81-
└── utils.ts
98+
├── docs
99+
│ ├── components # For React components used in documentation
100+
│ │ └── Example.tsx
101+
│ ├── fragments # For document fragments
102+
│ │ └── example.mdx
103+
│ └── index.mdx
104+
└── theme
105+
├── components # For theme-related React components
106+
| └── DocFooter.tsx
107+
└── index.tsx
108+
```
109+
110+
```ts title="rspress.config.ts"
111+
import { defineConfig } from '@rspress/core';
112+
113+
export default defineConfig({
114+
route: {
115+
exclude: ['components/**/*', 'fragments/**/*'], // Files in these directories will not be registered as routes
116+
},
117+
});
118+
```
119+
120+
```json title="tsconfig.json"
121+
{
122+
"compilerOptions": {
123+
"lib": ["DOM", "ESNext"],
124+
"jsx": "react-jsx",
125+
"moduleResolution": "bundler",
126+
"paths": {
127+
"i18n": ["./i18n.json"],
128+
"@theme": ["./theme/index.tsx"]
129+
}
130+
},
131+
"include": ["docs", "theme", "rspress.config.ts"],
132+
"mdx": {
133+
"checkMdx": true
134+
}
135+
}
82136
```

‎website/docs/en/guide/use-mdx/_button.mdx‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎website/docs/en/guide/use-mdx/_escape-hatch.tsx‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
1+
import { getCustomMDXComponent } from '@rspress/core/theme';
2+
13
export default () => {
4+
const { p: P, code: Code } = getCustomMDXComponent();
25
return (
3-
<p className="rp-doc">
6+
<P className="rp-doc">
47
This is content in tsx, but the styles are the same as in the
5-
documentation, such as <code>@rspress/core</code>. However, this text with
8+
documentation, such as <Code>@rspress/core</Code>. However, this text with
69
className="rp-not-doc"
7-
<code className="rp-not-doc">@rspress/core</code> will not take effect
8-
</p>
10+
<Code className="rp-not-doc">@rspress/core</Code> will not take effect
11+
</P>
912
);
1013
};

‎website/docs/en/guide/use-mdx/components.mdx‎

Lines changed: 7 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,20 @@
22

33
Rspress supports [MDX](https://mdxjs.com/), a powerful way to develop content.
44

5-
## Markdown
5+
## MDX
66

77
MDX is a superset of Markdown, which means you can write Markdown files as usual. For example:
88

9-
```md
9+
```mdx
1010
# Hello world
1111
```
1212

13-
## Componentization
13+
## Componentization \{#component}
1414

1515
In MDX, every `.mdx` file is compiled into a React component, which means it can be imported like any component and can freely render React components. For example:
1616

1717
import { Tabs, Tab } from '@theme';
18-
import { Border } from './_Border';
18+
import { Border } from '../../../components/Border';
1919

2020
<Tabs>
2121
<Tab label="docs/index.mdx">
@@ -68,51 +68,11 @@ You can use [built-in components](/ui/components/index.mdx) provided by Rspress
6868

6969
## Routing convention
7070

71-
In the [docs directory](/api/config/config-basic#root), MDX fragments or React components need to be excluded from routing through the [route.exclude](/api/config/config-basic#routeexclude) configuration. For convenience, files starting with "\_" are excluded by default via [route.excludeConvention](/api/config/config-basic#routeexcludeconvention).
72-
73-
You can also place components in adjacent directories outside the docs directory, for example:
74-
75-
<Tabs>
76-
<Tab label="docsite/docs/index.mdx">
77-
78-
```mdx
79-
import ButtonFragment from './_button.mdx';
80-
import Button from '../../components/button';
81-
82-
<ButtonFragment />
83-
<Button />
84-
```
85-
86-
</Tab>
87-
<Tab label="docsite/docs/_button.mdx">
88-
89-
```mdx file="./_button.mdx"
71+
import RouteConvention from '@en/fragments/route-convention.mdx';
9072

91-
```
92-
93-
</Tab>
94-
<Tab label="docsite/components/button.tsx">
95-
96-
```tsx
97-
const Button = () => <button>Button</button>;
98-
export default Button;
99-
```
100-
101-
</Tab>
102-
</Tabs>
103-
104-
It will be rendered as:
105-
106-
<Border>
107-
108-
import Button from './_button.mdx';
109-
110-
<Button />
111-
<button>Button</button>
112-
113-
</Border>
73+
<RouteConvention />
11474

115-
## Escape Hatch: writing document content using tsx or html
75+
## Escape Hatch: writing document content in tsx
11676

11777
```tsx file="./_escape-hatch.tsx" title="_escape-hatch.tsx"
11878

‎website/docs/zh/fragments/_button.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#### button
2+
3+
这是一段来自 MDX 的文本

0 commit comments

Comments
 (0)