tiennm99
b2834749c9
Headline outcomes: - Feature parity with Stack/PaperMod on Tier A polish: breadcrumbs (+BreadcrumbList JSON-LD), prev/next post navigation (rel=prev/next), language switcher UI (gated on hugo.IsMultilingual), code-copy button polish, <details> styling. - Per-page-kind CSS bundles: core loads everywhere; home/single/archive/ search bundles load only where needed. Frees ~1 KB gz from non-post pages. code-copy.js gated to post pages. - Lighthouse-relevant network polish: Pagefind UI CSS preload-swap, conditional preconnect to giscus.app on comment-enabled posts, hreflang alternates on multilingual sites, <meta name=theme-color> light/dark variants, aria-pressed SSR-rendered on theme-toggle. - WCAG AA contrast: --tsuki-fg-subtle darkened to #6b6b6b (light); was 3.54:1 on bg, now 5:1. Pagination disabled uses --tsuki-fg-muted without opacity compound. Header tap targets bumped to 40×40; pagination to 44×44. - i18n: full i18n/en.yml mirror (~50 keys); render-heading aria-label i18n-driven via linkToSection key; new keys for breadcrumb*, prevPost, nextPost, copyCode, copiedCode. - Discovery: /llm.txt output format (llmstxt.org) on home; Speculation Rules opt-in via params.prefetch.enable. - <html lang> fallback: site.Language.LanguageCode → Lang → "en" (was hard-coded "vi"). Per-kind bundle gz sizes on demo: home 3673 / post 4167 / list 2897 / archives 3363 / search 3179 B (all under 4200 B cap). Plan: plans/260510-0144-tsuki-v0.3.0/
tsuki (月)
A Hugo blog + personal portfolio theme. The homepage is the portfolio — bio, featured projects, recent posts. Posts live at /post/. Vietnamese-first typography, View Transitions on navigation, Pagefind search, Giscus comments.
月 (tsuki): the moon. Quiet, observed, returned to. Companion to
bonsaiin the same naming family.
Status
v0.1.0 — initial release. See CHANGELOG.md.
Features
- Blog — posts, tags, categories, year-grouped archive, paginated post list
- Personal portfolio on the homepage — driven by
data/profile.yaml+data/projects.yaml, no separate/portfoliosection - Search — Pagefind, zero-runtime, indexed at build time
- Comments — Giscus (GitHub Discussions)
- Vietnamese-first — diacritic-safe typography, native vi date formats, ASCII heading IDs
- Dark mode —
prefers-color-scheme+ persistent toggle, no flash of wrong theme - View Transitions API — smooth same-document navigation in supporting browsers
- Table of contents — auto-mounted on long posts, sticky on wide viewports, IntersectionObserver active highlight
- No build step — pure Hugo + browser ES modules. No SCSS, no TypeScript, no bundler in the theme
- Light — CSS ≤ 4 KB gz, JS ≤ 1 KB gz (excluding Pagefind UI)
Quick start
git submodule add https://github.com/tiennm99/tsuki.git themes/tsuki
echo 'theme: tsuki' >> hugo.yaml
Full installation guide (submodule, Hugo Module, Pagefind setup, required site config): docs/installation.md.
exampleSite/hugo.yaml is a complete working example.
Documentation
docs/installation.md— submodule + Hugo Module + Pagefind setupdocs/config.md— full params referencedocs/data-schemas.md—profile.yaml+projects.yamldocs/customization.md— override layouts, tokens, fonts, calloutsdocs/migrating-from-stack.md— for users coming fromhugo-theme-stack
Search and comments
Search uses Pagefind, built post-Hugo via npx pagefind --site public. tsuki pins Pagefind in its own package.json for submodule consumers; Hugo Module consumers install Pagefind in their own site (see docs/installation.md). No runtime dependency.
Comments use Giscus. Generate config at giscus.app and add to params.comments.giscus.* to enable. Defaults to off.
Browser support
Modern evergreen browsers. View Transitions and :has() are progressive enhancements; the theme remains functional without them.