mirror of
https://github.com/tiennm99/iammiti99.git
synced 2026-10-11 03:13:37 +00:00
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
This commit is contained in:
tiennm99 committed
1 parent
f2b6737960
commit
a67bdc5790
4 files changed
+167
-43
No files matched your search
@@ -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 <https://tiennm99.github.io/bonsai/>.
|
||||
|
||||
### 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
|
||||
@@ -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.
|
||||
+77
-42
@@ -1,25 +1,43 @@
|
||||
# Bonsai
|
||||
|
||||
[](https://github.com/tiennm99/bonsai/actions/workflows/build.yml)
|
||||
[](LICENSE)
|
||||
[](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/<you>/<your-site>
|
||||
@@ -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 `<h1>`. |
|
||||
| `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.
|
||||
|
||||
</details>
|
||||
|
||||
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).
|
||||
@@ -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"
|
||||
|
||||
Reference in new issue
Block a user