Config Overlay Principles

About 808 wordsAbout 3 min

2026-09-01

In Shirone, all site configurations use a declarative overlay architecture. You do not need to touch the theme engine core code. Simply create YAML files in your content repository's config/ directory to customize any site behavior.

Core Design Principles

1. Minimal Overlay Principle Clean

In YAML files, you only need to declare fields you wish to customize. All unmentioned properties automatically inherit theme defaults.

Key benefits:

Clean Configuration: No need to maintain thousands of lines of default boilerplate;
Seamless Upgrades: When upstream introduces new features or refines defaults, your site inherits them automatically.

2. Object Merge vs Array Replacement

When parsing YAML configurations, two distinct merging rules apply:

Nested Objects (Recursive Deep Merge)

For instance, in site.yaml, if you only wish to adjust typewriter typing speed:

config/site.yaml
banner:
  homeText:
    typewriter:
      speed: 150

Deletion speed, pause delays, and wallpaper sliders automatically inherit upstream defaults.

List Arrays (Atomic Full Replacement)

All array structures (such as nav-bar.yaml, sidebar.yaml components, profile.links, site.favicon) use atomic full replacement.

Array Full Replacement Rule

Array order and member composition represent a cohesive whole. Partial patching causes ordering ambiguities. When configuring arrays, you must enumerate the complete list of items you wish to render.

Typo Safety & Auto Compilation

1. Intelligent Typo Suggestions

Shirone incorporates compile-time schema validation. When running pnpm content:validate or syncing content, mistakes are flagged instantly:

Terminal Typo Suggestion
  config/site.yaml's banner.homeText: Type '{ titel: string }' is not assignable to type 'DeepPartial<HomeTextConfig>'
    Did you mean "title"?

2. Automated Bridge Module Compilation

During sync (pnpm content:sync) or production build, all YAML files are compiled into src/user/user-config.ts:

Icon Offline Bundling
Scans declared icons and bundles them into local assets, eliminating external CDN icon requests.
Font Subsetting Extraction
Extracts site titles, author names, and descriptions to feed the Chinese font subsetting engine.
Zero Maintenance
The bridge file is regenerated on every sync; never edit it manually.

Configuration Quick Reference

All config files reside under config/ in your content repository, partitioned by functional domain:

1. Global Identity & Appearance

File Path	Functional Domain	Default Strategy
`config/site.yaml`	Site identity, timezone, banner wallpaper, typewriter	Recursive Object Merge
`config/profile.yaml`	Avatar, bio, and social links	Object Merge (`links` Array Replacement)
`config/nav-bar.yaml`	Top navigation items and dropdowns	Array Replacement
`config/sidebar.yaml`	Single/dual column layout and widgets	Object Merge (`components` Array Replacement)
`config/font.yaml`	Web fonts and subsetting rules	Object Merge (`fontFamilies` Array Replacement)
`config/image-bloom.yaml`	Adaptive image bloom filter and glow effects	Recursive Object Merge
`config/context-menu.yaml`	Desktop right-click context menu actions	Object Merge (`actions` Array Replacement)
`config/footer.yaml`	Footer copyright and ICP registration	Recursive Object Merge
`config/footer.html`	Custom injected footer HTML snippet	Full Replacement

2. Content & Reading Experience

File Path	Functional Domain	Default Strategy
`config/post-list.yaml`	Post pagination and card grid layout	Recursive Object Merge
`config/permalink.yaml`	Global permalink format and placeholder rules	Recursive Object Merge
`config/article.yaml`	Reading time, outdated alerts, recommendations	Recursive Object Merge
`config/license.yaml`	Creative Commons license and copyright terms	Recursive Object Merge
`config/fab.yaml`	Floating Action Button (FAB) workflow & display	Recursive Object Merge
`config/announcement.yaml`	Global floating announcement banner	Recursive Object Merge
`config/expressive-code.yaml`	Syntax highlighting and code block numbers	Recursive Object Merge

3. Features & Special Pages

File Path	Functional Domain	Default Strategy
`config/anime.yaml`	Anime sync sources and Bangumi config	Recursive Object Merge
`config/music.yaml`	Sidebar music player modes and playlist	Recursive Object Merge
`config/comment.yaml`	Comment providers and Twikoo / Giscus settings	Recursive Object Merge
`config/devices.yaml`	Hardware device showcase categories	Object Merge (`categories` Array Replacement)
`config/games.yaml`	Games showcase categories	Object Merge (`categories` Array Replacement)
`config/projects.yaml`	Open source project categories	Object Merge (`categories` Array Replacement)
`config/skills.yaml`	Skill graph categories	Object Merge (`categories` Array Replacement)
`config/timeline.yaml`	Milestones timeline categories	Object Merge (`categories` Array Replacement)
`config/friends.yaml`	Friend links grouping and health check	Object Merge (`groups` Array Replacement)
`config/umami.yaml`	Umami analytics tracking	Recursive Object Merge
`config/llms.yaml`	LLM AI search enhancement	Recursive Object Merge
`config/series.yaml`	Serial post series layout and index settings	Recursive Object Merge

Common Configuration Examples

config/site.yaml
# Only declare fields you want to change
title: "My Tech Notes"
description: "Exploring programming and design"
favicon: "/favicon.ico"

banner:
  enable: true
  homeText:
    title: "Hello World"
    subtitle: "Beauty in Simplicity"
    typewriter:
      enable: true
      speed: 120

config/sidebar.yaml
layout: "two-column"
sticky: "toc"

# Array full replacement: renders only these 4 widgets
components:
  - "profile"
  - "toc"
  - "recent-posts"
  - "tags"

Next Steps

Head to Cross-Repo CI Automation: Set up GitHub Actions for cross-repository automated builds

Copyright

License under:Attribution 4.0 International (CC-BY-4.0)

Deployment

Markdown

Organization

Advanced

Code Blocks

Charts

Media Embeds

User

Components