Flavor

Flavor is a Hugo theme for technical blogs that ships paper-light and blue-dark color schemes, reading in whichever mode the visitor's system prefers and offering a manual toggle. It runs on Hugo Extended 0.146 or newer (developed against 0.163.1) and takes a standard Hugo site as input — config in hugo.toml, content under content/, friend links in data/friends.yaml — producing a static public/ build. The repository is maintained by baozongwi, and a live demo built from the bundled exampleSite is published at bao2ongw1.github.io.

What is Flavor?

Flavor is a Hugo theme built for technical blogs, combining a light paper-toned scheme with a dark blue one and adding encrypted posts, a navbar search overlay, and friend-link cards. It consumes a normal Hugo site (config, markdown content, YAML data files) and outputs a static site through hugo; it requires Hugo Extended 0.146 or later. Pages go beyond the post listing: an about page, an archives page, and a friend-links page, each added under content/page/ with a matching layout value.

Key Features

• Dual color schemes — paper-light and blue-dark, driven by prefers-color-scheme plus a manual toggle.
• System-first typography — body text uses the PingFang SC / Microsoft YaHei system UI stack; the navbar additionally ships the Chillax typeface for the site name and menus, and params.font.css attaches an optional webfont with automatic preconnect for http(s) URLs.
• Pagefind search overlay — search lives in the navbar rather than a /search page; after hugo, Pagefind is run over public/ (the docs use npx -y pagefind@1.5.0 --site public).
• AES-256-GCM encrypted posts — plaintext stays in content/private/ (gitignored), a shell script writes a stub plus data/encrypted/<slug>.json, and decryption happens in the browser via Web Crypto with PBKDF2.
• Friend-link cards — data/friends.yaml groups render six across on desktop, shuffle on refresh, show the note only on hover, and support offline: true to grey an avatar until hover.
• Right-hand table of contents — a drawer that stays closed until opened, alongside code copy buttons, an image lightbox, and back-to-top on article pages.
• Build-time image processing — raster images pass through process-image.html to webp: body images at longest edge 1600 with an 850w srcset, friend cards at 144x144, homepage avatar at 264 wide; GIF, SVG, and favicon are left unconverted.
• Sticky posts and a stale notice — sticky: true pins posts to the home and first list page; posts more than 100 days past lastmod get a quote notice unless stale: false is set, with the threshold configurable via params.staleDays.

Who is it for?

• Technical bloggers writing in Chinese or English — UI chrome is switched by defaultContentLanguage via i18n/, so a single theme serves both.
• Writers publishing gated or private notes — the encrypt script and browser-side decryption let a post live in the repo as ciphertext while the draft stays out of git.
• Bloggers who curate a link roll — friends.yaml renders grouped, shuffling cards with optional descriptions and offline styling.
• Sites with image-heavy posts — the build pipeline converts originals to webp with srcsets and avoids copying unprocessed png/jpg into public/ when originals are mounted as assets.

How does Flavor work?

Add the theme as a git submodule at themes/flavor, copy hugo.toml.example to hugo.toml, and edit domain, name, and menus before running hugo server. For encrypted posts, create the note with hugo new --kind encrypted, run the theme's encrypt.sh with a password (or ENCRYPT_PASSWORD for several posts), then deploy with a normal hugo build without setting HUGO_ENCRYPT_PLAIN. The theme can alternatively be installed as a Hugo module, in which case hugo mod vendor places the encrypt script under _vendor/.

FAQ

Is Flavor free?

Yes. Flavor is released under the MIT license, so it can be used and modified freely.

Does Flavor support encrypted posts?

Yes. Posts are encrypted with AES-256-GCM and PBKDF2 and decrypted in the browser with the Web Crypto API. Plaintext must stay in content/private/ and must not be committed; the repo holds a stub and a JSON payload per slug.

What Hugo version does Flavor need?

It requires Hugo Extended 0.146 or newer; the theme was developed on version 0.163.1.

How is search handled if there is no search page?

Search is a navbar overlay powered by Pagefind. There is no /search route, so Pagefind must be run against the generated public/ directory after each hugo build.