Background Wallpaper

The background wallpaper configuration controls the site's background image display mode and related effects.

Config File

src/config/backgroundWallpaper.ts

Wallpaper Mode

Property	Type	Default	Description
mode	string	"banner"	Mode: "banner" banner, "fullscreen" full-screen, "overlay" overlay transparent, "none" solid color

TIP

The wallpaper mode switch toggle has been moved to displaySettingsConfig.wallpaperModeSwitchable. See Display Settings Panel.

Image Configuration

The src property supports multiple formats:

Separate Desktop and Mobile

src: {
  desktop: "assets/images/DesktopWallpaper/d1.avif",
  mobile: "assets/images/MobileWallpaper/m1.avif",
},

Multiple Images (Random)

src: {
  desktop: [
    "assets/images/DesktopWallpaper/d1.avif",
    "assets/images/DesktopWallpaper/d2.avif",
  ],
  mobile: [
    "assets/images/MobileWallpaper/m1.avif",
    "assets/images/MobileWallpaper/m2.avif",
  ],
},

Random Image API

src: {
  desktop: "https://t.alcy.cc/pc",
  mobile: "https://t.alcy.cc/mp",
},

TIP

Image path formats:

1. public directory (starts with /): not optimized
2. src directory (no leading /): auto-optimized (recommended)
3. Remote URL: not optimized, ensure small file size

Avoid renaming your custom images to d1-d6 or m1-m6, as these default sample image names may be overwritten during updates.

Background Video Player

Property	Type	Default	Description
playerEnable	boolean	false	Enable background video player. When enabled, a play button will appear in the navbar
src.playerUrl	string | string[]	-	Video URL(s). Supports a single path or an array for multi-video cycling
common.playerMode	"order" | "random"	"order"	Multi-video playback mode: "order" sequential loop, "random" random shuffle

export const backgroundWallpaper = {
  playerEnable: true,
  src: {
    desktop: [...],
    mobile: [...],
    // Single video
    // playerUrl: "/assets/videos/firefly.mp4",
    // Multiple videos
    playerUrl: [
      "/assets/videos/video1.mp4",
      "/assets/videos/video2.mp4",
    ],
  },
  common: {
    playerMode: "random",
  },
};

TIP

• Place local videos in the public/assets/videos/ directory
• The play button is automatically hidden in solid color mode (mode: "none")
• In multi-video mode, if a video fails to load, the player automatically tries the next one. A failure toast is shown when all videos fail

Common Configuration (Shared by Banner and Fullscreen)

Settings under common are shared between banner wallpaper and fullscreen wallpaper modes.

Text Overlay Dim

Property	Type	Default	Description
common.dimOpacity	number	0.2	Banner text overlay darkness, 0-1, higher values = darker

Home Banner Text

Property	Type	Default	Description
common.homeText.enable	boolean	true	Enable banner text
common.homeText.title	string	"Lovely firefly!"	Main title
common.homeText.titleSize	string	"3.8rem"	Title font size
common.homeText.subtitle	string | string[]	-	Subtitle(s)
common.homeText.subtitleSize	string	"1.5rem"	Subtitle font size

Typewriter Effect

Property	Type	Default	Description
common.homeText.typewriter.enable	boolean	true	Enable typewriter effect
common.homeText.typewriter.speed	number	100	Typing speed (ms)
common.homeText.typewriter.deleteSpeed	number	50	Delete speed (ms)
common.homeText.typewriter.pauseTime	number	2000	Pause time after completion (ms)

INFO

• Typewriter enabled — cycles through all subtitles
• Typewriter disabled — randomly shows one subtitle on each refresh

Link Icons Below the Title

Shows a customizable row of link icons (translucent round buttons) below the home banner title.

Property	Type	Default	Description
common.homeText.linksEnable	boolean	true	Show the link icons below the title
common.homeText.links	{ name; url; icon; showName? }[]	-	List of link icons. Empty to hide

