Config Reference

The theme extends the VitePress default theme configuration via FxThemeConfig, adding music ball, confetti effect, hero image color extraction, and code block folding options.

FxThemeConfig

FxThemeConfig extends DefaultTheme.Config with the following fields:

interface FxThemeConfig extends DefaultTheme.Config {
  /**
   * 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
}

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. Code blocks inside code-groups are not affected.

Full Configuration Example

// .vitepress/config.mts
import { defineConfigWithTheme } from "vitepress"
import fxConfig from "@fuxishi/vitepress-theme/config"
import type { FxThemeConfig } from "@fuxishi/vitepress-theme/config"

export default defineConfigWithTheme<FxThemeConfig>({
  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" }],
    },
  },
})