Global Configuration

This page covers the blog’s global configuration: site info, URL & permalinks, theme basics (Logo/Favicon), banner background, and the CDN mechanism. This is the foundation of the whole blog — every other config chapter builds on top of it.

Config has two layers: site config _config.yml (Hexo core + plugins) and theme config (layout/appearance/interaction). In this project the theme config file is overwritten by the userConfig/_config.tmp.yml template during CI builds — edit the template for theme config changes (see the Installation chapter). Unless marked “root config”, everything on this page is theme config.

1. Site Info

Purpose: site name, subtitle, description, author and other basic info; affects the title bar, SEO and site-wide text.

Config (root config _config.yml):

title: 夜法之书                 # site title, shown in browser tab and header
subtitle: '深度思考，深入生活！所有文章均持续滚动更新！'  # site subtitle
description: '~软件驱动世界~个人独立技术博客，关于Linux,开源，Nas，Docker，嵌入式，理财，健身等主题！'
author: 夜法之书                 # site-wide default author
language: zh-CN                 # site language
timezone: Asia/Shanghai         # timezone, affects date rendering

Notes: author is the fallback author — used when a post’s front-matter doesn’t set author; language affects the site html lang attribute and date localization; timezone must match your readers’ timezone, otherwise post dates will shift.

2. URL & Permalinks

Purpose: the site root URL and post link format. This blog uses abbrlink (CRC32 + hex) for short links, permanent after publishing.

Config (root config _config.yml):

url: https://blog.17lai.site   # site root URL (Vercel production domain)
permalink: posts/:abbrlink/     # post link format: /posts/8f9792ab/

# hexo-abbrlink plugin
abbrlink:
  alg: crc32      # hash algorithm: crc16 (default) | crc32
  rep: hex        # representation: dec (default) | hex
  drafts: false   # generate abbrlink for drafts
  force: false    # force recompute (ignores cache, use with care)
  writeback: false # writeback disabled (2026-09-22): prevents the resident server from clobbering source files

Notes: writeback: false (since 2026-09-22) means the plugin does not write back to source files — it was disabled because a resident hexo server that reads a file mid-edit (empty) would clobber the source with a truncated object (see docs/EXPERIENCE.md §55). abbrlink is written into each post’s front-matter on first generation and stays fixed thereafter, so renaming posts won’t break old links. url is the base of all absolute links (canonical, sitemap, RSS) — it must match the deployment domain in production.

3. Theme Basics: Logo & Favicon

Purpose: site icon and header logo, currently sharing the same image.

Config (theme config):

favicon: /favicon.webp   # browser tab icon (webp/png/ico supported)
logo: /favicon.webp      # header navbar logo

# Default direction for the Chinese trad/simp conversion, 1: 繁體中文, 2: 简体中文
zhDefaultEncoding: 2

Notes: images placed at the source/ root are served statically; zhDefaultEncoding is the default direction of the Chinese trad/simp conversion feature, paired with preference.translate (see the Multilingual & Wiki System chapter).

Purpose: the header banner image on all pages. Supports daily rotation, random images, parallax scrolling, plus a typewriter subtitle overlay.

Config (theme config):

banner:
  enable: true              # switch the banner daily
                            # false = always use /medias_webp/banner/0.webp
  random: true              # enable random featureimages
  parallax: false           # parallax scrolling (image moves with page scroll)
  width_height_ratio: 1.0   # minimum image aspect ratio, prevents over-cropping on mobile portrait; 0 disables
  typed:                    # banner subtitle typewriter
    enable: true
    loop: false             # loop
    showCursor: true        # show cursor
    cursorChar: "_"         # cursor character
    startDelay: 100         # start delay (ms)
    typeSpeed: 80           # typing speed
    backSpeed: 50           # deleting speed

Notes: with random: true images are picked from featureimages, combined with enable: true for “a new image every day”; the typed typewriter renders the subtitle (the site subtitle or the homepage index.slogan.text, see the Navigation Menu & Homepage chapter).

5. CDN Mechanism

Purpose: serve all static assets (JS/CSS/images) via CDN. This project uses jsDelivr + placeholder injection: templates contain {cdnPathVersion} and other placeholders, replaced with real CDN URLs at CI build time.