• name: link name (used for aria-label / title / optional showName display)
• url: link URL (http(s):// external links open in a new tab)
• icon: Iconify icon, e.g. fa7-brands:github, fa7-solid:envelope, fa7-solid:rss, mdi:rss
• showName: optional, true to show the name next to the icon

homeText: {
  // ...
  links: [
    { name: "GitHub", icon: "fa7-brands:github", url: "https://github.com/CuteLeaf" },
    { name: "Email", icon: "fa7-solid:envelope", url: "mailto:xiaye@msn.com" },
    { name: "RSS", icon: "fa7-solid:rss", url: "/rss/" },
    // optionally show text
    { name: "Blog", icon: "mdi:rss", url: "/rss/", showName: true },
  ],
},

Wallpaper Carousel

Shared carousel configuration for both banner and fullscreen modes. Only works when multiple images are configured.

Property	Type	Default	Description
common.carousel.enable	boolean	false	Enable wallpaper carousel. If disabled, one image is randomly chosen on page refresh
common.carousel.interval	number	5000	Carousel interval in milliseconds
common.carousel.transitionEffect	string	"fade"	Transition effect: "fade", "zoom", "slide", "kenburns"

common: {
  carousel: {
    enable: true,
    interval: 5000,
    transitionEffect: "kenburns", // "fade" | "zoom" | "slide" | "kenburns"
  },
},

TIP

The wallpaper carousel user toggle has been moved to displaySettingsConfig.bannerCarouselSwitchable. See Display Settings Panel.

Transition effects:

Effect	Description
fade	Cross-fade between images
zoom	New image scales up from small to full size
slide	New image slides in from the right
kenburns	Ken Burns (recommended) — image slowly zooms in while transitioning via LQIP blurred preview bridge for the smoothest effect

Wave Animation

Shared wave animation config for banner wallpaper and fullscreen wallpaper (classic layout). Enabling it affects page performance.

Property	Type	Default	Description
common.waves.enable	boolean | { desktop, mobile }	{ desktop: true, mobile: true }	Enable wave animation

WARNING

Wave animation affects page performance. Enable based on your needs.

TIP

The wave animation user toggle has been moved to displaySettingsConfig.wavesSwitchable. See Display Settings Panel.

Gradient Transition

Automatically enabled when waves are disabled, providing a smooth gradient fade from the wallpaper bottom to the background color.

Property	Type	Default	Description
common.gradient.enable	boolean | { desktop, mobile }	{ desktop: true, mobile: true }	Enable gradient transition
common.gradient.height	string	"15vh"	Gradient height

INFO

Gradient and waves are mutually exclusive: when waves are enabled, the gradient is automatically hidden; when waves are disabled, the gradient is automatically shown. Both user toggles have been moved to displaySettingsConfig. See Display Settings Panel.

The hero fullscreen layout (fullscreen.layout: "hero") does not show waves or gradient; the classic layout ("classic") shows them just like banner mode.

Banner Mode

Image Position

Property	Type	Default	Description
banner.position	string	"0% 20%"	CSS object-position value. Supports 'center', 'top', 'bottom', 'left', 'right', percentages, etc.

Post Banner Information

Property	Type	Default	Description
banner.postInfo.mode	"description" | "meta"	"description"	Post banner information mode: "description" shows the post description, while "meta" shows published/updated dates, word count, and reading time

Navbar Transparency

Property	Type	Default	Description
banner.navbar.transparentMode	string	"semi"	Mode: "semi" semi-transparent, "semifull" dynamic (transparent at the top of the home page, frosted on scroll; semi-transparent on other pages), "none" solid opaque
banner.navbar.blur	number	6	Blur intensity; 0 disables the navbar's frosted glass

INFO

The navbar's dropdown menus and float panels (search, display settings, light/dark, music, mobile menu) always keep a frosted glass. Its blur follows banner.navbar.blur with a minimum of 2px.

So setting blur to 0 only disables the frosted glass on the navbar itself — the panels are unaffected. In pure-color mode (mode: "none") the panels stay opaque.

Fullscreen Mode

Fullscreen wallpaper mode lets you pick a layout via fullscreen.layout (switchable directly in the settings panel; the runtime choice persists to localStorage).

classic (document-flow fullscreen, legacy)

The wallpaper scrolls with the content, behaving like banner mode:

• Home page: the wallpaper fills the first screen (100vh, in document flow) with centered home text; the content area sits below the fold and a scroll-down indicator appears at the bottom
• Other pages (desktop): the wallpaper shrinks to a 45vh banner and the content moves up to meet it, showing the page title (category/tag/archive) or post meta centered
• Other pages (mobile ≤1023px): no wallpaper; content starts right below the navbar
• The wallpaper is not blurred (blurRamp / overlay.blur have no effect) and shows waves and gradient transitions (same as banner mode)

hero (fixed first-screen fullscreen, new)

The wallpaper is fixed across the screen:

• Home page: the wallpaper is fixed and fills the first screen (100lvh) with centered home text that parallax-fades as you scroll; the content area slides up from the bottom to cover it, and the wallpaper transitions from crisp to blurred (blurRamp)
• Other pages: the wallpaper stays fixed and blurred with content at the top (same as overlay mode)
• The wallpaper is opaque (overlay.opacity does not apply); blur (blur), card opacity (cardOpacity) and z-index (zIndex) are reused from the overlay config below
• Waves and gradient transitions are not shown

Property	Type	Default	Description
fullscreen.layout	"classic" | "hero"	"classic"	Fullscreen layout: "classic" document-flow (legacy), "hero" fixed first screen (new). Defaults to "classic" when unset
fullscreen.position	string	"center"	CSS object-position value
fullscreen.navbar.transparentMode	string	"semifull"	Navbar mode: "semi" semi-transparent, "semifull" dynamic (transparent at the top of the home page, frosted on scroll; semi-transparent on other pages)
fullscreen.navbar.blur	number	6	Navbar frosted blur; 0 disables it (applies in the frosted state)
fullscreen.blurRamp.enable	boolean | object	{ desktop: true, mobile: true }	Blur ramp toggle for the home page scroll (blur ramps from 0 to overlay.blur as you scroll), only for the hero layout. Supports a boolean or per-device { desktop, mobile }; when disabled on a device, fullscreen wallpaper stays crisp there (home and other pages) and the settings-panel blur slider is hidden

fullscreen: {
  layout: "hero",
  position: "center",
  navbar: {
    transparentMode: "semifull",
    blur: 6,
  },
  blurRamp: {
    enable: {
      desktop: true,
      mobile: true,
    },
  },
},

INFO

The fullscreen navbar's transparency is controlled by fullscreen.navbar.transparentMode: "semifull" keeps the home page's top navbar transparent and shows a frosted card after scrolling (semi-transparent on other pages); "semi" is always semi-transparent. The navbar background opacity is controlled by overlay.cardOpacity.

TIP

The crisp-to-blurred wallpaper transition on scroll is expensive on mobile GPUs (it re-rasterizes a full-screen blur). If scrolling feels laggy on mobile, set blurRamp.enable.mobile to false — fullscreen wallpaper stays crisp on that device and the settings-panel blur slider is hidden as well.

Overlay Mode

Property	Type	Default	Description
overlay.zIndex	number	-1	Z-index, ensures wallpaper stays in background layer
overlay.opacity	number	0.8	Wallpaper opacity (0-1)
overlay.blur	number	10	Background blur (px)
overlay.cardOpacity	number	0.5	Card background opacity (0-1). Lower values make cards more transparent

TIP

The overlay parameter adjustment toggle has been moved to displaySettingsConfig.overlaySwitchable, supporting master toggle or per-item toggles. See Display Settings Panel.