From a67bdc57905ffd81b6c68271bfe9f48e4f31524b Mon Sep 17 00:00:00 2001 From: tiennm99 Date: Fri, 1 May 2026 14:20:37 +0700 Subject: [PATCH] docs: README polish + CONTRIBUTING + CHANGELOG - README: add badges (build/license/Hugo), live-demo callouts, full configuration parameter table, expanded features list - CONTRIBUTING.md: dev setup, icon-add workflow, PR/style guidelines - CHANGELOG.md: Keep-a-Changelog format with v0.1.0 + v0.0.1 entries - theme.toml: point demosite at live GitHub Pages URL --- themes/bonsai/CHANGELOG.md | 34 ++++++++++ themes/bonsai/CONTRIBUTING.md | 55 ++++++++++++++++ themes/bonsai/README.md | 119 ++++++++++++++++++++++------------ themes/bonsai/theme.toml | 2 +- 4 files changed, 167 insertions(+), 43 deletions(-) create mode 100644 themes/bonsai/CHANGELOG.md create mode 100644 themes/bonsai/CONTRIBUTING.md diff --git a/themes/bonsai/CHANGELOG.md b/themes/bonsai/CHANGELOG.md new file mode 100644 index 0000000..513623c --- /dev/null +++ b/themes/bonsai/CHANGELOG.md @@ -0,0 +1,34 @@ +# Changelog + +All notable changes to this project are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows [SemVer](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- (placeholder for v0.2 — layout variants, color presets, schema.org Person markup) + +## [0.1.0] — 2026-05-01 + +First production-ready release. Live demo at . + +### Added +- 35 icons out of the box: 25 brand (Simple Icons CC0) + 10 utility (Lucide ISC), vendored at build time +- `data/icons.yaml` manifest mapping public icon names → vendored SVG paths +- Data-driven `partials/icon.html` (13 lines) replacing the hand-curated `if/else if` chain +- `scripts/sync-icons.sh` — idempotent vendoring script, version-pinned to `simple-icons@13` + `lucide-static@0.460` +- Icon gallery page at `/icons/` (rendered from `exampleSite/content/icons/`) +- GitHub Actions `build` workflow — `hugo --gc --minify` on every PR and `main` push +- GitHub Actions `deploy` workflow — auto-deploys `exampleSite/` to GitHub Pages on `main` +- Dependabot config for weekly action updates +- `CONTRIBUTING.md` covering dev setup, icon-add workflow, PR guidelines +- `NOTICE` file crediting third-party icon sources + +### Changed +- README rewritten with badges, live-demo link, configuration table, all-parameters reference +- `exampleSite/hugo.toml` adds Mastodon and Bluesky example links +- `theme.toml` `demosite` field points at the live GitHub Pages URL + +## [0.0.1] — 2026-05-01 + +### Added +- Initial scaffold: theme structure, baseof/index/partial layouts, washi-paper light + sumi-ink dark CSS, 8 hand-curated inline SVG icons (github, globe, mail, twitter, linkedin, youtube, instagram, rss), exampleSite, Apache-2.0 LICENSE diff --git a/themes/bonsai/CONTRIBUTING.md b/themes/bonsai/CONTRIBUTING.md new file mode 100644 index 0000000..ec686fb --- /dev/null +++ b/themes/bonsai/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Contributing to Bonsai + +Thanks for your interest. Bonsai is intentionally small — every change should make it simpler, faster, or more useful, never bigger for its own sake. + +## Local development + +```bash +git clone https://github.com/tiennm99/bonsai.git +cd bonsai/exampleSite +hugo server --themesDir ../.. --bind 0.0.0.0 +``` + +Open `http://localhost:1313/`. Edits to `layouts/`, `static/`, `data/`, and `assets/` hot-reload. + +Hugo Extended ≥ 0.128 required. CI pins 0.154.0. + +## Adding an icon + +The icon system is data-driven — adding one means three small edits. + +1. **Vendor the SVG.** Edit `scripts/sync-icons.sh`: + - For brand/social icons → add the slug to the `BRAND_SLUGS` list (sourced from [Simple Icons](https://simpleicons.org)). + - For UI/utility icons → add the slug to the `UI_SLUGS` list (sourced from [Lucide](https://lucide.dev)). +2. **Run the script** to fetch and normalise: + ```bash + ./scripts/sync-icons.sh + ``` +3. **Register the public name** in `data/icons.yaml`: + ```yaml + newicon: { family: brand, slug: newicon } + ``` +4. Rebuild and verify the icon renders in the gallery: `cd exampleSite && hugo server --themesDir ../..` → `http://localhost:1313/icons/` +5. Add the new name to the appropriate table in `README.md`. + +## Pull requests + +- Branch from `main`. Keep PRs focused — one concern per PR. +- Conventional commit prefixes: `feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `refactor:`. +- For visual changes, attach a before/after screenshot (the live demo URL helps reviewers). +- CI must be green (`build` workflow runs `hugo --gc --minify` against `exampleSite`). + +## Style + +- HTML & CSS: 2-space indent. Keep `partials/` files under 30 lines where possible. +- Hugo templates: prefer `{{- ... -}}` to suppress whitespace; use `partials` for reuse. +- CSS: BEM-ish naming (`.bio__name`, `.link__icon`); CSS custom properties for theming. +- No build steps for end users — vendored assets only. If you reach for `npm install`, reconsider. + +## Reporting issues + +Include: Hugo version (`hugo version`), theme version/commit, minimal reproduction (a snippet of `hugo.toml` is usually enough), expected vs actual. + +## Philosophy + +YAGNI · KISS · DRY. If a feature would be useful for *some* sites, it doesn't belong here unless it's useful for *most* link-in-bio sites. The strength of Bonsai is what it leaves out. diff --git a/themes/bonsai/README.md b/themes/bonsai/README.md index 6d98a1c..c082591 100644 --- a/themes/bonsai/README.md +++ b/themes/bonsai/README.md @@ -1,25 +1,43 @@ # Bonsai +[![build](https://github.com/tiennm99/bonsai/actions/workflows/build.yml/badge.svg)](https://github.com/tiennm99/bonsai/actions/workflows/build.yml) +[![license](https://img.shields.io/github/license/tiennm99/bonsai)](LICENSE) +[![Hugo](https://img.shields.io/badge/hugo-%E2%89%A50.128-ff4088?logo=hugo)](https://gohugo.io) + A minimalist Hugo theme for link-in-bio pages, inspired by [Linktree](https://linktr.ee) and the Japanese art of [bonsai](https://en.wikipedia.org/wiki/Bonsai) — *small, curated, intentional*. +**→ [Live demo](https://tiennm99.github.io/bonsai/)** · **[Icon gallery](https://tiennm99.github.io/bonsai/icons/)** + > 盆栽 (bonsai): "tray planting" — the art of growing miniature trees through patient, deliberate cultivation. Every branch placed with care. Bonsai treats your bio page the same way: a quiet, well-pruned page that surfaces only what matters — your name, who you are, and where people can find you. ## Features -- **Single-page bio** — name, avatar, tagline, links, that's it -- **Data-driven links** — define every link in `hugo.toml` (or `data/links.yaml`); no content files needed -- **Light & dark mode** — respects system preference, toggleable -- **Zero JavaScript by default** — pure HTML + CSS; opt-in JS for theme toggle -- **Responsive** — mobile-first, looks right on every screen -- **Japanese-aesthetic defaults** — generous whitespace, calm palette, restrained typography -- **Fast** — < 10 KB CSS, no web fonts required (system stack) -- **Accessible** — semantic HTML, focus states, prefers-reduced-motion +- **Single-page bio** — name, avatar, tagline, links. Nothing else. +- **Data-driven links** — defined in `[[params.links]]`; no content files required. +- **35 icons out of the box** — 25 brand (GitHub, Mastodon, Bluesky, X, Threads, LinkedIn, Instagram…) + 10 utility (mail, globe, rss…). Vendored from [Simple Icons](https://simpleicons.org) and [Lucide](https://lucide.dev). +- **Light & dark mode** — respects `prefers-color-scheme`; optional toggle. +- **Zero JavaScript by default** — pure HTML + CSS; opt-in JS for theme toggle only. +- **Fast** — < 4 KB CSS, < 4 KB HTML, no web fonts (system stack), no runtime fetches. +- **Accessible** — semantic HTML, focus-visible outlines, `prefers-reduced-motion`. +- **Responsive** — mobile-first, looks right at every viewport. -## Installation +## Quick Start -### As a Hugo Module (recommended) +### As a Git submodule (simplest) + +```bash +git submodule add https://github.com/tiennm99/bonsai.git themes/bonsai +``` + +Add to `hugo.toml`: + +```toml +theme = "bonsai" +``` + +### As a Hugo Module ```bash hugo mod init github.com// @@ -34,50 +52,56 @@ Add to `hugo.toml`: path = "github.com/tiennm99/bonsai" ``` -### As a Git submodule - -```bash -git submodule add https://github.com/tiennm99/bonsai.git themes/bonsai -``` - -Set in `hugo.toml`: - -```toml -theme = "bonsai" -``` - ## Configuration Minimal `hugo.toml`: ```toml baseURL = "https://example.com/" -title = "Your Name" -theme = "bonsai" +title = "Your Name" +theme = "bonsai" + +# Single-page bio — disable everything Hugo doesn't need. +disableKinds = ["taxonomy", "term", "RSS", "sitemap", "404"] [params] - name = "Your Name" + name = "Your Name" tagline = "Tending my little corner of the internet" - avatar = "/images/avatar.jpg" - bio = "Short bio. One sentence is plenty." + bio = "Short bio. One sentence is plenty." + avatar = "/images/avatar.jpg" [[params.links]] title = "GitHub" - url = "https://github.com/yourname" - icon = "github" - - [[params.links]] - title = "Blog" - url = "https://yourblog.com" - icon = "globe" + url = "https://github.com/yourname" + icon = "github" [[params.links]] title = "Email" - url = "mailto:you@example.com" - icon = "mail" + url = "mailto:you@example.com" + icon = "mail" ``` -See `exampleSite/` for a full reference. +### All parameters + +| Param | Type | Default | Description | +|-------|------|---------|-------------| +| `name` | string | site `title` | Display name shown as `

