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.
3.2 KiB
Customization
Hugo's lookup order means anything in your site overrides the theme. No fork required.
Override layouts and partials
Drop a file with the same path under your site's layouts/ to replace the theme version.
your-site/
└── layouts/
├── _partials/
│ └── footer.html # overrides themes/tsuki/layouts/_partials/footer.html
└── single.html # overrides themes/tsuki/layouts/single.html
To extend rather than replace, copy the theme partial into your site, then modify. Common overrides:
_partials/footer.html— add license, build info, web ring links_partials/home/hero.html— restructure the homepage hero_partials/comments.html— swap Giscus for a different provider
Override design tokens
Tokens are CSS custom properties on :root and :where([data-theme="dark"]). Override them in a custom stylesheet without editing the theme.
/* your-site/assets/css/custom.css */
:root {
--tsuki-accent: #cc7a3b; /* warmer accent */
--tsuki-font-sans: "Public Sans", system-ui, sans-serif;
--tsuki-content-width: 48rem; /* wider posts */
}
:where([data-theme="dark"]) {
--tsuki-accent: #f0a070;
}
Append it to the bundle by overriding _partials/head.html. Copy the theme version, add your file:
{{- $cssFiles := slice
(resources.Get "css/tokens.css")
(resources.Get "css/reset.css")
...
(resources.Get "css/view-transitions.css")
(resources.Get "css/custom.css") {{/* your override, last in cascade */}}
-}}
Add custom icons
Drop SVGs into assets/icons/<name>.svg, then reference by name:
# data/profile.yaml
links:
- icon: bluesky
label: Bluesky
url: https://bsky.app/profile/...
Use currentColor for fill/stroke so icons inherit text color in light and dark modes:
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
<path d="..."/>
</svg>
Self-host fonts
The theme stack is "Inter", "Be Vietnam Pro", system-ui, .... The first two fall back to system fonts when missing. To self-host:
- Subset Be Vietnam Pro + Inter to
vietnamese,latinranges. - Drop the woff2 files into
static/fonts/. - Add
@font-facedeclarations inassets/css/custom.css(see "Override design tokens" above).
@font-face {
font-family: "Inter";
src: url("/fonts/Inter-VariableFont_slnt,wght.woff2") format("woff2-variations");
font-weight: 100 900;
font-display: swap;
}
@font-face {
font-family: "Be Vietnam Pro";
src: url("/fonts/BeVietnamPro-Regular.woff2") format("woff2");
font-weight: 400;
font-display: swap;
}
Override colors per-page
Set CSS variables inline via a frontmatter style you wire up yourself, or use the body_class block from baseof.html:
<!-- layouts/section/work.html -->
{{ define "body_class" }}list section-work{{ end }}
Then style body.section-work { --tsuki-accent: #...; } in your custom CSS.
Disable features
Every interactive feature has a kill switch:
params:
search:
enable: false # removes search button + /search/ route
comments:
giscus:
enable: false # comments partial becomes a no-op
Per-post:
toc: false
comments: false