Config (theme config):

jsDelivr:
  url: {cdnPathVersion}     # versioned CDN path (replaced at build time)
  latesturl: #{cdnPathLatest} # latest path (commented out, not enabled)

cdn:
  url: "{cdnUrl}"           # JS/CSS CDN URL
  mediaUrl: "{mediaUrl}"    # image/media CDN URL
  resUrl: "{resUrl}"        # resource CDN URL (default https://cfblog.17lai.site)

Placeholders and build-time replacement (done by userConfig/_config.tmp.yml + tools/cicd.sh sed):

Placeholder	Replaced with	Example
`{cdnPathVersion}`	jsDelivr versioned path	`https://cdn.jsdelivr.net/gh/appotry/hexo@1.1`
`{cdnPathLatest}`	latest CDN path	`https://cdn.jsdelivr.net/gh/appotry/hexo@latest`
`{urlVersion}`	file version number	`?v={urlVersion}`
`{cdnUrl}` / `{mediaUrl}` / `{resUrl}`	CDN domains	`https://cfblog.17lai.site`

Notes: when writing config here you don’t need to care about placeholders — keep {xxx} as-is, CI handles it. Release timing: after changing JS/CSS run tools/cicd.sh -r "feature" to bump the version (tools/.VERSION), otherwise browsers/PWA cache the old version; content-only changes use -c or -d.

6. Site Running Time (time)

Purpose: show “This site has been running for N years N days” in the footer, counted from the configured launch date.

Config (theme config):

time:
  enable: true
  year: 2020   # year
  month: 06    # month
  date: 28     # date
  hour: 00     # hour
  minute: 00   # minute
  second: 00   # second

Notes: set the date to when the blog first went live; the footer automatically calculates and displays the running duration.

7. Fork Me Badge (githubLink)

Purpose: show a “Fork Me on GitHub” corner badge in the header, linking to your repository.

Config (theme config):

githubLink:
  enable: false
  url: https://github.com/blinkfox/hexo-theme-matery  # change to your repo
  title: Fork Me

Notes: when enable: true, the badge appears in the header; url points to your GitHub repository.

8. Theme Colors (color)

Purpose: site-wide color scheme — PWA theme color, background, navbar, text, with light/dark pairs. Use custom CSS for colors not covered here.

Config (theme config):

color:
  theme_color: "#7e9fc4"            # PWA theme color (manifest + theme-color meta)
  body_bg_color: "#eee"             # body background
  body_bg_color_dark: "#181c27"     # dark mode background (same for *_dark below)
  navbar_bg_color: "rgba(255, 255, 255, 0.8)"  # navbar background
  navbar_bg_color_dark: "#1f3144"
  navbar_text_color: "#f8f8f8"      # navbar text
  navbar_text_color_dark: "#d0d0d0"
  subtitle_color: "#f8f8f8"         # subtitle text
  subtitle_color_dark: "#d0d0d0"
  text_color: "#3c4858"             # global text
  text_color_dark: "#c4c6c9"
  sec_text_color: "#718096"         # secondary text (excerpt, intro, etc.)
  sec_text_color_dark: "#a7a9ad"

Notes: every color key has a matching *_dark value — adjust both when changing colors; color inspiration: LOL Colors.

9. Fonts (font)

Purpose: site-wide body font size, font family, letter spacing and code font size.

Config (theme config):

font:
  font_size: 16px        # body font size
  font_family:           # font family (empty = theme default)
  letter_spacing: 0.02em # letter spacing
  code_font_size: 85%    # code font size (relative to body)

Notes: leaving font_family empty uses the theme’s default font stack; code font size scales as a percentage of the body size.

10. Design Tokens (design)

Purpose: design tokens for radius/shadow/transition/gradient/spacing/font-size scales, mapped to CSS variables by color-schema.styl and referenced by all components.

Config (theme config):

