Config Reference

The theme provides custom configuration via FxThemeCustomConfig. Consumers compose the full theme config using the intersection type DefaultTheme.Config & FxThemeCustomConfig.

FxThemeCustomConfig

FxThemeCustomConfig is a standalone pure interface with the following fields:

interface FxThemeCustomConfig {
  /**
   * Floating music ball configuration
   */
  musicBall?: {
    /** Enable music ball, default true */
    enable?: boolean
    /** Visibility, default true */
    visible?: boolean
    /** Autoplay, default false */
    autoplay?: boolean
    /** Loop playback (single mode only), default true */
    loop?: boolean
    /** Single music file URL */
    src?: string
    /** Music list */
    list?: MusicItem[]
  }

  /**
   * Click confetti effect configuration
   */
  confetti?: boolean | {
    /** Preset shape: 'star' gold stars | 'colored-paper' colorful paper pieces */
    shape?: 'star' | 'colored-paper'
    /** Custom Emoji shapes, supports single string or array */
    shapes?: string | string[]
    /** Whether to add secondary particles, default true */
    secondary?: boolean
  }

  /**
   * Auto-extract hero image colors for background glow and code block beam colors, default false
   */
  heroImageColor?: boolean

  /**
   * Enable smooth scrolling and outline marker transition, default false
   */
  smoothScroll?: boolean

  /**
   * Code block folding, default true (enabled)
   * Configurable fold line threshold
   */
  codeBlockFold?: boolean | {
    /** Line count threshold for folding, default 10 */
    lines?: number
  }
}

interface MusicItem {
  /** Song name */
  name: string
  /** Audio file URL */
  src: string
}

Usage in config file:

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

type ThemeConfig = DefaultTheme.Config & FxThemeCustomConfig

export default defineConfig<ThemeConfig>({ ... })

Music Ball Configuration

Single Mode

Set the src field to enable single mode:

themeConfig: {
  musicBall: {
    enable: true,
    autoplay: false,
    loop: true,
    src: '/music/my-song.mp3',
  },
}

Audio files should be placed in the public/ directory, e.g. public/music/my-song.mp3.

List Mode

Set the list field to enable a multi-song playlist:

themeConfig: {
  musicBall: {
    enable: true,
    autoplay: true,
    loop: true,
    list: [
      { name: 'Mariage d\'Amour', src: '/music/wedding-dream.mp3' },
      { name: 'Boundless Oceans', src: '/music/broad-sea-sky.mp3' },
      { name: 'A Few Coins', src: '/music/silver-coins.mp3' },
    ],
  },
}

TIP

When list contains only one song, it automatically switches to single mode (equivalent to setting src).

Confetti Effect Configuration

themeConfig: {
  // Enable confetti (default, gold stars)
  confetti: true,

  // Disable confetti
  confetti: false,

  // Colored paper
  confetti: { shape: "colored-paper" },

  // Custom Emoji
  confetti: { shapes: ["🌸", "🎀"] },
}

The confetti effect triggers when the user clicks anywhere on the page, releasing confetti particles at the click position. Three modes are supported:

Config	Description
true	Gold stars (default)
{ shape: "star" }	Gold stars
{ shape: "colored-paper" }	Colored paper pieces
{ shapes: "🌸" }	Custom single Emoji
{ shapes: ["🌸", "🎀"] }	Custom multiple Emoji
{ ..., secondary: false }	Disable secondary particles

Hero Image Color Extraction

When enabled, the theme automatically extracts dominant colors from the homepage hero.image and applies them to:

• Hero background glow — uses all extracted hues to build a conic-gradient
• Hero title gradient — uses two colors with the largest hue difference for a linear-gradient
• Code block beam borders — dynamically overridden via --fx-beam-c1 / --fx-beam-c2 CSS variables
• Music ball — progress ring gradient, orbit ring, play glow, slider colors sync accordingly

themeConfig: {
  // Enable hero image color extraction
  heroImageColor: true,
}

TIP

No need to manually configure image paths — the theme reads the homepage frontmatter hero.image automatically. Light and dark mode colors are extracted from their respective images. Colors are cached in localStorage and auto-invalidate when images change.

Smooth Scroll

When enabled, clicking the outline navigation smoothly scrolls to the corresponding heading, and the outline marker transitions smoothly:

themeConfig: {
  // Enable smooth scroll
  smoothScroll: true,
}

Effects when enabled:

• Clicking outline navigation smoothly scrolls the page to the corresponding heading
• Outline marker position transitions with a silky animation

Code Block Fold

Code blocks exceeding a specified line count are automatically folded with a fade-out mask and expand button:

themeConfig: {
  // Enable (default, 10 lines threshold)
  codeBlockFold: true,

  // Disable
  codeBlockFold: false,

  // Custom fold line threshold
  codeBlockFold: { lines: 20 },
}

Config	Description
true	Enable, default 10 lines threshold
false	Disable
{ lines: 20 }	Enable with custom 20 lines threshold

TIP

The fold uses a frosted glass blur overlay, which does not interfere with the beam border animation in dark mode.

Full Configuration Example

// .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",
  head: [["link", { rel: "icon", type: "image/png", href: "/favicon.png" }]],
  themeConfig: {
    logo: "/logo.png",
    nav: [{ text: "Guide", link: "/guide/" }],
    sidebar: {
      "/guide/": [{ text: "Getting Started", link: "/guide/getting-started" }],
    },
    footer: {
      copyright: "Copyright © 2025-present",
    },
    // Theme extension config
    confetti: true,
    heroImageColor: true,
    smoothScroll: true,
    codeBlockFold: true,
    musicBall: {
      enable: true,
      autoplay: false,
      loop: true,
      list: [{ name: "Song Name", src: "/music/song.mp3" }],
    },
  },
})