Theme Configuration#

The Butterfly Hexo theme is configured via _config.yml in the theme root. This single YAML file controls all theme behavior — navigation, images, typography, comments, analytics, effects, CDN, and more. The official English reference is the Theme Configuration doc, and the canonical source of truth for all keys and defaults is the config file itself.

Configuration File & Structure#

Primary file: _config.yml (~1,141 lines)

The file is organized into named sections with header comments :

Section	Top-level keys
Navigation	`nav`, `menu`
Code Blocks	`code_blocks`
Images	`favicon`, `avatar`, `cover`, `background`, `error_img`, …
Index Page	`index_layout`, `index_post_content`, `subtitle`
Post Settings	`toc`, `post_copyright`, `reward`, `related_post`
Footer / Aside	`footer`, `aside`
Bottom-right Button	`rightside_*`, `darkmode`, `readmode`, `translate`
Global / Beautify	`font`, `blog_title_font`, `theme_color`, `beautify`, `hr_icon`
Third-party integrations	`math`, `search`, `share`, `comments`, `chat`, `busuanzi`, analytics keys
Effects	`canvas_ribbon`, `canvas_nest`, `fireworks`, `activate_power_mode`
Misc	`lightbox`, `pjax`, `lazyload`, `pwa`, `inject`, `CDN`

JavaScript defaults: scripts/common/default_config.js defines fallback values merged at build time, ensuring all keys have safe defaults even if omitted from _config.yml.

Font Settings#

Font configuration lives under two top-level keys :

font — controls global and code font size/family:

font.global_font_size — base font size (e.g. 14px)
font.code_font_size — monospace font size
font.font_family — global font stack string
font.code_font_family — code/pre font stack string

blog_title_font — controls the site title / subtitle typeface:

blog_title_font.font_link — URL to a Google Fonts stylesheet (injected into <head>)
blog_title_font.font_family — CSS font-family string for site title elements

These keys are picked up in source/css/var.styl via hexo-config() at Stylus compile time:

$font-family = hexo-config('font.font_family') ? ...
$code-font-family = hexo-config('font.code_font_family') ? ...
$site-name-font = hexo-config('blog_title_font.font_family') && ...
$font-size = hexo-config('font.global_font_size') ? ...
$code-font-size = hexo-config('font.code_font_size') ? ...

The font_link value is injected as a <link> stylesheet in layout/includes/head.pug. $site-name-font is applied to #site-title, .site-name, and author info elements in source/css/_global/index.styl, while $code-font-family and $code-font-size are applied to pre/code blocks in source/css/_highlight/highlight.styl.

Naming Convention: Underscores, Not Hyphens#

All YAML configuration keys use underscores throughout _config.yml, default_config.js, Pug templates, and hexo-config() calls in Stylus :

# Correct (as defined in _config.yml)
font:
  global_font_size:
  code_font_size:
  font_family:
  code_font_family:

blog_title_font:
  font_link:
  font_family:

Any reports of hyphen-vs-underscore inconsistency between config and documentation likely originate from older documentation or third-party guides, not the current codebase. The actual YAML keys never use hyphens as word separators; hyphens appear only in internal Stylus variable names ($font-family, $code-font-family, $site-name-font) — a separate CSS/Stylus convention that does not reflect config key names.

When debugging: if a font setting seems ignored, check that your _config.yml uses underscores (e.g. font_family, not font-family). Hexo silently ignores unrecognized keys.

Key Sections & Source Pointers#

Topic	Config key(s)	Source reference
Navigation bar	`nav`, `menu`
Code block appearance	`code_blocks`
Global font / size	`font.*`	,
Site title font	`blog_title_font.*`	,
Theme colors	`theme_color.*`
Dark mode	`darkmode.*`
Sidebar (aside)	`aside.*`
Math rendering	`math.*`
Search	`search.*`
Comments	`comments.*`, provider keys
CDN overrides	`CDN.option.*`
Custom code/script injection	`inject.head`, `inject.bottom`
JS defaults / fallbacks	(all keys)

Official docs: butterfly.js.org — Theme Configuration (English, auto-translated; may lag the codebase).