tiennm99
25f36aec12
- docs/config.md: full params reference (required + optional + per-post frontmatter); explains why theme defaults don't deep-merge into consumer sites - docs/data-schemas.md: profile.yaml + projects.yaml field tables - docs/customization.md: layout overrides, design token override via custom CSS, font self-hosting, per-page color overrides, kill switches - docs/migrating-from-stack.md: submodule swap, drop list, Stack-to-tsuki param mapping, frontmatter compat, gotchas (heading id changes break inbound anchor links) - CHANGELOG.md: complete 0.1.0 entry covering all phases - README.md: drop "under construction"; add full params snippet, search + comments + browser support sections, links to all docs - exampleSite/data/projects.yaml: +tsuki, +penny-pincher (6 total) Screenshots, miti99 migration, and v0.1.0 tag are user-driven actions recorded in phase-08 plan.
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
As a git submodule
git submodule add https://github.com/tiennm99/tsuki.git themes/tsuki
Add to your site's hugo.yaml:
theme: tsuki
As a Hugo Module
hugo mod init github.com/<you>/<your-site>
hugo mod get github.com/tiennm99/tsuki
Then add to hugo.yaml:
module:
imports:
- path: github.com/tiennm99/tsuki
Configuration
Add the required keys to your site's hugo.yaml:
theme: tsuki
languageCode: vi
defaultContentLanguage: vi
pagination:
pagerSize: 10
path: page
taxonomies:
category: categories
tag: tags
permalinks:
post: /:year/:month/:day/:contentbasename/
markup:
goldmark:
renderer:
unsafe: true
parser:
autoHeadingIDType: github-ascii
tableOfContents:
startLevel: 2
endLevel: 4
Then drop data/profile.yaml and data/projects.yaml into your site (see docs/data-schemas.md).
Hugo doesn't deep-merge nested config from themes — settings above belong in your site hugo.yaml. The exampleSite/hugo.yaml is a complete working example.
Documentation
docs/config.md— full params referencedocs/data-schemas.md—profile.yaml+projects.yamldocs/customization.md— override layouts, tokens, fontsdocs/migrating-from-stack.md— for users coming fromhugo-theme-stack
Search and comments
Search uses Pagefind, built in CI via npx pagefind --site public after Hugo. Pinned in package.json; bumps via Dependabot. 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.