mirror of
https://github.com/tiennm99/tsuki.git
synced 2026-09-02 14:21:19 +00:00
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.
This commit is contained in:
@@ -3,6 +3,7 @@
|
||||
[](https://github.com/tiennm99/tsuki/actions/workflows/pages.yml)
|
||||
[](LICENSE)
|
||||
[](https://gohugo.io)
|
||||
[](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/<you>/<your-site>
|
||||
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.
|
||||
|
||||
|
||||
@@ -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/<you>/<your-site>
|
||||
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/<slug>/`, `/categories/<slug>/`, `/archives/`
|
||||
- Single post with reading-time byline, callouts (if used), related posts at the bottom
|
||||
- `<head>` containing OG, Twitter, JSON-LD on posts; `<meta name=generator content="tsuki">`
|
||||
|
||||
If something looks off, see [`customization.md`](customization.md) for override patterns or open an issue.
|
||||
+2
-7
@@ -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 = ""
|
||||
|
||||
Reference in New Issue
Block a user