Skip to content

Commit 526728a

Browse files
nekomeowwwnekomeowww
committed
docs: refined docs
Signed-off-by: Neko Ayaka <neko@ayaka.moe>
1 parent d10d13d commit 526728a

14 files changed

Lines changed: 410 additions & 9 deletions

File tree

‎docs/pages/en/integrations/vitepress-plugin-enhanced-readabilities/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,8 @@ Add the Enhanced Readabilities plugin package name `@nolebase/vitepress-plugin-e
7272

7373
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
7474

75+
<!--@include: @/pages/zh-CN/snippets/configure-tsconfig.md-->
76+
7577
```typescript twoslash
7678
import { defineConfig } from 'vitepress'
7779

@@ -108,6 +110,8 @@ You might have configured the separated [Vite configuration file](https://vitejs
108110

109111
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
110112

113+
<!--@include: @/pages/zh-CN/snippets/configure-tsconfig.md-->
114+
111115
```typescript twoslash
112116
import { defineConfig } from 'vite'
113117

@@ -146,6 +150,8 @@ In VitePress's [**theme configuration file**](https://vitepress.dev/reference/de
146150

147151
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
148152

153+
<!--@include: @/pages/zh-CN/snippets/configure-tsconfig.md-->
154+
149155
::: code-group
150156

151157
```typescript twoslash [docs/.vitepress/theme/index.ts]
@@ -811,6 +817,10 @@ The Enhanced Readabilities plugin provides accessibility support by default. You
811817

812818
## Problems? Let's Troubleshoot
813819

820+
### Encountered `Cannot find module ... or its corresponding type declarations` error?
821+
822+
<!--@include: @/pages/en/snippets/troubleshooting-cannot-find-module.md-->
823+
814824
### The requested module `vitepress` does not provide an export named `useData` or The requested module `vitepress` does not provide an export named `useRoute`
815825

816826
If you have already configured your VitePress that working properly, you might encounter the above error when you try to install and integrate the Enhanced Readabilities plugin for the first time.
@@ -872,3 +882,4 @@ The line `vitepress v1.0.0-rc.12` indicates your VitePress version as `v1.0.0-rc
872882
#### You might missed the configurations in section [Add plugin-specific options into configurations of Vite](#add-plugin-specific-options-into-configurations-of-vite)
873883
874884
If you incautiously missed the configurations in section [Add plugin-specific options into configurations of Vite](#add-plugin-specific-options-into-configurations-of-vite), the reference to `vitepress` inside of the Enhanced Readabilities plugin might be broken or miss-processed when building your VitePress site. So you have to configure it accurately by following the section [Add plugin-specific options into configurations of Vite](#add-plugin-specific-options-into-configurations-of-vite) accordingly.
885+

‎docs/pages/en/integrations/vitepress-plugin-git-changelog/configure-vite-plugins.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ Besides the UI widget components, Git-based page histories offer another two Vit
44

55
### Configure Vite plugins
66

7+
<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
8+
79
#### `GitChangelog` plugin
810

911
Remember this part back at the time where we first introduced the `GitChangelog` plugin?

‎docs/pages/en/integrations/vitepress-plugin-git-changelog/getting-started.md‎

Lines changed: 85 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,53 @@ Please pay attentions to the following configurations and steps to get started w
3535
It consists two major steps to integrate the Inline Links Previewing plugin into your VitePress project:
3636

3737
- [Configure Vite plugin](#configure-vite-plugin) (data fetching, logs aggregation)
38-
- [Integrate with VitePress](#integrate-with-vitepress) (UI and components)
38+
- [Integrate with VitePress](#integrate-with-vitepress-theme) (UI and components)
3939

4040
### Configure Vite plugin
4141

42-
#### Ensure `vite.config.ts` is created
42+
There are two ways to integrate the Git-based page histories Vite plugin into your VitePress project:
43+
44+
1. [**Recommended**: Use the `vite` option in VitePress's primary configuration file (usually located at `docs/.vitepress/config.ts`, file paths and extensions may be vary)](#configure-vite-plugin-in-vitepresss-config-file)
45+
2. [Create a separated Vite configuration file (e.g. `vite.config.ts`) in the root directory of your VitePress project](#configure-vite-plugin-in-a-separated-vite-configuration-file)
46+
47+
#### Configure Vite plugin in VitePress's config file
48+
49+
In VitePress's [**primary configuration file**](https://vitepress.dev/reference/site-config#config-resolution) (not this is not a **theme configuration file**, it's usually located at `docs/.vitepress/config.ts`, file paths and extensions may be vary), we need to import both `GitChangelog` (data fetcher), and `GitChangelogMarkdownSection` (widget embedder) the plugins and configure it properly:
50+
51+
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
52+
53+
<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
54+
55+
```typescript twoslash
56+
import { defineConfig } from 'vitepress'
57+
import { // [!code ++]
58+
GitChangelog, // [!code ++]
59+
GitChangelogMarkdownSection, // [!code ++]
60+
} from '@nolebase/vitepress-plugin-git-changelog/vite' // [!code ++]
61+
62+
// https://vitepress.dev/reference/site-config
63+
export default defineConfig({
64+
vite: { // [!code ++]
65+
plugins: [ // [!code ++]
66+
GitChangelog({ // [!code ++]
67+
// Fill in your repository URL here
68+
repoURL: () => 'https://github.com/nolebase/integrations', // [!code ++]
69+
}), // [!code ++]
70+
GitChangelogMarkdownSection(), // [!code ++]
71+
],
72+
}, // [!code ++]
73+
lang: 'en',
74+
title: 'Site Name',
75+
themeConfig: {
76+
// rest of the options...
77+
}
78+
// rest of the options...
79+
})
80+
```
81+
82+
#### Configure Vite plugin in a separated Vite configuration file
83+
84+
##### Ensure `vite.config.ts` is created
4385

4486
If you understand what `vite.config.ts` is already and have created it, you can skip this preparation step and jump to the next step [Configure plugin in `vite.config.ts`](#configure-plugin-in-viteconfigts).
4587

@@ -55,16 +97,49 @@ However, due to the order of plugins it registered, it's not enough to transform
5597

5698
Therefore, please create a separated `vite.config.ts` file in the root directory of your VitePress project:
5799

100+
::: tip Where is the root directory of VitePress project?
101+
102+
VitePress project's root directory is where the parent directory of `.vitepress` directory is.
103+
104+
For example:
105+
106+
```shell
107+
.
108+
├── docs
109+
│ ├── .vitepress
110+
│ │ ├── config.ts
111+
│ │ └── theme
112+
│ │ └── index.ts
113+
│ └── README.md
114+
```
115+
116+
In this case, the root directory is `docs`.
117+
118+
```shell
119+
.
120+
├── .vitepress
121+
│ ├── config.ts
122+
│ └── theme
123+
│ └── index.ts
124+
└── README.md
125+
```
126+
127+
In this case, the root directory is `./`.
128+
129+
:::
130+
58131
```shell
59132
touch vite.config.ts
60133
```
61134

62-
#### Configure plugin in `vite.config.ts`
135+
##### Configure plugin in `vite.config.ts`
63136

64137
In the standalone [Vite configuration file](https://vitejs.dev/config/) (e.g. `vite.config.ts`) file we have under our root directory, we need to import both `GitChangelog` (data fetcher), and `GitChangelogMarkdownSection` (widget embedder) the plugins and configure it properly:
65138

66139
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
67140

141+
<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
142+
68143
```typescript twoslash
69144
import { join } from 'node:path'
70145
import { defineConfig } from 'vite'
@@ -87,7 +162,7 @@ export default defineConfig(() => {
87162
})
88163
```
89164

90-
### Integrate with VitePress
165+
### Integrate with VitePress theme
91166

92167
Now, let's integrate the Git-based page histories UI widgets into your VitePress project.
93168

@@ -121,3 +196,9 @@ export default Theme
121196
```
122197

123198
:::
199+
200+
## Troubleshooting
201+
202+
### Encountered `Cannot find module ... or its corresponding type declarations` error?
203+
204+
<!--@include: @/pages/en/snippets/troubleshooting-cannot-find-module.md-->

‎docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,8 @@ Add the Blinking highlight targeted heading plugin package name `@nolebase/vitep
8888

8989
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
9090

91+
<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
92+
9193
```typescript twoslash
9294
import { defineConfig } from 'vitepress'
9395

@@ -114,6 +116,8 @@ You might have configured the separated [Vite configuration file](https://vitejs
114116

115117
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
116118

119+
<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
120+
117121
```typescript twoslash
118122
import { defineConfig } from 'vite'
119123

@@ -145,6 +149,8 @@ In VitePress's [**theme configuration file**](https://vitepress.dev/reference/de
145149

146150
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
147151

152+
<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
153+
148154
::: code-group
149155

150156
```typescript twoslash [docs/.vitepress/theme/index.ts]
@@ -189,3 +195,9 @@ Now build or open the VitePress development server again, you will be able to ob
189195
- The URL containing `#` is loaded for the first time
190196

191197
That's all, happy writing!
198+
199+
## Troubleshooting
200+
201+
### Encountered `Cannot find module ... or its corresponding type declarations` error?
202+
203+
<!--@include: @/pages/en/snippets/troubleshooting-cannot-find-module.md-->

‎docs/pages/en/integrations/vitepress-plugin-inline-link-preview/getting-started.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ First of all, in VitePress's [**primary configuration file**](https://vitepress.
3737

3838
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
3939

40+
<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
41+
4042
::: code-group
4143

4244
```typescript twoslash
@@ -85,6 +87,8 @@ In VitePress's [**theme configuration file**](https://vitepress.dev/reference/de
8587

8688
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
8789

90+
<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
91+
8892
::: code-group
8993

9094
```typescript twoslash [.vitepress/theme/index.ts]
@@ -111,3 +115,9 @@ export default Theme
111115
```
112116

113117
:::
118+
119+
## Troubleshooting
120+
121+
### Encountered `Cannot find module ... or its corresponding type declarations` error?
122+
123+
<!--@include: @/pages/en/snippets/troubleshooting-cannot-find-module.md-->

‎docs/pages/en/snippets/configure-tsconfig.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
::: details A TypeScript User?
2+
3+
You need to configure at least the following options:
4+
5+
```jsonc
6+
{
7+
"compilerOptions": {
8+
"module": "ESNext", // [!code hl]
9+
"moduleResolution": "Bundler", // [!code hl]
10+
},
11+
"include": [
12+
"**/.vitepress/**/*.ts",
13+
"**/.vitepress/**/*.mts",
14+
"**/.vitepress/**/*.vue"
15+
],
16+
"exclude": [
17+
"node_modules"
18+
]
19+
}
20+
```
21+
22+
And the options
23+
24+
- `module` option specifies the JavaScript/TypeScript module format, and Nolebase Integrations uses the `ESNext`-compatible module format by default.
25+
- `moduleResolution` option specifies the module resolution policy, since all Nolebase Integrations plugins follow the latest ECMAScript specifications and export declarations, if you encounter a `Cannot find module ... or its corresponding type declarations` error you may need to set `moduleResolution` to `Bundler`.
26+
27+
If you want more configurations, you can refer to the following example:
28+
29+
```jsonc
30+
{
31+
"compilerOptions": {
32+
"jsx": "preserve",
33+
"lib": [
34+
"DOM",
35+
"ESNext"
36+
],
37+
"module": "ESNext",
38+
"moduleResolution": "Bundler",
39+
"resolveJsonModule": true,
40+
"strict": true,
41+
"strictNullChecks": true,
42+
"noFallthroughCasesInSwitch": true,
43+
"noImplicitAny": true,
44+
"noUnusedLocals": true,
45+
"noUnusedParameters": true,
46+
"noEmit": true,
47+
"removeComments": false,
48+
"esModuleInterop": true,
49+
"forceConsistentCasingInFileNames": true,
50+
"isolatedModules": true,
51+
"verbatimModuleSyntax": true,
52+
"skipLibCheck": true
53+
},
54+
"include": [
55+
"**/.vitepress/**/*.ts",
56+
"**/.vitepress/**/*.mts",
57+
"**/.vitepress/**/*.vue"
58+
],
59+
"exclude": [
60+
"node_modules"
61+
]
62+
}
63+
```
64+
65+
:::

‎docs/pages/en/snippets/troubleshooting-cannot-find-module.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
If you are encountering this error with Nolebase Integrations packages inside of `.ts` or `.vue` files, you may need to configure the `moduleResolution` option in your `tsconfig.json` file.
2+
3+
```jsonc
4+
{
5+
"compilerOptions": {
6+
"module": "ESNext", // [!code focus]
7+
"moduleResolution": "Bundler", // [!code focus]
8+
},
9+
"include": [
10+
"**/.vitepress/**/*.ts",
11+
"**/.vitepress/**/*.mts",
12+
"**/.vitepress/**/*.vue"
13+
],
14+
"exclude": [
15+
"node_modules"
16+
]
17+
}
18+
```
19+
20+
If the error persists, please submit a [GitHub issue](https://github.com/nolebase/integrations/issues) for further assistance and troubleshooting.

‎docs/pages/zh-CN/integrations/vitepress-plugin-enhanced-readabilities/index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,8 @@ yarn add @nolebase/vitepress-plugin-enhanced-readabilities -D
7272

7373
<!--@include: @/pages/zh-CN/snippets/details-colored-diff.md-->
7474

75+
<!--@include: @/pages/zh-CN/snippets/configure-tsconfig.md-->
76+
7577
```typescript twoslash
7678
import { defineConfig } from 'vitepress'
7779

@@ -108,6 +110,8 @@ export default defineConfig({
108110

109111
<!--@include: @/pages/zh-CN/snippets/details-colored-diff.md-->
110112

113+
<!--@include: @/pages/zh-CN/snippets/configure-tsconfig.md-->
114+
111115
```typescript twoslash
112116
import { defineConfig } from 'vite'
113117

@@ -147,6 +151,8 @@ export default defineConfig(() => {
147151

148152
<!--@include: @/pages/zh-CN/snippets/details-colored-diff.md-->
149153

154+
<!--@include: @/pages/zh-CN/snippets/configure-tsconfig.md-->
155+
150156
::: code-group
151157

152158
```typescript twoslash [docs/.vitepress/theme/index.ts]
@@ -812,6 +818,10 @@ export interface Locale {
812818

813819
## 遇到了问题？
814820

821+
### 遭遇了 `Cannot find module ... or its corresponding type declarations` 错误？
822+
823+
<!--@include: @/pages/zh-CN/snippets/troubleshooting-cannot-find-module.md-->
824+
815825
### 请求的模块 `vitepress` 没有提供名为 `useData` 的导出 或者 请求的模块 `vitepress` 没有提供名为 `useRoute` 的导出
816826

817827
如果你已经正确配置好了 VitePress，你可能会在首次配置阅读增强插件的时候遇到如下的问题：

‎docs/pages/zh-CN/integrations/vitepress-plugin-git-changelog/configure-vite-plugins.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
### 配置 Vite 插件
66

7+
<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
8+
79
#### `GitChangelog` 插件
810

911
还记得我们第一次介绍 `GitChangelog` 插件时的这部分内容吗？

0 commit comments

Comments
 (0)