docs: add troubleshooting docs, improve bundler and theme usage guide

vuepress · Jan 26, 2024 · 033ebc5 · 033ebc5
1 parent 9653134
commit 033ebc5
Show file tree

Hide file tree

Showing 16 changed files with 100 additions and 28 deletions.
diff --git a/docs/.vuepress/config.ts b/docs/.vuepress/config.ts
@@ -8,7 +8,6 @@ import { registerComponentsPlugin } from '@vuepress/plugin-register-components'
 import { shikiPlugin } from '@vuepress/plugin-shiki'
 import { defaultTheme } from '@vuepress/theme-default'
 import { defineUserConfig } from 'vuepress'
-import type { UserConfig } from 'vuepress'
 import { getDirname, path } from 'vuepress/utils'
 import {
   head,
@@ -200,4 +199,4 @@ export default defineUserConfig({
         })
       : [],
   ],
-}) as UserConfig
+})
diff --git a/docs/.vuepress/configs/navbar/en.ts b/docs/.vuepress/configs/navbar/en.ts
@@ -17,6 +17,7 @@ export const navbarEn: NavbarConfig = [
       '/guide/plugin.md',
       '/guide/bundler.md',
       '/guide/migration.md',
+      '/guide/troubleshooting.md',
     ],
   },
   {

diff --git a/docs/.vuepress/configs/navbar/zh.ts b/docs/.vuepress/configs/navbar/zh.ts
@@ -17,6 +17,7 @@ export const navbarZh: NavbarConfig = [
       '/zh/guide/plugin.md',
       '/zh/guide/bundler.md',
       '/zh/guide/migration.md',
+      '/zh/guide/troubleshooting.md',
     ],
   },
   {

diff --git a/docs/.vuepress/configs/sidebar/en.ts b/docs/.vuepress/configs/sidebar/en.ts
@@ -17,6 +17,7 @@ export const sidebarEn: SidebarConfig = {
         '/guide/plugin.md',
         '/guide/bundler.md',
         '/guide/migration.md',
+        '/guide/troubleshooting.md',
       ],
     },
   ],

diff --git a/docs/.vuepress/configs/sidebar/zh.ts b/docs/.vuepress/configs/sidebar/zh.ts
@@ -17,6 +17,7 @@ export const sidebarZh: SidebarConfig = {
         '/zh/guide/plugin.md',
         '/zh/guide/bundler.md',
         '/zh/guide/migration.md',
+        '/zh/guide/troubleshooting.md',
       ],
     },
   ],

diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
@@ -17,7 +17,7 @@ To be more specific, we have a convention for config file paths (in order of pre
 
 You can also specify the config file via `--config` option of [CLI](../reference/cli.md):
 
-```sh
+```bash
 vuepress dev docs --config my-config.ts
 ```
 

diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
@@ -0,0 +1,14 @@
+# Troubleshooting
+
+## The bundler / theme option is missing?
+
+You need to set the bundler and theme to use explicitly in your config file.
+
+See the bundler reference for how to configure bundlers properly:
+
+- [Bundlers > Vite](../reference/bundler/vite.md)
+- [Bundlers > Webpack](../reference/bundler/webpack.md)
+
+See the default theme reference for how to configure the default theme properly:
+
+- [Default Theme > Config](../reference/default-theme/config.md)
diff --git a/docs/reference/bundler/vite.md b/docs/reference/bundler/vite.md
@@ -2,17 +2,19 @@
 
 <NpmBadge package="@vuepress/bundler-vite" />
 
-Vite bundler is provided by [@vuepress/bundler-vite](https://www.npmjs.com/package/@vuepress/bundler-vite) package. It is a dependency of the [vuepress](https://www.npmjs.com/package/vuepress) package, and you can also install it separately.
+Vite bundler is provided by [@vuepress/bundler-vite](https://www.npmjs.com/package/@vuepress/bundler-vite) package.
+
+## Usage
+
+Install the bundler package:
 
 ```bash
 npm i -D @vuepress/bundler-vite@next
 ```
 
-## Options
-
-Reference of vite bundler options:
+Specify the bundler option in your config file:
 
-```ts
+```ts title=".vuepress/config.ts"
 import { viteBundler } from '@vuepress/bundler-vite'
 import { defineUserConfig } from 'vuepress'
 
@@ -24,6 +26,8 @@ export default defineUserConfig({
 })
 ```
 
+## Options
+
 ### viteOptions
 
 - Details:

diff --git a/docs/reference/bundler/webpack.md b/docs/reference/bundler/webpack.md
@@ -2,17 +2,19 @@
 
 <NpmBadge package="@vuepress/bundler-webpack" />
 
-Webpack bundler is provided by [@vuepress/bundler-webpack](https://www.npmjs.com/package/@vuepress/bundler-webpack) package. It is a dependency of the [vuepress-webpack](https://www.npmjs.com/package/vuepress-webpack) package, and you can also install it separately.
+Webpack bundler is provided by [@vuepress/bundler-webpack](https://www.npmjs.com/package/@vuepress/bundler-webpack) package.
+
+## Usage
+
+Install the bundler package:
 
 ```bash
 npm i -D @vuepress/bundler-webpack@next
 ```
 
-## Options
-
-Reference of webpack bundler options:
+Specify the bundler option in your config file:
 
-```ts
+```ts title=".vuepress/config.ts"
 import { webpackBundler } from '@vuepress/bundler-webpack'
 import { defineUserConfig } from 'vuepress'
 
@@ -24,6 +26,8 @@ export default defineUserConfig({
 })
 ```
 
+## Options
+
 ### configureWebpack
 
 - Type: `(config: WebpackConfiguration, isServer: boolean, isBuild: boolean) => WebpackConfiguration | void`

diff --git a/docs/reference/default-theme/config.md b/docs/reference/default-theme/config.md
@@ -2,12 +2,24 @@
 
 <NpmBadge package="@vuepress/theme-default" />
 
-```ts
+Default theme is provided by [@vuepress/theme-default](https://www.npmjs.com/package/@vuepress/theme-default) package.
+
+## Usage
+
+Install the default theme package:
+
+```bash
+npm i -D @vuepress/theme-default@next
+```
+
+Specify the theme option in your config file:
+
+```ts title=".vuepress/config.ts"
 import { defaultTheme } from '@vuepress/theme-default'
 
 export default {
   theme: defaultTheme({
-    // set config here
+    // set theme config here
   }),
 }
 ```

diff --git a/docs/zh/guide/configuration.md b/docs/zh/guide/configuration.md
@@ -17,7 +17,7 @@ VuePress 站点的基本配置文件是 `.vuepress/config.js` ，但也同样支
 
 你也可以通过 [命令行接口](../reference/cli.md) 的 `--config` 选项来指定配置文件：
 
-```sh
+```bash
 vuepress dev docs --config my-config.ts
 ```
 

diff --git a/docs/zh/guide/troubleshooting.md b/docs/zh/guide/troubleshooting.md
@@ -0,0 +1,14 @@
+# 常见问题
+
+## 缺少 bundler / theme 配置？
+
+你需要在配置文件中明确指定要使用的打包工具 (bundler) 和主题 (theme) 。
+
+查看打包工具的配置参考，了解如何正确配置打包工具：
+
+- [打包工具 > Vite](../reference/bundler/vite.md)
+- [打包工具 > Webpack](../reference/bundler/webpack.md)
+
+See the default theme reference for how to configure the default theme properly:
+
+- [默认主题 > 配置](../reference/default-theme/config.md)
diff --git a/docs/zh/reference/bundler/vite.md b/docs/zh/reference/bundler/vite.md
@@ -2,17 +2,19 @@
 
 <NpmBadge package="@vuepress/bundler-vite" />
 
-Vite 打包工具是由 [@vuepress/bundler-vite](https://www.npmjs.com/package/@vuepress/bundler-vite) 包提供的。它是 [vuepress](https://www.npmjs.com/package/vuepress) 包的依赖之一，当然你也可以单独安装它：
+Vite 打包工具是由 [@vuepress/bundler-vite](https://www.npmjs.com/package/@vuepress/bundler-vite) 包提供的。
+
+## 使用方法
+
+安装打包工具：
 
 ```bash
 npm i -D @vuepress/bundler-vite@next
 ```
 
-## 配置项
-
-Vite 打包工具的配置项：
+在配置文件中指定打包工具：
 
-```ts
+```ts title=".vuepress/config.ts"
 import { viteBundler } from '@vuepress/bundler-vite'
 import { defineUserConfig } from 'vuepress'
 
@@ -24,6 +26,8 @@ export default defineUserConfig({
 })
 ```
 
+## 配置项
+
 ### viteOptions
 
 - 详情：

diff --git a/docs/zh/reference/bundler/webpack.md b/docs/zh/reference/bundler/webpack.md
@@ -2,17 +2,19 @@
 
 <NpmBadge package="@vuepress/bundler-webpack" />
 
-Webpack 打包工具是由 [@vuepress/bundler-webpack](https://www.npmjs.com/package/@vuepress/bundler-webpack) 包提供的。它是 [vuepress-webpack](https://www.npmjs.com/package/vuepress-webpack) 包的依赖之一，当然你也可以单独安装它：
+Webpack 打包工具是由 [@vuepress/bundler-webpack](https://www.npmjs.com/package/@vuepress/bundler-webpack) 包提供的。
+
+## 使用方法
+
+安装打包工具：
 
 ```bash
 npm i -D @vuepress/bundler-webpack@next
 ```
 
-## 配置项
-
-Webpack 打包工具的配置项：
+在配置文件中指定打包工具：
 
-```ts
+```ts title=".vuepress/config.ts"
 import { webpackBundler } from '@vuepress/bundler-webpack'
 import { defineUserConfig } from 'vuepress'
 
@@ -24,6 +26,8 @@ export default defineUserConfig({
 })
 ```
 
+## 配置项
+
 ### configureWebpack
 
 - 类型： `(config: WebpackConfiguration, isServer: boolean, isBuild: boolean) => WebpackConfiguration | void`

diff --git a/docs/zh/reference/default-theme/config.md b/docs/zh/reference/default-theme/config.md
@@ -2,12 +2,24 @@
 
 <NpmBadge package="@vuepress/theme-default" />
 
-```ts
+默认主题是由 [@vuepress/theme-default](https://www.npmjs.com/package/@vuepress/theme-default) 包提供的。
+
+## 使用方法
+
+安装默认主题：
+
+```bash
+npm i -D @vuepress/theme-default@next
+```
+
+在配置文件中指定主题：
+
+```ts title=".vuepress/config.ts"
 import { defaultTheme } from '@vuepress/theme-default'
 
 export default {
   theme: defaultTheme({
-    // 在这里进行配置
+    // 在这里添加主题配置
   }),
 }
 ```

diff --git a/tsconfig.json b/tsconfig.json
@@ -5,6 +5,7 @@
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "target": "ES2022",
+    "declaration": false,
   },
   "include": ["**/.vuepress/**/*"],
   "exclude": ["node_modules", ".cache", ".temp", "dist"],
-Original file line number
+Diff line change
@@ Expand Up @@
     You can also specify the config file via `--config` option of [CLI](../reference/cli.md):
-    ```sh
+    ```bash
     vuepress dev docs --config my-config.ts
     ```
@@ Expand Down @@