快速开始

版本兼容性

本版本（v2.x）基于 VitePress 2.0 开发，不向下兼容 VitePress 1.x。

安装

在你的 VitePress 项目中安装主题包：

npm

npm install @fuxishi/vitepress-theme

pnpm

pnpm add @fuxishi/vitepress-theme

yarn

yarn add @fuxishi/vitepress-theme

同时需要安装以下 peerDependencies：

npm install vitepress

配置主题

1. 注册主题

创建或修改 .vitepress/theme/index.ts：

import FxTheme from "@fuxishi/vitepress-theme"
import "@fuxishi/vitepress-theme/style.css"

export default FxTheme

2. 继承配置

创建或修改 .vitepress/config.mts：

import { defineConfig } from "vitepress"
import type { DefaultTheme } from "vitepress"
import fxConfig from "@fuxishi/vitepress-theme/config"
import type { FxThemeCustomConfig } from "@fuxishi/vitepress-theme"

type ThemeConfig = DefaultTheme.Config & FxThemeCustomConfig

export default defineConfig<ThemeConfig>({
  extends: fxConfig,
  lang: "zh-CN",
  title: "我的文档站",
  description: "使用 @fuxishi/vitepress-theme 构建的文档站",
  themeConfig: {
    // 在这里添加你的导航、侧边栏等配置
    nav: [{ text: "指南", link: "/guide/" }],
    sidebar: {
      "/guide/": [{ text: "介绍", link: "/guide/" }],
    },
  },
})

3. 启动开发服务器

npx vitepress dev

打开浏览器即可看到应用了主题的文档站。

主题预设

fxConfig 预设了以下基础配置：

配置项	预设值	说明
markdown.lineNumbers	true	代码块显示行号
vite.ssr.noExternal	自动配置	确保 Element Plus、canvas-confetti、node-vibrant、@fuxishi/vitepress-theme 在 SSR 中正确工作

你可以在 defineConfig<ThemeConfig> 中覆盖任何预设值。

下一步

• 配置参考 — 了解所有可配置项
• 样式定制 — 通过 CSS 变量自定义主题外观
• 音乐球 — 配置悬浮音乐播放器