Almanac

Almanac is a personal hub theme for Hugo that turns a site into a yearly record of what you read, watch, build and write. Published as an MIT-licensed theme by Amigoer, it takes structured Markdown content plus a hugo.toml config as input and outputs a static site with an editorial homepage, ready-made content shelves and a searchable feed.

What is Almanac?

Almanac is a Hugo theme for building a content-rich personal hub — part blog, part reading/watching tracker, part project shelf. It runs on Hugo (extended, version 0.128 or later) and produces a fully static site, using Markdown files in defined sections plus a hugo.toml params block as its input. The theme is made by Amigoer and released under the MIT license.

Key Features

• Editorial homepage — a magazine-style hero with avatar, status pill, social row and tagline, followed by a configurable "recent posts" feed.
• Built-in shelves — /projects/, /reading/ and /watching/ sections ship ready-made, while /douban/ aggregates books and movies behind a tab switcher.
• Moments micro stream — /moments/ posts text, photo grids (1, 2-4 or 5-9 layouts), NetEase Cloud/Spotify embeds and Bilibili/YouTube embeds, grouped by day.
• Friend links — /links/ provides a categorised friend grid plus a "my info" name-card for applications.
• Mixed card system — each post accepts cardSize: feature | standard | compact | note, with an automatic fallback when omitted.
• Pagefind search — a ⌘K command palette powered by Pagefind out of the box.
• Dark mode — a single-button cycle (system → light → dark) persisted in localStorage with no first-paint flash.
• Tailwind CSS v4 and Alpine.js — styling compiled by Hugo's built-in css.TailwindCSS (Node.js required), interactivity via Alpine.js 3.x from a CDN, no bundler.

Who is it for?

• Personal bloggers: run a magazine-style homepage that mixes long articles with short note-style cards.
• Readers and cinephiles: track books and films on the reading and watching shelves with status, rating and cover fields.
• Indie developers: list projects with status (active, maintained, experimental, archived), a tech array, repo and homepage links.
• Social diarists: publish WeChat-Moments-style micro posts with images, music and location.

Use cases

• Bloggers who want an editorial front page: mark selected posts cardSize: feature to build a mixed feed of hero, standard and note cards.
• Media loggers: create reading/ and watching/ entries with status, rating and summary, then browse them together under /douban/.
• Project maintainers: add entries under projects/ with repo and homepage to produce a GitHub-style shelf.
• Blogroll owners: maintain data/links.yaml to render a categorised friend grid and a copyable contact card.

How does Almanac work?

Add the theme as a Git submodule, Hugo Module or clone, install tailwindcss and @tailwindcss/cli with npm, then copy the example hugo.toml. Hugo records rendered classes into hugo_stats.json via buildStats, and the theme compiles CSS from that file — so the site must be built by running hugo from the site root, not with --source from elsewhere.

FAQ

Is Almanac free?

Yes. Almanac is released under the MIT license, so it can be used, modified and redistributed freely. You still need Hugo extended 0.128 or later and Node.js to install the Tailwind CSS CLI.

Does Almanac support comments?

Almanac ships Waline integration. Set params.waline.serverURL in hugo.toml to enable comments on posts; Moments entries accept a comments frontmatter flag that defaults to true.

How do I add search?

Search uses Pagefind. After running hugo --gc --minify to produce public/, run npx pagefind --site public, and the bundled script lazily loads the Pagefind UI and binds ⌘K or Ctrl+K.

What frontmatter does a Moments entry need?

A Moments entry requires only date. Optional fields are mood, location, device, images (file names inside a page bundle), music and video with a platform and id. The Moments nav link appears automatically once the section has at least one entry.