`. | +| `tagline` | string | — | One-liner under the name. | +| `bio` | string (markdown) | — | Short bio paragraph. Markdown supported. | +| `avatar` | string (URL) | — | Avatar image path. Omit to skip. | +| `favicon` | string (URL) | `/favicon.ico` | Favicon path. | +| `themeToggle` | bool | `false` | Render the light/dark toggle button + load the toggle script. | +| `footer` | bool | `true` | Show the footer. | +| `footerText` | string (HTML) | `© {year} {name}` | Override footer text. HTML allowed. | +| `links` | array | — | Bio links. See below. | + +**Each `[[params.links]]` entry:** + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `title` | string | yes | Link label. | +| `url` | string | yes | Link target. `mailto:` and `tel:` are rendered without `target=_blank`. | +| `icon` | string | no | Icon name from the available set (see below). Unknown names render a generic external-link glyph. | ## Available Icons @@ -132,17 +156,28 @@ See `exampleSite/` for a full reference. -Icons are vendored at build time — no CDN fetch at runtime. To refresh or add icons, edit `scripts/sync-icons.sh` and `data/icons.yaml`, then re-run the script. +Icons are vendored at build time — no CDN fetch at runtime. Live gallery: **[tiennm99.github.io/bonsai/icons/](https://tiennm99.github.io/bonsai/icons/)**. -See `exampleSite/content/icons/` for a rendered gallery (run locally). +To refresh or add icons, edit `scripts/sync-icons.sh` and `data/icons.yaml`, then re-run the script. See [CONTRIBUTING.md](CONTRIBUTING.md). ## Development ```bash -cd exampleSite -hugo server --themesDir ../.. +git clone https://github.com/tiennm99/bonsai.git +cd bonsai/exampleSite +hugo server --themesDir ../.. --bind 0.0.0.0 ``` +Build for inspection: + +```bash +cd exampleSite && hugo --themesDir ../.. --gc --minify +``` + +## Contributing + +PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the icon-add workflow, and PR guidelines. + ## License -Apache-2.0 © tiennm99 +Apache-2.0 © [tiennm99](https://github.com/tiennm99). See [LICENSE](LICENSE) and [NOTICE](NOTICE) for third-party attributions (Simple Icons CC0, Lucide ISC). diff --git a/themes/bonsai/theme.toml b/themes/bonsai/theme.toml index 07c6c0a..bf4072e 100644 --- a/themes/bonsai/theme.toml +++ b/themes/bonsai/theme.toml @@ -3,7 +3,7 @@ license = "Apache-2.0" licenselink = "https://github.com/tiennm99/bonsai/blob/main/LICENSE" description = "A minimalist Hugo theme for link-in-bio pages, inspired by Linktree and Japanese bonsai aesthetics — small, curated, intentional." homepage = "https://github.com/tiennm99/bonsai" -demosite = "https://github.com/tiennm99/bonsai" +demosite = "https://tiennm99.github.io/bonsai/" tags = ["bio", "linktree", "minimal", "japanese", "personal", "landing", "icons"] features = ["responsive", "dark mode", "fast", "no-js optional", "data-driven links"] min_version = "0.128.0"