From 5f023450a2c3f28042f2d527ed7917e971b60c8b Mon Sep 17 00:00:00 2001 From: tiennm99 Date: Sat, 9 May 2026 09:32:36 +0700 Subject: [PATCH] chore(release): theme metadata, module mounts, installation guide Update theme.toml with v0.2.0, configure module mounts for clean theme structure, add comprehensive installation documentation. --- README.md | 65 +++----------------------- docs/installation.md | 108 +++++++++++++++++++++++++++++++++++++++++++ theme.toml | 9 +--- 3 files changed, 117 insertions(+), 65 deletions(-) create mode 100644 docs/installation.md diff --git a/README.md b/README.md index e9d1458..b5ae6d7 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ [![build](https://github.com/tiennm99/tsuki/actions/workflows/pages.yml/badge.svg)](https://github.com/tiennm99/tsuki/actions/workflows/pages.yml) [![license](https://img.shields.io/github/license/tiennm99/tsuki)](LICENSE) [![Hugo](https://img.shields.io/badge/hugo-%E2%89%A50.146-ff4088?logo=hugo)](https://gohugo.io) +[![CSS](https://img.shields.io/badge/CSS-%E2%89%A44KB%20gz-blue)](https://github.com/tiennm99/tsuki/actions/workflows/pages.yml) 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. @@ -29,78 +30,26 @@ A Hugo blog + personal portfolio theme. The homepage *is* the portfolio — bio, ## Quick start -### As a git submodule - ```bash git submodule add https://github.com/tiennm99/tsuki.git themes/tsuki +echo 'theme: tsuki' >> hugo.yaml ``` -Add to your site's `hugo.yaml`: +Full installation guide (submodule, Hugo Module, Pagefind setup, required site config): [`docs/installation.md`](docs/installation.md). -```yaml -theme: tsuki -``` - -### As a Hugo Module - -```bash -hugo mod init github.com// -hugo mod get github.com/tiennm99/tsuki -``` - -Then add to `hugo.yaml`: - -```yaml -module: - imports: - - path: github.com/tiennm99/tsuki -``` - -## Configuration - -Add the required keys to your site's `hugo.yaml`: - -```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`](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. +`exampleSite/hugo.yaml` is a complete working example. ## Documentation +- [`docs/installation.md`](docs/installation.md) — submodule + Hugo Module + Pagefind setup - [`docs/config.md`](docs/config.md) — full params reference - [`docs/data-schemas.md`](docs/data-schemas.md) — `profile.yaml` + `projects.yaml` -- [`docs/customization.md`](docs/customization.md) — override layouts, tokens, fonts +- [`docs/customization.md`](docs/customization.md) — override layouts, tokens, fonts, callouts - [`docs/migrating-from-stack.md`](docs/migrating-from-stack.md) — for users coming from `hugo-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. +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`](docs/installation.md)). No runtime dependency. Comments use Giscus. Generate config at [giscus.app](https://giscus.app) and add to `params.comments.giscus.*` to enable. Defaults to off. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..a4a0260 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,108 @@ +# Installation + +tsuki supports two install methods. Pick the one that matches your team's tooling. + +## Git submodule + +```bash +git submodule add https://github.com/tiennm99/tsuki.git themes/tsuki +git submodule update --init --recursive +``` + +In your site `hugo.yaml`: + +```yaml +theme: tsuki +``` + +Pin to a specific version: + +```bash +cd themes/tsuki && git checkout v0.2.0 && cd - +git add themes/tsuki && git commit -m "chore: pin tsuki to v0.2.0" +``` + +## Hugo Module + +Requires Go installed locally (Hugo Modules use Go's module system). + +```bash +hugo mod init github.com// +hugo mod get github.com/tiennm99/tsuki@latest +``` + +In your site `hugo.yaml`: + +```yaml +module: + imports: + - path: github.com/tiennm99/tsuki +``` + +Update later with `hugo mod get -u github.com/tiennm99/tsuki`. + +## Required site config + +Hugo does not deep-merge nested config from themes — duplicate these into your *site* `hugo.yaml`. See [`config.md`](config.md) for the full block; the minimum is: + +```yaml +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 } +related: + threshold: 80 + includeNewer: true + toLower: true + indices: + - { name: tags, weight: 100 } + - { name: categories, weight: 60 } + - { name: date, weight: 10 } +``` + +Drop a `data/profile.yaml` and `data/projects.yaml` next; see [`data-schemas.md`](data-schemas.md). + +## Pagefind search + +Pagefind indexes content **after** Hugo builds. The theme assumes you run it as part of your build pipeline — it's not bundled into the layout. + +### For submodule users + +`tsuki/package.json` pins Pagefind. From your site root, after Hugo builds: + +```bash +cd themes/tsuki && npm ci && cd - +npx --prefix themes/tsuki pagefind --site public +``` + +Or simpler: install Pagefind in your own site `package.json` and run `npx pagefind --site public`. + +### For Hugo Module users + +Hugo Modules ignore `package.json` — it lives outside the module graph. Add Pagefind to your *site's* package.json: + +```bash +npm init -y +npm install --save-dev pagefind +``` + +Then in CI, run `npx pagefind --site public` after `hugo`. The supplied [`.github/workflows/pages.yml`](https://github.com/tiennm99/tsuki/blob/main/.github/workflows/pages.yml) is a drop-in template. + +If you don't want search at all, set `params.search.enable: false` in your `hugo.yaml` and skip the Pagefind step entirely. + +## Verify + +After installing, run `hugo server -s exampleSite` (if cloned) or `hugo server` from your own site. You should see: + +- Homepage with hero, optional projects grid, recent posts +- `/post/` list with pagination +- `/tags//`, `/categories//`, `/archives/` +- Single post with reading-time byline, callouts (if used), related posts at the bottom +- `` containing OG, Twitter, JSON-LD on posts; `` + +If something looks off, see [`customization.md`](customization.md) for override patterns or open an issue. diff --git a/theme.toml b/theme.toml index a9bfc37..6c3a8c0 100644 --- a/theme.toml +++ b/theme.toml @@ -1,18 +1,13 @@ name = "tsuki" license = "Apache-2.0" licenselink = "https://github.com/tiennm99/tsuki/blob/main/LICENSE" -description = "月 — Hugo blog + personal portfolio theme. Vietnamese-first typography, View Transitions API, Pagefind search, Giscus comments. Companion to bonsai." +description = "月 — Hugo blog + personal portfolio theme. Vietnamese-first typography, dark mode, View Transitions, Pagefind search, Giscus comments, native Markdown callouts, JSON-LD SEO. Zero build step." homepage = "https://github.com/tiennm99/tsuki" demosite = "https://tiennm99.github.io/tsuki/" tags = ["blog", "portfolio", "personal", "minimal", "dark", "vietnamese", "pagefind", "view-transitions"] -features = ["blog", "portfolio", "search", "comments", "dark-mode", "responsive", "i18n", "rss"] +features = ["blog", "portfolio", "search", "comments", "dark-mode", "responsive", "i18n", "rss", "callouts", "json-ld"] min_version = "0.146.0" [author] name = "Tien Nguyen" homepage = "https://miti99.com" - -[original] - author = "" - homepage = "" - repo = ""