design:
  # Radius (sm buttons/small tags, md cards/notes, lg modals, pill capsules, full circles)
  radius_sm: 3px
  radius_md: 8px
  radius_lg: 12px
  radius_pill: 999px
  radius_full: 50%
  # Shadow (sm hover micro-shadow, md card default, lg card hover, xl modals/overlays)
  shadow_sm: "0 1px 3px 0 rgba(0,0,0,0.12)"
  shadow_md: "0 2px 5px 0 rgba(0,0,0,0.16)"
  shadow_lg: "0 5px 11px 0 rgba(0,0,0,0.18)"
  shadow_xl: "0 10px 30px 0 rgba(0,0,0,0.2)"
  shadow_sm_dark: "0 1px 3px 0 rgba(0,0,0,0.4)"   # dark shadows (same below)
  shadow_md_dark: "0 2px 5px 0 rgba(0,0,0,0.45)"
  shadow_lg_dark: "0 5px 11px 0 rgba(0,0,0,0.5)"
  shadow_xl_dark: "0 10px 30px 0 rgba(0,0,0,0.55)"
  # Transition (fast hover feedback, normal panels/modals)
  transition_fast: 0.2s
  transition_normal: 0.3s
  # Gradient (primary navbar/buttons, accent card decoration)
  gradient_primary: "linear-gradient(to right, #4facfe, #00f2fe)"
  gradient_accent: "linear-gradient(135deg, #667eea, #764ba2)"
  # Spacing scale (4px base increments)
  space_1: 4px
  space_2: 8px
  space_3: 12px
  space_4: 16px
  space_5: 24px
  # Font size scale (rem-based, scales with --font-scale)
  font_size_xs: 0.75rem
  font_size_sm: 0.875rem
  font_size_md: 1.125rem
  font_size_lg: 1.25rem
  font_size_xl: 1.5rem
  font_size_2xl: 2rem

Notes: this is the theme’s design-system layer — components reference these tokens, so one change applies globally. Keep the scale system (radius/shadow/spacing each form a ladder) when adjusting; don’t break consistency by changing a single value. Font sizes are rem-based and scale with the root --font-scale variable (site-wide proportional scaling when the user adjusts font size) — don’t replace them with fixed px values.

11. Web Analytics (web_analytics)

Purpose: site-wide visitor analytics, supporting Baidu Analytics, Google Analytics 4 and self-hosted umami — all can run simultaneously.

Config (theme config):

web_analytics:
  enable: true
  follow_dnt: false   # respect browser "Do Not Track" (skip those visitors)

  baidu:              # Baidu Analytics
    enable: false
    id: 22cc5bdea6e529c1349d44b7306b3b8c   # string after `hm.js?`

  baiduPush: false    # Baidu Search Resource submission (requires site verification)

  google:             # Google Analytics 4
    enable: false
    measurement_id: 'G-JNYZP4ZLDJ'

  umami:              # self-hosted umami (this blog's primary)
    enable: true
    totalTraffic: true            # total visits
    totalNumberOfvisitors: true   # total visitors
    pageStats: true
    src: https://ana.17lai.site/script.js   # umami js URL (get after creating site in umami)
    start_time: '2023-01-01'      # PV/UV start time (quote it to prevent YAML Date parsing)
    token: "..."                  # umami viewOnly user token (for advanced stats)
    api_server: https://ana.17lai.site      # umami server address
    website_id: "..."             # umami website ID (get after creating site in umami)

Notes: umami’s totalTraffic/totalNumberOfvisitors drive the footer PV/UV display (with footer.statistics); start_time should be when the umami site was created and must be quoted, otherwise YAML parses it as a Date object and JSON.stringify turns it into {}; token requires creating a viewOnly user in the umami admin.

Appendix: Global Config Quick Reference

Config item	Location	Description
`title` / `subtitle` / `description`	root `_config.yml`	site basic info
`author` / `language` / `timezone`	root `_config.yml`	author fallback, language, timezone
`url` / `permalink`	root `_config.yml`	site root URL + `posts/:abbrlink/` link format
`abbrlink`	root `_config.yml`	crc32+hex short links, `writeback: false` (no writeback, prevents resident-server clobbering)
`logo` / `favicon`	theme config	header logo and site icon
`zhDefaultEncoding`	theme config	default trad/simp conversion direction
`banner`	theme config	daily rotation/random images/parallax/typewriter
`jsDelivr` / `cdn`	theme config	CDN placeholders (replaced at CI time)