Wire the @yunyoujun/docs preset into a VitePress documentation project, and complete dependency installation and configuration merging without breaking the existing configuration.
Target outcome
After completion, the project should have:
- Working
getViteConfig()integration (Vite plugin chain) - Working
getVitepressConfig()integration (VitePress default site configuration) - Theme entry includes
uno.cssandvirtual:group-icons.css - Dependencies installed completely, able to run
docs:devordocs:build
Execution flow
1. Identify the project structure and target directory
- Prioritize identifying the documentation subproject directory:
docs/(common)- Repository root directory (single project)
- Check the following candidate files:
- Vite configuration:
vite.config.ts、vite.config.mts、docs/vite.config.ts、docs/vite.config.mts - VitePress configuration:
.vitepress/config.ts、.vitepress/config.mts、.vitepress/config/index.ts、.vitepress/config/index.mts(includingdocs/prefix variants) - Theme entry:
.vitepress/theme/index.ts(includingdocs/prefix variants)
- Vite configuration:
- If the configuration file does not exist, create it according to the reference template (see
references/integration-templates.md)。
2. Install dependencies (by package manager)
Prioritize selecting the package manager based on the lock file (pnpm-lock.yaml > package-lock.json > yarn.lock),default to using pnpm。
Run the installation in the documentation project directory (for example, docs/ for the subproject, use pnpm -C docs):
# 文档项目位于仓库根目录
pnpm add -D @yunyoujun/docs unocss unplugin-vue-components vite-plugin-vue-devtools @shikijs/vitepress-twoslash
# 文档项目位于 docs/ 子目录
pnpm -C docs add -D @yunyoujun/docs unocss unplugin-vue-components vite-plugin-vue-devtools @shikijs/vitepress-twoslash
Note:
@yunyoujun/docsprovides the preset API.unocss、unplugin-vue-components、vite-plugin-vue-devtools、@shikijs/vitepress-twoslashis used by the preset chain; it is recommended to install it as well.- If dependencies already exist, do not repeatedly modify the version strategy.
3. Wire in the Vite configuration
In the target Vite configuration:
- Import
getViteConfig。 - Merge the preset configuration with the user's existing configuration, preserving the user's existing fields and plugins.
- Avoid overwriting the user's custom plugin logic.
Prefer using the following structure (can be adjusted to match the existing style):
import { getViteConfig } from '@yunyoujun/docs'
import { defineConfig } from 'vite'
const viteConfig = getViteConfig({})
export default defineConfig({
...viteConfig,
})
4. Wire in the VitePress configuration
In the VitePress configuration:
- Import
getVitepressConfiganddefineConfig。 - Based on
vpConfigspread, and preserve the user's existingtitle、description、themeConfig。 - If the repository address can be inferred, pass in
repoto automatically generateeditLinkandsocialLinks。
Recommended structure:
import { getVitepressConfig } from '@yunyoujun/docs'
import { defineConfig } from 'vitepress'
const vpConfig = getVitepressConfig({
repo: 'https://github.com/<owner>/<repo>',
})
export default defineConfig({
...vpConfig,
themeConfig: {
...vpConfig.themeConfig,
},
})
5. Wire in the theme style entry
In .vitepress/theme/index.ts ensure it includes:
import 'uno.css'
import 'virtual:group-icons.css'
If the file does not exist, create it according to the template and inherit the default theme (see the reference template).
6. Verification and regression
Run minimal verification according to the project scripts:
pnpm lint(if it exists)pnpm typecheck(if it exists)pnpm docs:build(root script) orpnpm -C docs run build(subproject script)
If the command does not exist, use the closest available script, and clearly state the substitute command in the result.
Modification principles
- Prefer "incremental merging"; do not crudely rewrite the existing configuration.
- Preserve the user's comments, existing plugins, and business configuration.
- Keep paths and import style consistent with the project (
ts/mts, single quotes/double quotes). - When multiple candidates exist for a configuration file, prioritize modifying the file actually used by the script.
- If the repository is a monorepo, clearly state which package the change occurs in.
Common Issues
- Only
@yunyoujun/docsis installed, but companion dependencies such asunocssare not, causing module-not-found errors at runtime. - When merging
themeConfig,...vpConfig.themeConfigis missed, causing the default search/outline configuration to be lost. docs/subproject and root directory configurations are mixed, causing the modified file not to be actually loaded.- The theme entry does not import
uno.css, so the style classes do not take effect. - In a pnpm workspace, if multiple VitePress dependency instances exist, a TS2345 type incompatibility may occur (inconsistent private fields). You can first assert the shared configuration as
unknown, then assert it as the current project'sUserConfig:
import type { UserConfig } from 'vitepress'
const vpConfig = getVitepressConfig({
repo: 'https://github.com/<owner>/<repo>',
}) as unknown as UserConfig
Output Format
The final reply should include:
- Change summary (what was done)
- List of changed files
- Verification commands and results
- Optional follow-up optimizations (e.g., TypeDoc, Mermaid, CI)