SuperAPI AI Directory

setup-yunyoujun-docs

General & other

View repository

Updated 10-16 09:31

About this skill

setup-yunyoujun-docs

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.css and virtual:group-icons.css
  • Dependencies installed completely, able to run docs:dev or docs:build

Execution flow

1. Identify the project structure and target directory

  1. Prioritize identifying the documentation subproject directory:
    • docs/(common)
    • Repository root directory (single project)
  2. 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(including docs/ prefix variants)
    • Theme entry:.vitepress/theme/index.ts(including docs/ prefix variants)
  3. 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/docs provides the preset API.
  • unocss、unplugin-vue-components、vite-plugin-vue-devtools、@shikijs/vitepress-twoslash is 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:

  1. Import getViteConfig。
  2. Merge the preset configuration with the user's existing configuration, preserving the user's existing fields and plugins.
  3. 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:

  1. Import getVitepressConfig and defineConfig。
  2. Based on vpConfig spread, and preserve the user's existing title、description、themeConfig。
  3. If the repository address can be inferred, pass in repo to automatically generate editLink and socialLinks。

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:

  1. pnpm lint(if it exists)
  2. pnpm typecheck(if it exists)
  3. pnpm docs:build(root script) or pnpm -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 as unocss are 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's UserConfig:
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:

  1. Change summary (what was done)
  2. List of changed files
  3. Verification commands and results
  4. Optional follow-up optimizations (e.g., TypeDoc, Mermaid, CI)