Getting Started

Version Compatibility

This version (v2.x) is built on VitePress 2.0 and is not backward compatible with VitePress 1.x.

Installation

Install the theme package in your VitePress project:

npm

npm install @fuxishi/vitepress-theme

pnpm

pnpm add @fuxishi/vitepress-theme

yarn

yarn add @fuxishi/vitepress-theme

Also install the following peerDependencies:

npm install vitepress

Configure Theme

1. Register Theme

Create or modify .vitepress/theme/index.ts:

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

export default FxTheme

2. Extend Configuration

Create or modify .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: "en",
  title: "My Docs",
  description: "A docs site built with @fuxishi/vitepress-theme",
  themeConfig: {
    // Add your navigation, sidebar, and other config here
    nav: [{ text: "Guide", link: "/guide/" }],
    sidebar: {
      "/guide/": [{ text: "Introduction", link: "/guide/" }],
    },
  },
})

3. Start Dev Server

npx vitepress dev

Open your browser to see the themed docs site.

Theme Presets

fxConfig provides the following default configuration:

Option	Preset Value	Description
markdown.lineNumbers	true	Show line numbers in code blocks
vite.ssr.noExternal	Auto-config	Ensures Element Plus, canvas-confetti, node-vibrant, @fuxishi/vitepress-theme work correctly in SSR

You can override any preset value in defineConfig<ThemeConfig>.

Next Steps

• Config Reference — Learn about all configuration options
• Customization — Customize theme appearance with CSS variables
• Music Ball — Configure the floating music player