mirror of
https://github.com/tiennm99/blog.git
synced 2026-10-14 10:18:11 +00:00
chore(tsuki): remove the theme's finished plans and reports
This commit is contained in:
tiennm99 committed
1 parent
56466ea213
commit
6294e15dd9
28 files changed
+1
-5587
No files matched your search
@@ -4,7 +4,7 @@ All notable changes to tsuki will be documented here. Format follows [Keep a Cha
|
||||
|
||||
## [Unreleased] — v0.3.0
|
||||
|
||||
Feature-parity round + Lighthouse ≥80 baseline. Six phases per `plans/260510-0144-tsuki-v0.3.0/`. Net: tsuki now ships breadcrumbs, prev/next post navigation, language switcher UI, llm.txt, English i18n bundle, and per-page-kind CSS bundles, while maintaining the ≤4 KB gz / page-kind / ≤1 KB gz JS hard caps.
|
||||
Feature-parity round + Lighthouse ≥80 baseline. Delivered in six phases. Net: tsuki now ships breadcrumbs, prev/next post navigation, language switcher UI, llm.txt, English i18n bundle, and per-page-kind CSS bundles, while maintaining the ≤4 KB gz / page-kind / ≤1 KB gz JS hard caps.
|
||||
|
||||
### Added
|
||||
|
||||
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
title: tsuki v0.2.0 prerelease checklist
|
||||
status: pending
|
||||
created: 2026-05-09
|
||||
target: v0.2.0 tag + Hugo theme gallery submission
|
||||
predecessor: plans/archive/260508-2305-tsuki-v0.2.0-roadmap/
|
||||
blocks: [260510-0232-tsuki-v0.2.1-patch, 260510-0144-tsuki-v0.3.0]
|
||||
---
|
||||
|
||||
# v0.2.0 prerelease checklist
|
||||
|
||||
The 7-phase v0.2.0 roadmap (`plans/archive/260508-2305-tsuki-v0.2.0-roadmap/`) is shipped to `main`. This plan captures what's left before the `v0.2.0` tag and before submitting to `themes.gohugo.io`.
|
||||
|
||||
Three buckets: **mechanical** (I can run autonomously), **decisions** (need maintainer judgment), **external** (network / off-machine).
|
||||
|
||||
## Mechanical (low-risk, ready to run)
|
||||
|
||||
- [ ] **Pin `wjdp/htmltest-action@master`** to a commit SHA in `.github/workflows/pages.yml`. Floating-tag is supply-chain risk flagged by Phase 7 reviewer. Look up the latest stable release (currently around `@v0.17.0` per the action's repo); pin to its SHA.
|
||||
- [ ] **Fix Phase 7 plan-TODO accuracy** in `plans/archive/260508-2305-tsuki-v0.2.0-roadmap/phase-07-ci-hardening.md`. Two checkmarks claim work that was deferred — uncheck and add `(deferred)` notes:
|
||||
- `- [x] Lighthouse CI job added` → not added; Phase 7 plan note marked it optional and the CI workflow has no `lighthouse:` job
|
||||
- `- [x] docs/ci.md section added` → no separate file; CI behavior lives in `CHANGELOG.md` Unreleased section
|
||||
- [ ] **Watch CI run on the latest pushed commit** (`5d73a13`). Confirm: Hugo build green, Pagefind index built, CSS budget assertion passes, smoke tests pass, htmltest passes, Pages deploy succeeds, demo at https://tiennm99.github.io/tsuki/ shows v0.2.0 features (callouts in sample post, JSON-LD on every post, related-posts aside, skip-link).
|
||||
- [ ] **Run `/ck:journal`** to write a session journal entry recording the v0.2.0 cycle (audit → research → 7-phase plan → cook execution → code-review pass → commit/push → tag).
|
||||
- [ ] **Tag `v0.2.0`** with annotated tag pointing to the post-CI HEAD. Release notes derive from `CHANGELOG.md` `[Unreleased]` section; promote that section to `[0.2.0]` with the tag date.
|
||||
|
||||
## Maintainer decisions (block specific follow-ups)
|
||||
|
||||
- [ ] **Q1 — Goldmark `unsafe: true`** — currently kept for compat. If no posts in your real sites use raw HTML (`<details>`, custom shortcodes, escaped footnote rendering), drop it. That fully eliminates the `profile.bio` XSS surface (audit C2 — currently documented, not closed). Quick test: `grep -r '<' content/post/*/index.md` on your live site; if no inline HTML matches, safe to disable.
|
||||
- [ ] **Q3 — Audience** — solo bloggers vs teams. Decision affects whether multi-author moves out of the deferred list for v0.3.0+. No code change required for v0.2.0 either way; affects the README's audience framing.
|
||||
|
||||
## External / off-machine
|
||||
|
||||
- [ ] **Manual smoke against `gohugoBasicExample`** — clone the upstream basic example and install tsuki under both methods:
|
||||
```bash
|
||||
git clone https://github.com/gohugoio/hugoBasicExample.git /tmp/he
|
||||
cd /tmp/he
|
||||
# path A: submodule
|
||||
git submodule add ../tsuki themes/tsuki && hugo server # verify clean
|
||||
# path B: Hugo Module
|
||||
hugo mod init x.com/test && hugo mod get github.com/tiennm99/tsuki@v0.2.0 && hugo server
|
||||
```
|
||||
Verify both produce a usable site. Required by `gohugoio/hugoThemes` registry CI.
|
||||
- [ ] **Submit to `gohugoio/hugoThemes`** — fork the registry, add `tsuki` as a submodule pointing at the `v0.2.0` tag, follow `gohugoio/hugoThemes/CONTRIBUTING.md`, open PR. Strictly post-tag.
|
||||
|
||||
## Optional / nice-to-have
|
||||
|
||||
- [ ] Add a callout-emit assertion to `scripts/smoke-tests.sh` (Phase 4 coverage gap flagged by reviewer; e.g., `assert "callout demo" 'class="callout callout-' "$post"`)
|
||||
- [ ] Add a `theme.toml` parse smoke-test in CI (`hugo --logLevel debug` would surface unparseable TOML; or use a TOML linter)
|
||||
|
||||
## Success criteria
|
||||
|
||||
- `v0.2.0` tag pushed to `origin`
|
||||
- GitHub release created with notes derived from CHANGELOG
|
||||
- All CI gates green on the tagged commit (build + smoke + htmltest + budget + Pages deploy)
|
||||
- `themes.gohugo.io` submission PR open and CI-green
|
||||
|
||||
## Unresolved questions
|
||||
|
||||
1. Is there an internal preferred Hugo version baseline (e.g., does the project want to require ≥0.150 to use the latest blockquote alert features cleanly, or stay at 0.146 for a wider compatibility window)?
|
||||
2. Should the htmltest-action pin be tracked via Dependabot (config exists for `npm`, not for GitHub Actions; could add)?
|
||||
3. Is the v0.2.0 release date sensitive to anything external (e.g., aligning with a personal blog migration, public announcement)?
|
||||
@@ -1,95 +0,0 @@
|
||||
---
|
||||
phase: 1
|
||||
title: "v0.2.1 carry — review P1s + CI hygiene"
|
||||
status: completed
|
||||
priority: P1
|
||||
effort: "1d"
|
||||
dependencies: []
|
||||
completed_date: 2026-05-10
|
||||
notes: "All 7 fixes shipped on main pre-tag. v0.2.1 plan owns the tag deliverable."
|
||||
---
|
||||
|
||||
# Phase 1: v0.2.1 carry — review P1s + CI hygiene
|
||||
|
||||
## Overview
|
||||
|
||||
Conditional phase: if maintainer ships v0.2.1 patch independently, this phase becomes a no-op. Otherwise carries the 5 review P1s + 2 CI hygiene items into v0.3.0 so they don't ship hidden under a "features" banner.
|
||||
|
||||
## Context Links
|
||||
|
||||
- Source: `plans/reports/code-reviewer-260510-0144-tsuki-v0.2.0-post-release-improvements.md` (P1-1..P1-5, P3-8, P3-9)
|
||||
- Brainstorm: `plans/reports/brainstorm-260510-0144-post-v0.2.0-direction.md`
|
||||
|
||||
## Requirements
|
||||
|
||||
- Functional: each P1 fix preserves existing demo-site rendering
|
||||
- Non-functional: smoke tests + htmltest still green; CSS/JS budget unchanged
|
||||
|
||||
## Key Insights
|
||||
|
||||
- P1-1 (`render-link.html` `safeHTML`) is self-XSS in single-author theme — fix is consistency, not crit-sec
|
||||
- P1-2 (`seo.html` profile.url chain) is fragile but currently works; refactor for nil-safety
|
||||
- htmltest-action floating-tag is supply-chain risk flagged in v0.2.0 prerelease checklist
|
||||
|
||||
## Architecture
|
||||
|
||||
Surgical edits, no structural changes. Each fix is 1–5 lines.
|
||||
|
||||
## Related Code Files
|
||||
|
||||
- Modify: `layouts/_markup/render-link.html` (P1-1, P1-6)
|
||||
- Modify: `layouts/_partials/head/seo.html` (P1-2)
|
||||
- Modify: `layouts/_partials/home/projects.html` (P1-3)
|
||||
- Modify: `layouts/_partials/nav.html` (P1-4)
|
||||
- Modify: `layouts/_partials/comments.html` (P1-5)
|
||||
- Modify: `.github/workflows/pages.yml` (P3-8 SHA pin, P3-9 dead branch)
|
||||
- Modify: `docs/data-schemas.md` (document `data/profile.yaml: url` if kept — see plan.md unresolved Q6)
|
||||
- Modify: `CHANGELOG.md` (Unreleased → 0.3.0 entries)
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **P1-1** — `render-link.html:10`: drop `| safeHTML` from `{{ .Text | safeHTML }}`. Verify italic/emphasis-in-link still renders (Goldmark emits already-escaped inline HTML via `.Text`). Add demo post `exampleSite/content/post/render-hooks-demo/index.md` with `[*emphasis*](https://example.com)` to confirm.
|
||||
2. **P1-2** — `seo.html:64`: replace fragile `site.Params.profile.url | default ...` chain with nil-safe `with` blocks resolving `$authorURL` from `site.Params.profile.url`, then `site.Data.profile.url`, then `site.Home.Permalink`.
|
||||
3. **P1-3** — `projects.html:30,33`: pipe both `repo` and `demo` URLs through `safeURL`; add `noreferrer` to `rel`. Optional `target="_blank"` for external nav (decision: yes, external project links should open new tab).
|
||||
4. **P1-4** — `nav.html:6`: pipe `.URL` through `relURL`. Idempotent on already-resolved permalinks; fixes sub-path deploys.
|
||||
5. **P1-5** — `comments.html:1-4`: change gate to `{{- if and $g $g.enable $g.repo $g.repoId $g.categoryId -}}`. Add HTML comment when gated-off for debug visibility.
|
||||
6. **P3-8** — `.github/workflows/pages.yml:74`: replace `wjdp/htmltest-action@master` with commit SHA. Fetch via `gh api repos/wjdp/htmltest-action/commits/master | jq -r .sha`. Add comment with date + tag for future audit.
|
||||
7. **P3-9** — `.github/workflows/pages.yml:48-54`: drop dead `if find ... | head -1 | grep -q . then ... else ... fi` guard around Pagefind. Just run `npx pagefind --site exampleSite/public`.
|
||||
8. Run `hugo --gc --minify -s exampleSite -d exampleSite/public` locally + `./scripts/smoke-tests.sh` to confirm no regression.
|
||||
9. Update CHANGELOG with each fix in `[Unreleased]` `### Fixed` block.
|
||||
|
||||
## Todo List
|
||||
|
||||
- [ ] P1-1 render-link.html safeHTML drop + demo post
|
||||
- [ ] P1-2 seo.html $authorURL nil-safe refactor
|
||||
- [ ] P1-3 projects.html safeURL + noreferrer + target=_blank
|
||||
- [ ] P1-4 nav.html .URL relURL pipe
|
||||
- [ ] P1-5 comments.html stricter gate
|
||||
- [ ] P3-8 htmltest-action SHA pin
|
||||
- [ ] P3-9 drop dead Pagefind branch
|
||||
- [ ] Local build + smoke test verification
|
||||
- [ ] CHANGELOG entries
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] All 5 P1 fixes applied, demo site builds clean
|
||||
- [ ] htmltest CI step uses pinned SHA (no `@master`)
|
||||
- [ ] No `if find` dead branch in pages.yml
|
||||
- [ ] Smoke tests still pass (no new failures)
|
||||
- [ ] CHANGELOG entries written
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **P1-1 risk:** Dropping `safeHTML` may break a hidden author-side use case. Mitigation: search `exampleSite` for any link-text-with-HTML; if found, document the change in CHANGELOG.
|
||||
- **P1-2 risk:** Refactor introduces new template error if Hugo idiom drifts. Mitigation: test demo build locally before pushing.
|
||||
- **P3-8 risk:** SHA pin requires periodic refresh. Mitigation: add Dependabot config for GitHub Actions in v0.3.1 (out of v0.3.0 scope).
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- P1-1, P1-3 reduce stored-HTML/URL surface
|
||||
- P3-8 closes supply-chain attack vector via floating master tag
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Phase 2 depends on Phase 1 completion (clean baseline before structural CSS bundle changes)
|
||||
- If maintainer ships v0.2.1 first → mark this phase `completed` and skip
|
||||
@@ -1,158 +0,0 @@
|
||||
---
|
||||
phase: 2
|
||||
title: "Theme-budget rebase — per-kind CSS + JS gate + default cleanup"
|
||||
status: completed
|
||||
priority: P1
|
||||
effort: "1d"
|
||||
dependencies: [1]
|
||||
completed_date: 2026-05-15
|
||||
---
|
||||
|
||||
# Phase 2: Theme-budget rebase
|
||||
|
||||
## Overview
|
||||
|
||||
Frees ~1.2 KB gz from the CSS bundle by switching from "concat-all-on-every-page" to per-page-kind bundles, gates `code-copy.js` on post pages only, and prunes ~30 redundant `| default ""` calls. This phase enables Phase 5 (Speculation Rules) and Phase 3 (details CSS) without breaching the 4 KB gz cap.
|
||||
|
||||
## Context Links
|
||||
|
||||
- Source: `plans/reports/code-reviewer-260510-0144-tsuki-v0.2.0-post-release-improvements.md` (P2-2, P2-3, P2-9)
|
||||
- CI assertion: `.github/workflows/pages.yml` CSS budget step
|
||||
|
||||
## Requirements
|
||||
|
||||
- Functional: every page kind (home, single, list, taxonomy, search) renders identically to v0.2.0
|
||||
- Non-functional: total CSS gz ≤ 4 KB on **each** kind individually (currently aggregate ≈ 4.2 KB)
|
||||
- JS gz ≤ 1 KB on site-wide bundle; `code-copy.js` excluded from non-post pages
|
||||
|
||||
## Key Insights
|
||||
|
||||
- Reviewer estimates ~30% of bundle is dead bytes on home/list/taxonomy (toc.css + comments.css + archive.css unused)
|
||||
- Per-kind split: `core.css` (always) + `home.css` (home only) + `single.css` (post only, includes toc/callouts/comments) + `archive.css` (list+archives) + `search.css` (search only)
|
||||
- Hugo `resources.Concat` accepts a slice; `head.html` switches on `.Kind`
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
head.html
|
||||
├── always: tokens.css + reset.css + typography.css + layout.css + components.css + view-transitions.css → core.css
|
||||
├── if .Kind == "home": + home.css → home.css
|
||||
├── if .Kind == "page": + toc.css + callouts.css + comments.css → single.css
|
||||
├── if .Kind == "term"|"taxonomy"|"section": + archive.css → archive.css
|
||||
└── if .Section == "search": + search.css → search.css
|
||||
```
|
||||
|
||||
Each bundle: `Concat | minify | fingerprint | resources.Get`, emit one `<link rel="stylesheet" integrity="...">` per applicable bundle.
|
||||
|
||||
## Related Code Files
|
||||
|
||||
- Modify: `layouts/_partials/head.html` (CSS bundle assembly)
|
||||
- Modify: `layouts/_partials/footer.html` (gate code-copy.js include on `eq .Kind "page"`)
|
||||
- Modify: ~10 templates for `| default ""` cleanup (`meta.html`, `header.html`, `footer.html`, `404.html`, `nav.html`, `home/*.html`, `search/list.html`)
|
||||
- Modify: `.github/workflows/pages.yml` CSS budget step (assert per-kind, not aggregate)
|
||||
- Modify: `scripts/smoke-tests.sh` (assert per-kind bundle size)
|
||||
- Modify: `CHANGELOG.md` Unreleased
|
||||
- Read: `assets/css/*.css` (no changes — partition only)
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. Map current CSS partials → kinds (use Hugo `.Kind` and `.Section`). Document the matrix in head.html comments.
|
||||
2. Refactor `head.html` to assemble bundles via `slice` + `where` + `resources.Concat`. Keep `core.css` as the fingerprinted base. Conditional bundles get their own `<link>` tags.
|
||||
3. Update SRI integrity emit to handle multiple bundles (loop over slice).
|
||||
4. Move `code-copy.js` `<script>` include from `head.html`/`footer.html` to behind `{{- if eq .Kind "page" -}}`. Verify on demo site.
|
||||
5. Find-and-replace `| default "..."` calls now redundant (vi.yml has all keys post-Phase-1 of v0.2.0):
|
||||
- `meta.html` lines for readingTime, wordCount
|
||||
- `404.html` for pageNotFound, backHome
|
||||
- `home/*.html` for featuredProjects, viewAll
|
||||
- `search/list.html` for search/searchSuggestion/altSearch/searchDisabled
|
||||
- List ~30 occurrences; remove only redundant defaults, keep defensive ones (e.g., `site.Title | default "tsuki"`)
|
||||
6. Update CI CSS budget assertion: loop over each bundle kind, assert each ≤ 4096 bytes gz.
|
||||
7. Update `scripts/smoke-tests.sh` to fetch a sample of each kind and confirm only relevant CSS is `<link>`-loaded.
|
||||
8. Local build all 5 kinds + visual diff in headless browser (or screenshot via `chrome-devtools` skill).
|
||||
9. CHANGELOG entry under Changed: per-kind CSS bundles, expected impact on consumers (none if they don't override head.html).
|
||||
|
||||
## Todo List
|
||||
|
||||
- [ ] CSS partial → kind matrix documented
|
||||
- [ ] head.html refactor with bundle slices
|
||||
- [ ] SRI integrity multi-bundle emit
|
||||
- [ ] code-copy.js gated on page kind
|
||||
- [ ] Redundant `| default ""` removal pass
|
||||
- [ ] CI per-kind budget assertion
|
||||
- [ ] Smoke test per-kind link presence assertion
|
||||
- [ ] Local build + visual diff verification
|
||||
- [ ] CHANGELOG entry
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] core.css + home.css ≤ 4 KB gz on home page
|
||||
- [ ] core.css + single.css ≤ 4 KB gz on post page
|
||||
- [ ] core.css + archive.css ≤ 4 KB gz on list/term/taxonomy
|
||||
- [ ] core.css + search.css ≤ 4 KB gz on search
|
||||
- [ ] code-copy.js absent from home/list/search HTML
|
||||
- [ ] No `| default "{vi-key}"` redundancies remain (≥25 removed)
|
||||
- [ ] CI passes per-kind budget assertion
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **Cache miss multiplication:** more bundles = more HTTP fetches per first paint per kind. Mitigation: cross-page revisits use `core.css` which is shared and fingerprinted; subsequent kinds add only one extra request.
|
||||
- **SRI integrity edge case:** Hugo fingerprint+integrity calls per resource. Test on Pagefind UI page where third-party CSS loads (no SRI on third-party).
|
||||
- **Visual regression:** dropping a CSS file by accident on a kind. Mitigation: smoke test `grep` for kind-specific class on each kind's HTML.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- SRI integrity preserved on all internal bundles
|
||||
- No new third-party assets
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Phase 3 depends on Phase 2's bundle layout (details CSS + breadcrumbs CSS + prev/next CSS slot into single.css)
|
||||
- Phase 5 depends on Phase 2's freed budget
|
||||
|
||||
## Added in audit pass (2026-05-15)
|
||||
|
||||
Cheap perf wins folded in here because they touch the same `head.html` / network-emit surface as the budget rebase. Both are <10 lines each.
|
||||
|
||||
### A2.1 — Pagefind UI CSS preload-swap (Lighthouse P0-2)
|
||||
|
||||
**Source:** code-reviewer-260515-lighthouse-80-baseline-audit.md → P0-2.
|
||||
|
||||
**Problem:** Pagefind UI ships its own stylesheet via `<link rel="stylesheet">` which is render-blocking on the search page.
|
||||
|
||||
**Fix:** ~3 lines in `layouts/search/list.html`. Use preload-swap pattern:
|
||||
|
||||
```html
|
||||
<link rel="preload" as="style" href="{{ ... pagefind-ui.css ... }}" onload="this.rel='stylesheet'">
|
||||
<noscript><link rel="stylesheet" href="{{ ... pagefind-ui.css ... }}"></noscript>
|
||||
```
|
||||
|
||||
**Why this phase:** Phase 2 owns CSS budget + load-order discipline; the Pagefind swap is the same discipline applied to the third-party stylesheet on the one page it lands.
|
||||
|
||||
**Files modified:**
|
||||
- `layouts/search/list.html` — swap link tag
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] Pagefind UI CSS uses preload-swap pattern on `/search/`
|
||||
- [ ] `<noscript>` fallback present (no-JS users still get styled search)
|
||||
|
||||
### A2.2 — Conditional preconnect to giscus.app (Lighthouse P1-5)
|
||||
|
||||
**Source:** code-reviewer-260515-lighthouse-80-baseline-audit.md → P1-5.
|
||||
|
||||
**Problem:** Giscus iframe lazy-loads from `giscus.app` post-paint; no preconnect means TLS+DNS happen on demand, hurting INP on comment-enabled posts.
|
||||
|
||||
**Fix:** In `layouts/_partials/head.html`, emit `<link rel="preconnect" href="https://giscus.app">` only when (a) page is a post (`.Kind == "page"`), (b) `params.comments.giscus.enable: true`, and (c) all required Giscus params present (matches Phase 1 P1-5 strict gate).
|
||||
|
||||
**Why this phase:** Same gate structure as P1-5 in Phase 1; same `<head>` emit logic as the per-kind CSS bundle in this phase. Single template branch.
|
||||
|
||||
**Files modified:**
|
||||
- `layouts/_partials/head.html` — add conditional preconnect block
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] preconnect emits only on post pages with Giscus fully configured
|
||||
- [ ] absent from home/list/search HTML even when Giscus configured
|
||||
- [ ] absent from post pages when Giscus disabled or partially configured
|
||||
|
||||
### Effort delta
|
||||
|
||||
+0.2d (small additions, but verification on demo + smoke test adjustments). Phase 2 still fits in ~1d if Phase 1 work is clean. **Code comments / smoke-test names must not reference "P0-2" or "P1-5"** — describe the behavior ("Pagefind CSS preload swap"; "Giscus preconnect when comments enabled") per project rules.
|
||||
@@ -1,255 +0,0 @@
|
||||
---
|
||||
phase: 3
|
||||
title: "Author UX + Tier A parity — details, TOC narrow, en.yml, breadcrumbs, prev/next, code-copy UI, lang switcher, hreflang"
|
||||
status: completed
|
||||
priority: P2
|
||||
effort: "2d"
|
||||
dependencies: [2]
|
||||
amended: 2026-05-15
|
||||
completed_date: 2026-05-15
|
||||
notes: "Narrow-viewport TOC <details> wrap deferred to v0.3.1 (UX ambiguity on wide + tight bundle budget)."
|
||||
---
|
||||
|
||||
# Phase 3: Author UX + Tier A feature parity
|
||||
|
||||
## Overview
|
||||
|
||||
Three additive improvements: (1) `<details>/<summary>` markdown blocks get styled CSS in light + dark mode (opens "rich content" door without a render hook), (2) on narrow viewports the TOC wraps in a `<details open>` so mobile users don't scroll past 60 lines of nav, (3) ship a starter `i18n/en.yml` so consumers can drop in English without copying every key.
|
||||
|
||||
## Context Links
|
||||
|
||||
- Source: `plans/reports/code-reviewer-260510-0144-tsuki-v0.2.0-post-release-improvements.md` (P2-1, P2-10, P3-4)
|
||||
|
||||
## Requirements
|
||||
|
||||
- Functional: `<details>` blocks render styled (border, padding, dark-mode contrast); TOC collapses on `<64rem` viewports; `en.yml` builds clean with `defaultContentLanguage: en`
|
||||
- Non-functional: CSS additions ≤ 200 B gz total in `single.css`; no JS additions
|
||||
|
||||
## Key Insights
|
||||
|
||||
- `<details>` doesn't need a Hugo render hook — Hugo passes raw HTML through (with `unsafe: true`); only CSS styling is missing
|
||||
- `<details>` is also the simplest collapse mechanism for narrow-viewport TOC — no JS, accessible by default
|
||||
- en.yml is documentation-as-code: signals i18n contract, lowers adoption friction for non-vi readers
|
||||
|
||||
## Architecture
|
||||
|
||||
- `assets/css/callouts.css` (or new `assets/css/details.css` — decide based on byte budget): `details { border: 1px solid var(--tsuki-border); ... } details[open] summary::marker { ... } summary:focus-visible { outline: ... }`. Dark-mode tokens via existing `[data-theme="dark"]` cascade.
|
||||
- `layouts/_partials/toc.html`: replace `<aside class="toc">` wrapper logic with conditional. Wide viewport: existing sticky aside. Narrow: `<details class="toc-collapsed" open>` containing same TOC body. CSS-only via media query on visibility, or a tiny class toggle.
|
||||
- `i18n/en.yml`: mirror every key in `vi.yml`, English values. Keep vi.yml canonical (don't add new keys to en first).
|
||||
|
||||
## Related Code Files
|
||||
|
||||
- Modify: `assets/css/callouts.css` OR create `assets/css/details.css` + add to Phase 2 single.css bundle
|
||||
- Modify: `layouts/_partials/toc.html` (narrow-viewport `<details>` wrap)
|
||||
- Modify: `assets/css/toc.css` (narrow-viewport collapse styles)
|
||||
- Create: `i18n/en.yml` (~40 keys translated)
|
||||
- Modify: `docs/customization.md` (document `<details>` styling, en.yml use)
|
||||
- Modify: `CHANGELOG.md` Unreleased
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. Audit current `<details>` rendering on demo: add a sample `<details>` block to `exampleSite/content/post/render-hooks-demo/index.md`. Screenshot in light + dark.
|
||||
2. Write CSS for `<details>`: border, padding, hover, `summary` cursor, `[open]` state. Test in both themes. Aim ≤ 150 B gz minified.
|
||||
3. TOC narrow wrap: in `layouts/_partials/toc.html`, conditionally output `<details class="toc-narrow" open><summary>{{ i18n "tableOfContents" }}</summary>...`. Use CSS `@media (min-width: 64rem) { details.toc-narrow > summary { display: none } details.toc-narrow[open], details.toc-narrow { all: unset } }` to revert to current sticky aside on wide. Verify keyboard nav (Tab into TOC, Enter on summary).
|
||||
4. Add `tableOfContents` i18n key to `vi.yml` ("Mục lục") if not present, then `en.yml`.
|
||||
5. Create `i18n/en.yml` from `vi.yml` keys. ~40 keys: skipToContent, search-related (×4), comments, calloutNote/Tip/Important/Warning/Caution, readingTime, wordCount, month, pageNotFound, backHome, featuredProjects, viewAll, relatedPosts, etc. English translations: short, blog-conventional ("Skip to content", "Search", "Reading time: {{ .Count }} min").
|
||||
6. Test: build demo with `defaultContentLanguage: en` (temp branch); verify no missing-key fallback paths fire.
|
||||
7. Document in `docs/customization.md`: how to use `<details>`, how to customize details CSS, how to use en.yml or add a third language file.
|
||||
8. CHANGELOG: Added — details styling, narrow-viewport TOC collapse, i18n/en.yml.
|
||||
|
||||
## Todo List
|
||||
|
||||
- [ ] Demo `<details>` post for visual reference
|
||||
- [ ] details CSS in light + dark
|
||||
- [ ] TOC narrow `<details>` wrap + responsive CSS
|
||||
- [ ] tableOfContents i18n key in vi.yml + en.yml
|
||||
- [ ] i18n/en.yml created with all vi.yml keys translated
|
||||
- [ ] Demo build with `defaultContentLanguage: en` clean
|
||||
- [ ] docs/customization.md updates
|
||||
- [ ] CHANGELOG entries
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] `<details>` renders with visible border + dark-mode aware in demo post
|
||||
- [ ] TOC on `<64rem` viewport renders inside `<details open>`; tappable summary
|
||||
- [ ] Demo site builds with `defaultContentLanguage: en`, no missing-key warnings
|
||||
- [ ] CSS budget on single.css still ≤ 4 KB gz (Phase 2 cap holds)
|
||||
- [ ] Keyboard nav: Tab → summary → Enter toggles, Tab continues into TOC links
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **CSS budget pressure:** details CSS adds ~150 B gz; if Phase 2 freed less than expected, drop hover-only enhancements. Hard floor: visible border in both themes.
|
||||
- **en.yml translation quality:** consumers may want different phrasing. Mitigation: keep en.yml minimal/conventional, document override path.
|
||||
- **Narrow-viewport TOC interaction with View Transitions:** `<details>` open state is non-document scope; should survive same-document VT. Test on demo.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
None — additive content/styling only, no new dynamic surface.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Phase 4 (WCAG audit + Lighthouse ≥80) inspects this phase's expanded keyboard + visual surface (breadcrumbs links, prev/next links, code-copy button, language switcher dropdown)
|
||||
- Phase 6 smoke tests get "details renders styled", "breadcrumbs JSON-LD valid", "prev/next link rel-attrs", "code-copy class present", "lang switcher emit gated"
|
||||
|
||||
## Added in audit pass (2026-05-15)
|
||||
|
||||
Phase 3 grew significantly. Tier A feature parity (researcher report) lives here because it's all author-facing UX, not AI-discovery. Folding into Phase 3 rather than spinning up a Phase 7 because:
|
||||
|
||||
1. Shared CSS bundle (`single.css` already touched for `<details>`); 1 bundle pass instead of 2.
|
||||
2. Shared i18n key updates with the existing en.yml work (breadcrumb labels, prev/next labels, language names).
|
||||
3. Phase 4 (WCAG + Lighthouse) needs the full surface to audit at once.
|
||||
|
||||
Cost: Phase 3 effort 1d → 2d. Cheaper than coordinating a 7th phase.
|
||||
|
||||
### A3.1 — Breadcrumbs partial with BreadcrumbList schema (Tier A)
|
||||
|
||||
**Source:** researcher-260515-tsuki-vs-stack-papermod-feature-gap.md → Tier A item #3.
|
||||
|
||||
**Problem:** Stack + PaperMod ship breadcrumbs; tsuki ships none. Hurts UX clarity on deep posts + loses BreadcrumbList SEO signal.
|
||||
|
||||
**Fix:** New partial `layouts/_partials/breadcrumbs.html`. Gated via `params.breadcrumbs.enable` (default off — opt-in per backwards-compat rule). Emits both rendered breadcrumb trail and `BreadcrumbList` JSON-LD when enabled.
|
||||
|
||||
**Markup pattern:** `Home > /posts/ > {{ .Title }}` (use `.CurrentSection`, `.Parent`, `.Title`).
|
||||
|
||||
**Schema:** Include `BreadcrumbList` JSON-LD inline in the partial (sibling to existing Article JSON-LD in `seo.html`); compose `itemListElement` from same hierarchy.
|
||||
|
||||
**Files modified/created:**
|
||||
- Create: `layouts/_partials/breadcrumbs.html`
|
||||
- Create: `assets/css/breadcrumbs.css` (~50 B gz; add to Phase 2 `single.css` bundle)
|
||||
- Modify: `layouts/_default/single.html` or relevant single layout — include partial above article header
|
||||
- Modify: `docs/config.md` — document `params.breadcrumbs.enable`
|
||||
- Modify: `i18n/vi.yml` + `i18n/en.yml` — add `breadcrumbHome` (vi: "Trang chủ", en: "Home")
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] `params.breadcrumbs.enable: true` renders trail above post title
|
||||
- [ ] BreadcrumbList JSON-LD parses (jq) and matches rendered trail
|
||||
- [ ] Disabled by default; absent on all kinds when flag unset
|
||||
- [ ] Breadcrumb link tap targets ≥48×48 (Phase 4 verifies)
|
||||
|
||||
### A3.2 — Prev/Next post navigation (Tier A)
|
||||
|
||||
**Source:** researcher-260515 → Tier A item #4.
|
||||
|
||||
**Problem:** Stack/PaperMod ship prev/next; tsuki users have to bounce back to list/index.
|
||||
|
||||
**Fix:** New partial `layouts/_partials/prev-next.html`. Gated via `params.prevNextNav.enable` (default true — researcher recommends, zero-friction). Uses Hugo's `.PrevInSection` / `.NextInSection`.
|
||||
|
||||
**Markup:** `<nav class="prev-next">` with two anchors; `rel="prev"` + `rel="next"` for SEO; visible labels from i18n.
|
||||
|
||||
**Files modified/created:**
|
||||
- Create: `layouts/_partials/prev-next.html`
|
||||
- Create: `assets/css/prev-next.css` (~100 B gz; add to `single.css` bundle in Phase 2)
|
||||
- Modify: `layouts/_default/single.html` — include below article body, above related-posts widget
|
||||
- Modify: `docs/config.md` — document `params.prevNextNav.enable`
|
||||
- Modify: `i18n/vi.yml` + `i18n/en.yml` — `prevPost` ("Bài trước"/"Previous post"), `nextPost` ("Bài tiếp"/"Next post")
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] Renders on post pages when prev or next exists
|
||||
- [ ] Single-element rendering when only prev OR next exists (don't emit empty cell)
|
||||
- [ ] `rel="prev"`/`rel="next"` correct
|
||||
- [ ] Disabled when `params.prevNextNav.enable: false`
|
||||
|
||||
### A3.3 — Code-copy button UI polish (Tier A)
|
||||
|
||||
**Source:** researcher-260515 → Tier A item #1; combines with existing v0.2.x `code-copy.js` work.
|
||||
|
||||
**Problem:** tsuki's `code-copy.js` exists (Phase 2 gates it to post pages) but visual polish lags Stack/PaperMod — button placement, hover state, "copied!" feedback.
|
||||
|
||||
**Fix:** CSS polish in `assets/css/code-copy.css` (already in `single.css` bundle post-Phase-2). Add:
|
||||
- Positioning: top-right of `<pre>`, ~8px offset
|
||||
- Hover/focus state (visible focus ring per WCAG 2.4.13)
|
||||
- "Copied!" feedback via `.code-copy[data-state="copied"]` ARIA-live region content
|
||||
- Tap target ≥48×48 (Phase 4 verifies)
|
||||
|
||||
**JS side:** Existing `assets/js/code-copy.js` should set `aria-label` (i18n via inline data attr or `i18n` key — pick simplest), toggle `data-state`, restore after 2s. Verify `navigator.clipboard` guard exists; hide button if unavailable per unresolved Q4 recommendation.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `assets/css/code-copy.css` — visual polish (~100 B gz add)
|
||||
- Modify: `assets/js/code-copy.js` — aria-label + data-state lifecycle (verify; may already be present)
|
||||
- Modify: `i18n/vi.yml` + `i18n/en.yml` — `copyCode` ("Sao chép"/"Copy"), `copiedCode` ("Đã sao chép"/"Copied!")
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] Button visible on `<pre>` blocks in demo post
|
||||
- [ ] Hidden if `navigator.clipboard` unavailable
|
||||
- [ ] Click copies + feedback fires + reverts after 2s
|
||||
- [ ] Focus ring visible in both themes
|
||||
- [ ] `aria-label` i18n-driven
|
||||
|
||||
### A3.4 — Language switcher UI (Tier A)
|
||||
|
||||
**Source:** researcher-260515 → Tier B item #7 (promoted because en.yml lands in this phase and switcher pairs naturally).
|
||||
|
||||
**Problem:** vi + en translations ship but no visible switcher. Adopters with multilingual sites can't expose the switch.
|
||||
|
||||
**Fix:** New partial `layouts/_partials/lang-switcher.html`. Auto-hides when `site.IsMultiLingual` is false. Renders as a small dropdown or inline list of `.AllTranslations`.
|
||||
|
||||
**Files modified/created:**
|
||||
- Create: `layouts/_partials/lang-switcher.html`
|
||||
- Create: `assets/css/lang-switcher.css` (~150 B gz; add to `core.css` bundle since header is global)
|
||||
- Modify: `layouts/_partials/header.html` — include partial in nav region
|
||||
- Modify: `docs/config.md` — document i18n setup + switcher behavior
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] Switcher hidden when only one language configured
|
||||
- [ ] Switcher visible when `site.IsMultiLingual: true`
|
||||
- [ ] Active language indicated (e.g., `aria-current="page"` or visual mark)
|
||||
- [ ] Keyboard accessible (Tab + Enter)
|
||||
- [ ] Tap target ≥48×48
|
||||
|
||||
### A3.5 — hreflang alternate links (Lighthouse P1-6)
|
||||
|
||||
**Source:** code-reviewer-260515-lighthouse-80-baseline-audit.md → P1-6.
|
||||
|
||||
**Problem:** Multilingual sites should emit `<link rel="alternate" hreflang="...">` per language for SEO.
|
||||
|
||||
**Fix:** ~6 lines in `layouts/_partials/head.html`, gated on `site.IsMultiLingual`. Loop `.AllTranslations`; emit `<link rel="alternate" hreflang="{{ .Language.Lang }}" href="{{ .Permalink }}">` for each, plus `hreflang="x-default"` pointing at the default language version.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `layouts/_partials/head.html`
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] hreflang emit absent when single-language
|
||||
- [ ] hreflang emit present + correct on multilingual demo (would need temp multilingual demo branch to verify; otherwise verify template logic locally)
|
||||
|
||||
### A3.6 — Cover-image override docs (Lighthouse P0-1)
|
||||
|
||||
**Source:** code-reviewer-260515 → P0-1.
|
||||
|
||||
**Problem:** Reviewer's P0-1 flagged either (a) default cover-image renderer with `images.Resize` srcset pipeline, or (b) documenting the override path. Decision per audit-pass: defer (a) to v0.4.0 (tied to AVIF + responsive-image work); land (b) in v0.3.0 to unblock adopters.
|
||||
|
||||
**Fix:** Add a "Cover images" section to `docs/customization.md`. Show how an adopter overrides `_partials/seo.html` or adds a per-post `cover` frontmatter field with their own image pipeline. Note explicit v0.4.0 promise for native srcset/AVIF support.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `docs/customization.md`
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] customization.md has "Cover images" section with copy-paste override snippet
|
||||
- [ ] Section notes v0.4.0 promise for built-in pipeline
|
||||
|
||||
### A3.7 — render-heading aria-label i18n key
|
||||
|
||||
**Source:** code-reviewer-260515 → noted alongside en.yml work.
|
||||
|
||||
**Problem:** `render-heading.html` likely uses a hard-coded English aria-label for the section-link anchor (e.g., "Link to section").
|
||||
|
||||
**Fix:** Audit `layouts/_markup/render-heading.html`; replace any hard-coded label with an `i18n` call. Add the matching key to both `vi.yml` and `en.yml`.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `layouts/_markup/render-heading.html`
|
||||
- Modify: `i18n/vi.yml` + `i18n/en.yml` — add `linkToSection` (vi: "Liên kết đến mục", en: "Link to section")
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] No hard-coded English strings in render-heading
|
||||
- [ ] aria-label resolves per active language
|
||||
|
||||
### Effort delta
|
||||
|
||||
Phase 3 effort 1d → 2d. The work splits roughly:
|
||||
- Day 1 (original scope): details CSS, TOC narrow, en.yml, customization docs
|
||||
- Day 2 (audit-pass additions): breadcrumbs (+schema), prev/next, code-copy UI polish, lang switcher, hreflang, render-heading i18n key, cover-image docs
|
||||
|
||||
### Implementer notes
|
||||
|
||||
- Per project rules: code comments, CSS class names, file names must not reference "P0-1", "Tier A", or "A3.x" — describe the behavior ("breadcrumb partial with schema.org markup", "prev/next post navigation"). Plan artifacts stay in this document and PR description only.
|
||||
- Single new `single.css` partial pass: breadcrumbs + prev/next + code-copy polish all land in the same `single.css` bundle. Verify aggregate gz size stays ≤4 KB after Phase 2 cleanup.
|
||||
- Language switcher CSS lands in `core.css` (header surface) not `single.css`.
|
||||
@@ -1,258 +0,0 @@
|
||||
---
|
||||
phase: 4
|
||||
title: "WCAG 2.2 AA audit + Lighthouse ≥80 baseline"
|
||||
status: completed
|
||||
priority: P2
|
||||
effort: "1.5d"
|
||||
dependencies: [3]
|
||||
amended: 2026-05-15
|
||||
completed_date: 2026-05-15
|
||||
notes: "Tap targets sized to 40×40 (header) / 44×44 (pagination); Lighthouse strict 48×48 audit will warn but a11y score still projected ≥95. docs/accessibility.md baseline table contains TBD entries — fill in after first production Lighthouse run."
|
||||
---
|
||||
|
||||
# Phase 4: WCAG 2.2 AA audit + Lighthouse ≥80 baseline
|
||||
|
||||
## Overview
|
||||
|
||||
Run Lighthouse + axe-devtools against the demo exampleSite, target WCAG 2.2 AA conformance, fix findings. Focus areas per researcher report: focus appearance (SC 2.4.13), target size 24×24 minimum (SC 2.5.8), dragging movements alternative (SC 2.5.7).
|
||||
|
||||
## Context Links
|
||||
|
||||
- Source: `plans/reports/researcher-260510-0144-hugo-theme-2026-evolution.md` (Tier 1 a11y)
|
||||
- W3C WCAG 2.2 SCs: 2.4.11, 2.4.12, 2.4.13 (focus), 2.5.7, 2.5.8 (target size), 3.3.7, 3.3.8 (auth) — only 2.4 + 2.5 SCs apply to this theme
|
||||
|
||||
## Requirements
|
||||
|
||||
- Functional: keyboard nav covers all interactive elements; focus is visible without ambiguity; all targets ≥ 24×24 CSS pixels
|
||||
- Non-functional: Lighthouse a11y ≥ 95 on home + post pages; axe issues count = 0 (or documented intentional exceptions)
|
||||
|
||||
## Key Insights
|
||||
|
||||
- v0.2.0 added focus rings + skip-link (covers SC 2.4.11 minimum). 2.2 adds **focus appearance** (2.4.13 AA) — focus indicator must have ≥ 2px outline AND ≥ 3:1 contrast against unfocused state.
|
||||
- Target size 2.5.8 AA (24×24) — likely fail points: pagination arrows, header nav small text links, footer links, search button mobile, theme toggle.
|
||||
- Dragging 2.5.7 — only relevant if there's a slider/drag UI. Theme has none. Verify and document as N/A.
|
||||
|
||||
## Architecture
|
||||
|
||||
Audit-driven. No new architecture; CSS adjustments to existing tokens + selective padding additions.
|
||||
|
||||
## Related Code Files
|
||||
|
||||
- Modify: `assets/css/tokens.css` (focus outline width/color tokens if needed)
|
||||
- Modify: `assets/css/components.css` (target size adjustments — likely pagination, theme toggle, search button)
|
||||
- Modify: `assets/css/layout.css` (header/footer link padding for tap targets)
|
||||
- Possibly modify: `layouts/_partials/header.html`, `nav.html`, `pagination.html` (semantic adjustments)
|
||||
- Add: `docs/accessibility.md` (statement of conformance, known exceptions, SCs covered)
|
||||
- Modify: `CHANGELOG.md`, `README.md` (a11y badge / claim)
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. Build demo: `hugo --gc --minify -s exampleSite -d exampleSite/public`. Serve locally.
|
||||
2. Run Lighthouse (CLI or DevTools) on home + post + tag list + search. Capture report.
|
||||
3. Run axe-devtools (browser extension) on the same pages. Cross-reference.
|
||||
4. Manual keyboard pass: Tab through entire home + post. Confirm: skip-link → header nav → main → TOC (post) → article links → comments → footer. No traps. All focus rings visible in light + dark.
|
||||
5. Measure target sizes: pagination arrows, theme toggle, search button, header nav links, footer links, in-content callout summary, TOC details summary (Phase 3). Use DevTools "Inspect → Computed → bounding box". Anything `<24×24` gets `padding` or `min-width`/`min-height`.
|
||||
6. Focus appearance: confirm `:focus-visible { outline: 2px solid var(--tsuki-accent) }` meets contrast against background in both themes. Adjust accent token if 3:1 contrast fails on either theme.
|
||||
7. Document SC 2.5.7 (dragging) as N/A — theme has no drag UI.
|
||||
8. Write `docs/accessibility.md`: SCs covered, known limitations, how to test (Lighthouse command), how consumers can verify their content.
|
||||
9. Add a11y badge to README (link to `docs/accessibility.md`).
|
||||
10. CHANGELOG entry under Added/Changed.
|
||||
|
||||
## Todo List
|
||||
|
||||
- [ ] Lighthouse + axe baseline reports captured
|
||||
- [ ] Manual keyboard nav verified on all kinds
|
||||
- [ ] Target size measurements + fixes (≥ 24×24 everywhere)
|
||||
- [ ] Focus appearance contrast verified ≥ 3:1 in both themes
|
||||
- [ ] docs/accessibility.md written
|
||||
- [ ] README a11y badge
|
||||
- [ ] CHANGELOG entries
|
||||
- [ ] Lighthouse a11y ≥ 95 on home + post
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Lighthouse a11y ≥ 95 on demo home + post
|
||||
- [ ] axe-devtools issue count = 0 on home + post + list + search
|
||||
- [ ] All interactive targets ≥ 24×24 CSS pixels
|
||||
- [ ] Focus rings visible with ≥ 3:1 contrast in light + dark
|
||||
- [ ] Skip link functional (Tab once, Enter, scrolls to `<main>`)
|
||||
- [ ] No keyboard traps
|
||||
- [ ] docs/accessibility.md published
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **Target size pressure on dense layouts:** pagination + footer often have small visual targets. Mitigation: increase padding without changing visual size (negative margin to compensate).
|
||||
- **Contrast fails in one theme but not the other:** accent token may need `--tsuki-accent-light` and `--tsuki-accent-dark` split.
|
||||
- **Audit findings beyond focus + target size:** axe may surface ARIA / heading hierarchy issues. Triage; defer non-2.2 items to v0.3.1 if scope balloons.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
None.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Phase 6 smoke tests get assertions tied to a11y outputs (skip-link, focus token presence, aria-pressed, tap-target CSS values, theme-color meta)
|
||||
- v0.3.1 may add pa11y CI integration to lock baseline
|
||||
|
||||
## Added in audit pass (2026-05-15)
|
||||
|
||||
Multiple Lighthouse-audit findings land here because they share the audit/measurement loop. Tighten the success criteria from "Lighthouse a11y ≥95" to the full "Lighthouse ≥80 on all 4 categories, ≥95 on a11y" project goal.
|
||||
|
||||
### A4.1 — Tighten tap-target SC from WCAG 24×24 to Lighthouse 48×48 (P0-3)
|
||||
|
||||
**Source:** code-reviewer-260515-lighthouse-80-baseline-audit.md → P0-3.
|
||||
|
||||
**Problem:** WCAG 2.5.8 AA requires 24×24 CSS pixels; Lighthouse Tap Targets audit enforces 48×48. To clear the ≥80 a11y category in Lighthouse (and ideally ≥95), tap targets must hit the tighter bar.
|
||||
|
||||
**Fix:** Audit + adjust padding/`min-height`/`min-width` on:
|
||||
- Theme-toggle button
|
||||
- Search button (header + mobile)
|
||||
- Pagination prev/next/page-number links
|
||||
- Footer links
|
||||
- (Phase 3 additions) Breadcrumb links, prev/next post nav links, language switcher items, code-copy buttons
|
||||
|
||||
Suggested value: `min-height: 2.75rem` (44px @16px root) or `min-height: 3rem` (48px). Pick one and apply consistently.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `assets/css/components.css`, `assets/css/layout.css`
|
||||
- Possibly: `assets/css/header.css`, `assets/css/footer.css`, `assets/css/pagination.css`
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] All interactive targets ≥48×48 CSS px (overrides existing ≥24×24)
|
||||
- [ ] Lighthouse "Tap targets are sized appropriately" passes
|
||||
|
||||
### A4.2 — `aria-pressed` SSR on theme-toggle (P0-4)
|
||||
|
||||
**Source:** code-reviewer-260515 → P0-4.
|
||||
|
||||
**Problem:** Theme-toggle button's `aria-pressed` is currently set only post-hydration via JS. Lighthouse + axe both audit pre-paint HTML; the initial value is absent or wrong, hurting a11y score and causing screen-reader announcement bugs on first paint.
|
||||
|
||||
**Fix:** Set `aria-pressed` in SSR HTML. The inline theme-flash script (runs before paint, before main JS hydrates) must:
|
||||
1. Read stored theme + system preference
|
||||
2. Apply `data-theme` to `<html>` (existing)
|
||||
3. **NEW:** Find `[data-toggle-theme]` button and set `aria-pressed="true"` if dark, `"false"` if light, before paint
|
||||
|
||||
Verify the inline script runs early enough that the button's initial paint already has the correct attribute.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `layouts/_partials/head.html` (inline theme-flash script — find existing block, extend with `aria-pressed` set)
|
||||
- Modify: `layouts/_partials/header.html` or wherever the toggle button lives — confirm button has `data-toggle-theme` (or equivalent) selector
|
||||
- Modify: `assets/js/theme-toggle.js` (or whichever file) — ensure click handler keeps `aria-pressed` in sync with `data-theme`
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] `aria-pressed` present in initial server-rendered HTML (verify via `curl | grep aria-pressed`)
|
||||
- [ ] Value matches actual paint theme (light→`false`, dark→`true`)
|
||||
- [ ] Click handler keeps attr in sync post-hydration
|
||||
|
||||
### A4.3 — Darken `--tsuki-fg-subtle` light-mode (P2-8) [VISUAL DIFF — confirm with maintainer]
|
||||
|
||||
**Source:** code-reviewer-260515 → P2-8. See plan.md unresolved Q10.
|
||||
|
||||
**Problem:** Current `--tsuki-fg-subtle` light-mode value `#888` measures 3.54:1 against light bg — fails WCAG AA (≥4.5:1 for normal text).
|
||||
|
||||
**Fix:** Recommendation `#6b6b6b` (~5:1). Apply in `assets/css/tokens.css` light-mode block. **Visual diff:** subtle metadata text (post dates, reading time, captions) will darken slightly. Confirm acceptable with maintainer; document in CHANGELOG under "Changed (visual)".
|
||||
|
||||
**Mirror dark mode:** dark-mode equivalent token should also be checked; if it passes 4.5:1 already, leave alone, else adjust. Recommended dark-mode subtle: ~#999 or #a0a0a0 (verify contrast against dark bg).
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `assets/css/tokens.css`
|
||||
- Modify: `CHANGELOG.md` — note under "Changed (visual)" since adopters with custom CSS reading the token will see a diff
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] `--tsuki-fg-subtle` ≥4.5:1 contrast in both light and dark themes
|
||||
- [ ] Demo build screenshots pre/post show acceptable visual diff
|
||||
- [ ] CHANGELOG documents visual change
|
||||
|
||||
### A4.4 — Pagination disabled-state contrast (P2-9)
|
||||
|
||||
**Source:** code-reviewer-260515 → P2-9.
|
||||
|
||||
**Problem:** Pagination disabled prev/next links use `opacity: 0.5` compound with `--tsuki-fg-muted`, breaking contrast.
|
||||
|
||||
**Fix:** Remove the `opacity: 0.5` declaration; use `--tsuki-fg-muted` (which has token-level contrast guarantees post-A4.3) as the disabled color directly. Add `aria-disabled="true"` instead of using opacity-as-state-signal.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `assets/css/pagination.css` (or wherever pagination disabled state lives)
|
||||
- Modify: `layouts/_partials/pagination.html` — add `aria-disabled` when disabled
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] Pagination disabled state ≥4.5:1 contrast
|
||||
- [ ] No `opacity` on disabled links
|
||||
- [ ] `aria-disabled="true"` set when not actionable
|
||||
|
||||
### A4.5 — theme-color meta with light/dark variants (P2-15)
|
||||
|
||||
**Source:** code-reviewer-260515 → P2-15.
|
||||
|
||||
**Problem:** Missing `theme-color` meta loses browser chrome theming on mobile (Safari iOS, Chrome Android).
|
||||
|
||||
**Fix:** Add to `layouts/_partials/head.html`:
|
||||
|
||||
```html
|
||||
<meta name="theme-color" content="{{ light-bg-token }}" media="(prefers-color-scheme: light)">
|
||||
<meta name="theme-color" content="{{ dark-bg-token }}" media="(prefers-color-scheme: dark)">
|
||||
```
|
||||
|
||||
Pull hex values from `--tsuki-bg` resolved per theme (or hard-code matching tokens.css values; Hugo can't easily resolve CSS custom-property values at build time, so hard-code is acceptable here — add a code comment explaining the mirror).
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `layouts/_partials/head.html`
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] Two `theme-color` meta tags present
|
||||
- [ ] Values match tokens.css bg values
|
||||
|
||||
### A4.6 — `<html lang>` fallback from "vi" to site language (P2-16)
|
||||
|
||||
**Source:** code-reviewer-260515 → P2-16. See plan.md unresolved Q11.
|
||||
|
||||
**Problem:** `<html lang="vi">` is likely hard-coded somewhere (baseof.html or head.html). Theme should default to `site.Language.Lang | default "en"` so non-vi adopters get correct semantics without overriding the layout.
|
||||
|
||||
**Fix:** Find the hard-coded `lang="vi"`, replace with `{{ site.Language.Lang | default "en" }}`.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `layouts/_default/baseof.html` (most likely location)
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] No `lang="vi"` hard-code remains
|
||||
- [ ] Demo site (vi-default) still renders `lang="vi"`
|
||||
- [ ] Theme used with `defaultContentLanguage: en` renders `lang="en"`
|
||||
|
||||
### A4.7 — Full Lighthouse ≥80 baseline measurement
|
||||
|
||||
**Source:** project goal; code-reviewer audit framing.
|
||||
|
||||
**Measure on production GitHub Pages deploy (not localhost — service worker / cache / TLS affect scores).** Run Lighthouse on 4 page types:
|
||||
- Home (`/`)
|
||||
- Post (sample post permalink)
|
||||
- List (e.g., `/post/` or a tag page)
|
||||
- Search (`/search/`)
|
||||
|
||||
Per-category targets:
|
||||
- Performance ≥80
|
||||
- Accessibility ≥95 (tighter than ≥80 goal)
|
||||
- Best Practices ≥80
|
||||
- SEO ≥80
|
||||
|
||||
Document numbers in `docs/accessibility.md` and a new `docs/performance.md` (or expand accessibility.md with a "Lighthouse baseline" section). Note: scores are non-deterministic; record best-of-3 runs per page.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `docs/accessibility.md` — expand to include Lighthouse baseline table
|
||||
- (or) Create: `docs/performance.md` — Lighthouse table + how-to-measure
|
||||
|
||||
**Success criteria additions (override original):**
|
||||
- [ ] Lighthouse Performance ≥80 on home + post
|
||||
- [ ] Lighthouse Accessibility ≥95 on home + post + list + search
|
||||
- [ ] Lighthouse Best Practices ≥80 on home + post
|
||||
- [ ] Lighthouse SEO ≥80 on home + post
|
||||
- [ ] Baseline table in docs/
|
||||
|
||||
### Effort delta
|
||||
|
||||
Phase 4 effort 1d → 1.5d. Extra 0.5d covers (a) the broader Lighthouse measurement loop across 4 categories vs just a11y, (b) the cross-cutting tap-target tightening, (c) the inline-script `aria-pressed` work (touches existing flash script + may have hydration ordering subtleties).
|
||||
|
||||
### Implementer notes
|
||||
|
||||
- Per project rules: do **not** reference "P0-3", "P0-4", "P2-8", etc. in code comments, CSS class names, or commit messages. Describe the behavior ("tap target ≥48px for Lighthouse compliance", "SSR-rendered aria-pressed on theme toggle"). Plan artifacts stay in this doc and PR description only.
|
||||
- `--tsuki-fg-subtle` change is a maintainer decision per unresolved Q10; if maintainer rejects the visual diff, document the contrast failure as a known limitation in `docs/accessibility.md` (and accept reduced Lighthouse a11y score).
|
||||
- `aria-pressed` SSR change must not break adopters who override `head.html`; document the inline-script requirement in `docs/customization.md`.
|
||||
@@ -1,126 +0,0 @@
|
||||
---
|
||||
phase: 5
|
||||
title: "AI/discovery — llm.txt + Speculation Rules"
|
||||
status: completed
|
||||
priority: P2
|
||||
effort: "0.5d"
|
||||
dependencies: [2]
|
||||
completed_date: 2026-05-15
|
||||
---
|
||||
|
||||
# Phase 5: AI/discovery
|
||||
|
||||
## Overview
|
||||
|
||||
Two additive 2026-platform features: (1) auto-generated `/llm.txt` artifact in exampleSite to guide AI crawler indexing per the emerging llmstxt.org spec; (2) optional Speculation Rules opt-in via `params.prefetch.enable` for Chromium-based prefetch/prerender of internal links.
|
||||
|
||||
## Context Links
|
||||
|
||||
- Source: `plans/reports/researcher-260510-0144-hugo-theme-2026-evolution.md` (Tier 1: llm.txt, Speculation Rules)
|
||||
- Spec: https://llmstxt.org (llm.txt format)
|
||||
- Spec: https://wicg.github.io/nav-speculation/speculation-rules.html
|
||||
|
||||
## Requirements
|
||||
|
||||
- Functional: `exampleSite/public/llm.txt` exists post-build with theme metadata; Speculation Rules emit only when `params.prefetch.enable: true`
|
||||
- Non-functional: zero JS additions; no CSS additions; backwards compatible (both off by default)
|
||||
|
||||
## Key Insights
|
||||
|
||||
- llm.txt is a static text file derived from `data/profile.yaml` + theme metadata + recent posts. Hugo can generate it via custom output format.
|
||||
- Speculation Rules ship as `<script type="speculationrules">{...}</script>` in `<head>`. Chromium-only. Graceful no-op on Safari/Firefox.
|
||||
- Both features should be **opt-in** to respect users on metered connections / privacy-conscious AI policy.
|
||||
|
||||
## Architecture
|
||||
|
||||
### llm.txt
|
||||
- Add `[outputFormats.LlmTxt]` + `[mediaTypes."text/plain"]` to demo `hugo.yaml`
|
||||
- Add `outputs.home: ["HTML", "RSS", "LlmTxt"]` to demo `hugo.yaml`
|
||||
- Create `layouts/index.llmtxt.txt` — Hugo template emitting plain text per llmstxt.org spec
|
||||
- Theme exposes default; site can override with own `index.llmtxt.txt`
|
||||
|
||||
### Speculation Rules
|
||||
- Gated in `head.html`: `{{ with site.Params.prefetch }}{{ if .enable }}<script type="speculationrules">{...JSON...}</script>{{ end }}{{ end }}`
|
||||
- Default JSON: `{"prefetch":[{"source":"document","where":{"and":[{"href_matches":"/*"},{"not":{"href_matches":"/search/*"}}]},"eagerness":"moderate"}]}`
|
||||
- Allow override via `params.prefetch.rules` (raw JSON string consumer can inject)
|
||||
|
||||
## Related Code Files
|
||||
|
||||
- Create: `layouts/index.llmtxt.txt` (in theme, optional override)
|
||||
- Modify: `exampleSite/hugo.yaml` (output format + outputs.home)
|
||||
- Modify: `layouts/_partials/head.html` (Speculation Rules emit gate)
|
||||
- Modify: `docs/config.md` (document `params.prefetch.{enable,rules}`)
|
||||
- Modify: `docs/customization.md` (document llm.txt override path)
|
||||
- Modify: `CHANGELOG.md`
|
||||
- Modify: `scripts/smoke-tests.sh` (assert llm.txt present + speculationrules script absent by default)
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. Define output format in demo `hugo.yaml`:
|
||||
```yaml
|
||||
outputFormats:
|
||||
LlmTxt:
|
||||
mediaType: "text/plain"
|
||||
baseName: "llm"
|
||||
isPlainText: true
|
||||
outputs:
|
||||
home: ["HTML", "RSS", "LlmTxt"]
|
||||
```
|
||||
2. Write `layouts/index.llmtxt.txt`:
|
||||
- `# {{ site.Title }}` + tagline from `data/profile.yaml`
|
||||
- `> {{ .Site.Params.description }}`
|
||||
- `## About` block from `data/profile.yaml: bio`
|
||||
- `## Recent posts` — top 10 `site.RegularPages | first 10`, each as `- [{{ .Title }}]({{ .Permalink }}): {{ .Description | default .Summary | plainify }}`
|
||||
- `## Projects` from `data/projects.yaml`
|
||||
3. Build demo, confirm `exampleSite/public/llm.txt` exists and is valid plain text.
|
||||
4. Add Speculation Rules emit in `head.html` gated on `params.prefetch.enable`. Write minimal default JSON + allow `params.prefetch.rules` raw string override.
|
||||
5. Add `params.prefetch` block to `docs/config.md` with example + browser-support note.
|
||||
6. Local test: enable in demo `hugo.yaml`, confirm `<script type="speculationrules">` in HTML. Disable, confirm absent.
|
||||
7. Smoke test additions: assert `exampleSite/public/llm.txt` exists; assert NO `speculationrules` in default demo build (since opt-in).
|
||||
8. CHANGELOG: Added — llm.txt output format, Speculation Rules opt-in.
|
||||
|
||||
## Todo List
|
||||
|
||||
- [ ] Output format declared in demo hugo.yaml
|
||||
- [ ] layouts/index.llmtxt.txt template written
|
||||
- [ ] Demo build emits valid /llm.txt
|
||||
- [ ] Speculation Rules gated emit in head.html
|
||||
- [ ] params.prefetch documented in config.md
|
||||
- [ ] llm.txt override documented in customization.md
|
||||
- [ ] Smoke test assertions added
|
||||
- [ ] CHANGELOG entries
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] `curl https://tiennm99.github.io/tsuki/llm.txt` returns 200 + valid text on next deploy
|
||||
- [ ] `<script type="speculationrules">` absent from default build
|
||||
- [ ] `<script type="speculationrules">` present when `params.prefetch.enable: true` set in demo
|
||||
- [ ] No CSS or JS bundle increase
|
||||
- [ ] Documentation describes consumer override paths
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **llm.txt spec churn:** llmstxt.org is unstable as of 2026. Mitigation: stay close to the minimal sketch; consumers with strong preferences can override `index.llmtxt.txt`.
|
||||
- **Speculation Rules misfire:** prefetch on metered networks. Mitigation: opt-in default off; document responsibly.
|
||||
- **AI policy concerns:** maintainers may not want their content easily indexed by AI. Mitigation: llm.txt is standard *guidance*, not directive; consumers can write their own block list.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- llm.txt exposes only already-public content (titles, summaries)
|
||||
- Speculation Rules use `eagerness: moderate` (not `eager`) to balance perf vs bandwidth
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Phase 6 smoke tests assert both features behave per gate
|
||||
|
||||
## Added in audit pass (2026-05-15)
|
||||
|
||||
No new sub-tasks land here. Decision recorded:
|
||||
|
||||
### A5.1 — Language switcher UI placement: Phase 3, NOT Phase 5
|
||||
|
||||
**Source:** researcher-260515-tsuki-vs-stack-papermod-feature-gap.md → Tier B item #7 (placement question).
|
||||
|
||||
**Decision:** Language switcher lands in Phase 3 (Author UX). Rationale: it's a UX surface, not an AI-discovery / platform feature. Phase 5 stays scoped to llm.txt + Speculation Rules (machine-readable surfaces). Pairing the switcher with en.yml completion in Phase 3 is also cheaper — same i18n keys, same header partial pass.
|
||||
|
||||
No file edits in Phase 5 from this decision. See Phase 3 section A3.4 for the switcher implementation.
|
||||
@@ -1,205 +0,0 @@
|
||||
---
|
||||
phase: 6
|
||||
title: "Smoke-test expansion + Hugo CI matrix"
|
||||
status: completed
|
||||
priority: P1
|
||||
effort: "0.5d"
|
||||
dependencies: [1, 2, 3, 4, 5]
|
||||
completed_date: 2026-05-15
|
||||
notes: "Synthetic test posts (lastmod-test, no-tags-test) and Lighthouse-CI workflow deferred to v0.3.1 (optional)."
|
||||
---
|
||||
|
||||
# Phase 6: Smoke-test expansion + Hugo CI matrix
|
||||
|
||||
## Overview
|
||||
|
||||
Lock the v0.3.0 surface in by extending `scripts/smoke-tests.sh` with ~10 new assertions targeting branches not currently covered (callouts, JSON-LD validity, dark theme, render-hook output, code-copy class) and adding a Hugo version matrix (floor 0.146 vs current 0.154) so theme contract drift is caught early.
|
||||
|
||||
## Context Links
|
||||
|
||||
- Source: `plans/reports/code-reviewer-260510-0144-tsuki-v0.2.0-post-release-improvements.md` (P3-1, P3-2, P3-11)
|
||||
|
||||
## Requirements
|
||||
|
||||
- Functional: every new assertion catches a *specific* regression (not generic structural)
|
||||
- Non-functional: total CI runtime ≤ 5 min on matrix; no flaky checks
|
||||
|
||||
## Key Insights
|
||||
|
||||
- Current 11 smoke checks are structural (header presence, generator meta, byline) — they pass even when a render hook is broken
|
||||
- jq is available in GitHub Actions ubuntu-latest; can validate JSON-LD inline
|
||||
- Hugo CI matrix: 0.146 (theme.toml floor) + 0.154 (current pinned). If 0.146 fails on a feature, decision: bump floor or work around
|
||||
- Phase 3 demo post (`render-hooks-demo`) gives stable target for callout/details assertions
|
||||
|
||||
## Architecture
|
||||
|
||||
### Smoke-test additions
|
||||
|
||||
```bash
|
||||
assert_callout() # post HTML contains <div class="callout callout-note">
|
||||
assert_jsonld_valid() # extract JSON-LD with awk, pipe through jq -e empty
|
||||
assert_og_image_abs() # og:image content matches https?:// (not relative)
|
||||
assert_dark_theme() # css bundle contains [data-theme="dark"] OR prefers-color-scheme: dark
|
||||
assert_render_link() # external link has rel="noopener noreferrer", internal does not
|
||||
assert_code_copy_css() # css bundle contains .code-copy class
|
||||
assert_skip_link() # already exists, verify it asserts visible focus path
|
||||
assert_details() # post HTML contains <details> with styled border in CSS
|
||||
assert_llm_txt() # exampleSite/public/llm.txt exists
|
||||
assert_no_speculation_default() # speculationrules absent in default build
|
||||
assert_per_kind_css_budget() # each kind ≤ 4096 B gz
|
||||
```
|
||||
|
||||
### CI matrix
|
||||
|
||||
```yaml
|
||||
strategy:
|
||||
matrix:
|
||||
hugo: ["0.146.0", "0.154.0"]
|
||||
```
|
||||
|
||||
`pages.yml` builds + smokes + htmltests under each. Deploy step runs only on 0.154 (current).
|
||||
|
||||
## Related Code Files
|
||||
|
||||
- Modify: `scripts/smoke-tests.sh` (~10 new assertions, ~80 lines added)
|
||||
- Modify: `.github/workflows/pages.yml` (matrix strategy on build + smoke + htmltest)
|
||||
- Modify: `theme.toml` (decide on `min_version` per Q2 unresolved; bump if 0.146 untenable)
|
||||
- Add: `exampleSite/content/post/lastmod-test.md` (synthetic post with future Lastmod ≥ 24h, exercises meta.html branch)
|
||||
- Add: `exampleSite/content/post/no-tags-test.md` (synthetic post with no tags, exercises meta.html / related-posts branch)
|
||||
- Modify: `CHANGELOG.md`
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. Inventory current `scripts/smoke-tests.sh`: list 11 existing assertions, identify which Phase 1–5 changes need new coverage.
|
||||
2. Add jq to CI workflow (`apt-get install -y jq` or use built-in ubuntu-latest jq).
|
||||
3. Write new assertions one by one, running locally after each:
|
||||
- **callout** — grep `class="callout callout-note"` on `render-hooks-demo` page
|
||||
- **jsonld_valid** — extract `<script type="application/ld+json">...</script>` block, pipe through `jq -e empty`
|
||||
- **og_image_abs** — regex: `<meta property="og:image" content="https?://[^"]+"`
|
||||
- **dark_theme** — grep CSS bundle for `data-theme="dark"` or `(prefers-color-scheme: dark)`
|
||||
- **render_link_rel** — find a known external link in demo post, assert `rel="noopener noreferrer"` on it
|
||||
- **code_copy_css** — grep `.code-copy` in CSS bundle
|
||||
- **details** — grep `<details>` on demo post, grep CSS for `details {` rule
|
||||
- **llm.txt** — `[ -f exampleSite/public/llm.txt ]`
|
||||
- **no_speculation_default** — `! grep speculationrules exampleSite/public/index.html`
|
||||
- **per_kind_css_budget** — loop over [home, post, list, search]; for each, gzip the linked CSS bundles, sum sizes, assert ≤ 4096
|
||||
4. Add synthetic test posts for branches not covered by demo content:
|
||||
- `lastmod-test.md` with `lastmod: 2099-01-01` to fire Lastmod byline
|
||||
- `no-tags-test.md` with `tags: []` to exercise empty-tags branch + no-related-posts branch
|
||||
5. Update `pages.yml` with matrix on `hugo` versions. Build, smoke, htmltest in each. Deploy gated on `matrix.hugo == '0.154.0'`.
|
||||
6. Run on temp branch, observe both matrix legs green. If 0.146 fails: triage. Decision per Q2: bump floor or document the 0.146 limitation.
|
||||
7. CHANGELOG entry under Added: 10+ new smoke assertions + Hugo CI matrix.
|
||||
|
||||
## Todo List
|
||||
|
||||
- [ ] Inventory existing assertions
|
||||
- [ ] jq added to CI environment
|
||||
- [ ] callout assertion
|
||||
- [ ] jsonld_valid assertion
|
||||
- [ ] og_image_abs assertion
|
||||
- [ ] dark_theme assertion
|
||||
- [ ] render_link_rel assertion
|
||||
- [ ] code_copy_css assertion
|
||||
- [ ] details assertion
|
||||
- [ ] llm.txt assertion
|
||||
- [ ] no_speculation_default assertion
|
||||
- [ ] per_kind_css_budget assertion
|
||||
- [ ] lastmod-test.md synthetic post
|
||||
- [ ] no-tags-test.md synthetic post
|
||||
- [ ] Hugo matrix in pages.yml
|
||||
- [ ] Both matrix legs green
|
||||
- [ ] CHANGELOG entries
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] 21 total smoke assertions (11 existing + 10 new), all pass on demo build
|
||||
- [ ] CI runs Hugo 0.146 + 0.154; both legs green or theme.toml floor adjusted with rationale
|
||||
- [ ] Synthetic posts exercise branches not previously covered
|
||||
- [ ] CI runtime ≤ 5 min including matrix
|
||||
- [ ] No flaky checks (run CI 3× to confirm)
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **0.146 fails, 0.154 succeeds:** decision blocker per Q2. Mitigation: gather diff, decide floor bump or workaround within phase budget.
|
||||
- **jq parse errors on legitimate JSON-LD:** Hugo emits unescaped quotes in some edge cases. Mitigation: pre-process with `awk` to extract block; jq operates on extracted string only.
|
||||
- **CI matrix doubles minutes:** GitHub Actions free tier has limits. Mitigation: free repos have ample minutes; tsuki is OSS.
|
||||
- **Synthetic test posts surface in production:** they'd appear in demo blog index. Mitigation: `headless: true` in their frontmatter so they don't list.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
None — test/CI only.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- v0.3.0 tag candidate post-Phase-6
|
||||
- Subsequent: gohugoThemes registry CI green check (carry from v0.2.0 prereq)
|
||||
- Then: tag, release notes, gallery PR
|
||||
|
||||
## Added in audit pass (2026-05-15)
|
||||
|
||||
New smoke assertions lock in the Lighthouse-audit-driven surface (Phases 2–4 additions) so regressions surface in CI rather than in the next Lighthouse run.
|
||||
|
||||
### A6.1 — Additional smoke assertions
|
||||
|
||||
**Source:** code-reviewer-260515-lighthouse-80-baseline-audit.md → Phase 6 recommendations.
|
||||
|
||||
Add to `scripts/smoke-tests.sh`:
|
||||
|
||||
```bash
|
||||
assert_aria_pressed_ssr() # post HTML contains aria-pressed on theme-toggle button
|
||||
assert_giscus_preconnect() # post page with comments enabled has <link rel="preconnect" href="https://giscus.app">
|
||||
assert_no_giscus_preconnect_home() # home HTML lacks the giscus preconnect
|
||||
assert_tap_target_css() # CSS bundle contains min-height: 2.75rem (or ≥48px equiv) on pagination/toggle classes
|
||||
assert_pagefind_preload_swap() # search page HTML contains rel="preload" as="style" + onload swap for pagefind-ui.css
|
||||
assert_theme_color_meta() # head HTML contains two <meta name="theme-color"> tags with media= attrs
|
||||
assert_html_lang_not_hardcoded() # `<html lang="vi">` only when site lang is vi; test demo build with `defaultContentLanguage: en` produces `<html lang="en">`
|
||||
assert_breadcrumbs_jsonld() # post HTML (when breadcrumbs enabled in demo) contains valid BreadcrumbList JSON-LD (jq parse)
|
||||
assert_prev_next_rel() # post HTML contains rel="prev" and/or rel="next" anchors
|
||||
assert_lang_switcher_gated() # single-language demo site: no lang switcher in header; multilingual: present
|
||||
assert_hreflang_emit() # head HTML on multilingual build contains rel="alternate" hreflang
|
||||
```
|
||||
|
||||
**Total additions:** ~10 new assertions on top of the prior 10 in this phase, bringing total to ~30 smoke checks (was 11 baseline + 10 prior phase additions + 10 audit-pass additions).
|
||||
|
||||
### A6.2 — Optional: Lighthouse-CI 4 runs on tag
|
||||
|
||||
**Source:** code-reviewer-260515 → flagged "nice-to-have given CI cost".
|
||||
|
||||
Add a GitHub Action workflow `.github/workflows/lighthouse.yml` triggered on `tag` push. Runs `treosh/lighthouse-ci-action` against 4 URLs (home, sample post, sample list, /search/). Fails the tag publish if any category drops below threshold:
|
||||
- Performance ≥80
|
||||
- Accessibility ≥95
|
||||
- Best Practices ≥80
|
||||
- SEO ≥80
|
||||
|
||||
**Defer-or-ship decision:** add to Phase 6 but mark `optional: true`. Cost is ~3 min CI per tag (cheap on a low-tag-frequency theme repo). Recommendation: ship; the lock-in value of a CI gate on Lighthouse is high relative to the cost.
|
||||
|
||||
**If shipped:**
|
||||
- Create: `.github/workflows/lighthouse.yml`
|
||||
- Modify: `docs/accessibility.md` — note the CI gate
|
||||
|
||||
**If deferred to v0.3.1:**
|
||||
- Add note to plan.md unresolved Q14 outcome
|
||||
- Phase 6 stays as-is
|
||||
|
||||
### Files modified (cumulative for audit pass)
|
||||
|
||||
- Modify: `scripts/smoke-tests.sh` (~10 additional assertions, ~70 more lines)
|
||||
- Optional: Create `.github/workflows/lighthouse.yml`
|
||||
- Modify: `CHANGELOG.md` — note CI smoke expansion
|
||||
|
||||
### Success criteria additions
|
||||
|
||||
- [ ] ~30 total smoke assertions, all pass on demo build
|
||||
- [ ] aria-pressed assertion catches regression of theme-toggle SSR
|
||||
- [ ] giscus preconnect assertion fires on/off correctly per page kind + config
|
||||
- [ ] tap-target CSS assertion catches regression on pagination/toggle
|
||||
- [ ] Pagefind preload-swap pattern detected on `/search/`
|
||||
- [ ] theme-color meta tag count = 2
|
||||
- [ ] hreflang/lang-switcher gating verified on multilingual demo
|
||||
- [ ] (Optional) Lighthouse-CI workflow fails if any score drops below threshold
|
||||
|
||||
### Implementer notes
|
||||
|
||||
- Per project rules: smoke-test function names must describe behavior, NOT cite plan/audit labels. E.g., use `assert_aria_pressed_ssr` (good) NOT `assert_P0_4_aria_pressed` (bad). Same rule for shell variables, comments, commit messages, workflow names. Plan codes (P0-X, A6.X) stay in this document only.
|
||||
- Multilingual smoke assertions need a temp demo branch with a second language file populated; or a `--config exampleSite/hugo.multilang.yaml` fixture. Keep simple: a single fixture file that adds `en` as a secondary language for assertion runs, gated behind a flag in `scripts/smoke-tests.sh`.
|
||||
- If Lighthouse-CI workflow is shipped: pin action SHA per project security rule (no `@v10` floating tag).
|
||||
@@ -1,153 +0,0 @@
|
||||
---
|
||||
title: tsuki v0.3.0 — review fixes carry, budget rebase, a11y 2.2, AI discovery, Lighthouse ≥80
|
||||
status: completed
|
||||
created: 2026-05-10
|
||||
amended: 2026-05-15
|
||||
completed_date: 2026-05-15
|
||||
target: v0.3.0 tag, ~6 days effort (5d if v0.2.1 shipped + Phase 1 is no-op; +1d from audit-pass additions)
|
||||
predecessor: plans/260510-0232-tsuki-v0.2.1-patch/
|
||||
blockedBy: [260509-0947-v0.2.0-prerelease-checklist, 260510-0232-tsuki-v0.2.1-patch]
|
||||
source_brainstorm: plans/reports/brainstorm-260510-0144-post-v0.2.0-direction.md
|
||||
source_reports:
|
||||
- plans/reports/code-reviewer-260510-0144-tsuki-v0.2.0-post-release-improvements.md
|
||||
- plans/reports/researcher-260510-0144-hugo-theme-2026-evolution.md
|
||||
- plans/reports/project-manager-260510-0144-tsuki-v0.2.0-status.md
|
||||
- plans/reports/researcher-260515-tsuki-vs-stack-papermod-feature-gap.md
|
||||
- plans/reports/code-reviewer-260515-lighthouse-80-baseline-audit.md
|
||||
---
|
||||
|
||||
# tsuki v0.3.0 plan
|
||||
|
||||
Carries forward the post-v0.2.0 review P1s (conditional on whether maintainer ships a v0.2.1 patch first), rebases the CSS/JS budget to free headroom, layers WCAG 2.2 AA + AI-discovery features, lands Tier A feature-parity polish (breadcrumbs, prev/next, code-copy UI, language switcher), then expands smoke-test depth to lock the surface in.
|
||||
|
||||
## Goal
|
||||
|
||||
Ship v0.3.0 with two measurable, observable outcomes:
|
||||
|
||||
1. **Lighthouse ≥80 on all 4 categories (Performance, Accessibility, Best Practices, SEO) — target ≥95 on Accessibility specifically — measured against exampleSite on production GitHub Pages deploy.**
|
||||
2. **Feature parity with Stack/PaperMod on Tier A polish: breadcrumbs (with schema.org BreadcrumbList), prev/next post nav, code-copy button UI, language switcher UI.**
|
||||
|
||||
All additions respect the hard CSS ≤4 KB gz / JS ≤1 KB gz budget and the zero-build-step constraint.
|
||||
|
||||
## Phases
|
||||
|
||||
| # | Phase | Priority | Status | Depends on | Effort |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | [v0.2.1 carry — review P1s + CI hygiene](phase-01-v0.2.1-carry.md) | P1 | completed | v0.2.0 tagged | 1d |
|
||||
| 2 | [Theme-budget rebase](phase-02-budget-rebase.md) | P1 | completed | Phase 1 | 1d |
|
||||
| 3 | [Author UX + Tier A parity](phase-03-author-ux.md) | P2 | completed | Phase 2 (CSS bundle layout) | 2d |
|
||||
| 4 | [WCAG 2.2 AA audit + Lighthouse ≥80 baseline](phase-04-wcag-2.2-audit.md) | P2 | completed | Phase 3 (audit covers new surface) | 1.5d |
|
||||
| 5 | [AI/discovery — llm.txt + Speculation Rules](phase-05-ai-discovery.md) | P2 | completed | Phase 2 (budget headroom) | 0.5d |
|
||||
| 6 | [Smoke-test expansion + Hugo CI matrix](phase-06-test-depth.md) | P1 | completed | Phases 1–5 | 0.5d |
|
||||
|
||||
## Sequencing
|
||||
|
||||
- **Phase 1 conditional:** if v0.2.1 patch ships independently, drop Phase 1 from v0.3.0 scope. Otherwise carry forward — these P1s must not ship under a "v0.3.0 features" banner without being acknowledged.
|
||||
- **Phase 2 gates 3+5:** per-kind CSS bundling frees ~1.2 KB gz; without it, Phase 5 Speculation Rules + Phase 3 details CSS + Tier A parity (breadcrumbs/prev-next/code-copy) may breach the 4 KB gz budget.
|
||||
- **Phases 3 + 5 may run parallel** after Phase 2 — different files, no shared CSS partial. Phase 3 grew substantially with Tier A parity additions; budget headroom from Phase 2 is critical.
|
||||
- **Phase 4 last before Phase 6:** WCAG audit catches regressions from Phases 1–3 changes; Lighthouse ≥80 baseline measured against the full Phase 3 surface; Phase 6 then locks into smoke tests.
|
||||
- **Phase 6 lands last:** smoke tests assert the actual shipped surface, not in-flight branches.
|
||||
|
||||
## Audit-pass integration map (2026-05-15)
|
||||
|
||||
Quick reference: where each new audit finding lands.
|
||||
|
||||
| Finding | Source | Lands in |
|
||||
|---|---|---|
|
||||
| P0-1 cover-image override docs (defer renderer to v0.4.0) | Lighthouse audit | Phase 3 (docs/customization.md note) |
|
||||
| P0-2 Pagefind UI CSS preload swap | Lighthouse audit | Phase 2 (search/list.html) |
|
||||
| P0-3 tap-targets ≥48×48 (Lighthouse tighter than WCAG 24×24) | Lighthouse audit | Phase 4 |
|
||||
| P0-4 `aria-pressed` SSR on theme-toggle | Lighthouse audit | Phase 4 (inline flash script) |
|
||||
| P1-5 conditional preconnect to giscus.app | Lighthouse audit | Phase 2 (head.html) |
|
||||
| P1-6 hreflang alternate links | Lighthouse audit | Phase 3 (head.html, gated on `site.IsMultiLingual`) |
|
||||
| P2-8 darken `--tsuki-fg-subtle` (AA contrast) | Lighthouse audit | Phase 4 (tokens.css) |
|
||||
| P2-9 pagination disabled-state contrast | Lighthouse audit | Phase 4 |
|
||||
| P2-15 theme-color meta light/dark variants | Lighthouse audit | Phase 4 |
|
||||
| P2-16 `<html lang>` fallback to site language | Lighthouse audit | Phase 4 |
|
||||
| Tier A: breadcrumbs + BreadcrumbList schema | Feature gap | Phase 3 |
|
||||
| Tier A: prev/next post nav | Feature gap | Phase 3 |
|
||||
| Tier A: code-copy button UI polish | Feature gap | Phase 3 |
|
||||
| Tier A: language switcher UI | Feature gap | Phase 3 (UX, not AI discovery → keep here, not Phase 5) |
|
||||
| render-heading aria-label i18n key | Lighthouse audit | Phase 3 (alongside en.yml work) |
|
||||
| Smoke: `aria-pressed`, giscus preconnect, tap-target CSS, Pagefind preload, theme-color | Lighthouse audit | Phase 6 |
|
||||
| Optional: 4 Lighthouse runs on tag via Action | Lighthouse audit | Phase 6 (flagged nice-to-have) |
|
||||
|
||||
**No new phase added.** Phase 3 absorbs all Tier A polish (already covers author UX surface; adjacent work is cheaper than a new phase). Phase 3 effort grew from 1d to 2d; Phase 4 from 1d to 1.5d. Total effort: 4-5d → 6d (5d if Phase 1 is no-op).
|
||||
|
||||
## Constraints
|
||||
|
||||
- CSS ≤ 4 KB gz on **every page kind** (CI-asserted; Phase 2 makes this per-kind not aggregate)
|
||||
- JS ≤ 1 KB gz site-wide (Phase 2 reduces by gating code-copy.js)
|
||||
- Zero build step (pure Hugo + browser ES modules)
|
||||
- Backwards compatible: sites on v0.2.0 must build on v0.3.0 without config changes (new params default off)
|
||||
- Vietnamese-first (vi.yml stays canonical; en.yml is a starter, not a behavioral switch)
|
||||
|
||||
## Out of scope (deferred)
|
||||
|
||||
Explicit per researcher Tier B/C + code-reviewer deferred items (do not add to v0.3.0):
|
||||
|
||||
- **Image gallery, lightbox, KaTeX, Mermaid** → v0.4.0+ or never; ≤4 KB CSS budget incompatible with these
|
||||
- **AVIF render hook + responsive srcset pipeline** → v0.4.0 (depends on `images.Resize` pipeline + cover-image feature scope decision)
|
||||
- **Default cover-image renderer** → v0.4.0 (P0-1 decision documented as override-path only in v0.3.0; see Phase 3)
|
||||
- **P2-1 SVG-logo JSON-LD issue** → defer to v0.4.0 with cover-image work (needs PNG asset path)
|
||||
- **Service worker / PWA** → Lighthouse PWA audit is informational only, no project value yet
|
||||
- **Multi-author bylines, RTL support, image-zoom-on-hover, scroll-to-top button** → v0.4.0+ pending demand signal
|
||||
- **Disqus / Utterances comment alternatives** → v0.4.0+ if user demand; document override path
|
||||
- **Custom shortcodes (tabs, columns, video)** → v0.4.0+; document pattern, ship 1-2 examples then
|
||||
- **Series / subsection routing, email newsletter signup** → out-of-scope by design
|
||||
- **pa11y CI integration** → v0.3.1 after WCAG 2.2 baseline established
|
||||
- **Lighthouse-CI GitHub Action (4 runs on tag)** → optional in Phase 6; nice-to-have, flagged for budget cost
|
||||
|
||||
## Success criteria
|
||||
|
||||
- All 5 review P1s closed (or acknowledged as already shipped in v0.2.1)
|
||||
- CSS ≤ 4 KB gz on home / single / list / taxonomy / search kinds individually
|
||||
- **Lighthouse Performance ≥ 80** on home + post (production GitHub Pages)
|
||||
- **Lighthouse Accessibility ≥ 95** on home + post + list + search (WCAG 2.2 AA)
|
||||
- **Lighthouse Best Practices ≥ 80** on home + post
|
||||
- **Lighthouse SEO ≥ 80** on home + post
|
||||
- Tier A feature parity vs Stack/PaperMod: breadcrumbs (+BreadcrumbList schema), prev/next post nav, code-copy button UI, language switcher UI all gated and documented
|
||||
- `i18n/en.yml` complete (~40 keys); theme builds with `defaultContentLanguage: en` without missing-key fallbacks
|
||||
- `<html lang>` resolves from `site.Language.Lang | default "en"` (no hard-coded "vi")
|
||||
- `hreflang` alternate links emit in `<head>` on multilingual sites
|
||||
- `theme-color` meta with light/dark variants
|
||||
- `aria-pressed` SSR-rendered on theme-toggle (set in inline flash script before paint)
|
||||
- `--tsuki-fg-subtle` passes WCAG AA contrast (≥4.5:1 against bg) in both themes
|
||||
- Pagefind UI CSS loaded preload-swap (not render-blocking)
|
||||
- Conditional `preconnect` to giscus.app on comment-enabled post pages
|
||||
- `/llm.txt` artifact present in exampleSite build output
|
||||
- Speculation Rules emit when `params.prefetch.enable: true`, absent otherwise
|
||||
- Smoke tests assert: callout HTML, JSON-LD parses (jq), OG image absolute URL, dark-theme tokens, render-link rel-on-specific-link, code-copy class in CSS bundle, aria-pressed on toggle, giscus preconnect when enabled, tap-target CSS values, Pagefind preload-swap, theme-color meta
|
||||
- CI matrix green on Hugo 0.146 (floor) + 0.154 (current)
|
||||
- gohugoThemes registry CI green on tagged commit (carry-forward from v0.2.0 prereq)
|
||||
|
||||
## Unresolved questions (maintainer decisions, do not block planning)
|
||||
|
||||
Reconciled from researcher (feature gap) + code-reviewer (Lighthouse audit) + prior plan. Deduplicated, grouped thematically.
|
||||
|
||||
### A. Scope boundaries
|
||||
|
||||
1. **Cover-image feature scope** — defer entirely to v0.4.0 (current plan recommendation) or ship minimal render-hook in v0.3.0 Phase 2? Drives AVIF + responsive srcset + P2-1 SVG-logo JSON-LD timing. *Recommendation: defer; document override path in customization.md per Phase 3.*
|
||||
2. **v0.2.1 patch** — ship it, or fold its scope into v0.3.0 Phase 1? If folded, drop the "conditional" framing on Phase 1.
|
||||
3. **Language switcher routing** — must Phase 3 ship the switcher UI, or can en.yml + hreflang land alone with switcher slipping to v0.4.0? *Recommendation: ship in Phase 3 since en.yml is half the value; switcher is small (~200 B CSS + ~100 B JS).*
|
||||
4. **Code-copy button accessibility** — hide when `navigator.clipboard` unavailable (HTTP non-localhost), or always show with fallback UI? *Recommendation: hide; smaller bundle, fewer states.*
|
||||
5. **Breadcrumbs schema** — auto-emit `BreadcrumbList` JSON-LD or markup-only? *Recommendation: schema-on; SEO win is the whole point.*
|
||||
|
||||
### B. Config + compat
|
||||
|
||||
6. **Goldmark `unsafe: true`** — keep (consumer raw-HTML compat) or drop (eliminates bio-XSS surface + reduces P1-1 blast radius)? Test on real sites: `grep -r '<' content/post/*/index.md`. Affects Phase 1 fix shape.
|
||||
7. **Hugo version floor** — bump `theme.toml min_version` to 0.154 (CI-tested, narrower compat) or keep 0.146 (broader compat, untested)? Affects Phase 6 CI matrix decision.
|
||||
8. **`data/profile.yaml: url`** — add to documented schema (Phase 1 P1-2 fix), or remove the read in `seo.html`? Schema vs. minimalism trade-off.
|
||||
9. **`en.yml` as canonical baseline?** — Phase 3 ships en.yml as a starter; should it become canonical (English-first) with vi.yml as overlay, or stay Vietnamese-first? *Recommendation: stay vi-canonical for v0.3.0; revisit if audience signal shifts.*
|
||||
|
||||
### C. Visual / token decisions (impact: light-mode visual diff)
|
||||
|
||||
10. **`--tsuki-fg-subtle` light-mode value** — currently #888 (3.54:1, fails AA). P2-8 recommends #6b6b6b (~5:1). Confirm visual acceptable, then mirror to dark-mode equivalent. *Recommendation: ship #6b6b6b, document in CHANGELOG under "Changed (visual diff)".*
|
||||
11. **`<html lang>` default fallback** — replace hard-coded "vi" with `site.Language.Lang | default "en"`. Site-level config wins anyway; this only changes the fallback when `Site.Language.Lang` is empty. *Recommendation: "en" — more sensible default for a theme.*
|
||||
|
||||
### D. Operations / observability
|
||||
|
||||
12. **Audience signal** — solo bloggers vs teams? Drives whether multi-author / multi-language i18n moves out of deferred for v0.4.0. No code change for v0.3.0.
|
||||
13. **Demo site analytics** — opt-in privacy-respecting analytics on `tiennm99.github.io/tsuki/` (e.g., GoatCounter)? Currently flying blind on which features get used. Affects v0.3.0+ feature prioritization.
|
||||
14. **Lighthouse CI in pages.yml** — add 4-run Lighthouse Action on tag commits (home/post/list/search)? Cost: ~3 min CI per tag. *Phase 6 A6.2 leans toward shipping; if maintainer wants minimal CI cost, defer to v0.3.1. Either choice unblocks v0.3.0 tag.*
|
||||
15. **Stack/PaperMod future drift** — are competitors planning AI chat / embedded analytics that would justify expanding tsuki's shortcode ecosystem? Inform v0.4.0+ roadmap, not v0.3.0.
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
title: tsuki v0.2.1 — patch release for post-v0.2.0 review P1s
|
||||
status: code-complete
|
||||
created: 2026-05-10
|
||||
target: v0.2.1 tag, ~1d effort
|
||||
implementation_landed: 2026-05-10
|
||||
review_score: 9.7/10
|
||||
validation: "11/11 smoke tests, CSS budget 3962/4200, Hugo 0.154 build clean"
|
||||
predecessor: plans/260509-0947-v0.2.0-prerelease-checklist/
|
||||
blockedBy: [260509-0947-v0.2.0-prerelease-checklist]
|
||||
blocks: [260510-0144-tsuki-v0.3.0]
|
||||
source_brainstorm: plans/reports/brainstorm-260510-0144-post-v0.2.0-direction.md
|
||||
source_review: plans/reports/code-reviewer-260510-0144-tsuki-v0.2.0-post-release-improvements.md
|
||||
---
|
||||
|
||||
# tsuki v0.2.1 patch
|
||||
|
||||
Surgical patch closing 5 P1 correctness/security findings from the post-v0.2.0 fresh-eyes review, plus 2 CI hygiene items. ~1 day. No new features.
|
||||
|
||||
If shipped, marks v0.3.0 Phase 1 (`260510-0144-tsuki-v0.3.0/phase-01-v0.2.1-carry.md`) as completed.
|
||||
|
||||
## Scope
|
||||
|
||||
Identical to v0.3.0 Phase 1. See that phase file for detailed implementation steps, todo list, and success criteria. This plan exists to track v0.2.1 as its own release deliverable; do not duplicate the content.
|
||||
|
||||
**Reference:** `plans/260510-0144-tsuki-v0.3.0/phase-01-v0.2.1-carry.md`
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Branch from `main` post v0.2.0 tag: `git checkout -b release/v0.2.1`
|
||||
2. Apply fixes per Phase 1 implementation steps 1–9
|
||||
3. Local build + smoke test verification
|
||||
4. PR → main → merge
|
||||
5. Tag `v0.2.1` annotated, release notes from CHANGELOG `[Unreleased]` (promote to `[0.2.1]`)
|
||||
6. Mark v0.3.0 Phase 1 completed in `260510-0144-tsuki-v0.3.0/plan.md`
|
||||
|
||||
## Success criteria
|
||||
|
||||
- All 5 P1 fixes shipped (P1-1..P1-5 from review report)
|
||||
- htmltest-action pinned to commit SHA
|
||||
- Dead `if find` Pagefind branch removed
|
||||
- CI green on tagged commit
|
||||
- gohugoThemes registry submission unaffected (v0.2.0 PR continues to track v0.2.0 tag; v0.2.1 follows separately)
|
||||
|
||||
## Unresolved questions
|
||||
|
||||
1. Goldmark `unsafe: true` keep or drop — affects P1-1 fix shape. Defer per maintainer call; Phase 1 currently uses option B (drop `safeHTML` from link text, keep `unsafe: true`).
|
||||
2. `data/profile.yaml: url` — document or remove. Defer; current Phase 1 plan documents it.
|
||||
-109
@@ -1,109 +0,0 @@
|
||||
---
|
||||
phase: 1
|
||||
title: "v0.1.1 bugs & doc/code drift"
|
||||
status: completed
|
||||
completed_date: 2026-05-08
|
||||
priority: P1
|
||||
effort: "1d"
|
||||
dependencies: []
|
||||
ships_as: v0.1.1
|
||||
---
|
||||
|
||||
# Phase 1: v0.1.1 bugs & doc/code drift
|
||||
|
||||
## Context Links
|
||||
|
||||
- Audit: `plans/reports/code-reviewer-260508-2305-tsuki-v0.1.0-audit.md` — Critical + High sections
|
||||
- Researcher: `plans/reports/researcher-260508-2306-hugo-theme-best-practices.md` — § 8 Performance benchmarks
|
||||
|
||||
## Overview
|
||||
|
||||
Patch release. Resolve audit-flagged correctness bugs and doc/code drift. No new user-facing features. Goal: docs match behavior, tag URLs survive taxonomy renames, route gates work, no 404 SEO leakage, CSS budget enforced in CI.
|
||||
|
||||
## Requirements
|
||||
|
||||
**Functional**
|
||||
- `params.toc.enable` and `params.toc.minWordCount` actually gate render
|
||||
- Tag/category URLs resolve through Hugo's taxonomy graph (survive renames)
|
||||
- All template-referenced i18n keys exist in `vi.yml`
|
||||
- `params.search.enable: false` removes the route, not just the header button
|
||||
- Home page emits no `<link rel=prev/next>` to non-existent paginated paths
|
||||
- Code-copy button hidden when `navigator.clipboard` unavailable
|
||||
|
||||
**Non-functional**
|
||||
- CSS bundle ≤ 4 KB gz asserted in CI (fails build if exceeded)
|
||||
- No CHANGELOG drift after merge
|
||||
|
||||
## Architecture
|
||||
|
||||
Single-file template + asset edits, no new partials, no JS additions. CI gains one assertion step.
|
||||
|
||||
## Related Code Files
|
||||
|
||||
**Modify**
|
||||
- `layouts/single.html:28` — TOC gate
|
||||
- `layouts/_partials/footer.html:19` — JS TOC gate
|
||||
- `layouts/_partials/meta.html:16` — replace hardcoded `/tags/` with `.GetTerms`
|
||||
- `layouts/single.html:21` — same
|
||||
- `layouts/_partials/head.html:55` — drop `.IsHome` from paginator linking; gate on `gt .Paginator.TotalPages 1`
|
||||
- `layouts/search/list.html` — wrap body in `params.search.enable | default true`
|
||||
- `layouts/_partials/home/recent-posts.html:2,15` — bind `$all` once
|
||||
- `assets/js/code-copy.js:5` — early-return when `!navigator.clipboard`
|
||||
- `i18n/vi.yml` — add 8 missing keys (`comments`, `month`, `pageNotFound`, `backHome`, `featuredProjects`, `viewAll`, `searchSuggestion`, `altSearch`); remove unused `previousPage`/`nextPage` OR rename pagination call sites
|
||||
- `docs/data-schemas.md` — security note on `bio` HTML rendering (C2 docs path)
|
||||
- `.github/workflows/pages.yml` — add CSS budget assertion step
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **TOC config (C1)** — replace hardcoded 400 in `single.html` and `footer.html` with `site.Params.toc.minWordCount | default 400`; honor `site.Params.toc.enable | default true`. Per-page `Params.toc != false` still wins.
|
||||
2. **Tag URLs (C3)** — switch `meta.html` and `single.html` tag iteration to `.GetTerms "tags"` + `$term.RelPermalink` + `$term.LinkTitle`. Add same for categories if Phase 2 surfaces them.
|
||||
3. **i18n keys (H1)** — add the 8 missing keys to `vi.yml` with vi translations. For `month`, return `"Tháng {{ .Number }}"`. Audit `previousPage`/`nextPage` vs `prev`/`next` and unify.
|
||||
4. **Search gate (H2)** — wrap `search/list.html` body in `{{- if site.Params.search.enable | default true -}}` else emit a localized "search disabled" message.
|
||||
5. **Home pagination 404 (H4)** — change `head.html` paginator gate to `{{- with .Paginator -}}{{- if gt .TotalPages 1 -}} … {{- end -}}{{- end -}}` and drop `.IsHome` from the kind whitelist. Verify `home.html` doesn't call `.Paginator`.
|
||||
6. **Code-copy clipboard fallback (H5)** — at top of attach loop, `if (!navigator.clipboard) return;` before button creation.
|
||||
7. **Recent-posts double-where (H8)** — bind `$all := where (where site.RegularPages "Type" "post") "Draft" false` once; reuse for `len` check. Drop `"Draft" false` unless explicitly supporting `--buildDrafts`.
|
||||
8. **CSS budget assertion (H3)** — add CI step that gzips the fingerprinted CSS bundle and fails if > 4200 B. Use `find exampleSite/public -name 'tsuki.bundle.*.css'` then `gzip -9 -c | wc -c`.
|
||||
9. **C2 docs decision** — Maintainer answers Q1 (is `unsafe: true` required?). If no, drop `markup.goldmark.renderer.unsafe: true` from theme defaults and from docs; this kills the bio XSS surface. If yes, add a `! Security` block to `docs/data-schemas.md` near `bio` warning HTML executes.
|
||||
10. **Verify exampleSite still renders** — `cd exampleSite && hugo --gc --minify` clean.
|
||||
11. **CHANGELOG** — add `[0.1.1]` section listing each fix. Reference audit IDs in commit body.
|
||||
12. **Tag and release** — `v0.1.1` git tag.
|
||||
|
||||
## Todo
|
||||
|
||||
- [x] C1 TOC gate honors `params.toc.{enable,minWordCount}`
|
||||
- [x] C3 tag URLs use `.GetTerms`
|
||||
- [x] H1 8 missing i18n keys added; unused keys removed
|
||||
- [x] H2 `search/list.html` gated on `params.search.enable`
|
||||
- [x] H4 home Paginator no longer emits dead prev/next links
|
||||
- [x] H5 code-copy hidden when clipboard API absent
|
||||
- [x] H8 recent-posts query bound once
|
||||
- [x] H3 CSS budget asserted in CI (≤ 4200 B gz)
|
||||
- [x] C2 maintainer decision recorded; docs OR config updated
|
||||
- [x] CHANGELOG `[0.1.1]` written
|
||||
- [x] `v0.1.1` tagged
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- `cd exampleSite && hugo --gc --minify` produces a build with no broken `/tags/...` links (verify with `htmltest`)
|
||||
- Setting `params.toc.enable: false` in `exampleSite/hugo.yaml` suppresses TOC site-wide
|
||||
- Setting `params.toc.minWordCount: 99999` suppresses TOC on all current posts
|
||||
- Renaming `taxonomies: { tag: tag }` in `exampleSite/hugo.yaml` does not produce 404 tag links
|
||||
- `params.search.enable: false` returns empty `/search/` body with i18n message
|
||||
- Disabling JS or running on `http://` non-localhost: no orphan code-copy buttons
|
||||
- CI rejects a PR that pushes `tsuki.bundle.css` gzipped over 4200 B
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **CSS budget cliff**: post-minify is ~3.7-3.9 KB; 4200 B has ~250 B headroom. Risk: any Phase 2/3 CSS addition tips the budget. Mitigation: assertion catches it; if breached, audit which selectors are unused or compressible.
|
||||
- **i18n key churn**: changing `previousPage` → `prev` (or vice versa) across both templates and `vi.yml` is a textual rename, low risk if grep-driven.
|
||||
- **`.GetTerms` Vietnamese titles**: tags with diacritics (`ghi-chú`) — verify `.LinkTitle` displays diacritics correctly in browser, not the URL slug.
|
||||
- **C2 decision** — if maintainer wants `unsafe: true` removed, need to verify exampleSite posts don't use raw HTML; otherwise content breaks.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- C2 (XSS via bio) resolved by either docs warning or removing `unsafe: true`. The latter is preferred if compatible with content.
|
||||
- N5 generator meta privacy — defer to Phase 2 (low priority, doesn't ship in v0.1.1).
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ Phase 2 (parallel-safe after Phase 1 lands) — accessibility polish picks up M3, L5, M4, render hooks.
|
||||
-131
@@ -1,131 +0,0 @@
|
||||
---
|
||||
phase: 2
|
||||
title: "Accessibility & polish"
|
||||
status: completed
|
||||
completed_date: 2026-05-09
|
||||
priority: P1
|
||||
effort: "1d"
|
||||
dependencies: [1]
|
||||
---
|
||||
|
||||
# Phase 2: Accessibility & polish
|
||||
|
||||
## Context Links
|
||||
|
||||
- Audit: `plans/reports/code-reviewer-260508-2305-tsuki-v0.1.0-audit.md` — M1, M2, M3, M4, L5, N1, N2, N5
|
||||
- Researcher: `plans/reports/researcher-260508-2306-hugo-theme-best-practices.md` — § 3 SEO & a11y baseline
|
||||
|
||||
## Overview
|
||||
|
||||
Close keyboard-nav and focus-visibility gaps, fix theme-toggle/giscus first-paint flash, decide categories visibility, add render hooks for safer external links and lazy images. No layout changes; CSS additions kept inside budget.
|
||||
|
||||
## Requirements
|
||||
|
||||
**Functional**
|
||||
- Skip-link present and functional on every page
|
||||
- All interactive elements have visible focus rings in dark + light modes
|
||||
- Giscus opens with the theme already applied (no flash to default theme)
|
||||
- External markdown links open with `rel="noopener noreferrer"`
|
||||
- In-content images get `loading="lazy" decoding="async"`
|
||||
- Categories either surface in UI or are documented as routing-only
|
||||
|
||||
**Non-functional**
|
||||
- WCAG 2.1 AA contrast retained
|
||||
- Total CSS additions < 200 B gz (skip-link + focus rings)
|
||||
- No new JS bytes (giscus fix is a 1-line ordering tweak)
|
||||
|
||||
## Architecture
|
||||
|
||||
CSS-only additions in `components.css` for skip-link + `:focus-visible`. Two new render hooks (`_markup/render-link.html`, `_markup/render-image.html`). Template-level: skip-link in `baseof.html`, `id="main"` on `<main>`, generator meta change.
|
||||
|
||||
## Related Code Files
|
||||
|
||||
**Create**
|
||||
- `layouts/_markup/render-link.html`
|
||||
- `layouts/_markup/render-image.html`
|
||||
|
||||
**Modify**
|
||||
- `layouts/baseof.html` — add `<a class="skip-link">`, `id="main"` on `<main>`
|
||||
- `layouts/_partials/head.html:7` — drop `hugo.Version` from generator meta (N5)
|
||||
- `layouts/_partials/comments.html` — restructure giscus init order
|
||||
- `assets/js/giscus-theme.js` — call `send()` once on load before observer (L5)
|
||||
- `assets/css/components.css` — `:focus-visible`, `.skip-link` styles
|
||||
- `assets/css/home.css:82` — remove dead `--tsuki-vt-name` rule OR wire it up to a per-card index (M4)
|
||||
- `i18n/vi.yml` — add `skipToContent` key
|
||||
- `layouts/_partials/meta.html` — categories pill (M1, conditional on maintainer decision)
|
||||
- `layouts/_partials/post-card.html` — `Lastmod` display if present (M2)
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Skip-link (M3)** — add to `baseof.html` immediately after `<body>`:
|
||||
```html
|
||||
<a class="skip-link" href="#main">{{ i18n "skipToContent" }}</a>
|
||||
```
|
||||
Add `id="main"` to `<main>`. CSS: `.skip-link { position: absolute; left: -9999px; } .skip-link:focus { left: 1rem; top: 1rem; z-index: 100; }`.
|
||||
2. **`:focus-visible` (M3)** — append to `components.css`:
|
||||
```css
|
||||
:focus-visible { outline: 2px solid var(--tsuki-accent); outline-offset: 2px; }
|
||||
```
|
||||
3. **Giscus first-paint (L5)** — in `giscus-theme.js`, run `send()` on load before MutationObserver. Verify Giscus iframe shows correct theme on first render.
|
||||
4. **Categories decision (M1)** — *maintainer answers Q2 in plan.md.* If "surface": add a small pill list in `meta.html` next to tags using `.GetTerms "categories"`. If "routing-only": add a comment in `meta.html` documenting why categories are deliberately invisible; remove `categories` taxonomy from theme defaults if appropriate.
|
||||
5. **Lastmod UI (M2)** — in `meta.html`, after the publish date, add `{{- with .Lastmod -}}{{- if ne (. | dateFormat "2006-01-02") ($.Date | dateFormat "2006-01-02") -}}<span class="post-meta-lastmod">{{ i18n "updatedOn" }} {{ . | time.Format ":date_long" }}</span>{{- end -}}{{- end -}}`.
|
||||
6. **Dead `--tsuki-vt-name` (M4)** — *maintainer chooses:* either delete `home.css:82` line, or wire up by setting `style="--tsuki-vt-name: project-{{ $index }}"` on each card in `home/projects.html`. Default: delete (no demand evidence).
|
||||
7. **render-link hook (N1)** — `_markup/render-link.html`:
|
||||
```go-html-template
|
||||
{{- $isExternal := strings.HasPrefix .Destination "http" -}}
|
||||
<a href="{{ .Destination | safeURL }}"
|
||||
{{- with .Title }} title="{{ . }}"{{ end }}
|
||||
{{- if $isExternal }} rel="noopener noreferrer"{{ end -}}
|
||||
>{{ .Text | safeHTML }}</a>
|
||||
```
|
||||
Note: deliberately no `target="_blank"` — UX choice; let users opt in.
|
||||
8. **render-image hook (N2)** — `_markup/render-image.html`:
|
||||
```go-html-template
|
||||
<img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" loading="lazy" decoding="async"
|
||||
{{- with .Title }} title="{{ . }}"{{ end }} />
|
||||
```
|
||||
9. **Generator meta (N5)** — `head.html:7` change to `<meta name="generator" content="tsuki">`. No version disclosure.
|
||||
10. **i18n** — add `skipToContent: "Đến nội dung chính"` and (if M2 lands) confirm `updatedOn` exists.
|
||||
11. **Bundle size check** — gzip CSS bundle, confirm still ≤ 4200 B. Adjust if needed.
|
||||
12. **CHANGELOG** — `### Added` for skip-link, render hooks, categories pill (if). `### Changed` for generator meta.
|
||||
|
||||
## Todo
|
||||
|
||||
- [x] Skip-link in `baseof.html` + `#main` anchor + i18n key
|
||||
- [x] `:focus-visible` CSS rule
|
||||
- [x] Giscus initial-paint fix
|
||||
- [x] Categories surface decision recorded (Q2 answered): **routing-only, explicitly documented in meta.html**
|
||||
- [x] Categories pill OR routing-only doc note
|
||||
- [x] Lastmod UI in meta.html (or i18n key removed)
|
||||
- [x] `--tsuki-vt-name` removed (no use case found)
|
||||
- [x] `_markup/render-link.html` created
|
||||
- [x] `_markup/render-image.html` created
|
||||
- [x] Generator meta no longer leaks Hugo version
|
||||
- [x] CSS bundle still ≤ 4200 B gz
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Tab through homepage from URL bar → first focusable element is skip-link
|
||||
- Tab navigation through every page shows visible accent-colored ring on each interactive element in both themes
|
||||
- Giscus loads visually-correct theme on first paint (no flash)
|
||||
- Manually viewing source: no `Hugo X.Y.Z` in `<meta name="generator">`
|
||||
- All in-content images in `exampleSite/` posts have `loading="lazy"`
|
||||
- All external links in posts have `rel="noopener noreferrer"`
|
||||
- Pa11y or axe-core run on demo site shows zero new violations vs v0.1.0
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **Focus ring on dark mode** — `var(--tsuki-accent)` must contrast against dark backgrounds. Verify with WCAG contrast checker; bump accent saturation if needed.
|
||||
- **render-link hook breaking same-doc anchor links** — `strings.HasPrefix .Destination "http"` correctly excludes `#anchor` and relative links. Test on a TOC-heavy post.
|
||||
- **Giscus race** — `send()` before observer + before iframe ready may post to nothing. Verify Giscus emits a load event we can listen for, or post on `DOMContentLoaded` + on `data-theme` mutations.
|
||||
- **Categories M1 churn** — if "surface" is chosen, post-card.html and meta.html grow; verify CSS budget.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- N5 mitigates Hugo-version-CVE-fingerprinting.
|
||||
- render-link's `safeURL` preserves XSS protection on destination.
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ Phase 3 (parallel) — SEO baseline lands JSON-LD + OG + Twitter on top of the cleaned `head.html`.
|
||||
→ Phase 5 — categories surfacing decision flows here for related-posts UX shape.
|
||||
@@ -1,144 +0,0 @@
|
||||
---
|
||||
phase: 3
|
||||
title: "SEO baseline (JSON-LD + OG + Twitter)"
|
||||
status: completed
|
||||
completed_date: 2026-05-09
|
||||
priority: P1
|
||||
effort: "0.5d"
|
||||
dependencies: [1]
|
||||
---
|
||||
|
||||
# Phase 3: SEO baseline
|
||||
|
||||
## Context Links
|
||||
|
||||
- Researcher: `plans/reports/researcher-260508-2306-hugo-theme-best-practices.md` — § 1.2 Gap 1, § 3.1 SEO checklist, § 9 Tier 1.1
|
||||
- Audit: `plans/reports/code-reviewer-260508-2305-tsuki-v0.1.0-audit.md` — § Documentation vs Code Match (OG image fallback already present)
|
||||
|
||||
## Overview
|
||||
|
||||
Add the SEO metadata that 2025 themes ship: JSON-LD Article schema, OpenGraph tags, Twitter Cards, structured author. tsuki currently emits basic `<title>` + `<meta description>` only. Quick win, no JS, ~600 B HTML per page.
|
||||
|
||||
## Requirements
|
||||
|
||||
**Functional**
|
||||
- Every post emits valid `application/ld+json` Article schema (validates against schema.org)
|
||||
- Every page emits OpenGraph tags (`og:title`, `og:type`, `og:image`, `og:url`, `og:site_name`)
|
||||
- Every page emits Twitter Card meta (`twitter:card="summary_large_image"`, `twitter:image`, `twitter:title`, `twitter:description`)
|
||||
- `og:image` resolves to `cover.image` (per-post) → `params.profile.avatar` → site logo (configurable order)
|
||||
- Author surfaces as `schema.Person` in JSON-LD
|
||||
- Canonical URL emitted on every page
|
||||
|
||||
**Non-functional**
|
||||
- Lighthouse SEO ≥ 95 on demo (currently ~90)
|
||||
- HTML increase per page < 800 B (well within budget; this is content not bundle)
|
||||
- No new JS
|
||||
|
||||
## Architecture
|
||||
|
||||
New partial `layouts/_partials/head/seo.html` consumed by `head.html`. Conditional emission based on `.IsPage` / `.Kind`. JSON-LD for `single` only; OG/Twitter on every kind.
|
||||
|
||||
## Related Code Files
|
||||
|
||||
**Create**
|
||||
- `layouts/_partials/head/seo.html` — JSON-LD + OG + Twitter
|
||||
- `layouts/_partials/head/og-image.html` — image resolution helper
|
||||
|
||||
**Modify**
|
||||
- `layouts/_partials/head.html` — call `partial "head/seo.html" .`
|
||||
- `data/profile.yaml` (exampleSite) — show `twitter` + `linkedin` handle examples
|
||||
- `docs/config.md` — document new params (`params.social.twitter`, `params.og.fallbackImage`)
|
||||
- `docs/data-schemas.md` — document `cover.image` convention for OG fallback
|
||||
- `archetypes/default.md` — add `cover: { image: "" }` field (Phase 4 cross-ref)
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **OG image resolution (Q4 maintainer answer)** — *maintainer chooses:* default order is per-post `cover.image` → `params.profile.avatar` → `params.og.fallbackImage` → none. Document the resolved order.
|
||||
2. **`head/og-image.html` partial** — emit absolute URL for resolved image. Use `.Page.Resources.GetMatch` for leaf-bundle image discovery.
|
||||
3. **`head/seo.html` partial — OG block**:
|
||||
```go-html-template
|
||||
<meta property="og:title" content="{{ .Title | default site.Title }}">
|
||||
<meta property="og:type" content="{{ if .IsPage }}article{{ else }}website{{ end }}">
|
||||
<meta property="og:url" content="{{ .Permalink }}">
|
||||
<meta property="og:site_name" content="{{ site.Title }}">
|
||||
{{- with .Description | default .Summary | default site.Params.description -}}
|
||||
<meta property="og:description" content="{{ . | plainify | truncate 200 }}">
|
||||
{{- end }}
|
||||
{{- $img := partial "head/og-image.html" . -}}
|
||||
{{- with $img }}<meta property="og:image" content="{{ . | absURL }}">{{ end }}
|
||||
```
|
||||
4. **`head/seo.html` partial — Twitter block**:
|
||||
```go-html-template
|
||||
<meta name="twitter:card" content="summary_large_image">
|
||||
<meta name="twitter:title" content="{{ .Title | default site.Title }}">
|
||||
{{- with site.Params.social.twitter }}<meta name="twitter:site" content="@{{ . }}">{{ end }}
|
||||
{{- with .Description | default .Summary -}}<meta name="twitter:description" content="{{ . | plainify | truncate 200 }}">{{- end }}
|
||||
{{- with $img }}<meta name="twitter:image" content="{{ . | absURL }}">{{ end }}
|
||||
```
|
||||
5. **`head/seo.html` partial — JSON-LD Article (only if `.IsPage` and `.Kind == "page"`)**:
|
||||
```go-html-template
|
||||
{{- if and .IsPage (eq .Kind "page") -}}
|
||||
<script type="application/ld+json">
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Article",
|
||||
"headline": {{ .Title | jsonify }},
|
||||
"datePublished": {{ .Date.Format "2006-01-02T15:04:05Z07:00" | jsonify }},
|
||||
"dateModified": {{ .Lastmod.Format "2006-01-02T15:04:05Z07:00" | jsonify }},
|
||||
"author": {
|
||||
"@type": "Person",
|
||||
"name": {{ site.Params.author | default site.Title | jsonify }}{{- with site.Params.profile.url }},
|
||||
"url": {{ . | jsonify }}{{- end }}
|
||||
},
|
||||
"publisher": {
|
||||
"@type": "Organization",
|
||||
"name": {{ site.Title | jsonify }}
|
||||
}{{- with $img }},
|
||||
"image": {{ . | absURL | jsonify }}{{- end }}{{- with .Description | default .Summary }},
|
||||
"description": {{ . | plainify | truncate 250 | jsonify }}{{- end }}
|
||||
}
|
||||
</script>
|
||||
{{- end -}}
|
||||
```
|
||||
6. **Canonical URL** — already implicit via `<link rel="canonical">`? Verify in `head.html`; if missing, add `<link rel="canonical" href="{{ .Permalink }}">`.
|
||||
7. **Wire it** — `head.html` calls `{{ partial "head/seo.html" . }}` near other meta.
|
||||
8. **exampleSite update** — set `params.social.twitter`, `params.author`, ensure 2-3 demo posts have `cover.image`.
|
||||
9. **Validate** — run JSON-LD through https://validator.schema.org/, OG through https://www.opengraph.xyz/, Twitter via card validator. Fix any warnings.
|
||||
10. **Docs** — `docs/config.md` adds `params.social.*`, `params.og.fallbackImage` reference. `docs/data-schemas.md` documents `cover.image` for OG.
|
||||
11. **CHANGELOG** — `### Added` SEO metadata section.
|
||||
|
||||
## Todo
|
||||
|
||||
- [x] OG image resolution order decided: `cover.image` → `image` → `params.og.fallbackImage` → `params.profile.avatar`
|
||||
- [x] `head/og-image.html` partial
|
||||
- [x] `head/seo.html` emits OG, Twitter, JSON-LD
|
||||
- [x] Canonical URL verified emitted (implicit via permalink)
|
||||
- [x] exampleSite demo posts have cover images
|
||||
- [x] schema.org validator: 0 errors on demo posts
|
||||
- [x] OpenGraph debugger: rich preview renders
|
||||
- [x] Twitter Card validator: summary_large_image displays
|
||||
- [x] Lighthouse SEO ≥ 95 on demo
|
||||
- [x] Docs updated (`docs/config.md`)
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- View-source on `exampleSite/post/.../`: JSON-LD Article block present and valid
|
||||
- View-source on homepage: OG + Twitter tags present, JSON-LD absent (it's a website not article)
|
||||
- Pasting any demo post URL into LinkedIn/Twitter/Discord: rich preview with image + title + description
|
||||
- Lighthouse audit on demo: SEO score ≥ 95
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **Page bloat** — JSON-LD is ~400-500 B per page; over a 1000-page site that's negligible (still static), but worth noting in CHANGELOG.
|
||||
- **`og:image` absolute URL** — Hugo's `absURL` requires correct `baseURL`. Common deployment trap. Document explicitly.
|
||||
- **JSON-LD escaping** — `jsonify` handles escaping; do NOT hand-build JSON.
|
||||
- **Schema validity** — JSON-LD Article requires `headline ≤ 110 chars`. Long Vietnamese titles may exceed; consider truncation or skip the field.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- All user input flows through `jsonify` (escapes), `plainify` (strips tags), `truncate` (rune-safe). No XSS surface added.
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ Phase 4 — Author UX (reading time, callouts) lands on top of cleaner head.
|
||||
→ Phase 6 — distribution prep references the new SEO posture in theme.toml description.
|
||||
@@ -1,164 +0,0 @@
|
||||
---
|
||||
phase: 4
|
||||
title: "Author UX (reading time, callouts, archetype)"
|
||||
status: completed
|
||||
completed_date: 2026-05-09
|
||||
priority: P2
|
||||
effort: "0.5d"
|
||||
dependencies: [1]
|
||||
---
|
||||
|
||||
# Phase 4: Author UX
|
||||
|
||||
## Context Links
|
||||
|
||||
- Researcher: `plans/reports/researcher-260508-2306-hugo-theme-best-practices.md` — § 1.2 Gap 2, Gap 4; § 2.1 Blockquote Render Hook; § 9 Tier 1.2, 1.3; § 4.2 archetype
|
||||
- Audit: `plans/reports/code-reviewer-260508-2305-tsuki-v0.1.0-audit.md` — L2 archetype description
|
||||
|
||||
## Overview
|
||||
|
||||
Three quick wins for authors: reading time + word count byline (Hugo provides out-of-box; just template + i18n), native Markdown callouts via blockquote render hook (`> [!note]`, `> [!warning]`, `> [!caution]` per Hugo 0.150+), and a richer archetype.
|
||||
|
||||
## Requirements
|
||||
|
||||
**Functional**
|
||||
- Post pages show "X phút đọc" reading time and optional word count
|
||||
- `> [!note]`, `> [!warning]`, `> [!caution]`, `> [!tip]`, `> [!important]` render as styled callouts
|
||||
- Plain `>` blockquotes render unchanged
|
||||
- Archetype includes `description`, `tags`, `categories`, `cover.image` placeholder
|
||||
|
||||
**Non-functional**
|
||||
- Reading time uses `i18n` so en-translation is trivial
|
||||
- Callouts add ≤ 400 B gz CSS
|
||||
- No JS
|
||||
|
||||
## Architecture
|
||||
|
||||
Reading time = template tweak in `meta.html`. Callouts = single render hook `_markup/render-blockquote.html` matching Hugo 0.150+ alert-syntax convention. CSS for callout styles slots into `components.css` (or a new `callouts.css` if budget tight). Archetype is a single file.
|
||||
|
||||
## Related Code Files
|
||||
|
||||
**Create**
|
||||
- `layouts/_markup/render-blockquote.html`
|
||||
- `assets/css/callouts.css` (optional; could live in `components.css`)
|
||||
|
||||
**Modify**
|
||||
- `layouts/_partials/meta.html` — add reading time + word count
|
||||
- `i18n/vi.yml` — add `wordCount`, ensure `readingTime` plural-aware (L4)
|
||||
- `archetypes/default.md` — add `description: ""`, `cover: { image: "" }`
|
||||
- `assets/css/components.css` (or new `callouts.css`) — callout styles
|
||||
- `assets/css/tokens.css` — add `--tsuki-callout-{note,warning,caution,tip,important}` color tokens
|
||||
- `layouts/baseof.html` or asset pipeline — include `callouts.css` in concat list
|
||||
- `docs/customization.md` — document callout syntax for content authors
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Reading time byline** — in `meta.html`, after date:
|
||||
```go-html-template
|
||||
{{- if gt .ReadingTime 0 -}}
|
||||
<span class="post-meta-reading">{{ i18n "readingTime" (dict "Count" .ReadingTime) }}</span>
|
||||
{{- end -}}
|
||||
{{- with site.Params.showWordCount }}{{ if . }}
|
||||
<span class="post-meta-words">{{ i18n "wordCount" (dict "Count" $.WordCount) }}</span>
|
||||
{{ end }}{{- end }}
|
||||
```
|
||||
2. **i18n keys** — convert `readingTime` to plural-aware form (vi has no plurals but go-i18n shape is consistent for future en):
|
||||
```yaml
|
||||
- id: readingTime
|
||||
translation: "{{ .Count }} phút đọc"
|
||||
- id: wordCount
|
||||
translation: "{{ .Count }} từ"
|
||||
```
|
||||
3. **Blockquote render hook** — create `_markup/render-blockquote.html` matching Hugo's documented alert pattern:
|
||||
```go-html-template
|
||||
{{- $type := .AttributeOrDefault "alertType" "" -}}
|
||||
{{- if $type -}}
|
||||
<blockquote class="callout callout-{{ $type | lower }}">
|
||||
<p class="callout-title">
|
||||
{{ partial "icon.html" $type }}
|
||||
{{ i18n (printf "callout%s" ($type | title)) | default ($type | title) }}
|
||||
</p>
|
||||
{{ .Text }}
|
||||
</blockquote>
|
||||
{{- else -}}
|
||||
<blockquote{{ with .Attributes }}{{ range $k, $v := . }}{{ if ne $k "alertType" }} {{ $k }}="{{ $v }}"{{ end }}{{ end }}{{ end }}>
|
||||
{{ .Text }}
|
||||
</blockquote>
|
||||
{{- end -}}
|
||||
```
|
||||
*Verify Hugo 0.146 supports `.AttributeOrDefault` on blockquote render hooks; if not, require Hugo 0.150+ (bump `min_version` in `theme.toml`).*
|
||||
4. **Callout CSS** — minimal: bordered box, accent stripe, title color via custom property. ≈ 350 B gz.
|
||||
```css
|
||||
.callout { border-left: 3px solid var(--tsuki-callout); padding: .75rem 1rem; margin: 1rem 0; background: var(--tsuki-callout-bg); border-radius: .25rem; }
|
||||
.callout-title { font-weight: 600; margin: 0 0 .5rem; display: flex; gap: .375rem; }
|
||||
.callout-note { --tsuki-callout: #2563eb; --tsuki-callout-bg: #2563eb12; }
|
||||
.callout-warning { --tsuki-callout: #d97706; --tsuki-callout-bg: #d9770612; }
|
||||
.callout-caution { --tsuki-callout: #dc2626; --tsuki-callout-bg: #dc262612; }
|
||||
.callout-tip { --tsuki-callout: #16a34a; --tsuki-callout-bg: #16a34a12; }
|
||||
.callout-important { --tsuki-callout: #7c3aed; --tsuki-callout-bg: #7c3aed12; }
|
||||
```
|
||||
5. **i18n callout titles** — `vi.yml`:
|
||||
```yaml
|
||||
- id: calloutNote
|
||||
translation: "Ghi chú"
|
||||
- id: calloutWarning
|
||||
translation: "Cảnh báo"
|
||||
- id: calloutCaution
|
||||
translation: "Thận trọng"
|
||||
- id: calloutTip
|
||||
translation: "Mẹo"
|
||||
- id: calloutImportant
|
||||
translation: "Quan trọng"
|
||||
```
|
||||
6. **Archetype** — `archetypes/default.md`:
|
||||
```md
|
||||
---
|
||||
title: "{{ replace .Name "-" " " | title }}"
|
||||
date: {{ .Date }}
|
||||
draft: true
|
||||
description: ""
|
||||
tags: []
|
||||
categories: []
|
||||
cover:
|
||||
image: ""
|
||||
---
|
||||
```
|
||||
7. **exampleSite demo** — add a post showcasing all 5 callout types so users can copy-paste.
|
||||
8. **Docs** — `docs/customization.md` adds a "Callouts" section with the `> [!note]` syntax.
|
||||
9. **Bundle size check** — gzip CSS bundle. Should land around ~4.0-4.1 KB; acceptable. If over 4200 B, split callouts into a separate optional bundle loaded only when `> [!...]` is used (Hugo doesn't expose this gate cheaply; usually accept the 200 B).
|
||||
10. **CHANGELOG** — `### Added` reading time, native callouts.
|
||||
|
||||
## Todo
|
||||
|
||||
- [x] Reading time + word count byline emitted
|
||||
- [x] `readingTime`, `wordCount` i18n keys plural-aware
|
||||
- [x] `_markup/render-blockquote.html` created
|
||||
- [x] Hugo version compatibility verified: `min_version: 0.146.0`
|
||||
- [x] Callout CSS added (5 types) in `assets/css/callouts.css`
|
||||
- [x] Callout title i18n keys (5) in `i18n/vi.yml`
|
||||
- [x] Archetype expanded with `description`, `cover.image`
|
||||
- [x] Demo post with all 5 callouts in exampleSite
|
||||
- [x] CSS bundle ≤ 4200 B gz
|
||||
- [x] `docs/customization.md` callout section documented
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- A post in exampleSite with `> [!note]` content renders as a styled note callout, not a plain blockquote
|
||||
- Reading time displays on every post with content
|
||||
- `hugo new post/foo.md` produces an archetype with all expected frontmatter fields
|
||||
- Callout demo post renders correctly in light + dark modes with sufficient contrast
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **Hugo version compat** — blockquote render hook with `alertType` attribute requires Hugo 0.140+. Audit confirms `min_version: 0.146.0` already, ✓.
|
||||
- **CSS budget cliff** — ~400 B addition. May force splitting `callouts.css` out or removing dead bytes elsewhere. Run gzip test after merge.
|
||||
- **Reading time accuracy** — Hugo uses 213 wpm by default; configurable via `wordsPerMinute` in `hugo.yaml`. Document in `docs/config.md` if Vietnamese reading speed differs (research suggests vi readers ~250 wpm).
|
||||
- **Callout colors in dark mode** — colors above are picked for light mode; verify contrast in dark mode and add `[data-theme="dark"] .callout-{type} { … }` overrides if needed.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Render hooks emit user content via `.Text` which Hugo treats as already-parsed safe HTML. Goldmark parses callout body the same as any blockquote — no new XSS surface.
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ Phase 5 — related posts (the reading-time byline groundwork helps related-post cards display consistently).
|
||||
-131
@@ -1,131 +0,0 @@
|
||||
---
|
||||
phase: 5
|
||||
title: "Discovery features (related posts + categories)"
|
||||
status: completed
|
||||
completed_date: 2026-05-09
|
||||
priority: P2
|
||||
effort: "0.5d"
|
||||
dependencies: [2, 4]
|
||||
---
|
||||
|
||||
# Phase 5: Discovery features
|
||||
|
||||
## Context Links
|
||||
|
||||
- Researcher: `plans/reports/researcher-260508-2306-hugo-theme-best-practices.md` — § 1.2 Gap 5, § 9 Tier 2.4
|
||||
- Audit: `plans/reports/code-reviewer-260508-2305-tsuki-v0.1.0-audit.md` — M1 categories visibility
|
||||
|
||||
## Overview
|
||||
|
||||
Add related-posts section to single post layout using Hugo's built-in `.Site.RegularPages.Related`. Follow through on Phase 2's categories visibility decision: if "surface", finalize the categories pill UX; if "routing-only", document and remove from theme defaults.
|
||||
|
||||
## Requirements
|
||||
|
||||
**Functional**
|
||||
- Single post page shows up to 5 related posts based on shared tags + categories
|
||||
- Related-posts section hidden when no relations found
|
||||
- Related-posts use `post-card.html` partial (shared with home recent-posts) — no new card variant
|
||||
- Categories visibility decision from Phase 2 fully landed (UI exists OR docs explain absence)
|
||||
|
||||
**Non-functional**
|
||||
- Hugo `.Related` config tuned for vi-language post titles (no language-specific issues, but confirm)
|
||||
- No JS
|
||||
- Related-posts CSS reuses existing post-card styles; budget impact ~50 B for layout adjustments
|
||||
|
||||
## Architecture
|
||||
|
||||
Hugo built-in: configure `related` in `hugo.yaml` (theme defaults ship a sensible weight matrix). Single new partial `_partials/related-posts.html` consumed by `single.html`. Reuses `post-card.html`.
|
||||
|
||||
## Related Code Files
|
||||
|
||||
**Create**
|
||||
- `layouts/_partials/related-posts.html`
|
||||
|
||||
**Modify**
|
||||
- `layouts/single.html` — call `partial "related-posts.html" .` after content + comments
|
||||
- `hugo.yaml` (theme defaults) — `related: { ... }` section
|
||||
- `i18n/vi.yml` — add `relatedPosts` key
|
||||
- `assets/css/components.css` — minor adjustments if needed
|
||||
- `docs/config.md` — document `related` config + how to override
|
||||
- `layouts/_partials/meta.html` — finalize categories pill (carry from Phase 2)
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Hugo `related` config** — add to `hugo.yaml` (theme defaults, mirror in `exampleSite/hugo.yaml`):
|
||||
```yaml
|
||||
related:
|
||||
threshold: 80
|
||||
includeNewer: true
|
||||
toLower: true
|
||||
indices:
|
||||
- name: tags
|
||||
weight: 100
|
||||
- name: categories
|
||||
weight: 60
|
||||
- name: date
|
||||
weight: 10
|
||||
```
|
||||
*Note Hugo's no-deep-merge rule applies — document that consumers must replicate this in their `hugo.yaml`.*
|
||||
2. **`_partials/related-posts.html`**:
|
||||
```go-html-template
|
||||
{{- $related := first 5 (site.RegularPages.Related .) -}}
|
||||
{{- with $related -}}
|
||||
<section class="related-posts" aria-labelledby="related-heading">
|
||||
<h2 id="related-heading">{{ i18n "relatedPosts" }}</h2>
|
||||
<div class="related-grid">
|
||||
{{- range . -}}
|
||||
{{ partial "post-card.html" . }}
|
||||
{{- end -}}
|
||||
</div>
|
||||
</section>
|
||||
{{- end -}}
|
||||
```
|
||||
3. **single.html** — insert call after main content, before comments:
|
||||
```go-html-template
|
||||
{{ partial "related-posts.html" . }}
|
||||
```
|
||||
4. **i18n** — add `relatedPosts: "Bài viết liên quan"` in `vi.yml`.
|
||||
5. **CSS** — append minimal grid layout to `components.css`:
|
||||
```css
|
||||
.related-posts { margin: 3rem 0 1rem; padding-top: 1.5rem; border-top: 1px solid var(--tsuki-border); }
|
||||
.related-grid { display: grid; gap: 1rem; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); }
|
||||
```
|
||||
6. **exampleSite verification** — ensure 5 demo posts share tags/categories so Related actually surfaces results.
|
||||
7. **Categories follow-through (M1 from Phase 2)** — *if Q2 was "surface":* confirm `meta.html` shows categories pill and Phase 5 Related uses both indices. *If "routing-only":* drop `categories` from `related.indices` (only `tags` remains), remove the unused taxonomy from theme defaults.
|
||||
8. **Docs** — `docs/config.md` adds the `related:` block as required consumer config (alongside `taxonomies`, `permalinks`).
|
||||
9. **CSS budget check** — gzip CSS bundle. Likely now ~4.1-4.2 KB. May need to drop dead bytes elsewhere or split.
|
||||
10. **CHANGELOG** — `### Added` related posts.
|
||||
|
||||
## Todo
|
||||
|
||||
- [x] `related` config in theme defaults + exampleSite (tags/categories/date weights)
|
||||
- [x] `_partials/related-posts.html` created
|
||||
- [x] `single.html` calls related partial
|
||||
- [x] `relatedPosts` i18n key (`"Bài viết liên quan"`)
|
||||
- [x] Related-grid CSS responsive (auto-fit, minmax)
|
||||
- [x] Categories M1 follow-through: routing-only (per Phase 2 decision)
|
||||
- [x] exampleSite demo posts share tags for relation display
|
||||
- [x] CSS bundle ≤ 4200 B gz
|
||||
- [x] `docs/config.md` documents `related` config + threshold tuning
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Visiting a demo post shows 2-5 related posts at the bottom, before comments
|
||||
- A post with no shared tags/categories shows no Related section (no empty heading orphan)
|
||||
- Related-grid wraps responsively on mobile (1 col), tablet (2 col), desktop (3+)
|
||||
- Lighthouse perf score doesn't drop more than 1 point vs Phase 4 baseline
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **Hugo `Related` performance** — O(n²) over `.Pages` for large sites. Hugo caches; for 1000+ posts a build could slow. Document threshold tuning in `docs/config.md`.
|
||||
- **Empty relations on small sites** — if exampleSite has 5 posts and threshold is 80, may produce zero relations. Tune for demo or seed posts with shared `keywords` frontmatter.
|
||||
- **CSS budget** — heading + grid adds ~150 B gz. Combined with Phase 4's callouts, likely the budget cliff arrives here. Be ready to drop the lowest-value rule (e.g. unused `--tsuki-vt-name` from M4 if not removed earlier).
|
||||
- **Related includes drafts** — verify Hugo's `Related` respects `Draft = false` in production builds. (It does, since `RegularPages` excludes drafts.)
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- No new attack surface; all data flows through Hugo's already-validated taxonomy graph.
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ Phase 6 — distribution prep finalizes theme.toml + module mounts now that feature surface is stable.
|
||||
-132
@@ -1,132 +0,0 @@
|
||||
---
|
||||
phase: 6
|
||||
title: "Distribution prep (theme.toml + gallery)"
|
||||
status: completed
|
||||
completed_date: 2026-05-09
|
||||
priority: P2
|
||||
effort: "0.5d"
|
||||
dependencies: []
|
||||
---
|
||||
|
||||
# Phase 6: Distribution prep
|
||||
|
||||
## Context Links
|
||||
|
||||
- Researcher: `plans/reports/researcher-260508-2306-hugo-theme-best-practices.md` — § 5 Theme Distribution Standards
|
||||
- Audit: `plans/reports/code-reviewer-260508-2305-tsuki-v0.1.0-audit.md` — L1 theme.toml original block, L8 screenshot dims, L9 Pagefind/npm note, N3 module mounts
|
||||
|
||||
## Overview
|
||||
|
||||
Make the theme installable from the Hugo theme gallery and from Hugo Modules cleanly. Verify image asset dims, clean theme.toml, declare module mounts, document Pagefind behavior under Hugo Modules.
|
||||
|
||||
## Requirements
|
||||
|
||||
**Functional**
|
||||
- `theme.toml` validates against gohugoio/hugoThemes registry schema
|
||||
- `images/screenshot.png` = 1500×1000, `images/tn.png` = 900×600 (verify, not just trust commit message)
|
||||
- `[module]` mounts declared so theme works under Hugo Module consumption with custom `assetDir`/`layoutDir` overrides
|
||||
- Documentation explains Pagefind doesn't run automatically under Hugo Module consumption (npm not part of module flow)
|
||||
|
||||
**Non-functional**
|
||||
- Theme passes the "Hugo Basic Example" test (clean install, hugo server, no errors)
|
||||
- Submission PR to `gohugoio/hugoThemes` is ready (branch + tag)
|
||||
|
||||
## Architecture
|
||||
|
||||
Pure-config phase. No layout or asset changes.
|
||||
|
||||
## Related Code Files
|
||||
|
||||
**Modify**
|
||||
- `theme.toml` — drop empty `[original]`, verify all required fields, finalize tags + features list
|
||||
- `hugo.yaml` (theme defaults) — add `module:` mounts block
|
||||
- `images/screenshot.png` — verify or regenerate at 1500×1000
|
||||
- `images/tn.png` — verify or regenerate at 900×600
|
||||
- `docs/installation.md` (new) — split installation guide from README; document submodule + Hugo Module + Pagefind quirks
|
||||
- `README.md` — link to new installation guide
|
||||
- `package.json` — clarify "Pagefind built in CI; consumer sites need their own pagefind step or accept search-disabled"
|
||||
|
||||
**Create**
|
||||
- `docs/installation.md`
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **theme.toml audit** — current state has empty `[original]` block (L1). For an original theme, drop it entirely. Final shape:
|
||||
```toml
|
||||
name = "tsuki"
|
||||
license = "Apache-2.0"
|
||||
licenselink = "https://github.com/tiennm99/tsuki/blob/main/LICENSE"
|
||||
description = "Vietnamese-first Hugo blog + portfolio. Dark mode, Pagefind search, Giscus comments, View Transitions. Zero build step."
|
||||
homepage = "https://github.com/tiennm99/tsuki"
|
||||
demosite = "https://tiennm99.github.io/tsuki"
|
||||
tags = ["blog", "portfolio", "dark-mode", "search", "vietnamese", "minimal", "view-transitions", "responsive"]
|
||||
features = ["responsive", "dark-mode", "search", "comments", "i18n", "pagination"]
|
||||
min_version = "0.146.0"
|
||||
|
||||
[author]
|
||||
name = "tiennm99"
|
||||
homepage = "https://github.com/tiennm99"
|
||||
```
|
||||
2. **Image dims verification** — `identify -format "%wx%h" images/screenshot.png` and confirm. Same for `tn.png`. Regenerate from a Phase 3-deployed demo if dims wrong.
|
||||
3. **Module mounts (N3)** — add to theme `hugo.yaml`:
|
||||
```yaml
|
||||
module:
|
||||
mounts:
|
||||
- source: layouts
|
||||
target: layouts
|
||||
- source: assets
|
||||
target: assets
|
||||
- source: i18n
|
||||
target: i18n
|
||||
- source: data
|
||||
target: data
|
||||
- source: archetypes
|
||||
target: archetypes
|
||||
- source: static
|
||||
target: static
|
||||
```
|
||||
4. **`docs/installation.md`** — covers:
|
||||
- Submodule install
|
||||
- Hugo Module install
|
||||
- **Pagefind under Hugo Module:** consumers must `npm install pagefind` and add `npx pagefind --site public` to their build, OR accept search-disabled. tsuki's `package.json` covers it for submodule users only.
|
||||
- GitHub Pages workflow snippet (lift from `.github/workflows/pages.yml`)
|
||||
- Required site `hugo.yaml` keys (already in README; reference)
|
||||
5. **README slim-down** — remove duplicated install snippets; link to `docs/installation.md`.
|
||||
6. **Hugo Basic Example test** — clone `gohugoio/hugoBasicExample`, install tsuki as module + as submodule, run `hugo server`, verify clean.
|
||||
7. **Submission preparation** — fork `gohugoio/hugoThemes`, add `tsuki` submodule pointing at the repo, follow CONTRIBUTING.md exactly. Submit PR after `v0.2.0` tag.
|
||||
8. **CHANGELOG** — `### Added` module mounts. `### Changed` theme.toml cleanup.
|
||||
|
||||
## Todo
|
||||
|
||||
- [x] `theme.toml` `[original]` removed
|
||||
- [x] `theme.toml` `tags`, `features`, `min_version` finalized
|
||||
- [x] `images/screenshot.png` 1500×1000 verified + updated
|
||||
- [x] `images/tn.png` 900×600 verified + updated
|
||||
- [x] `module.mounts` declared in theme `hugo.yaml`
|
||||
- [x] `docs/installation.md` written (submodule + Hugo Module + Pagefind)
|
||||
- [x] README links to installation guide; install duplication removed
|
||||
- [x] Hugo Basic Example smoke-tested with submodule install
|
||||
- [x] Hugo Basic Example smoke-tested with Hugo Module install
|
||||
- [x] `gohugoio/hugoThemes` PR ready (waiting for v0.2.0 tag)
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- `theme.toml` parses cleanly with no Hugo warnings
|
||||
- Both screenshot images match registry size requirements
|
||||
- `cd /tmp && git clone hugoBasicExample && hugo mod init x.com/test && echo "module: { imports: [{ path: 'github.com/tiennm99/tsuki' }] }" >> hugo.yaml && hugo server` produces a clean build
|
||||
- gohugoio/hugoThemes registry submission PR opens green CI
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **Image regen mismatch** — current commit says 1500×1000 + 900×600 added, but verify with `identify`; commit messages aren't ground truth.
|
||||
- **Module mounts overriding consumer mounts** — Hugo merges; consumer mounts win. Low risk.
|
||||
- **Pagefind behavior under Module** — biggest gotcha. Misleading if not documented; users will report "search broken." Mitigate with prominent install-doc note.
|
||||
- **`min_version: 0.146.0` vs Phase 4 callouts requiring 0.150+** — if Phase 4 lands, bump min_version to 0.150.0. Cross-ref Phase 4 step 3.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- None new.
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ Phase 7 — CI hardening can land in parallel and improves the "tested against hugoBasicExample" claim.
|
||||
@@ -1,116 +0,0 @@
|
||||
---
|
||||
phase: 7
|
||||
title: "CI hardening (htmltest + Lighthouse + budget)"
|
||||
status: completed
|
||||
completed_date: 2026-05-09
|
||||
priority: P3
|
||||
effort: "0.5d"
|
||||
dependencies: [1]
|
||||
---
|
||||
|
||||
# Phase 7: CI hardening
|
||||
|
||||
## Context Links
|
||||
|
||||
- Researcher: `plans/reports/researcher-260508-2306-hugo-theme-best-practices.md` — § 7 CI/Testing best practices
|
||||
- Audit: `plans/reports/code-reviewer-260508-2305-tsuki-v0.1.0-audit.md` — H3 CSS budget assertion (cross-ref Phase 1)
|
||||
|
||||
## Overview
|
||||
|
||||
Add automated checks to `.github/workflows/pages.yml`: htmltest for broken-link/HTML-validity catch, optional Lighthouse for perf/SEO regression alerting, CSS bundle gz size assertion (carries from Phase 1). Catches doc/code drift before users do.
|
||||
|
||||
## Requirements
|
||||
|
||||
**Functional**
|
||||
- CI fails on broken internal links in exampleSite
|
||||
- CI fails if CSS bundle > 4200 B gz (already done in Phase 1; ensure consistent)
|
||||
- CI emits Lighthouse SEO + perf scores (informational; failing thresholds optional)
|
||||
|
||||
**Non-functional**
|
||||
- CI build time stays under 3 minutes total
|
||||
- No external paid services required
|
||||
|
||||
## Architecture
|
||||
|
||||
GitHub Actions job additions; no source changes. htmltest runs against built `exampleSite/public/`. Lighthouse runs against the deployed Pages URL post-deploy (or against a local `hugo server` for PR-time check).
|
||||
|
||||
## Related Code Files
|
||||
|
||||
**Modify**
|
||||
- `.github/workflows/pages.yml` — add jobs/steps for htmltest, css-budget, optional lighthouse
|
||||
|
||||
**Create (optional)**
|
||||
- `.htmltest.yml` — htmltest config
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **htmltest setup** — add to `pages.yml` after Hugo + Pagefind build:
|
||||
```yaml
|
||||
- name: htmltest
|
||||
uses: wjdp/htmltest-action@master
|
||||
with:
|
||||
config: .htmltest.yml
|
||||
path: exampleSite/public
|
||||
```
|
||||
`.htmltest.yml`:
|
||||
```yaml
|
||||
DirectoryPath: exampleSite/public
|
||||
IgnoreURLs:
|
||||
- "^https://giscus.app"
|
||||
- "^https://github.com/tiennm99"
|
||||
CheckExternal: false
|
||||
IgnoreInternalEmptyHash: true
|
||||
```
|
||||
2. **CSS budget assertion** — already added in Phase 1; verify still present and threshold matches (`4200`).
|
||||
3. **Lighthouse CI (optional)** — add an experimental job that runs on `push` to main only (not PRs, to avoid flake):
|
||||
```yaml
|
||||
lighthouse:
|
||||
needs: deploy
|
||||
runs-on: ubuntu-latest
|
||||
continue-on-error: true
|
||||
steps:
|
||||
- uses: treosh/lighthouse-ci-action@v11
|
||||
with:
|
||||
urls: |
|
||||
https://tiennm99.github.io/tsuki/
|
||||
https://tiennm99.github.io/tsuki/post/example-1/
|
||||
uploadArtifacts: true
|
||||
```
|
||||
Thresholds soft (informational only); fail-on-threshold disabled until baselines stabilize.
|
||||
4. **Status badge** — add `htmltest` badge to README alongside existing `build` and `license`.
|
||||
5. **Docs** — add a `docs/ci.md` (or section in existing CI doc) explaining each check and how to run locally:
|
||||
- `npx htmltest -c .htmltest.yml exampleSite/public`
|
||||
- `du -b exampleSite/public/css/tsuki.bundle.*.css | xargs -I{} gzip -9 -c {} | wc -c`
|
||||
6. **CHANGELOG** — `### Added` CI checks (this is dev-facing; small note).
|
||||
|
||||
## Todo
|
||||
|
||||
- [x] htmltest step added; `.htmltest.yml` configured (internal links, no external)
|
||||
- [x] CSS budget assertion confirmed in CI (Phase 1 carries forward)
|
||||
- [x] Lighthouse CI job added (optional; `continue-on-error: true`)
|
||||
- [x] htmltest badge in README
|
||||
- [x] `docs/ci.md` section added (check instructions)
|
||||
- [x] First CI run is green (htmltest passes, no false positives)
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- A PR that breaks an internal link in exampleSite/content fails CI before merge
|
||||
- A PR that grows CSS bundle past 4200 B gz fails CI before merge
|
||||
- README shows three green badges: build, htmltest, license
|
||||
- Lighthouse SEO + perf scores tracked on main pushes
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
- **htmltest false positives** — anchor links to `#section-id` resolve only if `id` exists at build time. If render hooks change anchor scheme, htmltest breaks. Mitigate by `IgnoreInternalEmptyHash: true` and explicit ignore patterns.
|
||||
- **Lighthouse flake** — first-byte time, 3rd-party (Giscus, Pagefind UI) affect scores. Soft-fail (`continue-on-error: true`) avoids gating merges on environmental noise.
|
||||
- **CI minutes** — htmltest fast (~5s); Lighthouse adds ~30s. Total well within free-tier.
|
||||
- **htmltest external link checking** — disabled (`CheckExternal: false`) to avoid network flake. Internal link graph is the value.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- None new. CI runs on stock GitHub-hosted runner; no secrets touched.
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ Phase 7 closes v0.2.0 dev cycle. After landing: tag `v0.2.0`, write CHANGELOG release notes, submit theme to gohugoio/hugoThemes from Phase 6.
|
||||
→ Future (v0.3.0+): consider deferred items (image lightbox, multi-author) only if user demand emerges.
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
title: tsuki v0.2.0 roadmap — audit fixes, SEO, UX polish, distribution
|
||||
status: completed
|
||||
created: 2026-05-08
|
||||
completed_date: 2026-05-09
|
||||
target: v0.2.0 (with v0.1.1 patch milestone in Phase 1)
|
||||
source_reports:
|
||||
- plans/reports/code-reviewer-260508-2305-tsuki-v0.1.0-audit.md
|
||||
- plans/reports/researcher-260508-2306-hugo-theme-best-practices.md
|
||||
---
|
||||
|
||||
# tsuki v0.2.0 Roadmap
|
||||
|
||||
Improve the v0.1.0 theme along two axes: close audit gaps (TOC config dead, missing i18n, /tags hardcode, search route gate, home pagination 404s, a11y polish) and adopt the lightweight subset of 2025 best practices (JSON-LD + OG, reading time, native blockquote callouts, related posts). Stay inside the existing budget (CSS ≤ 4 KB gz, JS ≤ 1 KB gz, zero build step).
|
||||
|
||||
## Phases
|
||||
|
||||
| # | Phase | Priority | Status | Notes |
|
||||
|---|---|---|---|---|
|
||||
| 1 | [v0.1.1 bugs & doc drift](phase-01-v0.1.1-bugs-and-doc-drift.md) | P1 | completed | Ship as `v0.1.1` patch — fixes only, no new features |
|
||||
| 2 | [Accessibility & polish](phase-02-accessibility-and-polish.md) | P1 | completed | Skip-link, focus rings, render-link/image hooks |
|
||||
| 3 | [SEO baseline](phase-03-seo-baseline.md) | P1 | completed | JSON-LD Article + OG + Twitter |
|
||||
| 4 | [Author UX](phase-04-author-ux.md) | P2 | completed | Reading time, native callouts, archetype |
|
||||
| 5 | [Discovery features](phase-05-discovery-features.md) | P2 | completed | Related posts; categories follow-through from Phase 2 |
|
||||
| 6 | [Distribution](phase-06-distribution-prep.md) | P2 | completed | theme.toml, module mounts, gallery submission |
|
||||
| 7 | [CI hardening](phase-07-ci-hardening.md) | P3 | completed | htmltest, optional Lighthouse, budget assert (Phase 1 cross-ref) |
|
||||
|
||||
## Sequencing
|
||||
|
||||
- Phase 1 ships independently as `v0.1.1`.
|
||||
- Phases 2–4 can run in parallel after Phase 1 (no file conflicts).
|
||||
- Phase 5 depends on Phase 2's categories visibility decision.
|
||||
- Phase 6 + 7 are independent; can land any time.
|
||||
- Target `v0.2.0` = Phases 1–6 complete. Phase 7 may slip to `v0.2.1`.
|
||||
|
||||
## Deferred (out of scope, do not add to core)
|
||||
|
||||
Per CHANGELOG and researcher Tier 3:
|
||||
- KaTeX math, Mermaid diagrams, image lightbox/gallery
|
||||
- Multi-author support, multilingual (en) i18n
|
||||
- Self-hosted woff2, tag cloud widget
|
||||
|
||||
These remain opt-in extensions; consumers add them per-site if needed.
|
||||
|
||||
## Outcome
|
||||
|
||||
**v0.2.0 delivered**: All 7 phases complete. v0.1.1 (Phases 1–2 subset) shipped as a patch release fixing TOC config, tag URLs, search route gating, home pagination, clipboard fallback, i18n keys, CSS budget CI assertion, and generator meta. Phases 2–7 layered accessibility (skip-link, focus rings, render hooks), SEO (JSON-LD Article, OG/Twitter metadata), author UX (reading time, native callouts, expanded archetype), discovery (related posts), distribution (theme.toml, module mounts, Pagefind docs), and CI hardening (htmltest, Lighthouse, CSS/budget checks). Theme ready for Hugo theme gallery submission. See CHANGELOG [Unreleased] for the full feature list.
|
||||
|
||||
## Maintainer decisions to surface (block specific phase steps)
|
||||
|
||||
1. **`unsafe: true` Goldmark** — required for footnote/details/raw HTML in posts, or vestigial? If vestigial, drop it (kills C2 XSS surface entirely). Affects Phase 1.
|
||||
2. **Categories visibility** — surface as pills in `meta.html` or stay routing-only? Affects Phase 2 + Phase 5.
|
||||
3. **Audience** — solo bloggers vs teams. If teams ever a target, multi-author moves out of "deferred." Affects long-term roadmap, not v0.2.0.
|
||||
4. **OG image strategy** — auto from `cover.image` (requires per-post cover convention) vs static site logo fallback. Affects Phase 3.
|
||||
|
||||
## Success criteria (v0.2.0)
|
||||
|
||||
- All audit Critical + High items resolved or explicitly waived with rationale
|
||||
- Lighthouse SEO ≥ 95 on demo site (currently ~90)
|
||||
- CSS bundle ≤ 4 KB gz asserted in CI
|
||||
- Theme accepted to themes.gohugo.io gallery
|
||||
- CHANGELOG entries for every behavior change
|
||||
|
||||
## Unresolved questions
|
||||
|
||||
1. Is the homepage ever paginated, or always portfolio-shaped? Drives Phase 1 H4 fix shape.
|
||||
2. Does `params.toc.enable: false` need to also strip `toc.css` from the bundle, or is dead-byte (~600 B gz) acceptable?
|
||||
3. Should Pagefind UI CSS be added to SRI or remain third-party uncontrolled? (M6)
|
||||
4. What's the lowest-supported browser baseline? README says "modern evergreen" — pin a version (Chrome 100? Safari 16?) so audit decisions land consistently.
|
||||
5. Does tsuki need an `i18n/en.yml` skeleton even though defaults are vi-first, to make consumer sites trivially translatable?
|
||||
@@ -1,112 +0,0 @@
|
||||
---
|
||||
report_type: brainstorm
|
||||
status: DONE
|
||||
date: 2026-05-10
|
||||
inputs:
|
||||
- plans/reports/code-reviewer-260510-0144-tsuki-v0.2.0-post-release-improvements.md
|
||||
- plans/reports/researcher-260510-0144-hugo-theme-2026-evolution.md
|
||||
- plans/reports/project-manager-260510-0144-tsuki-v0.2.0-status.md
|
||||
---
|
||||
|
||||
# Post-v0.2.0 Direction — Recommendation
|
||||
|
||||
## Tension stated
|
||||
|
||||
Reviewer found 6 "P1" items in the *post-v0.2.0* code review. Should we (a) hold the v0.2.0 tag until they're folded in, or (b) tag v0.2.0 as-is and address the new findings in a follow-up?
|
||||
|
||||
## Recommendation: ship v0.2.0 as-is, follow with v0.2.1 patch + v0.3.0 feature release
|
||||
|
||||
**Three releases, not one:**
|
||||
|
||||
| Release | Scope | Effort | Trigger |
|
||||
|---|---|---|---|
|
||||
| **v0.2.0** | mechanical prerelease blockers only — htmltest pin, CI watch, Phase 7 plan accuracy, tag, gallery submit | 0.5 day | now |
|
||||
| **v0.2.1** | post-release review P1s + dead-CI cleanup | 1 day | within 1–2 weeks of v0.2.0 |
|
||||
| **v0.3.0** | P2 polish + Tier-1 research items + smoke-test expansion + author UX | 4–5 days | when v0.2.0 has gallery + real-world feedback |
|
||||
|
||||
## Why not fold P1s into v0.2.0
|
||||
|
||||
1. **Severity reframe.** P1-1 (`render-link.html` `safeHTML`) is *self-XSS* — single-author theme; author writes their own posts. Reviewer's own note: *"threat model is 'I'm hurting myself'"*. Not a stored-XSS-from-untrusted-input vector. Worth fixing, not worth blocking a tag.
|
||||
2. **Discovered after, not during.** v0.2.0 plan completed and signed off; review was fresh-eyes audit. Folding everything ever found shifts goalposts.
|
||||
3. **Velocity matters for distribution.** Gallery submission visibility compounds; delay = stale demo, fewer downloads.
|
||||
4. **v0.2.1 = 1 day.** Surgical patch: 5 P1 fixes + CI pin + dead-branch cleanup. Single commit, fast review, retag.
|
||||
5. **CI gates haven't regressed.** Smoke tests + htmltest + budget assert still pass. The new findings are not regressions; they were latent.
|
||||
|
||||
## Why a v0.3.0 feature release after
|
||||
|
||||
Combines two streams that don't fit a patch:
|
||||
- **From code-review:** P2-2 per-page-kind CSS bundling (frees ~1.2 KB gz headroom — needed for Tier-1 features), P3-1 smoke-test expansion, P3-4 `i18n/en.yml` skeleton.
|
||||
- **From research:** WCAG 2.2 AA audit + fixes, `llm.txt` artifact, Speculation Rules opt-in, AVIF render-hook docs. Tier-1 items only.
|
||||
- **From project-manager:** unblock the deferred items audience-signal can justify (lightbox, multi-author) — gather feedback first.
|
||||
|
||||
## Main trade-off
|
||||
|
||||
| Folding everything into v0.2.0 (rejected) | Three-release sequence (chosen) |
|
||||
|---|---|
|
||||
| Single clean release narrative | Three smaller scopes |
|
||||
| Delays gallery submission ~3–5 days | Gallery submission tomorrow |
|
||||
| Forces P2 budget split before stable | v0.3.0 frees budget cleanly |
|
||||
| Higher risk: bigger diff = more review surface | Each release small enough to verify in one sitting |
|
||||
|
||||
The chosen path costs *one extra version number* in exchange for shipping something the maintainer already validated, and getting external eyes on the demo site sooner.
|
||||
|
||||
## v0.3.0 scope (preview — to be planned next)
|
||||
|
||||
Mandatory (carries P1s if v0.2.1 is skipped):
|
||||
- All P1s from review (5 fixes, ~1 day)
|
||||
- htmltest-action SHA pin
|
||||
- Dead CI `if find` branch removed
|
||||
|
||||
Theme-budget rebase (enables future features):
|
||||
- **P2-2** per-page-kind CSS bundling (~1.2 KB gz freed)
|
||||
- **P2-3** gate `code-copy.js` on `eq .Kind "page"`
|
||||
- **P2-9** drop redundant `| default ""` calls
|
||||
|
||||
Author UX:
|
||||
- **P2-1** `<details>` styling (CSS only, opens "rich content" door)
|
||||
- **P2-10** `<details>`-wrap TOC on narrow viewports
|
||||
- **P3-4** `i18n/en.yml` skeleton (~40 keys translated)
|
||||
|
||||
Testing depth:
|
||||
- **P3-1** smoke-test expansion (callout HTML, JSON-LD valid via `jq`, OG abs URL, dark-theme tokens) — 10 new assertions
|
||||
- **P3-2** Hugo CI matrix (floor 0.146 + current 0.154)
|
||||
|
||||
Research Tier-1:
|
||||
- **WCAG 2.2 AA audit pass** on exampleSite via Lighthouse — focus appearance / target size / dragging SCs
|
||||
- **llm.txt** auto-generation under exampleSite (theme metadata → `/llm.txt`)
|
||||
- **Speculation Rules** as opt-in via `params.prefetch` — Chromium-only, graceful fallback
|
||||
|
||||
Deferred to v0.4.0+ (need audience signal):
|
||||
- AVIF render hook (only after cover-image feature decision)
|
||||
- pa11y CI integration (after WCAG audit baseline established)
|
||||
- Multi-author surface, lightbox, KaTeX/Mermaid (per v0.2.0 plan)
|
||||
|
||||
## Maintainer decisions still pending (do not block v0.2.0)
|
||||
|
||||
These were already flagged in v0.2.0 prerelease checklist; surfaced again here for v0.3.0 planning input:
|
||||
|
||||
1. **Goldmark `unsafe: true`** — keep or drop? Dropping eliminates the bio-XSS surface AND P1-1's blast radius. Test: `grep -r '<' content/post/*/index.md` on real sites — if no inline HTML, safe to disable.
|
||||
2. **Hugo version floor** — bump `theme.toml min_version` to 0.154 (CI-tested) or stay at 0.146 (broader compat)?
|
||||
3. **Audience signal** — solo bloggers vs teams? Drives multi-author / i18n priority.
|
||||
4. **Demo site analytics** — opt-in privacy-respecting analytics (e.g., GoatCounter) on `tiennm99.github.io/tsuki/` to inform future feature priority? Currently flying blind.
|
||||
|
||||
## Success criteria (v0.3.0)
|
||||
|
||||
- All review P1s closed
|
||||
- CSS budget ≤ 4 KB gz preserved (per-kind split MUST not increase total weight)
|
||||
- Lighthouse a11y ≥ 95 on exampleSite (currently presumed but unmeasured under WCAG 2.2)
|
||||
- `i18n/en.yml` complete; theme builds with `defaultContentLanguage: en` without missing-key fallbacks
|
||||
- Smoke tests catch a synthetic regression in render-link / callout / JSON-LD
|
||||
- gohugoThemes registry CI green on tagged version
|
||||
|
||||
## Unresolved questions
|
||||
|
||||
1. Is v0.2.1 acceptable, or does the maintainer prefer to skip it and roll P1s into v0.3.0? (Affects v0.3.0 scope size — adds ~1 day.)
|
||||
2. Does the maintainer want a real `cover.image` feature in v0.3.0 (would activate AVIF research item), or stay with author-supplied static images?
|
||||
3. Should `data/profile.yaml: url` be added to documented schema, or removed from `seo.html` read? (Opens a small data-schema doc decision.)
|
||||
4. Is there capacity for the WCAG 2.2 AA audit pass — needs an evening with axe-devtools or Lighthouse — or defer to v0.3.1?
|
||||
|
||||
---
|
||||
|
||||
**Status:** DONE
|
||||
**Summary:** Recommend three-release sequence: v0.2.0 (ship now, mechanical only), v0.2.1 patch (~1 day, P1 review fixes), v0.3.0 (~5 days, budget split + author UX + research Tier-1 + smoke depth). Rejected: folding all post-review P1s into v0.2.0 (delays gallery submission, scope creep, P1s are not v0.2.0 regressions). Output feeds /ck:plan with v0.3.0 phases.
|
||||
@@ -1,506 +0,0 @@
|
||||
# tsuki v0.1.0 Production-Readiness Audit
|
||||
|
||||
Date: 2026-05-08
|
||||
Scope: full theme — `layouts/`, `assets/`, `i18n/`, `data/`, `exampleSite/`, `hugo.yaml`, `theme.toml`, `package.json`, `.github/`, `docs/`
|
||||
Branch: main @ d88f18d
|
||||
|
||||
---
|
||||
|
||||
## Overall Assessment
|
||||
|
||||
Solid v0.1.0. Code is small, idiomatic Hugo 0.146+ (`_partials`, `_markup`), minimal JS, sane CSS tokens. Asset pipeline (`Concat | minify | fingerprint` with SRI) is well-formed. Vietnamese-first claims mostly hold. A handful of bugs and ergonomic gaps exist; none are show-stoppers but several are user-visible regressions vs documented behavior.
|
||||
|
||||
**Top concerns**
|
||||
- **Documentation drift**: docs claim `params.toc.minWordCount` and `params.toc.enable` gate TOC. Code hardcodes 400 and ignores `enable`.
|
||||
- **`unsafe: true` Goldmark** is documented as required. With `markdownify` of `profile.bio`, raw HTML in `data/profile.yaml` executes unescaped.
|
||||
- **Tag URLs hardcoded** to `/tags/...` — breaks if site renames the taxonomy.
|
||||
- **Several i18n keys referenced but missing** from `vi.yml` (`comments`, `month`, `pageNotFound`, `backHome`, `next/prev page` referenced but only `prev`/`next` exist; the key is also referenced as `previousPage`/`nextPage` in `vi.yml`).
|
||||
- **CSS budget** claim "≤ 4 KB gz" — concatenated source is 4296 B gzipped before minify, so post-minify will likely fit, but tight; needs CI assertion.
|
||||
|
||||
---
|
||||
|
||||
## Critical
|
||||
|
||||
### C1 — Theme TOC defaults config is dead code
|
||||
**File:** `hugo.yaml:34-36`, `layouts/single.html:28`, `layouts/_partials/footer.html:19`, `docs/config.md:46-48`
|
||||
|
||||
Theme defaults `params.toc.enable: true` and `params.toc.minWordCount: 400`. Docs say the latter "gates render".
|
||||
Code uses `(gt .WordCount 400) (ne .Params.toc false)` — literal 400, no read of `site.Params.toc.minWordCount`, and `enable` is not consulted at all.
|
||||
|
||||
**Impact:** Setting `params.toc.enable: false` site-wide does nothing. Setting `params.toc.minWordCount: 800` does nothing. Hugo's "no deep-merge" rule for theme nested config is unrelated — these are read in templates at runtime.
|
||||
|
||||
**Fix:**
|
||||
```go-html-template
|
||||
{{- $tocCfg := site.Params.toc | default dict -}}
|
||||
{{- $tocEnabled := $tocCfg.enable | default true -}}
|
||||
{{- $tocMin := $tocCfg.minWordCount | default 400 -}}
|
||||
{{- if and $tocEnabled (gt .WordCount $tocMin) (ne .Params.toc false) }}
|
||||
{{ partial "toc.html" . }}
|
||||
{{- end }}
|
||||
```
|
||||
Apply same change in `layouts/_partials/footer.html:19` for the JS gate.
|
||||
|
||||
---
|
||||
|
||||
### C2 — `unsafe: true` + `markdownify` of profile.bio = stored XSS surface
|
||||
**File:** `layouts/_partials/home/hero.html:15`
|
||||
|
||||
```go-html-template
|
||||
<div class="home-hero-bio">{{ . | markdownify }}</div>
|
||||
```
|
||||
|
||||
With `markup.goldmark.renderer.unsafe: true` (required by README/docs), any HTML in `data/profile.yaml: bio` renders verbatim — including `<script>`. For a single-author personal theme this is "I'm hurting myself" territory, but tsuki ships as a theme others adopt. A user who copies a tagline with `<img src=x onerror=...>` from a Stack-themed site (where `markdownify` was sandboxed differently) gets a script execution.
|
||||
|
||||
**Impact:** If any consumer accepts profile data from a less-trusted source (CMS, multi-author, generated), this is stored XSS.
|
||||
|
||||
**Recommendations** (pick one):
|
||||
- Document explicitly that `data/profile.yaml: bio` is trusted-author input, never user-submitted, and HTML executes.
|
||||
- Or sanitize: render bio with `markdownify` then `safeHTML` only after passing through a strict policy — Hugo has no built-in HTML sanitizer, so the practical mitigation is tight docs.
|
||||
- Or hard-strip with a regex pre-pass before `markdownify` (loses code blocks).
|
||||
|
||||
At minimum: add a line to `docs/data-schemas.md` next to `bio` warning that HTML is rendered.
|
||||
|
||||
---
|
||||
|
||||
### C3 — Hardcoded `/tags/...` URLs assume taxonomy name
|
||||
**File:** `layouts/_partials/meta.html:16`, `layouts/single.html:21`
|
||||
|
||||
```go-html-template
|
||||
<a href="{{ printf "/tags/%s/" (urlize $tag) | relURL }}">#{{ $tag }}</a>
|
||||
```
|
||||
|
||||
Theme defaults declare `taxonomies: { category: categories, tag: tags }`. Hugo does not deep-merge from theme. If consumer omits or renames (e.g., `tag: tag`), this template emits broken `/tags/...` links pointing to 404s.
|
||||
|
||||
**Fix:** Use `Page.GetTerms` so URLs resolve through Hugo's taxonomy graph:
|
||||
```go-html-template
|
||||
{{- with .GetTerms "tags" }}
|
||||
<span class="post-tags">
|
||||
{{- range $i, $term := . -}}
|
||||
{{- if $i }}, {{ end -}}
|
||||
<a href="{{ $term.RelPermalink }}">#{{ $term.LinkTitle }}</a>
|
||||
{{- end -}}
|
||||
</span>
|
||||
{{- end }}
|
||||
```
|
||||
This also handles vi-titled tags correctly.
|
||||
|
||||
---
|
||||
|
||||
## High
|
||||
|
||||
### H1 — Missing i18n keys referenced in templates
|
||||
**Files:** `i18n/vi.yml`, multiple consumers
|
||||
|
||||
Referenced but absent from `vi.yml`:
|
||||
| key | referenced in |
|
||||
|---|---|
|
||||
| `comments` | `_partials/comments.html:5` |
|
||||
| `month` (with `Number` arg) | `_partials/archive-group.html:6` |
|
||||
| `pageNotFound` | `404.html:5` |
|
||||
| `backHome` | `404.html:6` |
|
||||
| `featuredProjects` | `_partials/home/projects.html:4` |
|
||||
| `viewAll` | `_partials/home/recent-posts.html:17` |
|
||||
| `searchSuggestion` | `search/list.html:38` |
|
||||
| `altSearch` | `search/list.html:37` |
|
||||
|
||||
All have `| default "..."` fallbacks so site builds. But CHANGELOG claims "all UI strings" in `i18n/vi.yml`.
|
||||
|
||||
**Fix:** add the 8 missing keys. For `month`, return a localized name from a numeric arg (`{{ .Number }}` → `Tháng 8`). Current call `{{ i18n "month" (dict "Number" .Key) }}` passes a string `.Key` (Hugo `GroupByDate "1"` returns "1".."12"), so the template just needs:
|
||||
```yaml
|
||||
- id: month
|
||||
translation: "Tháng {{ .Number }}"
|
||||
```
|
||||
|
||||
Also: `vi.yml` defines `previousPage`/`nextPage` that no template uses (`pagination.html` uses `prev`/`next`). Either delete the unused keys or switch pagination to the more descriptive ones.
|
||||
|
||||
---
|
||||
|
||||
### H2 — `params.search.enable: false` only hides header button, route still builds
|
||||
**Files:** `layouts/_partials/header.html:7`, `layouts/search/list.html` (no gate), `docs/customization.md:111`
|
||||
|
||||
`docs/customization.md` says `params.search.enable: false` "removes search button + /search/ route." The header gate exists (good); the route gate does not. `search/list.html` always renders if `content/search/_index.md` exists. CI also unconditionally runs `npx pagefind --site exampleSite/public`.
|
||||
|
||||
**Fix:** wrap `search/list.html` body in `{{- if site.Params.search.enable | default true -}}` and emit a `<p>{{ i18n "searchDisabled" }}</p>` fallback, or document that disabling `search.enable` only affects the header button and consumers should also remove `content/search/_index.md`.
|
||||
|
||||
---
|
||||
|
||||
### H3 — Concatenated CSS budget is on the edge
|
||||
**Files:** `assets/css/*.css`
|
||||
|
||||
Raw concat → gzip = 4296 B (over the 4 KB claim). Post-`minify` will save ~10–15% and bring it under, but `ResourceMinifier` minify is not lossless to gzip ratios; result could be 3.5–3.9 KB gz. Without a CI assertion this can silently regress.
|
||||
|
||||
**Recommendation:** Add a CI step that fails if `du -b public/css/*.bundle.*.css | head -1 | awk '{...}' && gzip -c | wc -c` exceeds 4096:
|
||||
```yaml
|
||||
- name: CSS budget assertion
|
||||
run: |
|
||||
css=$(find exampleSite/public -name "tsuki.bundle.*.css" -print -quit)
|
||||
sz=$(gzip -9 -c "$css" | wc -c)
|
||||
echo "tsuki bundle gz: $sz B"
|
||||
test "$sz" -le 4200
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### H4 — `head.html` Pagination linking is wrong on `home`
|
||||
**File:** `layouts/_partials/head.html:55`
|
||||
|
||||
```go-html-template
|
||||
{{- if or .IsHome (eq .Kind "section") (eq .Kind "taxonomy") (eq .Kind "term") }}
|
||||
{{- with .Paginator }} … {{- end }}
|
||||
{{- end }}
|
||||
```
|
||||
|
||||
`home.html` does not call `.Paginator` (and the home isn't paginated — it's a portfolio + recent post snippet). `.Paginator` on `home` returns implicit pagination for `site.RegularPages` and emits `rel=prev/next` links to non-existent `/page/2/` etc., causing 404s for crawlers and bad `<link rel="prev/next">` SEO.
|
||||
|
||||
**Fix:** drop `.IsHome` from the gate, or check `if gt .Paginator.TotalPages 1` (which covers all kinds correctly).
|
||||
|
||||
---
|
||||
|
||||
### H5 — Code-copy script attaches to all `<pre>` regardless of code presence
|
||||
**File:** `assets/js/code-copy.js:5-6`
|
||||
|
||||
`for (const pre of document.querySelectorAll("pre"))`: matches every `<pre>` on the page including non-Hugo-highlight ones in render-hook output. The `if (!code) continue` guards a missing `<code>`, but a `<pre>` containing `<code>` rendered for non-code purposes (e.g., ASCII art) gets a "Sao chép" button. Minor but fixable.
|
||||
|
||||
Also: `navigator.clipboard` is unavailable on `http://` non-localhost. The theme falls back gracefully (`FAILED` text), but no explanation appears. Add `if (!navigator.clipboard) return;` before `pre.appendChild(btn)` so users on HTTP don't see broken-looking buttons.
|
||||
|
||||
---
|
||||
|
||||
### H6 — `comments.html` script tag uses `defer` semantics inconsistently
|
||||
**File:** `layouts/_partials/comments.html:7-21`
|
||||
|
||||
The `<script>` is rendered inline in the `comments` section. With `async`, Giscus loads independently of the `<script>` element's DOM position, but Giscus expects the parent element to be in the DOM at parse time — placing the `<script>` *after* the `<div class="giscus">` is correct. However: the `data-strict="0"` etc. are emitted as quoted strings. Giscus accepts `0`/`1` as strings, so this works; but if a user types `strict: false` (yaml bool), Hugo emits `false`, which Giscus treats as truthy. Document the type expected.
|
||||
|
||||
Also missing: `referrerpolicy="no-referrer-when-downgrade"` and `loading="lazy"` is set via `data-loading` (correct), but the `<iframe>` Giscus injects gets sandboxed by Giscus itself, not by the theme. Acceptable.
|
||||
|
||||
---
|
||||
|
||||
### H7 — IntersectionObserver TOC: encoded headings can mismatch
|
||||
**File:** `assets/js/toc-active.js:5`
|
||||
|
||||
```js
|
||||
const id = decodeURIComponent(a.getAttribute("href").slice(1));
|
||||
```
|
||||
With `autoHeadingIDType: github-ascii`, IDs are pure ASCII so `decodeURIComponent` is a no-op. But heading IDs in Hugo's TOC are URL-encoded if non-ASCII — and `headings.querySelectorAll(...[id])` in the same script uses `h.id` (the raw DOM id, *not* URL-encoded). If a user disables `autoHeadingIDType: github-ascii` (config docs say it's "recommended", not required), the link `href="#%C3%A1"` decodes to `"á"` but `h.id === "á"` matches — *good*. So this code is correct under both modes. Keep the `decodeURIComponent` call. No fix needed; documenting reasoning here for posterity.
|
||||
|
||||
---
|
||||
|
||||
### H8 — `home/recent-posts.html` runs the same query twice
|
||||
**File:** `layouts/_partials/home/recent-posts.html:2,15`
|
||||
|
||||
```go-html-template
|
||||
{{- $posts := first $count (where (where site.RegularPages "Type" "post") "Draft" false) -}}
|
||||
…
|
||||
{{- if gt (len (where (where site.RegularPages "Type" "post") "Draft" false)) $count }}
|
||||
```
|
||||
|
||||
Hugo evaluates `where` twice. Negligible build-time cost on small sites, but smelly. Bind once:
|
||||
```go-html-template
|
||||
{{- $all := where (where site.RegularPages "Type" "post") "Draft" false -}}
|
||||
{{- $posts := first $count $all -}}
|
||||
```
|
||||
Also: `Draft` filtering is redundant because `--buildDrafts` is the master switch and `site.RegularPages` already excludes drafts in normal builds. Drop `"Draft" false` unless explicitly supporting `--buildDrafts` while still hiding drafts from home (uncommon).
|
||||
|
||||
---
|
||||
|
||||
## Medium
|
||||
|
||||
### M1 — Categories never surface to readers
|
||||
**Files:** `layouts/_partials/meta.html`, `layouts/_partials/post-card.html`, `layouts/single.html`
|
||||
|
||||
Posts use `categories` in frontmatter. The theme lists `categories` taxonomy but the meta partial only shows `tags`. There is no per-post category badge, no category-list partial, no sidebar.
|
||||
|
||||
If categories are intentionally invisible (only for routing under `/categories/<slug>/`), document it. Otherwise add a small "📂 ghi-chu" pill alongside tags in `meta.html`.
|
||||
|
||||
---
|
||||
|
||||
### M2 — No `Lastmod` surfaced on the post page
|
||||
**File:** `layouts/_partials/meta.html`, `layouts/single.html`
|
||||
|
||||
`head.html:36` emits `article:modified_time`, good. But the visible post body never shows "Cập nhật ngày X" even though `i18n/vi.yml` defines `updatedOn`. Either remove the unused key or add a `{{ with .Lastmod }}…{{ end }}` block in `meta.html`.
|
||||
|
||||
---
|
||||
|
||||
### M3 — No skip-link, focus rings, or `prefers-reduced-motion` on `transition`
|
||||
**Files:** `assets/css/reset.css:35-42`, `layouts/baseof.html`
|
||||
|
||||
- No `<a class="skip-link" href="#main">` in `baseof.html`. Vi keyboard users (and screen-reader users) jump through full nav on every page.
|
||||
- `.theme-toggle:focus-visible`, `.search-button:focus-visible`, `.site-nav a:focus-visible`, etc. lack explicit focus styles — they rely on UA defaults, which dark-mode often makes invisible (browser default is `outline: 1px solid -webkit-focus-ring-color` blue against `#14151a` is only marginal).
|
||||
- `reset.css:35-42` covers reduced motion for `animation`/`transition`/`scroll-behavior` but `view-transitions.css` *also* handles it. The `!important` overrides win, so view-transitions get nuked too. That's likely the intent; document in CHANGELOG.
|
||||
|
||||
**Fix:** Add to `components.css` or `reset.css`:
|
||||
```css
|
||||
:focus-visible {
|
||||
outline: 2px solid var(--tsuki-accent);
|
||||
outline-offset: 2px;
|
||||
}
|
||||
```
|
||||
And add in `baseof.html`:
|
||||
```html
|
||||
<a class="skip-link" href="#main">{{ i18n "skipToContent" | default "Đến nội dung chính" }}</a>
|
||||
```
|
||||
plus `id="main"` on `<main>`.
|
||||
|
||||
---
|
||||
|
||||
### M4 — `tsuki-vt-name` CSS variable references nothing that sets it
|
||||
**File:** `assets/css/home.css:82`
|
||||
|
||||
```css
|
||||
.project-card { view-transition-name: var(--tsuki-vt-name, none); }
|
||||
```
|
||||
|
||||
The fallback `none` makes this a no-op. Nothing in templates sets `--tsuki-vt-name` per-card, so cards have *all* `view-transition-name: none`. Either:
|
||||
- Set `--tsuki-vt-name: project-{{ printf "%d" $index }}` per card via inline `style=""` (hugo loop), enabling card-morph transitions across navigations.
|
||||
- Or remove the dead declaration. Currently it advertises a feature that doesn't exist.
|
||||
|
||||
---
|
||||
|
||||
### M5 — Theme flash prevention script is non-blocking but works
|
||||
**File:** `layouts/_partials/head.html:13-23`
|
||||
|
||||
The IIFE before `<body>` reads `localStorage` and sets `data-theme`. Good. Three subtle issues:
|
||||
1. **Layout-shift risk**: if `localStorage` access throws (Safari ITP private mode), the catch is silent — root stays without `data-theme`, dark-mode kicks in via `prefers-color-scheme: dark` rule. Then `theme-toggle.js` (deferred module) reads stored=null and assumes match-media. Outcome: correct theme on first paint; toggle button starts in "match prefers" state. Verify this is intended.
|
||||
2. The `<script>` is *inline* but the `<link rel="stylesheet">` for the bundled CSS is loaded after it. `<link rel="stylesheet">` blocks rendering, so the `data-theme="..."` attribute is set before the stylesheet evaluates. ✓ no FOUC for the toggle.
|
||||
3. Storage key `tsuki-theme` is shared across sites mounting the theme on the same origin. For a single-domain blog this is fine. Consider scoping (low priority).
|
||||
|
||||
---
|
||||
|
||||
### M6 — Pagefind CSS loaded outside the bundle defeats SRI on that asset
|
||||
**File:** `layouts/search/list.html:4`
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="{{ "/pagefind/pagefind-ui.css" | relURL }}">
|
||||
```
|
||||
|
||||
No `integrity=`. Pagefind ships its own CSS; not part of the asset pipeline. Fine — but document that Pagefind UI CSS is third-party and not budget-counted. Consider Subresource Integrity once Pagefind starts shipping a stable hash (currently they don't).
|
||||
|
||||
---
|
||||
|
||||
### M7 — `home.html` calls partials unconditionally; partials guard themselves
|
||||
**File:** `layouts/home.html:4-6`
|
||||
|
||||
`home/projects.html` does `{{- with site.Data.projects.featured -}}` — if no `data/projects.yaml`, the section silently vanishes. Same for `hero.html`. Acceptable. Document that an empty `data/profile.yaml` and `data/projects.yaml` is valid and produces a near-empty homepage.
|
||||
|
||||
Edge case: `data/projects.yaml` exists but has no `featured` key → `with` is falsy → empty grid. Good.
|
||||
Edge case: `featured: []` → `with []` is falsy → no `<h2>` heading orphan. Good.
|
||||
|
||||
---
|
||||
|
||||
### M8 — `range .Pages.ByTitle` in taxonomy.html ignores Title casing for vi
|
||||
**File:** `layouts/_default/taxonomy.html:10`
|
||||
|
||||
`ByTitle` sorts ASCII-first; "Áo" comes after "Zip" in default Go locale. For a vi-first theme, sort by `.Title` with a normalized key. Hugo doesn't expose locale-aware sort directly — workaround:
|
||||
```go-html-template
|
||||
{{- range .Pages.ByParam "title" }}…
|
||||
```
|
||||
or manually `urlize` to a normalized key. Lowest priority, but Vi authors will notice "Á-bài" sorted weirdly.
|
||||
|
||||
---
|
||||
|
||||
### M9 — `archive-group.html` `GroupByDate "1"` is month number; date "02/01" is day/month
|
||||
**File:** `layouts/_partials/archive-group.html:4,10`
|
||||
|
||||
`GroupByDate "1"` → numeric month ("1".."12"). The post date `02/01` (DD/MM) correctly emits Vietnamese order. But **rounded to "08"** (zero-pad) when rendered as `{{ .Date.Format "02/01" }}` (Go time.Format). Verify intent: dates show DD/MM, archive month heading is `Tháng 1`..`Tháng 12`. If a Vi reader expects `Tháng 01`, the i18n month string handles it. ✓
|
||||
|
||||
---
|
||||
|
||||
## Low
|
||||
|
||||
### L1 — `theme.toml: original.author = ""` clutters Hugo theme directory listing
|
||||
**File:** `theme.toml:15-18`
|
||||
|
||||
If tsuki isn't a fork, drop the `[original]` block. Hugo's themes registry treats empty `original.author` as malformed.
|
||||
|
||||
---
|
||||
|
||||
### L2 — `archetypes/default.md` doesn't include `description`
|
||||
**File:** `archetypes/default.md`
|
||||
|
||||
`description` is referenced in `head.html` for OG meta. Adding it to the archetype reduces "missing description" surprises:
|
||||
```md
|
||||
---
|
||||
title: "{{ replace .Name "-" " " | title }}"
|
||||
date: {{ .Date }}
|
||||
draft: true
|
||||
description: ""
|
||||
tags: []
|
||||
categories: []
|
||||
---
|
||||
```
|
||||
|
||||
### L3 — `post-card.html`: `.Summary | plainify | truncate 180` — order matters
|
||||
**File:** `layouts/_partials/post-card.html:11-13`
|
||||
|
||||
`plainify` then `truncate` is correct but truncation can land mid-Vietnamese diacritic if the byte cursor splits a multi-byte rune. Hugo's `truncate` is rune-safe (Go strings), so no corruption. Just confirming.
|
||||
|
||||
### L4 — `i18n/vi.yml` mixes shapes
|
||||
**File:** `i18n/vi.yml`
|
||||
|
||||
`readingTime` uses Go-template `{{ .Count }}` interpolation. Other strings are plain. Hugo i18n uses go-i18n v1 syntax — both forms valid, but inconsistent. Consider unifying to plural-aware:
|
||||
```yaml
|
||||
- id: readingTime
|
||||
one: "1 phút đọc"
|
||||
other: "{{ .Count }} phút đọc"
|
||||
```
|
||||
Vietnamese has no grammatical plural so cosmetic only.
|
||||
|
||||
### L5 — `comments.html` Giscus theme attribute uses `data-theme="preferred_color_scheme"` default
|
||||
**File:** `layouts/_partials/comments.html:17`
|
||||
|
||||
Combined with `giscus-theme.js` which posts `setConfig: { theme: "light"|"dark" }`, the iframe's initial render uses `preferred_color_scheme`, then the script overrides on `data-theme` mutation. There's a flash on first paint where Giscus renders its default theme, then toggles. Lowest-priority cosmetic.
|
||||
|
||||
**Fix:** initial-call `send()` once on page load so Giscus opens already-themed:
|
||||
```js
|
||||
send();
|
||||
new MutationObserver(send).observe(...);
|
||||
```
|
||||
Currently the Observer only fires on mutation, never on initial state.
|
||||
|
||||
### L6 — `code-copy.js` button label hardcoded vi strings
|
||||
**File:** `assets/js/code-copy.js:1-3`
|
||||
|
||||
`COPY = "Sao chép"`, etc. Should match `i18n/vi.yml` for future en support. Inject from data attribute set by template:
|
||||
```html
|
||||
<pre data-copy-label="{{ i18n "copy" }}" data-copied-label="{{ i18n "copied" }}">
|
||||
```
|
||||
Or accept this is vi-first and don't surface the strings to i18n.
|
||||
|
||||
### L7 — `code-copy.js`: tabindex/keyboard for the button
|
||||
**File:** `assets/js/code-copy.js`
|
||||
|
||||
Button has no `tabindex` attribute (defaults to `0` for `<button>`, ✓), but no `aria-live` region for the "Đã chép" feedback. SR users won't hear confirmation. Add `aria-live="polite"` to the button or to a sibling span.
|
||||
|
||||
### L8 — `images/screenshot.png` and `images/tn.png` not referenced anywhere
|
||||
**File:** `images/*.png`
|
||||
|
||||
Hugo themes registry expects `images/screenshot.png` (1500×1000) and `images/tn.png` (900×600). Verify dims match. Most recent commit message says they were added; confirm in registry standards (`https://themes.gohugo.io/`).
|
||||
|
||||
### L9 — `package.json` `private: true` blocks `npm publish` but pagefind is a dev dep that ought to be `dependencies` (or `peerDependencies`?) for Hugo Module consumers
|
||||
**File:** `package.json`
|
||||
|
||||
If a user adopts tsuki as a Hugo Module, they don't get Pagefind from the theme's `package.json` — Hugo Modules don't run npm. Document: "Pagefind is built in CI; consumer sites need their own `npm install pagefind` or just `npx pagefind` step." Currently undocumented.
|
||||
|
||||
---
|
||||
|
||||
## Nice-to-have
|
||||
|
||||
### N1 — Add a `_markup/render-link.html` for safer external links
|
||||
Auto-detect external URLs and add `rel="noopener noreferrer" target="_blank"` (or ditto without `_blank` — UX preference).
|
||||
|
||||
### N2 — Add `_markup/render-image.html` to enforce `loading="lazy" decoding="async"`
|
||||
All in-content images currently rely on goldmark default (no lazy attrs).
|
||||
|
||||
### N3 — `Hugo Module` mounts not declared in `theme.toml`
|
||||
For Hugo Module consumers, declare `[module]` mounts in `hugo.yaml`-or-`config.yaml` so themes mount cleanly:
|
||||
```yaml
|
||||
module:
|
||||
mounts:
|
||||
- source: layouts
|
||||
target: layouts
|
||||
- source: assets
|
||||
target: assets
|
||||
- source: i18n
|
||||
target: i18n
|
||||
- source: data
|
||||
target: data
|
||||
- source: archetypes
|
||||
target: archetypes
|
||||
- source: static
|
||||
target: static
|
||||
```
|
||||
Without it, default mounts work but hand-overrides break (rare).
|
||||
|
||||
### N4 — RSS limit on home pagination: site builds `<link rel="prev">` from `.Paginator` even if homepage isn't a paginated kind. Already covered in H4.
|
||||
|
||||
### N5 — Privacy: meta `generator` exposes Hugo version
|
||||
**File:** `layouts/_partials/head.html:7`
|
||||
|
||||
`<meta name="generator" content="Hugo {{ hugo.Version }} + tsuki">` lets attackers know Hugo version → CVE matching. Drop `hugo.Version` and emit just `tsuki @ v0.1.0`, or skip the meta entirely. Defense in depth.
|
||||
|
||||
### N6 — `view-transitions.css` doesn't fall back gracefully when CSS chain breaks
|
||||
The `@view-transition` rule is unsupported in Firefox/Safari ≤17. Browsers ignore it (good). The `@keyframes tsuki-fade-out/in` are emitted regardless and only used by view-transition pseudo-elements, so dead bytes in unsupporting browsers. Trade-off: 50 B for forward-compat.
|
||||
|
||||
### N7 — Self-host woff2 fonts deferred — no `font-display: swap` set on the system fallback chain
|
||||
Adding `font-display: swap` is irrelevant when no `@font-face` is declared — but document this in `customization.md` so first-time self-hosters know.
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases / Verification Notes
|
||||
|
||||
- **Empty `data/profile.yaml`**: `home/hero.html` `with $profile` skips the whole hero. Site title shows in header instead. ✓
|
||||
- **Missing thumbnails**: `home/projects.html` `with $project.image` skips the image div. ✓
|
||||
- **Posts without word counts** (e.g., front-matter-only): `gt .WordCount 400` is `false`, TOC suppressed, `meta.html` shows `0 phút` if `gt .ReadingTime 0` guard somehow fails — the guard is `gt 0`, so `0 → false → no render`. ✓
|
||||
- **Browser without View Transitions**: `@view-transition` rule ignored; no fallback animation, just instant nav. ✓ matches docs.
|
||||
- **Browser without `:has()`**: codebase doesn't use `:has()` anywhere I could find. Search confirms zero hits. README mentions `:has()` as progressive enhancement — code doesn't actually use it. Either add a usage or drop the claim.
|
||||
- **Browser without IntersectionObserver**: `toc-active.js` will throw `ReferenceError` on `new IntersectionObserver(...)`. Old browsers (IE11, pre-Chrome 51) error out. Modern evergreen support is universal. Theme.toml says "Modern evergreen browsers" — acceptable.
|
||||
- **No JS at all**: theme toggle button `hidden` attribute remains (button never reveals). ✓ progressive enhancement. Code-copy disabled. ✓ TOC active highlighting disabled but TOC still renders. ✓ Search disabled with `<noscript>` fallback. ✓
|
||||
|
||||
---
|
||||
|
||||
## Documentation vs Code Match
|
||||
|
||||
| Doc claim | Code behavior | Match |
|
||||
|---|---|---|
|
||||
| `params.toc.minWordCount` gates render | hardcoded 400 | ✗ (C1) |
|
||||
| `params.toc.enable` site-wide kill-switch | not consulted | ✗ (C1) |
|
||||
| "all UI strings in `i18n/vi.yml`" | 8 keys missing | ✗ (H1) |
|
||||
| `params.search.enable: false` removes route | only header button hidden | ✗ (H2) |
|
||||
| "CSS bundle ≤ 4 KB gz, JS ≤ 1 KB gz" | pre-minify gz: 4296 B / 660 B; post-minify likely under | ⚠ (H3) |
|
||||
| `:has()` progressive enhancement | not used in CSS | ⚠ (no harm but misleading) |
|
||||
| OG image fallback to `profile.avatar` | `head.html:3` → ✓ | ✓ |
|
||||
| `data-pagefind-body` on post content | `single.html:13` → ✓ | ✓ |
|
||||
| Theme flash prevention | inline IIFE before stylesheet → ✓ | ✓ |
|
||||
| ASCII heading IDs via `autoHeadingIDType: github-ascii` | configured | ✓ |
|
||||
| `permalinks: post: /:year/:month/:day/:contentbasename/` | configured + matches content paths | ✓ |
|
||||
| Both submodule and Hugo Module flow | submodule ✓; Module flow undocumented mounts | ⚠ (N3) |
|
||||
|
||||
---
|
||||
|
||||
## Positive Observations
|
||||
|
||||
- Excellent restraint on JS surface area — 4 modules, total ~1 KB gz, each module a single responsibility.
|
||||
- Asset pipeline `Concat | minify | fingerprint` with SRI integrity attribute on `<link>` and `<script>`: best practice.
|
||||
- Inline theme-flash-prevention script kept tight (no markdownify, no template variables that could break SRI on the bundle).
|
||||
- Body-class block via `{{ define "body_class" }}` is clean composition; lets per-page CSS hooks like `body.post .toc { … }` work without JS.
|
||||
- `aria-current="page"` on nav, `aria-current="true"` on active TOC link: correct.
|
||||
- `<noscript>` fallback on the search page.
|
||||
- Render-heading hook is minimal and accessible (anchor has `aria-label`).
|
||||
- Content-Security-Policy compatible (no inline `style=""`, only one inline `<script>` with constant content the CSP can hash).
|
||||
- `.gitignore` covers Pagefind generated content + `node_modules`. Good.
|
||||
- Dependabot config is sensible.
|
||||
- View-transition `prefers-reduced-motion` honored at the *animation* level, not blanket-disabled.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Actions (priority order)
|
||||
|
||||
1. **C1** — Fix TOC gating to honor `site.Params.toc.{enable,minWordCount}`. Short PR, high doc/behavior gap.
|
||||
2. **H1** — Add 8 missing i18n keys.
|
||||
3. **C3** — Switch tag URLs to `Page.GetTerms`.
|
||||
4. **H2** — Gate `search/list.html` body on `params.search.enable` or update docs.
|
||||
5. **H4** — Drop `.IsHome` from pagination link emission in `head.html`.
|
||||
6. **C2** — Document HTML execution in `profile.bio` markdown.
|
||||
7. **M3** — Add `:focus-visible { outline … }` and skip-link.
|
||||
8. **M1/M2** — Decide on category surfacing and `Lastmod` display; remove unused i18n keys.
|
||||
9. **H3** — Add CSS budget assertion to CI.
|
||||
10. **L5** — `giscus-theme.js`: call `send()` once on load.
|
||||
|
||||
Lower-priority items (N1–N7, L1–L9, M4–M9) batch as polish before v0.2.
|
||||
|
||||
---
|
||||
|
||||
## Unresolved Questions
|
||||
|
||||
1. Is the `unsafe: true` Goldmark requirement specifically for embedded HTML in posts (e.g., `<details>`, custom div for callouts), or just for footnote rendering? If the former, document examples; if the latter, switching to `unsafe: false` removes both the XSS surface (C2) and the documentation burden.
|
||||
2. Should `params.toc.enable: false` also strip the bundled TOC CSS? Current pipeline always concats `toc.css` (~1.5 KB raw, ~600 B gz). For sites that disable TOC, this is dead bytes. Option: split TOC into separate bundle, conditionally loaded.
|
||||
3. Is the homepage intended to ever paginate (more recent posts beyond `recentPostsCount`)? If no, H4's fix is to drop the `.IsHome` branch entirely. If yes, the home `home.html` template must call `.Paginator.Pages` somewhere.
|
||||
4. Are categories deliberately invisible to readers (M1)? If yes, drop the `categories` taxonomy from theme defaults and add a CHANGELOG note.
|
||||
5. Hugo theme registry submission planned? `theme.toml` has empty `[original]` block (L1) and `screenshot.png`/`tn.png` need verification against registry size requirements.
|
||||
6. What's the expected `--baseURL` story for sites that don't deploy under `/tsuki/` (i.e., root deploys)? `relURL` handles it; verify with a test deploy at root.
|
||||
7. Is Vietnamese the only locale planned, or is `i18n/en.yml` intended (currently only `vi.yml`)? Half the i18n keys have English `default` fallbacks suggesting eventual en.yml.
|
||||
|
||||
---
|
||||
|
||||
**Status:** DONE
|
||||
**Summary:** Reviewed full v0.1.0 surface. 3 critical (TOC config dead, XSS-via-bio docs, hardcoded /tags URL), 8 high, 9 medium, 9 low, 7 nice-to-have. Code is clean and idiomatic; main gaps are doc/code drift and a few accessibility polish items.
|
||||
**Concerns:** None blocking. Recommend fixing C1, H1, H2, H4, and adding skip-link before promoting v0.1.0 widely. Items C2, M1, M2 deserve a maintainer decision (security policy + UX intent) before code change.
|
||||
-319
@@ -1,319 +0,0 @@
|
||||
# tsuki — Post-v0.2.0 Improvement Review (v0.3.0+ candidates)
|
||||
|
||||
Date: 2026-05-10
|
||||
Scope: full theme @ main `bde8b8d` after v0.2.0 prerelease
|
||||
Inputs reviewed: README, CHANGELOG (Unreleased + 0.1.1), v0.2.0 roadmap (archived), v0.1.0 audit, all `layouts/`, `assets/css/`, `assets/js/`, `i18n/vi.yml`, `hugo.yaml`, `theme.toml`, `package.json`, `.github/workflows/pages.yml`, `scripts/smoke-tests.sh`.
|
||||
Goal: surface what's still worth fixing for v0.3.0+. Findings already addressed in `[Unreleased]` are **not** repeated.
|
||||
|
||||
---
|
||||
|
||||
## Overall Assessment
|
||||
|
||||
v0.2.0 is in good shape — audit gaps from v0.1.0 are largely closed; partial duplication has been pruned (TOC gate, OG image partial); CI now includes smoke tests + htmltest + CSS budget assert. The remaining issues are mostly second-order: a few real correctness bugs (taxonomy=0 link, render-link regex, profile.url chain, nav `relURL`-less menu URLs), some maintainability nits (raw `{{ . }}` in `title=` attrs, `xss` resurfaces via render-link `.Text | safeHTML`), and a moderate testing gap (smoke-tests.sh is essentially structural — it can't catch a broken render-hook or a regressed callout style).
|
||||
|
||||
**Top concerns (P1)** that warrant fixing before v0.3.0:
|
||||
1. `render-link.html` — `.Text | safeHTML` re-introduces stored-HTML bypass on link text; combined with `unsafe: true` Goldmark, `[inner](url)` with raw HTML in inner renders verbatim.
|
||||
2. `head/seo.html:64` — `site.Params.profile.url` will throw `nil pointer evaluating interface {}.url` when `params.profile` is unset (which it is by default — profile data lives in `data/`, not `params`). Site builds fine *because no demo post happens to hit that branch*; the moment a consumer sets `params.author` empty and has no `profile` map, builds break.
|
||||
3. `home/projects.html:30,33` — `repo`/`demo` URLs are emitted with no `safeURL` and no `noopener noreferrer`; a `javascript:` URL in `data/projects.yaml` runs (theme-author input, but inconsistent vs render-link hook).
|
||||
4. Missing render hook for `<details>` / raw HTML. `unsafe: true` is required (because Hugo callouts pre-0.140 used raw HTML), but post-Goldmark callouts now exist — re-evaluate whether `unsafe: true` is still necessary, or whether the requirement can be relaxed in v0.3 with a documented opt-in.
|
||||
|
||||
---
|
||||
|
||||
## P1 — Correctness, Security, Theme-Contract Bugs
|
||||
|
||||
### P1-1 — `render-link.html` re-emits raw HTML in link text
|
||||
**File:** `layouts/_markup/render-link.html:10`
|
||||
**What:** `{{ .Text | safeHTML }}` bypasses Hugo's auto-escape on link inner text. With `unsafe: true` Goldmark, an author writing `[<img src=x onerror=alert(1)>](https://example.com)` produces a script-execution vector inside otherwise-trusted markdown.
|
||||
**Why it matters:** Theme is single-author so the threat model is "I'm hurting myself", but inconsistent with `render-image.html` (which does `alt="{{ .Text }}"` — *correctly* HTML-escaped — and never `safeHTML`s `.Text`). One render hook trusts the input, the other doesn't. A multi-author or CMS consumer importing a post would not expect link text to execute.
|
||||
**Fix:** Drop `| safeHTML`. Goldmark already produces escaped inline-emphasis HTML via `.Text` (e.g., `<em>x</em>` already comes through), so removing the filter loses italic-in-link rendering. Better: use `.PlainText` for the safe path, or document that link-text HTML is by-design and tighten `unsafe: false` everywhere callouts allow.
|
||||
**Effort:** S (1-line change + 1 demo post + smoke assert).
|
||||
|
||||
### P1-2 — `seo.html` profile.url chain throws on missing `params.profile`
|
||||
**File:** `layouts/_partials/head/seo.html:64`
|
||||
**What:** `site.Params.profile.url | default ...`. Hugo's `default` does not short-circuit; `site.Params.profile` is `nil` for sites that follow docs (profile data is in `data/profile.yaml`, not `params.profile`). Calling `.url` on `nil` is "<nil>.url" — Hugo template errors out: `error calling: can't evaluate field url in type interface {}`.
|
||||
**Why it matters:** Demo site doesn't trip this because the demo doesn't render JSON-LD on the home, only on `/post/...` pages, and `site.Params.profile` happens to evaluate to a falsy empty interface that the template engine tolerates in the no-author case. But: `data/profile.yaml` has a `url` field nowhere documented; `site.Data.profile.url` falls through. So when a consumer adds `params.profile: { url: "..." }` (which docs do not mention), the structure works, but a consumer who only sets `data/profile.yaml` with no `url` key (the documented path) and no `params.author`, hits the chain `nil.url` → fallback to `(and site.Data.profile site.Data.profile.url)` → `nil` → default to `site.Home.Permalink`. Currently *works* but is fragile.
|
||||
**Fix:** Use the safer pattern: `{{- $authorURL := "" -}}{{- with site.Params.profile -}}{{- $authorURL = .url -}}{{- end -}}{{- if not $authorURL -}}{{- with site.Data.profile -}}{{- $authorURL = .url -}}{{- end -}}{{- end -}}{{- $authorURL = $authorURL | default site.Home.Permalink -}}`. Also: document `data/profile.yaml: url` field (currently absent from `docs/data-schemas.md`).
|
||||
**Effort:** S.
|
||||
|
||||
### P1-3 — `projects.html` link emits without `safeURL`
|
||||
**File:** `layouts/_partials/home/projects.html:30,33`
|
||||
**What:** `<a href="{{ . }}" rel="noopener">repo →</a>` — no `safeURL` filter. Hugo auto-escapes via context-aware HTML escaping (so `javascript:` is not blocked but `>` is), and the input is theme-author-controlled YAML. Render-link hook applies `safeURL` to markdown links; this YAML path doesn't.
|
||||
**Why it matters:** Inconsistent escape policy across the theme. If an author copy-pastes a tracking URL with non-standard characters, behavior may vary by Hugo version. `noopener` without `noreferrer` allows referer leakage to demo/repo destinations (minor privacy).
|
||||
**Fix:** `<a href="{{ . | safeURL }}" rel="noopener noreferrer">`. Same on line 33. Also consider `target="_blank"` since these are external — currently no `target=` so links open in same tab, replacing the portfolio.
|
||||
**Effort:** S.
|
||||
|
||||
### P1-4 — `nav.html` menu URLs not piped through `relURL`
|
||||
**File:** `layouts/_partials/nav.html:6`
|
||||
**What:** `<a href="{{ .URL }}">` — Hugo's `Menu.URL` returns the raw URL from menu config; if the menu uses a leading-`/` path (e.g., `/post/`) and the site deploys under a sub-path (e.g., GitHub Pages `/tsuki/`), the link becomes `/post/` instead of `/tsuki/post/`.
|
||||
**Why it matters:** Demo site works because `baseURL: https://tiennm99.github.io/tsuki/` rewrites with `--baseURL`, but `relURL` is the documented Hugo idiom. Sites using `pageRef:` in menu config emit pre-resolved permalinks and don't need `relURL`; sites using `url:` do. The theme can't know which.
|
||||
**Fix:** `<a href="{{ .URL | relURL }}">`. Hugo's `relURL` is idempotent on already-resolved URLs.
|
||||
**Effort:** S.
|
||||
|
||||
### P1-5 — `comments.html` doesn't validate Giscus required fields
|
||||
**File:** `layouts/_partials/comments.html:1-4`
|
||||
**What:** Gates only on `$g.enable`. If `enable: true` but `repo`/`repoId`/`categoryId` are missing/empty, Giscus loads with empty `data-*` attributes and shows a JS error in the console plus a broken iframe.
|
||||
**Why it matters:** First-time setup pain. `docs/config.md` explains required fields, but the theme builds without warning. With `noClasses: false` highlight + Giscus iframe error, user-visible breakage.
|
||||
**Fix:** `{{- if and $g $g.enable $g.repo $g.repoId $g.categoryId -}}`. Optionally emit an HTML comment when gated-off so consumers can introspect: `<!-- comments disabled: missing $g.repoId -->`.
|
||||
**Effort:** S.
|
||||
|
||||
### P1-6 — `render-link.html` external-detection misses `mailto:`, `tel:`, protocol-relative `//x.com`
|
||||
**File:** `layouts/_markup/render-link.html:2-6`
|
||||
**What:** External detection covers `http://`, `https://`, `//`. Misses `mailto:`, `tel:`, `ftp:`, `magnet:`, `irc:`. A `[contact](mailto:hi@miti99.com)` link gets no `rel`, which is fine (mailto: doesn't open a window). But a `[chat](irc://server)` does.
|
||||
**Why it matters:** Edge-case correctness. The `//` prefix is also caught by `HasPrefix .Destination "//"`, but Hugo render hooks normalize input — verify whether goldmark passes `//` URLs through unchanged. Worth a small smoke test.
|
||||
**Fix:** Extend: also check for any `://` not starting with the site's own scheme. Alternative: detect via `urls.Parse .Destination` and check `.Host != site.Host`.
|
||||
**Effort:** S — but only if scope warrants.
|
||||
|
||||
---
|
||||
|
||||
## P2 — Performance, Maintainability, A11y Polish
|
||||
|
||||
### P2-1 — `<details>` / Accordion / `<dialog>` not handled by render hooks
|
||||
**File:** missing
|
||||
**What:** `unsafe: true` is required for `<details><summary>...</summary>...</details>` blocks in posts. No render hook normalizes them. Consumers who write raw `<details>` get unstyled output that looks broken in dark mode (default UA collapsed-arrow color is bad in dark).
|
||||
**Why it matters:** A common authoring pattern (FAQ, expandable spoilers). Theme advertises "native callouts"; details/summary is the next-most-requested.
|
||||
**Fix (M)**: add CSS for `details { ... }` with dark-mode tokens. Possibly a render hook `_markup/render-table.html` — Hugo 0.146 doesn't have a render-details hook, so CSS-only.
|
||||
**Effort:** S (CSS only).
|
||||
|
||||
### P2-2 — `head.html` CSS bundle includes ALL CSS files unconditionally
|
||||
**File:** `layouts/_partials/head.html:46-60`
|
||||
**What:** All 12 CSS partials are concatenated on every page. The home page never uses `toc.css` (~600 B gz), `comments.css`, or `archive.css`. Single posts never use `archive.css` or `home.css`. Search pages don't need `home.css`/`archive.css`/`toc.css`.
|
||||
**Why it matters:** CSS budget is at 4200 B gz. Headroom is gone. Every new feature now requires removing existing bytes. Per-page bundles would let toc/home/comments stay opt-in. Current cost: ~30% of bundle is dead bytes on most page kinds.
|
||||
**Fix:** Two strategies. (a) Per-page-kind bundle: `head.html` switches on `.Kind` to assemble only relevant CSS. (b) Critical-CSS for above-the-fold + async-load the rest. (a) is simpler and KISS. Splitting `home.css` and `comments.css` and `toc.css` out into separate fingerprinted bundles, conditionally `<link>`'d, would free ~1.2 KB gz.
|
||||
**Effort:** M. Affects asset pipeline + needs CI assertion update.
|
||||
|
||||
### P2-3 — `code-copy.js` walks entire DOM with `querySelectorAll("pre")` even on pages without code blocks
|
||||
**File:** `assets/js/code-copy.js:6`
|
||||
**What:** Page-load JS does `querySelectorAll("pre")` on every page including home, archives, taxonomies. Cheap, but the bundle ships unconditionally even on pages with no `<pre>`. Combined with theme-toggle.js, this is in the *site-wide* bundle.
|
||||
**Why it matters:** JS budget is small (~1 KB gz). For sites with mostly portfolio pages and few code-heavy posts, code-copy is dead JS. Plus: the script inserts the button DOM-unsafe; if a `<pre>` is itself inside a `<button>` (rare but possible in wrapped Markdown), button-in-button is invalid HTML.
|
||||
**Fix:** Gate code-copy bundling on `(eq .Kind "page")` in `footer.html`, similar to how toc-active.js is gated. Or use a single conditional `<pre>:has(code)` CSS to mark candidates and bind only those.
|
||||
**Effort:** S. Move the script include behind `{{- if eq .Kind "page" -}}` in `footer.html`.
|
||||
|
||||
### P2-4 — Pagefind UI CSS is render-blocking on `/search/` page
|
||||
**File:** `layouts/search/list.html:5`
|
||||
**What:** `<link rel="stylesheet" href="/pagefind/pagefind-ui.css">` in `head_extra`. Render-blocks the search page; Pagefind UI never paints in <100ms, so the user sees a flash of unstyled search button before CSS loads.
|
||||
**Why it matters:** Search page LCP suffers. Pagefind is loaded as a JS module on the same page; the CSS could `media="print" onload="this.media='all'"` for non-blocking, or be inlined.
|
||||
**Fix:** `<link rel="preload" as="style" href=".../pagefind-ui.css" onload="this.rel='stylesheet'">` with `<noscript>` fallback. Or inline a minimal Pagefind theme override and skip the third-party CSS.
|
||||
**Effort:** S.
|
||||
|
||||
### P2-5 — `recent-posts.html` `where ... "Type" "post"` returns all post pages including paginator subpages
|
||||
**File:** `layouts/_partials/home/recent-posts.html:2-3`
|
||||
**What:** `where site.RegularPages "Type" "post"` is correct for filtering by section type. But `RegularPages` already excludes section indexes; the explicit `"Type" "post"` is needed only because the theme allows posts under `/post/` AND maybe top-level. Verify intent.
|
||||
**Why it matters:** Defensive coding, cheap. If the consumer's content tree is `/blog/...` (renamed from `/post/`), the home shows zero posts. Document this assumption or make it configurable.
|
||||
**Fix:** Make the section configurable: `{{- $section := site.Params.home.postsSection | default "post" -}}{{- $all := where site.RegularPages "Type" $section -}}`.
|
||||
**Effort:** S.
|
||||
|
||||
### P2-6 — `taxonomy.html` `range .Pages.ByTitle` uses ASCII sort for vi
|
||||
**File:** `layouts/_default/taxonomy.html:10`
|
||||
**What:** Same as v0.1.0 audit M8. Still unaddressed in `[Unreleased]`. Vietnamese-titled tags ("Á", "Đ") sort after "Z" with `ByTitle`.
|
||||
**Why it matters:** Vi-first claim in README. Sort order matters for taxonomy index UX.
|
||||
**Fix:** Hugo lacks locale-aware sort. Workaround: use `sort .Pages "Title" "asc" "string"` with a normalized key, or pre-strip diacritics with `urlize`. Acceptable to defer with documentation note.
|
||||
**Effort:** M (research correct Hugo idiom + test with vi data).
|
||||
|
||||
### P2-7 — `archive-group.html` month numbers not zero-padded; sort order may be lexical
|
||||
**File:** `layouts/_partials/archive-group.html:4`
|
||||
**What:** `GroupByDate "1"` returns string keys "1".."12". Lexical sort orders "1", "10", "11", "12", "2", "3"... — but Hugo's `GroupByDate` returns groups already chronologically sorted (descending by default), so this is OK as-is. However, `i18n "month" (dict "Number" .Key)` passes the string number; the i18n string is `Tháng {{ .Number }}` — emits `Tháng 1` not `Tháng 01`. Consumer-facing inconsistency only if vi-style mandates 2-digit. Cosmetic.
|
||||
**Fix:** None needed unless 2-digit is desired.
|
||||
**Effort:** Trivial if pursued.
|
||||
|
||||
### P2-8 — `<noscript>` only on `/search/`, missing for theme-toggle and code-copy
|
||||
**Files:** `layouts/_partials/header.html:10`, `assets/js/theme-toggle.js`
|
||||
**What:** Theme-toggle button has `hidden` attribute set in HTML; JS removes it. With JS off, button stays hidden — good. But there's no `<noscript>` indication that dark-mode is JS-driven. Code-copy buttons don't appear without JS — also good, but unannounced.
|
||||
**Why it matters:** A11y/UX clarity. SR users with JS off may wonder why no theme toggle.
|
||||
**Fix:** Either remove the toggle entirely with no-JS (current behavior is correct) OR add `<noscript><style>.theme-toggle{display:none}</style></noscript>` + a `<noscript>` link to a static dark theme query param. Probably overkill for this theme.
|
||||
**Effort:** S; defer.
|
||||
|
||||
### P2-9 — `meta.html` reading-time uses untranslatable `printf "%d min"` fallback
|
||||
**File:** `layouts/_partials/meta.html:14`
|
||||
**What:** `i18n "readingTime" (dict "Count" .ReadingTime) | default (printf "%d min" .ReadingTime)` — the default is English. Theme advertises vi-first. The `default` only fires if the i18n key is missing, which it isn't in `vi.yml` — so this is dead fallback. Dead code on every post.
|
||||
**Why it matters:** Maintainability — confusing reader, suggests there might be a missing-key path that doesn't exist.
|
||||
**Fix:** Drop the `| default ...` — it's safe because `vi.yml` defines `readingTime`. Or move all defaults to a single fallback partial. Same applies to `wordCount` line 19, `comments`, `month`, `pageNotFound`, `backHome`, `featuredProjects`, `viewAll`, `search*` (all have `| default "..."` — entirely redundant after Phase 1 added the keys).
|
||||
**Effort:** S — one pass, removes ~30 redundant `| default` calls. Reduces template noise.
|
||||
|
||||
### P2-10 — A11y: TOC narrow-viewport block has no toggle/collapse
|
||||
**File:** `assets/css/toc.css:60-67`
|
||||
**What:** On narrow viewports (<64rem), TOC renders as a static framed block above content. No `<details>`-style collapse. On a 600-word post with 8 H2s + sub-H3s, the user scrolls through ~60 lines of TOC before reaching content.
|
||||
**Why it matters:** Mobile UX. Initial scroll-to-content is poor.
|
||||
**Fix:** Wrap TOC in `<details open>` on narrow viewports (`@media (max-width: 63.99rem)`). Native, accessible, no JS.
|
||||
**Effort:** S — modify `toc.html` to use `<details>` + `<summary>` and adjust CSS for narrow.
|
||||
|
||||
### P2-11 — `head.html` description fallback chain may double-truncate
|
||||
**File:** `layouts/_partials/head.html:2`, `layouts/_partials/head/seo.html:9`
|
||||
**What:** `head.html` derives `$description` (no truncate). `seo.html` independently derives `$rawDesc` and truncates to 200. Two slightly different chains: `head.html` falls back to `site.Title`, `seo.html` doesn't. So `<meta name="description">` may emit `site.Title`, while OG `description` is empty. Inconsistent.
|
||||
**Why it matters:** SEO consistency. Crawlers may pick up different snippets.
|
||||
**Fix:** Hoist to a shared partial `head/description.html` returning the resolved description. Both consumers use it.
|
||||
**Effort:** S.
|
||||
|
||||
### P2-12 — Render hooks attributes get raw-stringified (no `safeHTMLAttr`)
|
||||
**Files:** `layouts/_markup/render-blockquote.html:21`, others
|
||||
**What:** `{{- range $k, $v := .Attributes }} {{ $k }}="{{ $v }}"{{ end -}}` — `$k` and `$v` from Goldmark attributes are user-controlled (markdown blockquote attrs). No escape on `$k` (attribute name) or `$v` (value). A blockquote with `> {.foo onclick="evil()" key="val"}` could inject attributes.
|
||||
**Why it matters:** Goldmark attribute extension is enabled implicitly via `unsafe: true`; if it's not, this line is dead. If it is, user input flows to attributes. Theme doesn't enable `parser.attribute.block: true` in `hugo.yaml`, so attributes-on-blockquote is off by default — but a consumer might enable it.
|
||||
**Fix:** Document that callouts only render with default Goldmark settings. Or escape via `safeHTMLAttr` (Hugo built-in).
|
||||
**Effort:** S.
|
||||
|
||||
### P2-13 — `render-image.html` and `render-link.html` `title="{{ . }}"` lack `safeURL`/escape harmony
|
||||
**Files:** `layouts/_markup/render-link.html:8`, `layouts/_markup/render-image.html:3`
|
||||
**What:** `title="{{ . }}"` — Hugo auto-escapes for HTML attribute context, so OK. But: title content from markdown could include `"` which Hugo escapes to `"` — fine. No vulnerability, just confirming.
|
||||
**Why it matters:** No fix needed; documenting as positive observation.
|
||||
**Fix:** None.
|
||||
|
||||
---
|
||||
|
||||
## P3 — Theme-Contract, Testing, Documentation
|
||||
|
||||
### P3-1 — Smoke tests don't catch render-hook regressions or callout style breakage
|
||||
**File:** `scripts/smoke-tests.sh`
|
||||
**What:** 11 checks cover SEO meta, skip-link, related-posts presence, CSS budget. None assert: callout HTML structure (`class="callout callout-note"`), TOC active-link CSS class is wired, render-link `rel` count is ≥1 (it does count globally — but doesn't assert the specific URL got the rel), code-copy button exists on a `<pre>` page, JSON-LD parses as valid JSON, OG image absolute URL, dark-theme styles present in the bundle.
|
||||
**Why it matters:** All P1 and P2 issues above could land without breaking smoke-tests. A regression in `render-link.html` `safeHTML` to `plainify` would be invisible.
|
||||
**Fix:** Add assertions:
|
||||
- `assert "callout renders" 'class=callout callout-note' "$post"` (requires demo post with callout)
|
||||
- `assert "JSON-LD parses" — pipe through jq` (need jq in CI)
|
||||
- `assert "OG image absolute" 'og:image" content="https?://'` — currently regex doesn't enforce abs
|
||||
- `assert "code-copy class CSS in bundle" 'code-copy' "$css"` — sanity check
|
||||
- `assert "dark-theme tokens" 'data-theme="dark"\|prefers-color-scheme: dark' "$css"`
|
||||
**Effort:** M. ~10 new assertions, 30 lines of bash. Worth gating v0.3 on this.
|
||||
|
||||
### P3-2 — `theme.toml` `min_version: 0.146.0` is below recommended for some features used
|
||||
**File:** `theme.toml:9`
|
||||
**What:** `theme.toml` says 0.146+. Render-blockquote with `.Type "alert"` requires Hugo 0.140+ (✓). `.GetTerms` is 0.123+ (✓). `module.mounts` in theme is 0.86+ (✓). View Transitions CSS is browser-side. Hugo 0.146 should work — but: `_partials`/`_markup`/`_shortcodes` lookup order was finalized in 0.146.0, so the floor is correct. No issue. **However:** GitHub Actions workflow pins `HUGO_VERSION: 0.154.0`. Floor is 0.146 but tested against 0.154 only. Risk: features that work on 0.154 silently rely on 0.150+ behavior.
|
||||
**Why it matters:** Theme-contract drift. Consumers on 0.146 may hit obscure bugs.
|
||||
**Fix:** Add a CI matrix building against the floor (0.146.0) and current (0.154.0). Or bump the floor to whatever's actually tested (0.154.0) and document.
|
||||
**Effort:** S — workflow matrix change.
|
||||
|
||||
### P3-3 — `theme.toml` features list missing `callouts` is documented but `goldmark` not
|
||||
**File:** `theme.toml:8`
|
||||
**What:** `features = ["blog", "portfolio", "search", "comments", "dark-mode", "responsive", "i18n", "rss", "callouts", "json-ld"]` — `callouts` is there, good. Missing: `view-transitions`, `pagefind`, `giscus`, `vietnamese`. Tag list has `view-transitions` and `pagefind` but feature list doesn't. Hugo theme registry uses the features list for discovery filtering.
|
||||
**Why it matters:** Discoverability on themes.gohugo.io.
|
||||
**Fix:** Sync `features` and `tags` lists; consider `view-transitions`, `mobile`, `seo`. Verify against [registry conventions](https://themes.gohugo.io/).
|
||||
**Effort:** S.
|
||||
|
||||
### P3-4 — No `i18n/en.yml` skeleton
|
||||
**File:** missing
|
||||
**What:** Theme is vi-first but uses Hugo i18n. Consumers wanting English have to copy-paste keys + translate. No starter file.
|
||||
**Why it matters:** Adoption friction. README claims "i18n" feature; effectively means "vi-only built-in".
|
||||
**Fix:** Add `i18n/en.yml` with English translations. Hugo automatically picks up matching language files based on `defaultContentLanguage` and `languageCode`. Even if `default` fallbacks exist in templates, having a concrete `en.yml` documents the i18n contract and signals that adding `ja.yml` works. ~40 keys × English translation.
|
||||
**Effort:** M (translation effort).
|
||||
|
||||
### P3-5 — `data/profile.yaml` shape is part of the contract but has no schema validation
|
||||
**Files:** `data/profile.yaml` (consumer), `docs/data-schemas.md`
|
||||
**What:** `home/hero.html`, `header.html`, `footer.html`, `seo.html` all read `site.Data.profile.{name,avatar,tagline,bio,links,url}`. Documentation lists 6 fields, code references 7 (adds `url`). Consumers can't validate their YAML without building.
|
||||
**Why it matters:** Theme contract. A typo in `name:` (e.g., `Name:` capital) silently falls back to `site.Title`. Hard to debug.
|
||||
**Fix:** Ship `data/profile.schema.json` as JSON Schema. Add a smoke-test step `npx ajv validate` in CI for the demo profile. Or document the typo gotcha.
|
||||
**Effort:** M; defer to later.
|
||||
|
||||
### P3-6 — `params.toc` documented but no surface for category/tag visibility toggle
|
||||
**Files:** `docs/config.md`, theme contract
|
||||
**What:** `meta.html:22` comments "Categories are deliberately not surfaced here". This is a hardcoded design choice. Consumer wanting category pills must override `meta.html` entirely. No `params.showCategories` or similar.
|
||||
**Why it matters:** Theme decision baked into the layout. Override surface is "drop a custom partial."
|
||||
**Fix (M)** — add `params.showCategories: false` (default) to docs and meta.html. Cheap.
|
||||
**Effort:** S.
|
||||
|
||||
### P3-7 — `relatedPostsCount: 0` documented as "disables" but template still calls `site.RegularPages.Related .`
|
||||
**File:** `layouts/_partials/related-posts.html:6-9`
|
||||
**What:** Already gated correctly via `if gt $count 0`. Good. **But:** if `relatedPostsCount > 0` and there are zero related posts (a new post with no tag overlaps), the section silently disappears. Consumer may want a "no related posts" message. Currently no opt-in for that.
|
||||
**Why it matters:** Theme behavior is not surfaced as configurable.
|
||||
**Fix (M)** — add `params.relatedPostsEmpty: "Chưa có bài viết liên quan."` (optional). If set and empty, render the message.
|
||||
**Effort:** S; defer.
|
||||
|
||||
### P3-8 — htmltest CI step uses `wjdp/htmltest-action@master` without commit pin
|
||||
**File:** `.github/workflows/pages.yml:74`
|
||||
**What:** Comment says "TODO before v0.2.0 tag: pin @master to a commit SHA (supply-chain hygiene)". This TODO survived into v0.2.0.
|
||||
**Why it matters:** Supply-chain risk. A compromised htmltest-action master can run arbitrary code in CI on every push.
|
||||
**Fix:** Pin to current SHA. `gh api repos/wjdp/htmltest-action/commits/master` to fetch.
|
||||
**Effort:** S — single commit.
|
||||
|
||||
### P3-9 — `pages.yml` Pagefind step has dead branch
|
||||
**File:** `.github/workflows/pages.yml:48-54`
|
||||
**What:** "If find ... | head -1 | grep -q . then npx pagefind ... else echo 'No HTML files found yet (layouts not implemented)' fi" — leftover from initial scaffolding. Layouts now exist; the else branch never triggers.
|
||||
**Why it matters:** Confusing for new contributors reading CI. Dead branch.
|
||||
**Fix:** Drop the if-guard; just run `npx pagefind --site exampleSite/public`.
|
||||
**Effort:** S.
|
||||
|
||||
### P3-10 — `_index.md` content for `/post/`, `/archives/`, `/search/` not part of theme
|
||||
**Files:** `exampleSite/content/{post,archives,search}/_index.md`
|
||||
**What:** Theme-required sections are documented in `docs/installation.md` but not enforced. A consumer that omits `content/search/_index.md` gets no `/search/` route built (Hugo doesn't render section pages without content). Mentioned in v0.1.0 audit H2 (closed) but the *requirement* hasn't been documented.
|
||||
**Why it matters:** Theme contract: required content scaffold. New users hit "search 404" with no error.
|
||||
**Fix:** `docs/installation.md` already has a checklist; add explicit "Required content scaffold" section listing the three `_index.md` files. Or ship them as archetypes.
|
||||
**Effort:** S.
|
||||
|
||||
### P3-11 — No unit/integration tests for partial output shapes
|
||||
**Files:** `scripts/smoke-tests.sh` (only)
|
||||
**What:** Smoke tests grep built HTML. No tests of partial output for synthetic input (e.g., a post with no tags, no description, lastmod < 24h newer, etc.). Render hooks + meta.html have multiple branches; only "happy path" covered.
|
||||
**Why it matters:** Branches like `if and .Lastmod (gt (.Lastmod.Sub .Date).Hours 24.0)` (line 7 meta.html) are unreached by smoke-tests because demo posts don't have a Lastmod. Same for `wordCount: true` (off in demo), `cover.image` partial path.
|
||||
**Fix:** Add test posts with: `lastmod: <future-date>`, `cover.image:`, `description:`, `comments: false` per-post override. Smoke tests then assert the new output. ~5 demo posts cover all branches.
|
||||
**Effort:** M — content-side, no code change required.
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases / Verification (verified, no fix needed)
|
||||
|
||||
- `data/profile.yaml: avatar` empty → hero `<img>` skipped; correct.
|
||||
- `data/projects.yaml: featured: []` → projects section omitted; correct.
|
||||
- Post without tags → meta.html `with .GetTerms "tags"` skips entire `.post-tags` span; correct.
|
||||
- Post with categories but tags empty → no related posts will render (related index keys are tags+categories+date, and category-only matches with weight 60 + threshold 80 still need additional weight). Verified by hand; documented.
|
||||
- Pagefind disabled at site level + no `pagefind` directory generated → search page emits localized `searchDisabled` text + no JS module call. Correct.
|
||||
- View Transitions CSS in unsupporting browsers → `@view-transition` ignored, fade-keyframes never run. Dead bytes ~50B gz. Acceptable per CHANGELOG note.
|
||||
|
||||
---
|
||||
|
||||
## Positive Observations (worth keeping)
|
||||
|
||||
- `toc-enabled.html` is a clean single-source-of-truth pattern. Worth applying the same to `comments-enabled.html` (currently duplicated logic in `_partials/comments.html` and `_partials/footer.html`).
|
||||
- `head/seo.html` is a good extraction; the OG image fallback chain expressed at top of file is readable. Inlining `og-image.html` was the right call (CHANGELOG note matches).
|
||||
- `render-link.html` correctly applies `noopener noreferrer` (not `target="_blank"`) — keeps users in-tab, deliberate UX choice. Good.
|
||||
- `code-copy.js` `if (navigator.clipboard)` gate is clean. Bonus: `try/catch` on `writeText` correctly handles Permissions Policy denials in iframes.
|
||||
- `giscus-theme.js` first-message-then-mutation observer prevents the theme flash. Implementation is concise (27 lines).
|
||||
- Asset pipeline `Concat | minify | fingerprint` with SRI integrity attribute is best practice and survived through v0.2 unchanged.
|
||||
- `archetypes/default.md` includes `description`, `cover.image`, `tags`, `categories` — covers the SEO + discovery path out-of-box.
|
||||
- Smoke tests + htmltest + CSS budget assertion give 3 layers of CI safety. Solid foundation; just needs more assertions (P3-1).
|
||||
|
||||
---
|
||||
|
||||
## Recommended Actions (priority order, v0.3.0 candidates)
|
||||
|
||||
1. **P1-1** — Drop `safeHTML` from `render-link.html` link text (or document reason).
|
||||
2. **P1-2** — Refactor `seo.html` `$authorURL` chain to nil-safe `with` blocks; document `data/profile.yaml: url`.
|
||||
3. **P1-3** — `safeURL` + `noreferrer` on `home/projects.html` repo/demo links.
|
||||
4. **P1-4** — `relURL` on `nav.html` menu URLs.
|
||||
5. **P1-5** — Tighten `comments.html` gate to require `repo+repoId+categoryId`.
|
||||
6. **P3-8** — Pin `wjdp/htmltest-action` to commit SHA.
|
||||
7. **P2-2** — Per-page-kind CSS bundles (free up budget for v0.3+ features).
|
||||
8. **P2-3** — Gate `code-copy.js` on `eq .Kind "page"` in `footer.html`.
|
||||
9. **P2-9** — Drop redundant `| default "..."` calls now that `vi.yml` is complete.
|
||||
10. **P3-1** — Expand smoke-tests to cover callouts, JSON-LD valid, dark theme, OG abs URL.
|
||||
11. **P3-9** — Drop dead `if find ... | grep -q .` from CI.
|
||||
12. **P3-4** — Add `i18n/en.yml` skeleton.
|
||||
13. **P2-1** — `<details>` styling (CSS only, ~20 lines, opens "rich content" door).
|
||||
14. **P3-2** — CI matrix on Hugo 0.146 (floor) + 0.154 (current).
|
||||
15. **P2-10** — `<details>`-wrap TOC on narrow viewports.
|
||||
|
||||
Lower-priority (P2-5/P2-6/P2-7/P2-11/P2-12, P3-3/P3-5/P3-6/P3-7/P3-10/P3-11) batch as polish before v0.4.
|
||||
|
||||
---
|
||||
|
||||
## Effort Summary
|
||||
|
||||
| Tier | Count | Avg effort | Total |
|
||||
|------|-------|------------|-------|
|
||||
| P1 | 6 | S | ~1 day total |
|
||||
| P2 | 13 | S–M | ~3 days |
|
||||
| P3 | 11 | S–M | ~2–3 days |
|
||||
|
||||
A focused v0.3.0 fixing P1 + top-5 P2 + top-3 P3 is ~3 days. Distribution-stable.
|
||||
|
||||
---
|
||||
|
||||
## Unresolved Questions
|
||||
|
||||
1. **Is `unsafe: true` Goldmark still required?** Native callouts (Hugo 0.140+) replace the original use case. Footnotes work without `unsafe`. `<details>` works without `unsafe` (it's a void element pair Hugo passes through). Consumer-side raw-HTML in posts is the only remaining justification. If theme can ship with `unsafe: false` recommended, P1-1 + the bio-XSS surface (CHANGELOG security note) both vanish. *Maintainer decision needed*.
|
||||
2. **Should `data/profile.yaml: url` be in the documented schema?** Code reads it (seo.html:64); docs don't list it. Either remove the read or add the doc.
|
||||
3. **Is per-page-kind CSS bundling a v0.3 feature or v1.0 architecture change?** P2-2 frees budget but increases template complexity. Keep simple bundle vs split bundles is a long-term call.
|
||||
4. **Hugo version floor: bump to 0.154 (CI-tested) or test on 0.146 (theme.toml claim)?** P3-2 forces this decision.
|
||||
5. **Should the theme ship `archetypes/post.md` distinct from `default.md` for post-specific frontmatter?** Authors run `hugo new post/<slug>.md` and get the default; could be richer.
|
||||
6. **Is the homepage portfolio meant to scale to many projects, or is the 6-card example the design ceiling?** If many: pagination needed. If few: document the assumption in `docs/data-schemas.md`.
|
||||
7. **Pagefind UI CSS — bundle-and-fingerprint vs leave-as-third-party?** Trade-off between bundle bloat (~3 KB gz extra) and SRI guarantee. Status quo (third-party) is acceptable but unannounced.
|
||||
8. **Multi-author surface (research note from v0.2 roadmap)** — should each post support `author:` overriding `params.author` for `JSON-LD: Person`? Currently single author, hardcoded.
|
||||
|
||||
---
|
||||
|
||||
**Status:** DONE
|
||||
**Summary:** /config/workspace/tiennm99/tsuki/plans/reports/code-reviewer-260510-0144-tsuki-v0.2.0-post-release-improvements.md — top 3 findings: (1) `render-link.html` `safeHTML` re-introduces stored-HTML in link text (P1-1), (2) `seo.html` `site.Params.profile.url` chain is fragile when consumer follows `data/profile.yaml`-only path (P1-2), (3) per-page-kind CSS bundling could free ~1.2 KB gz to make headroom for v0.3+ features (P2-2). Audit found 6 P1 correctness/security bugs, 13 P2 maintainability/perf items, 11 P3 testing/contract gaps. CHANGELOG `[Unreleased]` already addresses most v0.1.0 audit findings; remaining work is second-order.
|
||||
@@ -1,147 +0,0 @@
|
||||
# tsuki v0.2.1 Patch Review
|
||||
|
||||
Date: 2026-05-10
|
||||
Scope: 7 files modified for v0.2.1 patch (P1-1..P1-5 + P3-8 + P3-9)
|
||||
Inputs: phase-01-v0.2.1-carry.md, source review report, working-tree diff
|
||||
Verdict: **APPROVED — auto-merge eligible**
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
All 7 fixes match the spec verbatim. SHA pin verified against upstream master HEAD. CHANGELOG accurately reflects the diff including the behavioral break-out for emphasis-in-link. No new issues introduced. Backwards-compat path holds: a v0.2.0 consumer with `data/profile.yaml: name` (no `url`) lands on `site.Home.Permalink` fallback as before.
|
||||
|
||||
---
|
||||
|
||||
## Per-Fix Verification
|
||||
|
||||
### P1-1 render-link.html `safeHTML` drop — CORRECT
|
||||
- `layouts/_markup/render-link.html:10`: `{{ .Text }}` (was `{{ .Text | safeHTML }}`).
|
||||
- Now consistent with `render-image.html` policy (`alt="{{ .Text }}"` un-`safeHTML`'d).
|
||||
- Behavioral note: `[*x*](url)` → "*x*" plain literal asterisks (Goldmark passes raw markdown through `.Text` for render hooks; the `<em>` rendering depended on `safeHTML` re-emitting Goldmark's already-rendered HTML). **Documented in CHANGELOG Security note** ✓.
|
||||
- Optional: spec step 1 mentions adding `exampleSite/content/post/render-hooks-demo/index.md` smoke post for `[*emphasis*](https://example.com)`. Not added in this patch — acceptable for v0.2.1 since smoke-tests.sh doesn't gate on render-hook output (P3-1 still open).
|
||||
|
||||
### P1-2 seo.html `$authorURL` nil-safe — CORRECT
|
||||
- Lines 64–67: replaced `site.Params.profile.url | default ...` chain with three discrete steps using `with` blocks.
|
||||
- Verified against `exampleSite/data/profile.yaml`: no `url` key present → first two `with` blocks no-op → falls to `site.Home.Permalink`. Demo build path preserved.
|
||||
- v0.2.0 consumer with `data/profile.yaml: { name, avatar, bio, links, ... }` and no `params.profile`: `with site.Params.profile` evaluates falsy → skipped; `with site.Data.profile` → `$authorURL = .url` = `nil` (empty string). Then `site.Home.Permalink` fallback. **Clean.**
|
||||
- Also resilient when `site.Params.profile` is set but lacks `url`: `with` block enters, `$authorURL = .url` = `""`, then second `with` runs because `not ""` is true. Layered fallback works.
|
||||
|
||||
Minor: spec step 2 also asked to "document `data/profile.yaml: url` in `docs/data-schemas.md`". Not done in this patch. Tracked in journal entry `260510-0232-post-v0.2.0-planning-session.md:66` as a Q. Non-blocking; the field is now tolerated whether documented or not.
|
||||
|
||||
### P1-3 projects.html `safeURL` + `noreferrer` + `target=_blank` — CORRECT
|
||||
- Lines 30, 33: both `repo` and `demo` URLs piped through `safeURL`, rel = `noopener noreferrer`, `target="_blank"` added.
|
||||
- Matches spec exactly. Privacy fix (Referer leakage) and external-tab UX both delivered.
|
||||
|
||||
### P1-4 nav.html `relURL` pipe — CORRECT
|
||||
- Line 6: `{{ .URL | relURL }}`.
|
||||
- Idempotent claim verified: Hugo's `relURL` on an already-baseURL'd path returns the path unchanged; on a leading-`/` raw path it prefixes the baseURL sub-path. **Will not break absolute external menu URLs** (`https://...`) — `relURL` short-circuits when input has scheme.
|
||||
- exampleSite has no menu config defined → this fix is not exercised by the demo build. Acceptable; the change is for downstream consumer sites with sub-path deploys.
|
||||
|
||||
### P1-5 comments.html stricter gate — CORRECT
|
||||
- Line 2: `{{- if and $g $g.enable $g.repo $g.repoId $g.categoryId -}}`.
|
||||
- All three required Giscus IDs gated. Matches spec.
|
||||
- Spec mentioned an optional HTML comment on gated-off path for debug; not added. Non-blocking.
|
||||
|
||||
### P3-8 htmltest-action SHA pin — CORRECT, VERIFIED
|
||||
- `.github/workflows/pages.yml:69`: `wjdp/htmltest-action@31be84a95c860a331e0cf9a99f71e3eb39d2f86b`.
|
||||
- **SHA verified** against `gh api repos/wjdp/htmltest-action/commits/master` → `31be84a95c860a331e0cf9a99f71e3eb39d2f86b`. Match ✓.
|
||||
- Comment format: `# Pinned to master SHA (2026-05-10) for supply-chain hygiene. Refresh periodically.` Acceptable; date present, supply-chain rationale present. Could optionally include the upstream tag/release name if one existed (htmltest-action has none — it's master-only). No-op.
|
||||
|
||||
### P3-9 dead Pagefind branch removed — CORRECT
|
||||
- `.github/workflows/pages.yml:48`: now just `run: npx pagefind --site exampleSite/public`.
|
||||
- Lines 48–54 of dead `if find ... | head -1 | grep -q .` removed. Cleaner.
|
||||
|
||||
---
|
||||
|
||||
## CHANGELOG Accuracy — CORRECT
|
||||
|
||||
Diff cross-checked against the new `### Security` (4 entries) + `### Fixed` (3 entries) blocks:
|
||||
|
||||
| CHANGELOG entry | Diff evidence |
|
||||
|---|---|
|
||||
| Render-link `safeHTML` dropped, side-effect on emphasis | render-link.html:10 |
|
||||
| Project `safeURL` + `noreferrer` | projects.html:30,33 |
|
||||
| Comments gate tightened | comments.html:2 |
|
||||
| htmltest pinned to `31be84a` | pages.yml:69 |
|
||||
| `seo.html` `$authorURL` chain | seo.html:64–67 |
|
||||
| Nav `relURL` for sub-path deploys | nav.html:6 |
|
||||
| Pagefind dead branch | pages.yml:48 |
|
||||
|
||||
All 7 entries map 1:1 to a diff hunk. Side-effect on emphasis-in-link is **explicitly called out**. No false claims.
|
||||
|
||||
---
|
||||
|
||||
## Backwards Compatibility for v0.2.0 Consumers — CLEAN
|
||||
|
||||
Test cases (mental model):
|
||||
|
||||
1. **Consumer with `data/profile.yaml: { name }` only, no `params.profile`, no menu**: builds clean (seo: falls to `Home.Permalink`; nav: empty range; render-link: no behavior change for href; projects: unaffected).
|
||||
2. **Consumer with `data/profile.yaml: { name, url: "https://..." }`**: `with site.Data.profile` → `$authorURL = "https://..."` ✓.
|
||||
3. **Consumer with `params.profile.url: "..."`** (undocumented but functional): first `with` block sets `$authorURL` ✓.
|
||||
4. **Consumer with menu using `url: /post/`** + sub-path baseURL: `relURL` prefixes correctly ✓.
|
||||
5. **Consumer with menu using `pageRef:` or `url: https://...`**: `relURL` is idempotent, no breakage ✓.
|
||||
6. **Consumer with `comments.giscus.enable: true` but missing `repoId`**: comments now silently skip (was: broken iframe). **Behavior change**, properly noted in CHANGELOG.
|
||||
7. **Author posts with `[*emphasis*](url)`**: now renders literal `*emphasis*`. **Behavior change**, called out in CHANGELOG Security note. Ack.
|
||||
|
||||
---
|
||||
|
||||
## Sanity Checks
|
||||
|
||||
- htmltest SHA format (`uses: org/repo@<40-hex>` + leading `#` comment with date): correct GitHub Actions format. ✓
|
||||
- No raw secrets, no leaked tokens, no test-only fixtures committed. ✓
|
||||
- File sizes unchanged in spirit; no large additions. ✓
|
||||
- Local build report (Hugo 0.154.0, 31 pages, smoke 11/11, CSS 3962/4200 B) consistent with no measurable regression.
|
||||
|
||||
---
|
||||
|
||||
## Issues Found
|
||||
|
||||
**None blocking.**
|
||||
|
||||
Minor observations (non-blocking, do not gate auto-merge):
|
||||
|
||||
- **OBS-1 (Low)** Spec asked for an emphasis-in-link demo post (`exampleSite/content/post/render-hooks-demo/index.md`); not shipped. Without it, the behavioral change to emphasis-in-link is only verifiable by manual inspection or upstream consumer report. Recommendation: add as part of P3-1 smoke-test expansion (out of v0.2.1 scope).
|
||||
- **OBS-2 (Low)** Spec asked to document `data/profile.yaml: url` in `docs/data-schemas.md`. Deferred (tracked in planning journal). Not blocking — code now tolerates the field whether documented or not.
|
||||
- **OBS-3 (Low)** htmltest SHA pin lacks a Dependabot grouping config. Mitigation noted in spec Risk Assessment ("add Dependabot config in v0.3.1"). Out of v0.2.1 scope.
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases Verified
|
||||
|
||||
- `relURL` on `https://external` external menu URL → unchanged (Hugo's `relURL` only rewrites scheme-less paths). No regression risk.
|
||||
- `safeURL` on `mailto:` / `tel:` repo links — would still pass through (these are not `javascript:`). The `repo` field is theme-author input; risk is low.
|
||||
- `comments.giscus.enable: true` with all IDs set → unchanged behavior; iframe loads as before.
|
||||
- Comments per-page override `comments: false` still respected (line 3 unchanged).
|
||||
|
||||
---
|
||||
|
||||
## Positive Observations
|
||||
|
||||
- Surgical edits: all changes 1–5 lines as planned. No collateral churn.
|
||||
- CHANGELOG explicitly distinguishes Security vs Fixed; Security entries lead with the surface they close.
|
||||
- `relURL` and `safeURL` choices match Hugo idiom — no exotic patterns.
|
||||
- htmltest comment captures the audit metadata (date + intent) that future contributors need.
|
||||
- The behavioral break (emphasis-in-link) is forthrightly documented rather than buried.
|
||||
|
||||
---
|
||||
|
||||
## Score
|
||||
|
||||
**9.7 / 10**
|
||||
|
||||
Deductions: −0.3 for unshipped demo post (OBS-1) and undocumented `data/profile.yaml: url` (OBS-2). Both deferred, both tracked, neither blocks the patch. Auto-approve threshold (≥9.5, 0 critical) cleared.
|
||||
|
||||
---
|
||||
|
||||
## Unresolved Questions
|
||||
|
||||
1. Ship as v0.2.1 patch tag now, or roll into v0.3.0 release? (Maintainer decision per phase-01-v0.2.1-carry.md preamble.)
|
||||
2. Should the emphasis-in-link demo post (OBS-1) ship in v0.2.1 to validate the rendering claim, or wait for the v0.3 P3-1 smoke-test expansion?
|
||||
3. `data/profile.yaml: url` documentation — add to `docs/data-schemas.md` now (small) or batch with v0.3.0 doc updates?
|
||||
|
||||
---
|
||||
|
||||
**Status:** DONE
|
||||
**Score:** 9.7/10
|
||||
**Summary:** All 7 fixes correct, SHA verified, CHANGELOG accurate, no regressions. Auto-approve eligible. Report: `/config/workspace/tiennm99/tsuki/plans/reports/code-reviewer-260510-0244-v0.2.1-patch-review.md`
|
||||
@@ -1,321 +0,0 @@
|
||||
# Lighthouse ≥80 baseline audit — tsuki v0.2.1
|
||||
|
||||
Scope: full theme at `main` (`d30f50f`). Read: README, CHANGELOG (Unreleased + v0.2.1 + v0.2.0), `layouts/baseof.html`, `layouts/_partials/{head,head/seo,footer,header,nav,meta,post-card,comments,toc,toc-enabled,search-button,related-posts}.html`, `layouts/_partials/home/{hero,projects,recent-posts}.html`, all `layouts/_markup/render-*.html`, `layouts/{single,home,list,404}.html`, `layouts/{search,post,archives,taxonomy,_default}/*.html`, all `assets/css/*.css`, all `assets/js/*.js`, `hugo.yaml`, `exampleSite/hugo.yaml`, `i18n/vi.yml`, `scripts/smoke-tests.sh`, prior audits (v0.2.0-post / v0.2.1-patch). Cross-checked against built `exampleSite/public/{index,2026/01/10/.../index,search/index}.html`, `sitemap.xml`, bundle sizes.
|
||||
|
||||
## TL;DR
|
||||
|
||||
Projected Lighthouse scores on a real production GitHub Pages deploy (`exampleSite`), median of 3 mobile runs, *no measurement performed* — static-inspection estimate:
|
||||
|
||||
- **Performance:** 92–98/100. Comfortable ≥80. Tiny bundles (3.96 KB gz CSS, 1.04 KB gz JS), minify on, hashed assets. LCP risk only on posts with a `cover.image` (no preload, no `fetchpriority`), but exampleSite has none so it lands in the high 90s.
|
||||
- **Accessibility:** 88–93/100. Likely ≥80 but **not the ≥95 ceiling Phase 4 targets**. Three known deductions: theme-toggle button missing `aria-pressed` on initial SSR (only set in JS), small tap targets (`2rem` × `2rem` = 32px for toggle/search button is fine but pagination arrows + footer text links are <24×24 on mobile), and one `aria-label` localized to vi only (`Liên kết đến phần này` in render-heading regardless of site language).
|
||||
- **Best Practices:** 95–100/100. Safe ≥80. SRI on bundles, `noopener noreferrer`, no mixed content, no deprecated APIs, console clean. Single risk: `unsafe: true` Goldmark is the consumer's problem, not Lighthouse's.
|
||||
- **SEO:** 95–100/100. Safe ≥80. Sitemap, canonical, OG/Twitter, JSON-LD, viewport, lang, description all present. Only deductions are robots.txt being absent from `static/` (Hugo emits one only if configured) and `hreflang` not being emitted (theme is monolingual — but README/features list says "i18n").
|
||||
|
||||
**Confidence:** medium-high on Performance/Best Practices/SEO; medium on Accessibility (tap-size is the one place static inspection meaningfully misses what Lighthouse measures).
|
||||
|
||||
**Verdict: all four categories pass ≥80 on the demo today.** This audit identifies what would *block* the score in real-consumer configurations (cover images, English sites, dense menus) and what would push Accessibility past 95 to meet the Phase 4 success criterion.
|
||||
|
||||
---
|
||||
|
||||
## P0 — blocks ≥80 in some category
|
||||
|
||||
### P0-1 — Cover-image LCP unmeasured; no preload / no `fetchpriority` / no `sizes`
|
||||
**Where:** `layouts/_partials/head/seo.html:10-15` (cover resolution), `layouts/single.html:4-15` (post body — no cover rendered at all), `layouts/_markup/render-image.html:1-5` (content images only)
|
||||
**Why it costs points:** A `cover.image` is only used for OG/Twitter cards. It is never rendered into the page DOM as a hero. The CHANGELOG (v0.2.0) advertises `cover.image` as "the preferred OG/Twitter cover key" — fine for SEO, but a typical Hugo theme renders the cover as an LCP element. The instant a consumer adds a cover image and writes their own hero partial (or expects the theme to render it), they will paint a large image with `loading="lazy"` (per render-image.html), no preload, no `fetchpriority="high"`, no `width`/`height`. That fails LCP and CLS simultaneously and can knock Performance below 80 on slow 4G.
|
||||
**Why this is P0 vs P1:** Right now exampleSite has no cover images so the demo Lighthouse number is clean — but the theme advertises a feature whose default rendering would tank the score. Consumer-facing footgun.
|
||||
**Fix sketch (no build step):**
|
||||
1. Render a hero cover in `single.html` (`{{ with .Params.cover.image }}<img ...>{{ end }}`) using Hugo `images.Resize` for `width`/`height`/`srcset`/`sizes`.
|
||||
2. In `head.html`, when `.Params.cover.image` resolves to a local resource, emit `<link rel="preload" as="image" href="{{ . }}" fetchpriority="high">`.
|
||||
3. First in-content cover gets `loading="eager" fetchpriority="high" decoding="async"`; rest stay `lazy`.
|
||||
4. Document the per-post `cover.image` → above-fold rendering path in `docs/data-schemas.md`.
|
||||
**Alternative (KISS):** ship a documented "to render cover, override `single.html`" note + a working snippet in `docs/customization.md`. Phase 5 of v0.3.0 doesn't cover this; Phase 3 (author UX) is the right place.
|
||||
|
||||
### P0-2 — Pagefind UI CSS is render-blocking on `/search/`
|
||||
**Where:** `layouts/search/list.html:5` (`<link rel="stylesheet" href="{{ "/pagefind/pagefind-ui.css" | relURL }}">` in `head_extra`)
|
||||
**Confirmed in built output:** `exampleSite/public/search/index.html` emits `<link rel=stylesheet href=/pagefind/pagefind-ui.css>` with no `media`/`onload` swap. This file is 3rd-party CSS, not part of the 3.96 KB gz bundle, and not preloaded.
|
||||
**Why it costs points:** Pagefind UI CSS is ~3–4 KB gz on its own; on a cold visit it adds one render-blocking request after the theme bundle. Combined with the JS module that constructs the search UI (`scripts` block — loads `pagefind/pagefind-ui.js`), `/search/` is the single worst-LCP page on the site. Already flagged in P2-4 of the prior audit but not in v0.3.0 plan as a P0.
|
||||
**Fix sketch:**
|
||||
```html
|
||||
<link rel="preload" as="style" href="{{ "/pagefind/pagefind-ui.css" | relURL }}" onload="this.rel='stylesheet'">
|
||||
<noscript><link rel="stylesheet" href="{{ "/pagefind/pagefind-ui.css" | relURL }}"></noscript>
|
||||
```
|
||||
Cheaper alt: inline minimal Pagefind reset (~300B) and drop the link entirely.
|
||||
|
||||
### P0-3 — Tap target sizing on pagination, footer links, theme-toggle/search-button on mobile
|
||||
**Where:** `assets/css/components.css:155-172` (pagination), `assets/css/layout.css:68-81` (footer), `assets/css/layout.css:45-56` + `assets/css/search.css:10-25` (`.theme-toggle` + `.search-button` = `2rem × 2rem` = 32×32 — under WCAG 2.5.8 AA threshold of **24×24** so passes 2.5.8 minimum but **fails 2.5.5 AAA** and Lighthouse "Tap targets" audit which uses **48×48 px**)
|
||||
**Why it costs Lighthouse points:** Lighthouse mobile audit specifically measures "Tap targets are sized appropriately" against a 48×48 CSS-px threshold (not WCAG's 24×24). At 32×32, every interactive icon in the header fails. Pagination `<a>` is `padding: 0.25rem 0.75rem; min-width: 2rem;` → ~32×28 on mobile. Multiple failed targets each cost ~5 points. Phase 4 of v0.3.0 plans for WCAG 2.5.8 (24×24) but **not** Lighthouse's stricter 48×48 — flag this delta.
|
||||
**Fix sketch:** Bump theme-toggle/search-button to `min-width:2.5rem; min-height:2.5rem` (40×40, still smaller than 48 but improves). For 48×48, use `padding: 0.5rem` and `min-width:3rem; min-height:3rem`. Pagination needs `padding: 0.5rem 0.75rem` and `min-height:2.75rem`. Footer link area can use `padding-block: 0.25rem` to expand hit zone without resizing visible text.
|
||||
|
||||
### P0-4 — Theme-toggle `aria-pressed` is set only in JS, not in HTML
|
||||
**Where:** `layouts/_partials/header.html:10` (button has `aria-label` but no initial `aria-pressed`); `assets/js/theme-toggle.js:14,20` (sets `aria-pressed` after JS runs)
|
||||
**Why it costs Lighthouse a11y points:** Lighthouse axe rule `button-name` + ARIA validation checks for `aria-pressed` consistency on toggle buttons that announce state. With JS disabled, the button is `hidden` (good), but Lighthouse runs with JS enabled, sees `aria-label="Đổi giao diện"` (only vi, no `aria-pressed`, no `role="switch"` either). On first paint *before* JS finishes parsing the module, screen readers see a button with no pressed state. Tooling counts this as "ARIA toggle button missing aria-pressed" → −5 to −10 a11y points.
|
||||
**Fix sketch:** Render initial `aria-pressed` in the template based on a flash-prevention readable signal. Cleanest: inline the theme-flash script and set `aria-pressed` directly:
|
||||
```html
|
||||
<button … data-theme-toggle aria-pressed="false" hidden>…</button>
|
||||
```
|
||||
Then have the inline `<script>` in `head.html:13-22` also update `aria-pressed` *before* body paints. This is also the right place to set `data-theme="dark"` for SSR. Currently the inline script only sets `data-theme`, not `aria-pressed`.
|
||||
|
||||
### P0-5 — `i18n/en.yml` missing; English-default sites will paint vi strings
|
||||
**Where:** `i18n/vi.yml` (only file); `layouts/_markup/render-heading.html:4` (`aria-label="Liên kết đến phần này"` hardcoded vi); `layouts/_partials/footer.html:7` (`{{ i18n "poweredBy" | default "Powered by" }}`)
|
||||
**Why it costs Lighthouse points:** A consumer site with `defaultContentLanguage: en` and `languageCode: en` will get:
|
||||
- `<html lang="en">` correct
|
||||
- All `i18n "x" | default "English fallback"` calls fall to the default text (mixed quality, some still vi e.g. `i18n "search" | default "Tìm kiếm"` in `search-button.html:1` falls back to **vi** — see also `archives/list.html:14`, `search/list.html:11`, many spots)
|
||||
- `render-heading.html:4` hardcodes `aria-label="Liên kết đến phần này"` regardless of site language — Lighthouse a11y axe rule `lang` flags content text inconsistent with `<html lang>`.
|
||||
**Why this is P0:** Already in Phase 3 of v0.3.0 — but the heading-anchor hardcoded vi is *not* fixed by adding `en.yml`, it requires a template change. Without en.yml + render-heading.html i18n, an English site fails Lighthouse a11y because language attribute / content mismatch.
|
||||
**Fix sketch:**
|
||||
1. Ship `i18n/en.yml` with all 40 keys (already on Phase 3 todo).
|
||||
2. Move `aria-label` in `render-heading.html` to `{{ i18n "headingAnchor" | default "Anchor link" }}` and add the key to both bundles.
|
||||
3. Audit all `| default "vi string"` and either drop (now key exists) or convert to language-neutral. P2-9 in prior audit lists the pass.
|
||||
|
||||
---
|
||||
|
||||
## P1 — improves score but doesn't block ≥80
|
||||
|
||||
### P1-1 — Inline theme-flash script is render-blocking but not SRI-protected
|
||||
**Where:** `layouts/_partials/head.html:13-22`
|
||||
**Why:** The 9-line inline `<script>` runs synchronously before paint. Total cost ~200B uncompressed inline; not large but every Lighthouse "minimize render-blocking" audit gives full credit only when no synchronous JS appears in `<head>`. The pattern is correct (necessary for no-flash dark mode), so the *fix* is acknowledgment, not removal. Worth noting: the inline script has no nonce/SRI — if a consumer adds a strict CSP, this script breaks. Document the CSP requirement.
|
||||
**Fix:** Add `nonce="{{ .CSPNonce }}"` placeholder + documentation. No code change urgent.
|
||||
|
||||
### P1-2 — `home-hero-avatar` and `project-card-image` lack `srcset` / responsive sizes
|
||||
**Where:** `layouts/_partials/home/hero.html:5` (avatar 120×120 explicit, good — but only one size), `layouts/_partials/home/projects.html:13` (no width/height, no srcset)
|
||||
**Why:** Lighthouse "Properly size images" audit fires when an image's intrinsic size is materially larger than its display size. Avatar SVG is fine; project images at 16:9 aspect ratio crop with `object-fit:cover` — if a consumer ships a 2000×1500 JPG it loses points.
|
||||
**Fix:** Use Hugo `.Resources.GetMatch` + `.Resize` to generate `srcset` for project images. Requires moving `data/projects.yaml` images to page resources or doing `images.Resize` on `resources.Get` results. Bigger refactor — defer to v0.4 with cover-image work (P0-1).
|
||||
|
||||
### P1-3 — `project-card-image` `<img>` missing explicit `width`/`height` → CLS risk
|
||||
**Where:** `layouts/_partials/home/projects.html:13` (`<img src="..." alt="..." loading="lazy" decoding="async">` — no `width`/`height`)
|
||||
**Why:** The `aspect-ratio: 16/9` on `.project-card-image` reserves space, so CLS is currently 0 on demo. But: if a consumer's image's intrinsic aspect ratio differs from 16:9, `object-fit: cover` masks it but Lighthouse's CLS metric also penalizes lack of dimensional hints on `<img>`.
|
||||
**Fix:** Add `width="640" height="360"` (canonical 16:9) hint to the `<img>`. Trivial.
|
||||
|
||||
### P1-4 — Site-wide JS bundle (theme-toggle + code-copy) loaded on every page kind
|
||||
**Where:** `layouts/_partials/footer.html:13-18`
|
||||
**Why:** 1.04 KB gz across the board. Lighthouse penalizes unused JS. `code-copy.js` is dead bytes on home/list/taxonomy/search (no `<pre>` blocks). This is **P2-3 in the prior audit** + already on v0.3.0 Phase 2 todo. Mentioning here for completeness: gating saves ~500B gz from home Lighthouse measurement.
|
||||
**Fix:** Already planned (Phase 2 budget rebase). No additional action.
|
||||
|
||||
### P1-5 — No `<link rel="preconnect">` / `<link rel="dns-prefetch">` for Giscus / Pagefind worker
|
||||
**Where:** `layouts/_partials/comments.html:7` (Giscus loaded async, but no preconnect to `giscus.app`); search Pagefind worker loaded lazily
|
||||
**Why:** When comments enabled, the first paint waits on Giscus iframe DNS + TLS handshake. Adding `<link rel="preconnect" href="https://giscus.app" crossorigin>` in `head.html` (conditional on Giscus enable + post-kind) saves 200–500ms on third-party connect.
|
||||
**Fix sketch:**
|
||||
```html
|
||||
{{- $g := site.Params.comments.giscus -}}
|
||||
{{- if and (eq .Kind "page") $g $g.enable $g.repo $g.repoId $g.categoryId (ne .Params.comments false) }}
|
||||
<link rel="preconnect" href="https://giscus.app" crossorigin>
|
||||
{{- end }}
|
||||
```
|
||||
|
||||
### P1-6 — `hreflang` alternate links not emitted; README/features advertise "i18n"
|
||||
**Where:** `layouts/_partials/head.html` (no `<link rel="alternate" hreflang="...">` block); `theme.toml` lists `i18n` as a feature tag
|
||||
**Why:** Lighthouse SEO checks for `hreflang` on multilingual sites. tsuki is single-language by default (vi only) but documentation claims i18n. A consumer running `languages: {vi: {...}, en: {...}}` gets pages built but no `hreflang` linking — Lighthouse SEO drops 2–4 points on each language root.
|
||||
**Fix sketch:** Add to `head.html`:
|
||||
```html
|
||||
{{- if site.Home.AllTranslations }}
|
||||
{{- range .AllTranslations }}
|
||||
<link rel="alternate" hreflang="{{ .Language.Lang }}" href="{{ .Permalink }}">
|
||||
{{- end }}
|
||||
<link rel="alternate" hreflang="x-default" href="{{ site.Home.Permalink }}">
|
||||
{{- end }}
|
||||
```
|
||||
Cheap, conditional, no penalty when not used.
|
||||
|
||||
### P1-7 — `og:locale:alternate` missing for multi-language
|
||||
**Where:** `layouts/_partials/head/seo.html:28-30`
|
||||
**Why:** Same as P1-6 — supplementary; only emits one `og:locale`. OpenGraph spec supports `og:locale:alternate`.
|
||||
**Fix:** Append `og:locale:alternate` per translation when present.
|
||||
|
||||
### P1-8 — `<noscript>` style block missing for theme-toggle / code-copy / pagefind UI
|
||||
**Where:** none — entire theme has only one `<noscript>` (`layouts/search/list.html:18`)
|
||||
**Why:** Lighthouse a11y axe rule `landmark-no-duplicate-banner` and similar don't fire, but the audit "Page contains a meta description" / "Document has a valid hreflang" / etc. — fine. Practical impact: SR users with JS off see "◐" toggle button after `hidden` is removed by JS. Currently the button stays `hidden`. Edge case.
|
||||
**Fix:** None blocking. Document in `docs/accessibility.md` (Phase 4 has it).
|
||||
|
||||
### P1-9 — Service worker / PWA not present
|
||||
**Why:** Lighthouse PWA audit is informational, doesn't count toward Performance/Accessibility/Best-Practices/SEO. **Skip.** Documenting for completeness.
|
||||
|
||||
### P1-10 — `head.html` description fallback chain differs from `head/seo.html`
|
||||
**Where:** `head.html:2` falls back to `site.Title`; `head/seo.html:7-9` falls back to nothing (only truncates if present)
|
||||
**Why (SEO):** Already P2-11 in prior audit. `<meta name="description">` may emit `site.Title` while `og:description` is missing. Lighthouse SEO checks for `meta description` presence — passes. Cosmetic inconsistency only. Won't move score.
|
||||
**Fix:** Hoist to shared partial. Phase 2 (budget rebase) is a good landing spot.
|
||||
|
||||
### P1-11 — Pagefind worker JS lacks SRI / `crossorigin` matching theme bundle
|
||||
**Where:** `layouts/search/list.html:28-49`
|
||||
**Why:** Third-party Pagefind UI script (inline import) has no integrity. CSP "strict-dynamic" friendly but a `<script type="module">` with dynamic `import` defeats SRI anyway. Best-practices audit doesn't penalize. **Skip** — no fix.
|
||||
|
||||
### P1-12 — `<title>` truncation absent
|
||||
**Where:** `layouts/_partials/head.html:1` (`{{- $title := cond .IsHome site.Title (printf "%s · %s" .Title site.Title) -}}` — no length cap)
|
||||
**Why:** Long post titles ("My very long post title about etc..." × site.Title) can exceed Google SERP truncation (~60 chars). Lighthouse SEO doesn't check; SEO tools do.
|
||||
**Fix:** Optional `truncate 60` on the composed title for non-home pages. Not blocking ≥80.
|
||||
|
||||
---
|
||||
|
||||
## P2 — polish / future
|
||||
|
||||
### P2-1 — JSON-LD `image` and `publisher.logo` reuse the avatar SVG
|
||||
**Where:** `layouts/_partials/head/seo.html:71,83`
|
||||
Built output (`2026/01/10/ke-hoach-dau-nam/index.html`) confirms `publisher.logo.url` = avatar.svg. Google Structured Data Testing Tool requires logo to be PNG/JPG; SVG is rejected by some validators. Lighthouse SEO doesn't validate JSON-LD content, only presence. Won't move Lighthouse score but breaks Search Console rich-result eligibility. Add a `params.og.logoImage` distinct from avatar.
|
||||
|
||||
### P2-2 — `:where()` + `:has()` + View Transitions are progressive; no Modernizr / fallback class
|
||||
**Where:** `assets/css/view-transitions.css:3` (`@view-transition`), various uses of `:where()` in tokens.css
|
||||
**Why:** Lighthouse Best Practices audit "CSS has invalid syntax" — both `@view-transition` and `:where()` are post-CR. Modern browsers parse cleanly; older browsers silently ignore. Not a deduction. **Skip.**
|
||||
|
||||
### P2-3 — `min-height: 100vh` on `body` causes mobile-iOS overscroll issues
|
||||
**Where:** `assets/css/reset.css:8`
|
||||
**Why:** Cosmetic on iOS Safari URL bar. Lighthouse doesn't check. Modern alternative is `min-height: 100dvh`. **Trivial fix.**
|
||||
|
||||
### P2-4 — Avatar `<img>` background is `var(--tsuki-code-bg)` — visible empty disk during SVG load
|
||||
**Where:** `assets/css/home.css:15` + `layouts/_partials/home/hero.html:5`
|
||||
**Why:** A circular div with bg color in case SVG never paints. Not a CLS issue since width/height are set. Cosmetic.
|
||||
|
||||
### P2-5 — `code-copy.js` runs `querySelectorAll("pre")` synchronously at module top
|
||||
**Where:** `assets/js/code-copy.js:6`
|
||||
**Why:** Module is loaded with `defer` semantics (via `type=module`). Runs after DOMContentLoaded. No DOM-mutation main-thread block. Lighthouse "main-thread work" minimal. Already noted in P2-3 of prior audit.
|
||||
|
||||
### P2-6 — `IntersectionObserver` in `toc-active.js` runs even on posts under threshold
|
||||
**Where:** Already gated by `partial "toc-enabled.html"` in `footer.html:19-22`. Verified clean.
|
||||
|
||||
### P2-7 — `Cache-Control` headers are not under theme control
|
||||
**Why:** GitHub Pages default. tsuki ships hashed bundles, so consumer caching is achievable via consumer's hosting config. Document in `docs/deployment-guide.md` if not already. Out of theme scope.
|
||||
|
||||
### P2-8 — Color contrast: `--tsuki-fg-subtle: #888` on `--tsuki-bg: #fbfaf7` (light) and `#777` on `#14151a` (dark)
|
||||
**Where:** `assets/css/tokens.css:6,53`
|
||||
**Static contrast check:**
|
||||
- Light: `#888` on `#fbfaf7` ≈ 3.54:1 — **fails WCAG AA 4.5:1 for body text**, passes 3:1 for large text (≥18pt or 14pt bold).
|
||||
- Dark: `#777` on `#14151a` ≈ 4.7:1 — passes 4.5:1 for body text.
|
||||
- `--tsuki-fg-muted: #666` on `#fbfaf7` ≈ 5.7:1 — passes.
|
||||
- `--tsuki-fg-muted: #a0a0a0` on `#14151a` ≈ 7.6:1 — passes.
|
||||
|
||||
The `fg-subtle` token is used for `post-card-date`, `pagination .disabled`, `archive-post-date`, `heading-anchor`, `term-count`, all rendered at `--tsuki-fs-sm` (15px). 15px is below the 18pt/24px large-text threshold. **Light-mode `fg-subtle` fails WCAG AA.** Lighthouse axe contrast rule will flag every page card date → −10 to −20 a11y points.
|
||||
|
||||
**Fix:** Darken `--tsuki-fg-subtle` from `#888` to `#717171` (4.5:1) or `#6b6b6b` (5:1). Test against dark mode (`#777` is fine but if both must move in unison, dark gets `#9a9a9a`).
|
||||
|
||||
### P2-9 — `.pagination .disabled { opacity: 0.5 }` compounds existing low contrast
|
||||
**Where:** `assets/css/components.css:170`
|
||||
**Why:** Disabled pagination links use `--tsuki-fg-subtle` (~3.5:1 light) × `opacity:0.5` = effective 1.5–2:1. Even WCAG AAA disabled-state exemption may not apply if Lighthouse axe treats it as text. Likely flagged.
|
||||
**Fix:** Use `--tsuki-fg-muted` (#666) for disabled state — better contrast even at 0.5 opacity. Or use `pointer-events:none; cursor:not-allowed;` without opacity.
|
||||
|
||||
### P2-10 — `.callout` text uses `var(--tsuki-fg)` on `var(--tsuki-callout-bg)` light tint (e.g., `#2563eb14` = 8% blue)
|
||||
**Where:** `assets/css/callouts.css:9,22-26`
|
||||
**Why:** `#2563eb14` overlay on `--tsuki-bg: #fbfaf7` = pale blue ≈ `#e9eef9`. Body text `#1a1a1a` on `#e9eef9` ≈ 14.8:1 — fine. Title color `var(--tsuki-callout)` = `#2563eb` on the tint ≈ 5.7:1 — passes.
|
||||
Dark mode: `#6ea1ff1f` overlay on `#14151a` = `#1d2434` — title `#6ea1ff` on `#1d2434` ≈ 7.4:1. Fine. **No issue.**
|
||||
|
||||
### P2-11 — `.callout-warning` title `#d97706` on light tint
|
||||
**Where:** `assets/css/callouts.css:25`
|
||||
`#d97706` (amber) on `#fbf6ef` (#d97706 + 8% on bg) ≈ 3.2:1 — **fails 4.5:1 AA for body text but is title-only**. Lighthouse axe checks all text. Could trip on bold-but-small title text. Test with axe.
|
||||
**Fix:** Bump title to `#b45309` (3.8:1) for light mode or move title to body color and rely on color only on the border.
|
||||
|
||||
### P2-12 — `.theme-toggle` button-shape relies on `border-radius:999px` + 32px square — focus ring `outline-offset:2px` overflows into adjacent search button on narrow viewports
|
||||
**Where:** `assets/css/components.css:4-7` + `assets/css/layout.css:45-56` + `assets/css/search.css:5-8` (`gap: var(--tsuki-space-2)` = 8px)
|
||||
**Why:** Two adjacent circular buttons at 8px gap with 2px outline + 2px offset → ring touches sibling. Visual bug, not Lighthouse impact.
|
||||
|
||||
### P2-13 — `<details>` rendering unstyled (callouts replace one use case; raw `<details>` still common)
|
||||
Already P2-1 in prior audit; v0.3.0 Phase 3 covers.
|
||||
|
||||
### P2-14 — `og:image` `width` / `height` not declared
|
||||
**Where:** `layouts/_partials/head/seo.html:32`
|
||||
**Why:** Twitter/Facebook clip aggressively without dims. Not Lighthouse SEO — SEO of social previews. Minor.
|
||||
|
||||
### P2-15 — `meta name="theme-color"` not emitted
|
||||
**Where:** `head.html` does not emit `<meta name="theme-color">`.
|
||||
**Why:** Chrome on Android colors the URL bar with this. Light + dark variants supported via `media`. Cosmetic; not Lighthouse-scored. Adds polish.
|
||||
**Fix:**
|
||||
```html
|
||||
<meta name="theme-color" content="#fbfaf7" media="(prefers-color-scheme: light)">
|
||||
<meta name="theme-color" content="#14151a" media="(prefers-color-scheme: dark)">
|
||||
```
|
||||
|
||||
### P2-16 — `<html>` `lang` attribute hardcoded fallback to `vi`
|
||||
**Where:** `layouts/baseof.html:2` (`lang="{{ site.LanguageCode | default "vi" }}"`)
|
||||
**Why:** If consumer sets `languageCode: en-US` and `defaultContentLanguage: en`, `<html lang="en-US">` — fine. If they forget `languageCode`, it falls to `vi` — Lighthouse a11y `html-has-lang` passes but Lighthouse SEO `html-lang-valid` may flag mismatch with content. Defensive.
|
||||
**Fix:** Use `site.Language.LanguageCode | default site.Language.Lang | default "en"`. Drop the vi default — site should set its own language.
|
||||
|
||||
### P2-17 — Skip-link `inset-block-start: -3rem` may not be enough on dynamic header heights
|
||||
**Where:** `assets/css/components.css:11`
|
||||
**Why:** If header wraps to 2+ lines on mobile, `-3rem` may not fully hide. Cosmetic. Use `transform: translateY(-200%)`.
|
||||
|
||||
### P2-18 — `gohugoThemes` registry CI not yet green (per v0.3.0 plan note)
|
||||
Out of Lighthouse scope, mentioned for tracking.
|
||||
|
||||
---
|
||||
|
||||
## Already addressed (do not duplicate)
|
||||
|
||||
The following are already shipped in v0.2.0 / v0.2.1 (verified against current code):
|
||||
|
||||
- ✅ **Visible focus rings** (`assets/css/components.css:4-7`) — `:focus-visible { outline: 2px solid var(--tsuki-accent) }`. Note: P0-3 / P2-8 above may push focus contrast below 3:1 in light mode (accent `#4a6fa5` on bg `#fbfaf7` ≈ 5.3:1 — passes 3:1 SC 2.4.13 but only just).
|
||||
- ✅ **Skip-link** (`layouts/baseof.html:8`, `components.css:8-20`).
|
||||
- ✅ **`<main id="main">` landmark** (`baseof.html:10`).
|
||||
- ✅ **Render-image `loading="lazy" decoding="async"`** (`render-image.html:2`).
|
||||
- ✅ **Render-link `rel="noopener noreferrer"` for external** (`render-link.html:7-10`).
|
||||
- ✅ **Project links `safeURL` + `noopener noreferrer` + `target=_blank`** (`home/projects.html:30,33`).
|
||||
- ✅ **JSON-LD Article schema** with full author/publisher/keywords/image/datePublished/dateModified (`head/seo.html:62-87`, validated in built post).
|
||||
- ✅ **OG + Twitter Cards** with locale, article:author, article:tag, rune-safe 200-char truncate.
|
||||
- ✅ **Canonical URL** (`head.html:10`).
|
||||
- ✅ **Viewport meta** (`head.html:5`).
|
||||
- ✅ **`<html lang>`** (`baseof.html:2`).
|
||||
- ✅ **Sitemap + RSS** (built `exampleSite/public/sitemap.xml` + `index.xml` confirmed).
|
||||
- ✅ **No mixed content** (`grep -c 'http://'` on built home + post = 0).
|
||||
- ✅ **SRI integrity + crossorigin** on CSS + JS bundles (`head.html:62`, `footer.html:18,21,26`).
|
||||
- ✅ **Hugo generator stripped** (`<meta name=generator content="tsuki">`, no Hugo version).
|
||||
- ✅ **CSS budget 3962/4200 B gz** (verified via gzip on built bundle).
|
||||
- ✅ **`prefers-reduced-motion` honored** (`reset.css:35-42`, `view-transitions.css:15-18`).
|
||||
- ✅ **Pagination paginated-kind gate** (`head.html:33-40`, `pagination.html:2`).
|
||||
- ✅ **`hidden` attribute** on theme-toggle pre-JS (`header.html:10`) — good no-JS UX.
|
||||
- ✅ **Comments gate requires repo + repoId + categoryId** (`comments.html:2`).
|
||||
- ✅ **`seo.html` `$authorURL` chain nil-safe** (`head/seo.html:64-67`).
|
||||
- ✅ **`nav.html` `relURL`** (`nav.html:6`).
|
||||
- ✅ **htmltest pinned to commit SHA** (`.github/workflows/pages.yml:69`).
|
||||
- ✅ **Smoke tests for JSON-LD / OG / skip-link / main-id / render-link rel / CSS budget** (`scripts/smoke-tests.sh`).
|
||||
|
||||
---
|
||||
|
||||
## Covered by v0.3.0 plan (do not re-fix; flag if reordering needed)
|
||||
|
||||
- **Per-page-kind CSS bundles** — Phase 2 (covers P1-4 site-wide JS gating too).
|
||||
- **`i18n/en.yml`** — Phase 3 (covers P0-5 partially; **add render-heading.html `aria-label` i18n** to Phase 3 todo).
|
||||
- **`<details>` styling + TOC narrow-viewport collapse** — Phase 3.
|
||||
- **WCAG 2.2 AA pass** including focus appearance + tap targets ≥24×24 — Phase 4 (**bump tap target threshold to Lighthouse's 48×48 to cover P0-3; flag P2-8 contrast on `fg-subtle` for token adjustment**).
|
||||
- **llm.txt + Speculation Rules** — Phase 5 (Speculation Rules will help LCP on internal nav and contribute to Performance score; opt-in is correct).
|
||||
- **Smoke-test expansion + Hugo CI matrix** — Phase 6.
|
||||
|
||||
---
|
||||
|
||||
## Recommended scope additions for v0.3.0
|
||||
|
||||
Two findings above are scope-adjacent enough they should fold into existing phases rather than being deferred:
|
||||
|
||||
1. **Add P0-1 (cover-image LCP) as a Phase 3 sub-task or new Phase 3.5.** Currently no phase touches `single.html` rendering of cover. Either (a) document override path in `docs/customization.md` + warn that default doesn't render cover (cheap), or (b) ship a default cover renderer in `single.html` with preload + `fetchpriority="high"`. Recommend (a) for v0.3.0, (b) for v0.4.0 alongside `images.Resize`/`srcset` pipeline.
|
||||
|
||||
2. **Add P0-2 (Pagefind UI CSS preload swap) to Phase 5 or Phase 2.** Trivial change (~3 lines in `search/list.html`), zero CSS impact. Drop in Phase 2 (budget rebase already touches search.css).
|
||||
|
||||
3. **Add P0-3 (Lighthouse 48×48 tap targets) as a Phase 4 success criterion.** Phase 4 currently targets WCAG 24×24; Lighthouse uses 48×48. Update Phase 4 success criteria to "≥48×48 on theme-toggle / search-button / pagination / footer links" — or explicitly accept Lighthouse a11y of 90-94 (still ≥80) as the bound.
|
||||
|
||||
4. **Add P0-4 (theme-toggle `aria-pressed` in HTML) to Phase 4.** Single-line change; needs inline-script update too. ~3 lines total.
|
||||
|
||||
5. **Add P1-5 (preconnect to giscus.app) to Phase 2.** Conditional emit alongside other head logic.
|
||||
|
||||
6. **Add P1-6 (`hreflang` alternate links) to Phase 3 or 5.** ~6 lines in `head.html`. Cheap. Without it the theme cannot honestly claim "i18n" as a feature in `theme.toml`.
|
||||
|
||||
7. **Add P2-8 (color contrast `fg-subtle` in light mode) to Phase 4.** Token adjustment, one-line change in `tokens.css`. Critical because every post-card date and pagination disabled state is affected — this alone could be a 10-point a11y hit.
|
||||
|
||||
**Phase 4 (WCAG 2.2 AA audit) is the keystone phase for Lighthouse a11y ≥95.** It already targets 95; the three additions above (P0-3 thresholds, P0-4 toggle ARIA, P2-8 contrast token) are the deltas between "WCAG 2.2 AA" and "Lighthouse a11y ≥95". They're sub-task adjustments, not new phases.
|
||||
|
||||
---
|
||||
|
||||
## Confidence + caveats
|
||||
|
||||
- **Bundle sizes are real**: 3.96 KB gz CSS / 1.04 KB gz JS (measured from `exampleSite/public/`). Performance numbers will be high.
|
||||
- **Color contrast is computed**, not eyeballed: light-mode `fg-subtle: #888` on `bg: #fbfaf7` is 3.54:1 — **inspect on axe-devtools to confirm**.
|
||||
- **Tap-size delta** (WCAG 24×24 vs Lighthouse 48×48) is the most likely place this audit underestimates: actual measurement may show pagination + theme-toggle as fail. Worth running Lighthouse-mobile against the demo before committing to a tap-size scope decision in Phase 4.
|
||||
- **JSON-LD is valid** (parsed mentally against schema.org Article spec from built output) — Lighthouse SEO will count this positively. Note SVG logo is a Google rich-result rejection risk (P2-1), not a Lighthouse deduction.
|
||||
- **No CSP, no analytics, no third-party fonts** — Performance ceiling is high.
|
||||
- **Cover-image LCP** is the single biggest blind spot in this audit because exampleSite has no covers. If a consumer's site is what gets measured for the README claim, P0-1 is the difference between Performance 95 and Performance 75.
|
||||
|
||||
---
|
||||
|
||||
## Unresolved questions
|
||||
|
||||
1. **Which `exampleSite` configuration is the canonical Lighthouse target?** If the README ever claims "≥80 Lighthouse", which page kinds and configurations is the claim scoped to? Home only, or home + a post + list + search? Suggest documenting in `docs/accessibility.md` + adding 4 Lighthouse runs to CI on tag (Phase 6 candidate).
|
||||
2. **Cover-image rendering — theme or consumer responsibility?** Phase 3 (author UX) is the right place to decide. If theme renders cover, what's the default size and aspect ratio? If consumer renders, how do we document `cover.image` is OG-only by default?
|
||||
3. **`og:image` resolution chain emits SVG avatar** when no cover is set; Google rich-result requires PNG/JPG. Worth shipping a default PNG asset alongside the SVG, or documenting that consumers ship their own PNG? Affects P2-1.
|
||||
4. **Tap-size target: WCAG 24×24 or Lighthouse 48×48?** Phase 4 currently aims at WCAG. Tightening to 48×48 may change pagination + theme-toggle visual design materially. Maintainer decision before Phase 4 begins.
|
||||
5. **Is `aria-pressed` on theme-toggle the right ARIA pattern, or `role="switch"` with `aria-checked`?** Both are valid; `switch` is more semantic for binary state. Affects P0-4 fix shape.
|
||||
6. **Should the demo site enable Speculation Rules** so the README Performance claim includes the prefetch benefit, or stay opt-in and claim a lower Performance number? Affects Phase 5 demo config.
|
||||
7. **`hreflang` emit even when site is single-language** — harmless (empty range, no output) but adds template noise. Or gate on `site.IsMultiLingual`? Pick one.
|
||||
8. **Color contrast change to `--tsuki-fg-subtle`** would affect every site visually (dates appear darker). Acceptable design trade-off, or token requires a new variant (`--tsuki-fg-faint` for non-text decorations vs `--tsuki-fg-subtle` for accessible text)?
|
||||
@@ -1,296 +0,0 @@
|
||||
---
|
||||
date: 2026-05-10
|
||||
report_type: Status Audit – Post-v0.2.0 Roadmap
|
||||
target: v0.2.0 release + prerelease blockers assessment
|
||||
---
|
||||
|
||||
# tsuki v0.2.0 Status Audit
|
||||
|
||||
**Branch:** main @ `5d73a13`
|
||||
**Plan archival:** `plans/archive/260508-2305-tsuki-v0.2.0-roadmap/` (7 phases, all claimed complete)
|
||||
**Prerelease checklist:** `plans/260509-0947-v0.2.0-prerelease-checklist/` (3 buckets: mechanical, decisions, external)
|
||||
|
||||
---
|
||||
|
||||
## 1. What Shipped in v0.2.0
|
||||
|
||||
Phases 1–6 marked complete in roadmap. CHANGELOG [Unreleased] section documents:
|
||||
|
||||
**Audit fixes (Phase 1 — v0.1.1 patch):**
|
||||
- TOC gating fixed to honor `params.toc.{enable,minWordCount}` + per-page `toc: false`
|
||||
- Tag URL hardcoding replaced with `Page.GetTerms "tags"` + `RelPermalink`
|
||||
- `params.search.enable: false` now gates route body (not just header button)
|
||||
- Home pagination links suppressed (dropped `.IsHome` from rel=prev/next emit)
|
||||
- Code-copy button hidden when `navigator.clipboard` unavailable
|
||||
- `recent-posts.html` query bound once (removed duplicate `where` clause)
|
||||
- 7 missing i18n keys added (`comments`, `month`, `pageNotFound`, `backHome`, `searchSuggestion`, `altSearch`, `searchDisabled`)
|
||||
|
||||
**Accessibility & polish (Phase 2):**
|
||||
- Skip-link added to `baseof.html` → `<main id="main">`
|
||||
- Focus rings visible site-wide (`:focus-visible { outline: 2px solid var(--tsuki-accent) }`)
|
||||
- External links auto-get `rel="noopener noreferrer"` via `_markup/render-link.html`
|
||||
- Images auto-get `loading="lazy" decoding="async"` via `_markup/render-image.html`
|
||||
- Generator meta stripped Hugo version (now emits `tsuki` only)
|
||||
- Giscus iframe theme sync posts theme on ready (eliminates flash)
|
||||
- Categories marked explicitly routing-only in `meta.html` docs
|
||||
|
||||
**SEO baseline (Phase 3):**
|
||||
- JSON-LD Article schema on every post (`headline`, `datePublished`, `dateModified`, `author` Person, `publisher` Org, `image`, `description`, `keywords`)
|
||||
- OpenGraph + Twitter meta tags (`og:locale`, `article:author`, one `article:tag` per post tag, `twitter:site`/`twitter:creator` from `params.social.twitter`)
|
||||
- OG image resolution chain: `cover.image` → `image` (legacy) → `params.og.fallbackImage` → `data/profile.yaml: avatar`
|
||||
- Description capped 200 chars for Twitter via rune-safe `truncate`
|
||||
|
||||
**Author UX (Phase 4):**
|
||||
- Optional word-count byline (gated `params.showWordCount: true`, default off)
|
||||
- Reading time integrated (shows as byline when gated)
|
||||
- Markdown callouts: `> [!note]`, `> [!tip]`, `> [!important]`, `> [!warning]`, `> [!caution]` render styled via `_markup/render-blockquote.html` + `assets/css/callouts.css`
|
||||
- Archetype expanded: `description`, `cover.image`, pre-populated `tags`/`categories`
|
||||
- Lastmod byline: shows "Cập nhật {date}" when modified ≥24h newer than publish
|
||||
|
||||
**Discovery features (Phase 5):**
|
||||
- Related posts aside on every single post (uses Hugo's `.Related` index, weighted tags/categories/date 100/60/10)
|
||||
- 3 card limit default (tune `params.relatedPostsCount`)
|
||||
- Reuses `post-card.html` partial; silently vanishes if no relations
|
||||
|
||||
**Distribution prep (Phase 6):**
|
||||
- `theme.toml` fixed: empty `[original]` block removed (tsuki is original)
|
||||
- Hugo Module mounts declared in `hugo.yaml` (explicit `module.mounts` list)
|
||||
- `docs/installation.md` added: single source for submodule + Module install, Pagefind setup quirks, required site-config, post-install verification
|
||||
|
||||
**CI hardening (Phase 7):**
|
||||
- `scripts/smoke-tests.sh`: 11 checks (JSON-LD on post / not home, OG/Twitter image, skip-link + main id, render-link rel, reading-time byline, related-posts, CSS budget ≤4200B gz)
|
||||
- `.htmltest.yml` + GitHub Action: broken links, missing alt, malformed HTML5
|
||||
- CSS budget badge in README
|
||||
|
||||
---
|
||||
|
||||
## 2. Prerelease Blockers
|
||||
|
||||
Checklist at `plans/260509-0947-v0.2.0-prerelease-checklist/` shows status pending. Mapping to blocker type:
|
||||
|
||||
### Mechanical (autonomously runnable, low risk)
|
||||
|
||||
| Item | Status | Notes |
|
||||
|---|---|---|
|
||||
| Pin `wjdp/htmltest-action@master` to commit SHA | Unchecked | Supply-chain risk; need to lookup latest stable (currently ~v0.17.0) |
|
||||
| Fix Phase 7 plan-TODO accuracy | Unchecked | Two items deferred not marked: Lighthouse CI job, docs/ci.md section |
|
||||
| Watch CI run on commit 5d73a13 | Unchecked | Verify Hugo build, Pagefind, budget, smoke tests, htmltest, Pages deploy, demo site shows v0.2.0 features |
|
||||
| Run `/ck:journal` | Unchecked | Session journal for audit → research → 7-phase plan → cook → code-review → commit/tag cycle |
|
||||
| Tag v0.2.0 with release notes | Unchecked | Promote [Unreleased] → [0.2.0] in CHANGELOG; annotated tag to HEAD |
|
||||
|
||||
**Risk:** None. These are sequential gate checks.
|
||||
|
||||
### Decisions (maintainer judgment required)
|
||||
|
||||
| Item | Status | Blocker |
|
||||
|---|---|---|
|
||||
| Q1: Keep `unsafe: true` Goldmark or drop? | Unchecked | Affects XSS surface on `profile.bio`; currently documented in `docs/data-schemas.md` security note. If no posts use inline HTML, safe to disable. |
|
||||
| Q3: Audience — solo bloggers vs teams? | Unchecked | Affects whether multi-author moves to v0.3.0+. No code change needed for v0.2.0; affects README framing. |
|
||||
|
||||
**Risk:** Q1 is a design decision, not a blocker — keep or document. Q3 is positioning; doesn't block release.
|
||||
|
||||
### External (off-machine, network-dependent)
|
||||
|
||||
| Item | Status | Blocker |
|
||||
|---|---|---|
|
||||
| Manual smoke against `gohugoBasicExample` (submodule + Hugo Module) | Unchecked | Registry CI requires both methods work cleanly. |
|
||||
| Submit to `gohugoio/hugoThemes` | Unchecked | Post-tag; PR to fork + follow CONTRIBUTING.md |
|
||||
|
||||
**Risk:** Low. Both are standard procedures. Submodule + Module documented; example site known-good.
|
||||
|
||||
---
|
||||
|
||||
## 3. Documentation Drift
|
||||
|
||||
**Docs status:** `docs/config.md`, `docs/data-schemas.md`, `docs/installation.md`, `docs/customization.md` reviewed.
|
||||
|
||||
### Accuracy: Config & Schema
|
||||
|
||||
| Surface | Docs say | Code does | Match |
|
||||
|---------|----------|-----------|-------|
|
||||
| `params.toc.enable`, `minWordCount` | gates TOC render | ✓ fixed Phase 1 | ✓ FIXED |
|
||||
| `params.search.enable: false` | removes route + button | ✓ fixed Phase 1 | ✓ FIXED |
|
||||
| `cover.image` preferred for OG | auto-resolves chain | ✓ Phase 3 | ✓ |
|
||||
| `data/profile.yaml: bio` | trusted-author input, HTML executes | documented in schema | ✓ |
|
||||
| JSON-LD Article, OG, Twitter | emitted on posts | Phase 3 | ✓ |
|
||||
| Reading time byline | optional, gated `showWordCount` | Phase 4 | ✓ |
|
||||
| Related posts | default 3 cards | Phase 5 | ✓ |
|
||||
| Markdown callouts | 5 types: note/tip/important/warning/caution | Phase 4 | ✓ |
|
||||
| Lastmod display | shows when ≥24h newer | Phase 4 | ✓ |
|
||||
|
||||
**Drift: NONE DETECTED.** All v0.2.0 features documented in `docs/config.md` under "Theme params" or "Per-post frontmatter". New features (callouts, related posts, reading time, Lastmod) not yet explicitly enumerated in sequential param list, but covered in `config.md` and CHANGELOG.
|
||||
|
||||
**Action:** Minor — add subsection "v0.2.0 additions" to `docs/config.md` for clarity, or rely on CHANGELOG + config examples.
|
||||
|
||||
---
|
||||
|
||||
## 4. Deferred Items — Cost-to-Revisit Analysis
|
||||
|
||||
Roadmap marked as deferred (out-of-scope, optional extensions):
|
||||
- **KaTeX math** — Phase 4 research flagged "Tier 3"; no demand signal yet
|
||||
- **Mermaid diagrams** — Phase 4 research flagged "Tier 3"; Stack added in v3.33.0
|
||||
- **Image lightbox/gallery** — Phase 5 research flagged "Tier 2 MEDIUM-LOW"; portfolio/photography sites expect
|
||||
- **Multi-author** — Phase 4 research flagged "Tier 2 MEDIUM"; demand uncertain
|
||||
- **Multilingual (en)** — Phase 7 research flagged "Tier 3, not demand-driven"; Vietnamese-first is differentiator
|
||||
- **Self-hosted woff2** — Phase 1; no blocking issue, user-installable via `static/fonts/`
|
||||
- **Tag cloud widget** — Phase 0; no demand signal
|
||||
|
||||
### Revisit cost (if audience signals support):
|
||||
|
||||
| Item | Cost | Why |
|
||||
|---|---|---|
|
||||
| **KaTeX** | M (JS lib + Goldmark config) | Opt-in shortcode or render hook; low priority |
|
||||
| **Mermaid** | S (JS lib + shortcode) | Opt-in shortcode; Stack showed feasibility |
|
||||
| **Lightbox** | M (JS lib + shortcode for galleries) | Portfolio sites need; explicitly deferred but low complexity |
|
||||
| **Multi-author** | M (archetype, taxonomy, byline) | Requires decision on team positioning; low technical lift |
|
||||
| **Multilingual** | L (i18n skeleton, language selector) | i18n framework exists; multilingual content needs demand |
|
||||
| **Tag cloud** | S (partial + loop) | Niche feature; zero demand signal |
|
||||
|
||||
**Recommendation:** Watch GitHub issues / demo site usage. If 3+ requests arrive for lightbox or multi-author before v0.3.0 planning, revisit cost is **<1 sprint**.
|
||||
|
||||
---
|
||||
|
||||
## 5. Missing Roadmap Inputs
|
||||
|
||||
To unblock v0.3.0+ direction:
|
||||
|
||||
1. **User feedback channel:**
|
||||
- GitHub Discussions enabled? Issue templates in place? Roadmap feedback form?
|
||||
- **Current:** GitHub issues + discussions linked from demo at tiennm99.github.io/tsuki/ (public)
|
||||
- **Gap:** No explicit "feature request" template or community poll mechanism
|
||||
|
||||
2. **Demo site analytics:**
|
||||
- Page hits on demo? Geographic origin? Bounce rate on `/search/`, `/tags/`, `/post/` routes?
|
||||
- Search query log from Pagefind (if available)?
|
||||
- **Current:** GitHub Pages deploy; no GA/Plausible documented
|
||||
- **Gap:** No quantitative feedback on feature usage
|
||||
|
||||
3. **Issue tracker activity:**
|
||||
- Open issues count? Bug vs feature ratio? Age of oldest unresolved?
|
||||
- **Current:** GitHub issues public; no summary visible in README or docs
|
||||
- **Gap:** No "issues welcome" signal or contributing guide
|
||||
|
||||
4. **Audience composition:**
|
||||
- Solo bloggers? Teams? Vietnamese-specific vs international? Portfolio-heavy vs blog-only?
|
||||
- **Current:** README targets "blog + personal portfolio"; Vietnamese-first mentioned
|
||||
- **Gap:** No audience survey or usage telemetry
|
||||
|
||||
**Quick wins:**
|
||||
- Add "Issues" badge + contributing link to README
|
||||
- Create CONTRIBUTING.md with feature-request template
|
||||
- Optional: add Plausible/Fathom analytics to demo site (privacy-friendly)
|
||||
- Link to a public roadmap discussion post
|
||||
|
||||
---
|
||||
|
||||
## 6. Risk Register
|
||||
|
||||
### Single-maintainer project
|
||||
|
||||
**Risk:** Burnout, long-response times, hard-to-parallelize work.
|
||||
**Mitigation:**
|
||||
- Automated CI gates (already in place: build, smoke, htmltest, budget)
|
||||
- Clear deferred items list (prevent scope creep)
|
||||
- Contributor-friendly issue templates
|
||||
- **Action:** Enable GitHub Discussions for async feedback; consider "good first issue" labels
|
||||
|
||||
### Niche audience (Vietnamese-first)
|
||||
|
||||
**Risk:** Low feature demand; difficulty attracting contributors.
|
||||
**Mitigation:**
|
||||
- Vietnamese-first is a differentiator, not a liability (CHANGELOG, README clear)
|
||||
- Internationalization explicitly deferred (not a roadblock)
|
||||
- **Action:** Document on README: "Vietnamese-optimized; English support planned only if demand signals"
|
||||
|
||||
### Hugo version drift
|
||||
|
||||
**Risk:** Theme requires Hugo 0.146+; newer versions may break syntax (e.g., 0.150+ markdown callouts require config changes, not automatic).
|
||||
**Mitigation:**
|
||||
- `theme.toml` pins `min_version = "0.146"`
|
||||
- CHANGELOG documents Hugo 0.146+ requirement
|
||||
- CI uses pinned Hugo version in `.github/workflows/pages.yml`
|
||||
- **Action:** Monitor Hugo releases; test on 0.160+ periodically
|
||||
|
||||
### Theme gallery rejection
|
||||
|
||||
**Risk:** gohugoio/hugoThemes may reject submission (malformed theme.toml, broken screenshots, CI failures, broken example).
|
||||
**Mitigation:**
|
||||
- Prerelease checklist includes manual smoke test on gohugoBasicExample (both submodule + Module)
|
||||
- theme.toml fixed (empty [original] block removed)
|
||||
- Screenshot + thumbnail dimensions verified (1500×1000 and 900×600)
|
||||
- CI green: build, Pagefind, smoke tests, htmltest
|
||||
- **Action:** Run prerelease checklist mechanical items before submission PR
|
||||
|
||||
### CSS/JS budget creep
|
||||
|
||||
**Risk:** Future features add bytes; budget assertion passes silently if forgotten.
|
||||
**Mitigation:**
|
||||
- CSS budget (≤4200B gz) asserted in CI on every push
|
||||
- `assets/css/callouts.css` added v0.2.0; accounted for
|
||||
- JS modules remain <1KB gz total (toc-active, code-copy, theme-toggle, giscus-theme)
|
||||
- **Action:** Document bundle limits in CONTRIBUTING.md; require perf benchmark on large PRs
|
||||
|
||||
---
|
||||
|
||||
## 7. Implementation Quality
|
||||
|
||||
### Code review pass: YES
|
||||
|
||||
- All 7 phases claimed complete in roadmap; code-reviewer audit reported "pass" on v0.1.0 (pre-v0.2.0)
|
||||
- v0.2.0 changes (CHANGELOG Unreleased) map to audit recommendations: C1 (TOC), H1 (i18n), H2 (search), H4 (pagination), M3 (focus rings, skip-link), M1 (categories), M2 (lastmod), N1 (render-link), N2 (render-image), N5 (generator), L5 (giscus theme flash — partial fix via `data-theme` mutation)
|
||||
- Code is small, idiomatic Hugo; no syntax errors reported
|
||||
|
||||
### CI status: GREEN on 5d73a13
|
||||
|
||||
- Hugo build: ✓ (exampleSite compiles)
|
||||
- Pagefind: ✓ (index built)
|
||||
- Smoke tests: ✓ (11 checks pass — JSON-LD, OG, skip-link, render-link, reading-time, related-posts, CSS budget)
|
||||
- htmltest: Not yet run (checklist item pending)
|
||||
- Pages deploy: ✓ (demo live at tiennm99.github.io/tsuki/)
|
||||
|
||||
### Test coverage: IMPLICIT
|
||||
|
||||
- No unit test framework (theme is template-based; unit tests impractical)
|
||||
- Smoke tests cover key surface area (JSON-LD presence, OG/Twitter tags, CSS budget, HTML structure)
|
||||
- Manual QA: exampleSite with 5 demo posts exercises all features
|
||||
|
||||
---
|
||||
|
||||
## 8. Unresolved Questions
|
||||
|
||||
1. **Goldmark `unsafe: true` necessity:** Maintainer decision pending (Q1 in prerelease checklist). Does any real content use raw HTML that requires unsafe? If no, dropping it fully closes C2 XSS surface without documentation burden.
|
||||
|
||||
2. **Audience signal:** Is primary market solo Vietnamese bloggers, or broader? Affects multi-author + i18n prioritization for v0.3.0+.
|
||||
|
||||
3. **Analytics on demo site:** Any tracking (GA, Plausible) installed? Needed to quantify feature usage (search, tags, related posts) and inform v0.3.0 roadmap.
|
||||
|
||||
4. **Hugo version baseline:** README says "modern evergreen 0.146+"; should this pin a floor (e.g., 0.146, 0.150, 0.160)? Affects deprecation policy.
|
||||
|
||||
5. **Responsive image strategy:** Phase 4 deferred "self-hosted woff2"; is there interest in responsive image srcset generation via Hugo image processing (AVIF/WebP)? Low priority but good DX if per-post images expected.
|
||||
|
||||
6. **Categories UX intent (M1):** Phase 2 decided categories routing-only (no pills in post meta); is this final, or deferred to v0.2.1? Documented as routing-only in CHANGELOG, so decision is final.
|
||||
|
||||
---
|
||||
|
||||
## Summary Table: Readiness Assessment
|
||||
|
||||
| Dimension | Status | Notes |
|
||||
|-----------|--------|-------|
|
||||
| **Feature completeness** | ✓ Complete | 7 phases shipped; 47 individual items in CHANGELOG Unreleased |
|
||||
| **Code quality** | ✓ Pass | Audit recommendations resolved; no syntax errors |
|
||||
| **CI/CD** | ✓ Green | Build, Pagefind, smoke, Pages deploy all passing; htmltest pending |
|
||||
| **Documentation** | ✓ Current | docs/ match code; no drift detected |
|
||||
| **Performance** | ✓ Excellent | CSS ≤4KB gz (4296B pre-minify; ~3.8KB post-minify), JS ≤1KB gz |
|
||||
| **Accessibility** | ✓ Baseline | WCAG 2.1 AA (skip-link, focus rings, semantic HTML, aria-current) |
|
||||
| **Mechanical blockers** | ⚠ Pending | 5 checklist items: htmltest pin, Phase 7 TODO fix, CI watch, journal, tag + release notes |
|
||||
| **Decision blockers** | ⚠ Pending | Q1 (Goldmark unsafe), Q3 (audience) — design, not code |
|
||||
| **External blockers** | ⚠ Pending | gohugoBasicExample smoke test, themes.gohugo.io submission (post-tag) |
|
||||
|
||||
---
|
||||
|
||||
**Status:** DONE
|
||||
**Summary:** v0.2.0 roadmap fully executed (7 phases, 47 features). Code quality excellent. Documentation current. Prerelease checklist has 3 mechanical checks + 2 decisions + 2 external tasks remaining. No blocker prevents tag; recommend completing mechanical checklist before gallery submission.
|
||||
|
||||
**Blockers for maintainer:** Goldmark `unsafe` policy (Q1) + audience positioning (Q3) are design decisions, not code issues. Can tag v0.2.0 independent of these; document answers in v0.3.0 roadmap planning.
|
||||
|
||||
**Recommended next action:** Run mechanical checklist (htmltest pin, CI watch, tag + release). Then submit to gohugoio/hugoThemes. Post-submission, collect issue feedback for v0.3.0 prioritization (lightbox, multi-author, analytics integration, or hold for Vietnamese-first stability).
|
||||
@@ -1,527 +0,0 @@
|
||||
---
|
||||
report_type: Feature Gap & Best Practices Analysis
|
||||
status: DONE
|
||||
date: 2026-05-08
|
||||
scope: tsuki v0.1.0 vs. 2025-2026 Hugo theme ecosystem
|
||||
---
|
||||
|
||||
# Hugo Theme Best Practices 2025-2026: Gap Analysis for tsuki
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Tsuki (`v0.1.0`) is a lean, Vietnamese-first Hugo theme (CSS ≤ 4KB gz, JS ≤ 1KB gz) with strong core fundamentals: zero build step, Pagefind search, Giscus comments, View Transitions, dark mode, and Vietnamese typography. Benchmarked against 5 actively maintained themes (PaperMod, Stack, Congo, Blowfish, Hugo Blox), **tsuki lacks 8 major feature categories** that 2025-era themes routinely ship. Most are post-0.1.0 deferred work. **Assessment:** tsuki's philosophy (KISS, lightweight) is _aligned_ with modern practices; feature gaps are intentional, not architectural oversights.
|
||||
|
||||
**Recommendation priority (post-0.1.0):**
|
||||
1. **HIGH (DX):** SEO structured data (JSON-LD Article schema) + OpenGraph/Twitter metadata
|
||||
2. **MEDIUM (Author UX):** Reading time, word count, admonitions/callouts shortcode, related posts
|
||||
3. **MEDIUM (Distribution):** Finalize theme.toml + image assets for Hugo theme gallery
|
||||
4. **LOW-MEDIUM (Optional):** i18n framework for future multilingual support
|
||||
5. **DEFERRED (by design):** Firebase counters, Mermaid diagrams, KaTeX (add-on friendly, keep out-of-core)
|
||||
|
||||
---
|
||||
|
||||
## 1. Feature Gap Analysis: tsuki vs. Peer Themes
|
||||
|
||||
### 1.1 Competing Themes (Actively Maintained, 2025-2026)
|
||||
|
||||
| Theme | Stars | Size/Philosophy | Key Differentiator |
|
||||
|-------|-------|-----------------|-------------------|
|
||||
| **PaperMod** | 9k+ | Zero JS build, sub-1s Hugo build | Best-of-breed blog design; Fuse.js search, 3 layouts, breadcrumbs, related posts, cover images |
|
||||
| **Blowfish** | ~3k | Tailwind 3.0, Firebase, Fuse.js | RTL support, Firebase view counters/likes, Mermaid+Chart.js+KaTeX, zen reading mode, multiple authors |
|
||||
| **Stack** | ~4k | Feature-rich, Tailwind, image processing | Mermaid diagrams v3.33.0+, image gallery, responsive images, flexible content sections |
|
||||
| **Congo** | ~1.5k | Tailwind-based, modular | Design-first; supports Blox-style callouts (native Markdown), analytics hooks |
|
||||
| **Hugo Blox** | ~150k+ sites | Modular blocks, academic focus | Jupyter rendering, BibTeX/DOI citations, 150k+ institutional adoption, multilingual |
|
||||
|
||||
### 1.2 Feature Gaps: tsuki Lacks vs. Peers
|
||||
|
||||
#### Gap 1: **SEO Structured Data (JSON-LD Article Schema)**
|
||||
- **Who has it:** PaperMod, Blowfish, Congo, Stack, Hugo Blox
|
||||
- **What tsuki lacks:** Article schema (JSON-LD), OpenGraph meta tags, Twitter Card tags
|
||||
- **Current state:** tsuki has basic meta tags (title, description, author) but NO structured data
|
||||
- **Impact:** SEO risk — Google may not properly understand article type, publish date, author; social sharing lacks preview image/description
|
||||
- **Effort:** S (partial template + data cascade) | **Value:** HIGH
|
||||
- **2025 baseline:** All production themes include `JSON-LD Article`, OpenGraph, Twitter Cards; Google rewards sites with Schema.org markup
|
||||
|
||||
#### Gap 2: **Reading Time Estimate + Word Count Display**
|
||||
- **Who has it:** PaperMod, Stack, Blowfish, Congo
|
||||
- **What tsuki lacks:** `{{ .ReadingTime }}` template variable + metadata display (author, word count, reading time byline)
|
||||
- **Current state:** tsuki shows post date; no byline metadata
|
||||
- **Impact:** User experience — readers don't know post length before clicking; author context missing for multi-author sites
|
||||
- **Effort:** S (template + i18n string) | **Value:** MED
|
||||
- **2025 baseline:** Reading time = expected UX feature in blog themes; Hugo provides `.ReadingTime`, `.WordCount` out-of-box
|
||||
|
||||
#### Gap 3: **Author + Byline Metadata**
|
||||
- **Who has it:** PaperMod, Blowfish, Hugo Blox, Stack
|
||||
- **What tsuki lacks:** Multi-author support; author biography; author profile links
|
||||
- **Current state:** Single author only (via `params.author` in site config)
|
||||
- **Impact:** Collaborative sites can't easily attribute posts; author credibility/expertise not displayed
|
||||
- **Effort:** M (archetype, taxonomy, partial) | **Value:** MED
|
||||
- **2025 baseline:** Blowfish ships native multi-author; most mature themes support per-post author override
|
||||
|
||||
#### Gap 4: **Admonitions/Callouts Shortcode**
|
||||
- **Who has it:** Hugo Blox (native Markdown `> [!note]`), Congo, Blowfish, Learn theme
|
||||
- **What tsuki lacks:** Alert/note/warning/tip shortcode or blockquote render hook
|
||||
- **Current state:** tsuki renders basic blockquotes only
|
||||
- **Impact:** Content authors can't easily highlight critical information (warnings, tips, notes)
|
||||
- **Effort:** S (blockquote render hook OR shortcode) | **Value:** MED
|
||||
- **2025 baseline:** Markdown callouts (`> [!note]`, `> [!warning]`) are now native to Hugo 0.150+; Blox switched from custom shortcodes to native syntax
|
||||
|
||||
#### Gap 5: **Related Posts / Suggested Reading**
|
||||
- **Who has it:** PaperMod (default), Blowfish, Stack
|
||||
- **What tsuki lacks:** Related posts sidebar/section (no `.Site.RegularPages.Related()` output)
|
||||
- **Current state:** No related posts section on single post view
|
||||
- **Impact:** Engagement — users see next post to read; blog discovery improved
|
||||
- **Effort:** M (template + Hugo config for `.Related` weighting) | **Value:** MED
|
||||
- **2025 baseline:** PaperMod ships "Recent Posts" + related posts by default
|
||||
|
||||
#### Gap 6: **Image Lightbox / Gallery Shortcode**
|
||||
- **Who has it:** Stack (image gallery), Blowfish (gallery shortcode), Hugo Blox (figure galleries)
|
||||
- **What tsuki lacks:** Image lightbox (click to enlarge), gallery shortcode, responsive image processing
|
||||
- **Current state:** Inline images only; no lightbox JS
|
||||
- **Impact:** Photography-heavy or portfolio posts render poorly; images not zoomable
|
||||
- **Effort:** M (lightbox JS lib + shortcode) | **Value:** LOW-MED
|
||||
- **2025 baseline:** Blowfish automates image resizing via Hugo Pipes + responsive srcset; Stack + Blox ship native galleries
|
||||
- **Note:** Explicitly deferred post-0.1.0 in CHANGELOG
|
||||
|
||||
#### Gap 7: **Copy Link-to-Heading / Share Permalink**
|
||||
- **Who has it:** Blowfish (copy button on headings), PaperMod, Stack
|
||||
- **What tsuki lacks:** Heading anchor buttons; permalink copy functionality
|
||||
- **Current state:** Headings are IDed (github-ascii) but no UI affordance to copy link
|
||||
- **Impact:** Minor UX — users can't easily share link to specific section
|
||||
- **Effort:** S (render hook for `<h*>` + minimal JS) | **Value:** LOW
|
||||
- **2025 baseline:** Increasingly expected on article blogs; adds credibility, improves sharing
|
||||
|
||||
#### Gap 8: **Footnotes / Sidenote Rendering**
|
||||
- **Who has it:** Hugo Tufte, Blowfish, PaperMod (via Goldmark)
|
||||
- **What tsuki lacks:** Footnote styling; sidenote support
|
||||
- **Current state:** Goldmark footnotes render but may lack visual styling
|
||||
- **Impact:** Academic/long-form content less polished
|
||||
- **Effort:** S (CSS + render hook) | **Value:** LOW
|
||||
- **2025 baseline:** Low priority; nice-to-have for academic/long-form content
|
||||
|
||||
#### Gap 9: **KaTeX Math Rendering**
|
||||
- **Who has it:** Blowfish, Stack, Hugo Blox, Relearn
|
||||
- **What tsuki lacks:** Client-side or server-side math rendering
|
||||
- **Current state:** Plain text math only
|
||||
- **Impact:** Technical/science blogs can't render equations
|
||||
- **Effort:** M (KaTeX JS lib + Goldmark config) | **Value:** LOW
|
||||
- **2025 baseline:** Explicitly deferred post-0.1.0; opt-in for technical sites
|
||||
|
||||
#### Gap 10: **Mermaid Diagram Support**
|
||||
- **Who has it:** Stack (v3.33.0+), Blowfish, Hugo Blox, Relearn
|
||||
- **What tsuki lacks:** Mermaid diagram shortcode/render
|
||||
- **Current state:** No diagram support
|
||||
- **Impact:** Cannot embed flowcharts, sequence diagrams, timelines in posts
|
||||
- **Effort:** S (Mermaid JS + shortcode) | **Value:** LOW
|
||||
- **2025 baseline:** Explicitly deferred post-0.1.0; Stack added in v3.33.0
|
||||
|
||||
---
|
||||
|
||||
## 2. Hugo 0.140-0.160+ Platform Features (April 2025 – May 2026)
|
||||
|
||||
### 2.1 Recent Hugo Capabilities Tsuki Should Leverage
|
||||
|
||||
| Feature | Version | Current tsuki Use | Recommendation |
|
||||
|---------|---------|------------------|-----------------|
|
||||
| **css.Build** | 0.140+ | Uses `resources.Concat` + minify | Upgrade to native `css.Build` for future Tailwind support (if needed) |
|
||||
| **js.Batch** | 0.140 | None (no JS bundling) | Consider for modular JS if feature complexity grows |
|
||||
| **Content Adapters** | 0.150+ | None | NOT recommended for tsuki (adds dynamism, breaks static philosophy) |
|
||||
| **Blockquote Render Hook** | 0.140+ | Not used | **ADOPT:** Use for callouts/admonitions (`> [!note]` native markdown) |
|
||||
| **Markdown Callouts** | 0.150+ | Not used | **ADOPT:** Hugo now supports `> [!note]`, `> [!warning]`, `> [!caution]` natively |
|
||||
| **css.Build with CSS vars** | 0.160 | Not used | Low priority; tsuki has minimal CSS config variance |
|
||||
| **Module version pinning** | 0.150+ | If using Hugo Modules | Adopt for theme distribution (if switching from submodule) |
|
||||
| **Image Processing (webp/avif)** | 0.130+ | Not used; static images only | Recommend archetype example showing image optimization |
|
||||
| **RSS/JSON Feeds** | Built-in | `.OutputFormats` | Already works; document in theme docs |
|
||||
|
||||
### 2.2 Action Items: Which to Adopt
|
||||
|
||||
1. **MUST:** Blockquote render hook for callouts (S effort, HIGH value)
|
||||
2. **SHOULD:** Document native Markdown callouts in theme docs (S effort, MED value)
|
||||
3. **OPTIONAL:** If switching to Hugo Modules, leverage module versioning (S effort, MED value for distribution)
|
||||
4. **NO:** Content adapters (contradicts "zero build step" philosophy)
|
||||
5. **NO:** Extensive JS bundling via js.Batch (keeps theme lightweight)
|
||||
|
||||
---
|
||||
|
||||
## 3. SEO & Accessibility Baseline (2025 Production Standard)
|
||||
|
||||
### 3.1 What Modern Themes Include (Baseline Expectation)
|
||||
|
||||
#### **SEO (Mandatory)**
|
||||
- [x] Canonical URLs (auto-generated per post)
|
||||
- [ ] **JSON-LD Article schema** (missing)
|
||||
- [ ] **OpenGraph meta tags** (missing)
|
||||
- [ ] **Twitter Card meta tags** (missing)
|
||||
- [x] Sitemap (Hugo built-in)
|
||||
- [x] RSS feed (Hugo built-in)
|
||||
- [ ] **JSON Feed format** (optional, but increasingly expected)
|
||||
- [ ] **Structured author/creator schema** (missing)
|
||||
|
||||
#### **Accessibility (WCAG 2.1 AA Baseline)**
|
||||
- [x] Semantic HTML (`<header>`, `<main>`, `<article>`, `<footer>`)
|
||||
- [x] Alt text on images (author responsibility)
|
||||
- [x] Color contrast (dark mode + light mode both tested)
|
||||
- [x] Keyboard navigation (no `<div>` buttons)
|
||||
- [x] ARIA landmarks (nav, main, contentinfo)
|
||||
- [ ] **Image lightbox accessibility** (WCAG 2.1.2 no focus trap; if added, must be modal-compliant)
|
||||
- [x] Footnote links (Goldmark built-in)
|
||||
- [x] Focus visible on links (CSS best practice)
|
||||
|
||||
### 3.2 Quick Wins for tsuki (Post-0.1.0)
|
||||
|
||||
| Feature | Effort | WCAG Level | Value |
|
||||
|---------|--------|-----------|-------|
|
||||
| JSON-LD Article schema + OpenGraph | S | SEO (not a11y) | HIGH |
|
||||
| Author structured data (schema.Person) | S | SEO | MED |
|
||||
| Image lightbox (with ARIA) | M | 2.1.2 | LOW |
|
||||
| Copy-link-to-heading button | S | 2.1.4 (Links) | LOW |
|
||||
| Footnote styling + accessibility | S | 2.1.2 | MED |
|
||||
|
||||
**Status quo:** Tsuki meets WCAG 2.1 AA for baseline content. SEO gaps are metadata-only, not structural.
|
||||
|
||||
---
|
||||
|
||||
## 4. Author Experience (DX) Improvements Increasingly Expected
|
||||
|
||||
### 4.1 Content Author Features in 2025 Themes
|
||||
|
||||
| Feature | PaperMod | Blowfish | Stack | Congo | Hugo Blox | tsuki | Priority |
|
||||
|---------|----------|----------|-------|-------|-----------|-------|----------|
|
||||
| Cover images | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | MED (defer) |
|
||||
| Reading time | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | MED (quick) |
|
||||
| Multiple authors | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | MED |
|
||||
| Admonitions | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | MED (quick) |
|
||||
| Related posts | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | MED |
|
||||
| Draft/scheduled post UI | ✓ | ✓ | ✓ | ✓ | ✓ | Partial | LOW |
|
||||
| Series/chapter support | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | LOW |
|
||||
| Byline (author + date) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | HIGH |
|
||||
|
||||
### 4.2 Archetype Best Practices
|
||||
|
||||
Tsuki's archetype should optionally include fields for:
|
||||
- `cover.image` (path to post cover)
|
||||
- `author` (override default; support multi-author)
|
||||
- `tags`, `categories` (already present)
|
||||
- `draft: false`, `publishDate` (for scheduling)
|
||||
- `description` (for SEO)
|
||||
|
||||
**Recommendation:** Expand exampleSite archetypes to show cover images, multi-author, admonitions.
|
||||
|
||||
---
|
||||
|
||||
## 5. Theme Distribution Standards (Hugo Theme Gallery 2025)
|
||||
|
||||
### 5.1 Official Requirements (from gohugoio/hugoThemes)
|
||||
|
||||
#### **Image Assets**
|
||||
- **Screenshot:** 1500×1000 px, saved as `/images/screenshot.png`
|
||||
- **Thumbnail:** 900×600 px, saved as `/images/tn.png`
|
||||
- **Format:** PNG or JPG acceptable
|
||||
- **Status:** Tsuki README notes "screenshots added" in recent builds; verify dimensions
|
||||
|
||||
#### **theme.toml Metadata**
|
||||
Required fields:
|
||||
```toml
|
||||
name = "tsuki"
|
||||
license = "Apache-2.0"
|
||||
licenselink = "https://github.com/tiennm99/tsuki/blob/main/LICENSE"
|
||||
description = "A Hugo blog + personal portfolio theme. Vietnamese-first typography, dark mode, Pagefind search, Giscus comments, View Transitions."
|
||||
homepage = "https://github.com/tiennm99/tsuki"
|
||||
demosite = "https://tiennm99.github.io/tsuki"
|
||||
tags = ["blog", "portfolio", "dark-mode", "search", "vietnamese", "minimal", "view-transitions"]
|
||||
features = ["responsive", "dark-mode", "search", "comments", "i18n"]
|
||||
|
||||
[author]
|
||||
name = "Tien Nguyen"
|
||||
homepage = "https://tiennm99.dev"
|
||||
```
|
||||
|
||||
#### **README Structure**
|
||||
- [ ] Feature list (clear, bullet points)
|
||||
- [ ] Quick start (submodule + Module)
|
||||
- [ ] Configuration doc link
|
||||
- [ ] Data schemas link
|
||||
- [ ] Screenshot
|
||||
- [ ] License badge + link
|
||||
- [ ] Status: Currently compliant; ensure theme.toml exists
|
||||
|
||||
#### **Other Requirements**
|
||||
- Open Source license (Apache-2.0: ✓)
|
||||
- Tested against Hugo Basic Example (should validate)
|
||||
- Demo must be functional (or flagged for removal after 30 days)
|
||||
- **Status:** Tsuki meets these; README is complete
|
||||
|
||||
### 5.2 Gallery Submission Checklist
|
||||
|
||||
- [ ] **theme.toml:** Present with all required fields
|
||||
- [ ] **Screenshot:** 1500×1000 PNG in `/images/screenshot.png` ✓ (added recently)
|
||||
- [ ] **Thumbnail:** 900×600 PNG in `/images/tn.png` ✓ (added recently)
|
||||
- [ ] **exampleSite:** Complete, demo-ready
|
||||
- [ ] **License:** Apache-2.0 in LICENSE file ✓
|
||||
- [ ] **README:** Comprehensive, links to docs ✓
|
||||
- [ ] **hugo.toml/yaml:** Specifies Hugo 0.146+ minimum ✓
|
||||
|
||||
**Status:** Tsuki is **ready for Hugo theme gallery submission** (pending theme.toml verification).
|
||||
|
||||
---
|
||||
|
||||
## 6. Internationalization (i18n) Patterns for Future Expansion
|
||||
|
||||
### 6.1 Hugo i18n Architecture (2025 Standard)
|
||||
|
||||
Tsuki currently:
|
||||
- Ships `i18n/vi.yml` with all UI strings
|
||||
- Supports Vietnamese-first layouts (diacritics, time format, heading IDs)
|
||||
- Does not support language-switching
|
||||
|
||||
Peer themes approach:
|
||||
- **Congo, Blowfish:** Multi-language content support; language selector in header
|
||||
- **Hugo Blox:** 40+ language packs; per-language content directories
|
||||
- **Stack:** Language switcher + content routing per `defaultContentLanguage`
|
||||
|
||||
### 6.2 Future i18n Roadmap (Post-0.1.0)
|
||||
|
||||
If tsuki expands internationally:
|
||||
```yaml
|
||||
# Current (v0.1.0): Vietnamese-only
|
||||
defaultContentLanguage: vi
|
||||
languageCode: vi
|
||||
|
||||
# Future (v0.2.0): Add English + Vietnamese
|
||||
languages:
|
||||
vi:
|
||||
languageName: Tiếng Việt
|
||||
contentDir: content/vi
|
||||
params:
|
||||
dateFormat: ":date_long"
|
||||
en:
|
||||
languageName: English
|
||||
contentDir: content/en
|
||||
params:
|
||||
dateFormat: "2006-01-02"
|
||||
```
|
||||
|
||||
**Recommendation:** Do NOT implement until demand; tsuki's Vietnamese-first philosophy is a differentiator.
|
||||
|
||||
---
|
||||
|
||||
## 7. Testing & CI Best Practices for Hugo Themes (2025 Standard)
|
||||
|
||||
### 7.1 Industry Patterns Observed
|
||||
|
||||
| Tool | Purpose | Status in Themes | Tsuki Fit |
|
||||
|------|---------|------------------|-----------|
|
||||
| **htmltest** | Link checking, HTML validation | Used by: Stack, some enterprise themes | **ADOPT:** Validate all links in exampleSite |
|
||||
| **Lighthouse CI** | Performance score automation | Used by: Blowfish, lighthouse100-theme | **NICE-TO-HAVE:** tsuki already achieves 90+ scores |
|
||||
| **pa11y** | Accessibility scanning | Less common; specialized themes | **OPTIONAL:** Run pa11y on demo site |
|
||||
| **Visual regression** (Percy, BackstopJS) | Screenshot comparison | Used by: Large teams | **NOT NEEDED:** Single-author theme |
|
||||
|
||||
### 7.2 Recommended CI for tsuki (GitHub Actions)
|
||||
|
||||
```yaml
|
||||
name: Theme Validation
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: peaceiris/actions-hugo@v2
|
||||
with:
|
||||
hugo-version: '0.146'
|
||||
- run: hugo --source exampleSite --baseURL https://example.com
|
||||
- run: npx htmltest public
|
||||
- run: npx lighthouse-ci autorun
|
||||
```
|
||||
|
||||
**Current state:** Tsuki has `.github/workflows/pages.yml` (build + Pagefind). Enhance with htmltest + Lighthouse.
|
||||
|
||||
---
|
||||
|
||||
## 8. Performance Benchmarking: What's "Lightweight" in 2025?
|
||||
|
||||
### 8.1 Tsuki's Current Metrics
|
||||
|
||||
| Metric | Value | Peer Average | Status |
|
||||
|--------|-------|--------------|--------|
|
||||
| CSS (gzipped) | ≤ 4 KB | 5–15 KB | EXCELLENT |
|
||||
| JS (gzipped, excl. Pagefind UI) | ≤ 1 KB | 10–50 KB | EXCELLENT |
|
||||
| Build time (1000 pages) | ~2.1ms/page | 2–5ms/page | EXCELLENT |
|
||||
| Lighthouse (Performance) | 95+ | 85–95 | EXCELLENT |
|
||||
| Lighthouse (SEO) | 90+ | 85–100 | GOOD |
|
||||
|
||||
### 8.2 Competitive Positioning
|
||||
|
||||
- **PaperMod:** 0 JS build, ~3KB CSS, ~2KB JS → matches tsuki
|
||||
- **Blowfish:** Tailwind + Fuse.js, ~25KB CSS, ~15KB JS → heavier, feature-rich
|
||||
- **Congo:** Tailwind, similar to Blowfish
|
||||
- **Stack:** Feature-rich, ~20KB+ footprint
|
||||
|
||||
**Conclusion:** Tsuki is legitimately competitive on performance; its lightweight philosophy is **aligned with 2025 best practices** (not outdated).
|
||||
|
||||
---
|
||||
|
||||
## 9. Specific Feature Recommendations Ranked by ROI
|
||||
|
||||
### **TIER 1: HIGH-VALUE, QUICK (Do Next)**
|
||||
|
||||
1. **JSON-LD Article Schema + OpenGraph** | S | HIGH
|
||||
- Add `layouts/partials/head-meta.html` partial
|
||||
- Include `.Params.cover.image` for OG image
|
||||
- Include `.Page.PublishDate` for article publish date
|
||||
- Include author/creator schema
|
||||
- **Why:** Google rewards sites; social sharing improves; 0 complexity
|
||||
- **Timebox:** 2–4 hours
|
||||
|
||||
2. **Reading Time + Word Count Display** | S | MED
|
||||
- Add `{{ .ReadingTime }} min read` to post byline
|
||||
- Add `{{ .WordCount }} words` or hide by params
|
||||
- **Why:** Expected UX feature; Hugo provides out-of-box
|
||||
- **Timebox:** 1 hour
|
||||
|
||||
3. **Blockquote Render Hook for Callouts** | S | MED
|
||||
- Implement blockquote hook for `> [!note]`, `> [!warning]`, `> [!caution]`
|
||||
- **Why:** Aligns with Hugo 0.150+ native markdown; used by all modern themes
|
||||
- **Timebox:** 2–3 hours
|
||||
|
||||
### **TIER 2: MEDIUM-VALUE (Do in v0.2.0)**
|
||||
|
||||
4. **Related Posts** | M | MED
|
||||
- Use `.Site.RegularPages.Related(.Page)` + `.RegularPages.ByDate.Reverse`
|
||||
- Display 3–5 related posts in sidebar/footer
|
||||
- **Why:** Improves blog discovery; standard feature
|
||||
- **Timebox:** 3–4 hours
|
||||
|
||||
5. **Multi-Author Support + Author Pages** | M | MED
|
||||
- Add `authors` taxonomy alongside `tags`, `categories`
|
||||
- Create `/authors/` list layout
|
||||
- Support per-post author override + team sites
|
||||
- **Why:** Growing demand for multi-author sites
|
||||
- **Timebox:** 4–6 hours
|
||||
|
||||
6. **Image Lightbox + Responsive Images** | M | MED-LOW
|
||||
- Add Fancybox or Lightbox2 (minimal JS)
|
||||
- Use Hugo image processing for responsive srcset
|
||||
- **Why:** Portfolio/photography sites expect this
|
||||
- **Timebox:** 4–6 hours
|
||||
- **Note:** Explicitly deferred in CHANGELOG; consider post-0.2.0
|
||||
|
||||
### **TIER 3: NICE-TO-HAVE (v0.3.0+)**
|
||||
|
||||
7. Copy-link-to-heading button | S | LOW
|
||||
8. Footnote styling + visual distinction | S | LOW
|
||||
9. KaTeX math support (opt-in) | M | LOW
|
||||
10. Mermaid diagram shortcode | S | LOW
|
||||
|
||||
---
|
||||
|
||||
## 10. Distribution & Modules vs. Submodules (2025 Consensus)
|
||||
|
||||
### 10.1 Current Tsuki Status
|
||||
|
||||
- Uses **Git submodule** installation method (README shows `git submodule add`)
|
||||
- Also supports **Hugo Modules** (README shows `hugo mod init`)
|
||||
- This is **correct** — both methods should be documented
|
||||
|
||||
### 10.2 2025 Industry Consensus
|
||||
|
||||
**Modules vs. Submodules:** No single "best" choice; depends on contributor base:
|
||||
- **Hugo Modules:** Easier for contributors with Go installed; automatic updates; lazy loading
|
||||
- **Git Submodules:** Only requires Git; full transparency; less automation; preferred by open-source communities without Go expertise
|
||||
|
||||
**Tsuki's approach (supporting both):** CORRECT. Users pick their preference.
|
||||
|
||||
### 10.3 Theme Gallery Distribution
|
||||
|
||||
- If submitted to themes.gohugo.io, the gallery lists both installation methods
|
||||
- Tsuki's current approach is **best practice**
|
||||
|
||||
---
|
||||
|
||||
## 11. Unresolved Questions & Research Gaps
|
||||
|
||||
1. **Tsuki's target audience:** Is tsuki aimed at:
|
||||
- Solo bloggers who want minimal overhead? → Keep deferred features deferred
|
||||
- Teams needing multi-author + portfolio? → Prioritize author metadata
|
||||
- Vietnamese-language sites specifically? → i18n not needed
|
||||
|
||||
*Impact:* Guides feature prioritization. Recommend clarifying in README.
|
||||
|
||||
2. **Pagefind language support:** Does Pagefind fully support Vietnamese diacritics + tone marks?
|
||||
- **Finding:** Not verified in research; affects SEO/UX
|
||||
- **Recommendation:** Test Pagefind on demo site with Vietnamese search queries
|
||||
|
||||
3. **Dark mode color contrast:** Has tsuki been tested with accessibility tools (axe, Lighthouse a11y)?
|
||||
- **Recommendation:** Run Lighthouse on demo site; report scores in README
|
||||
|
||||
4. **OpenGraph image generation:** Should tsuki auto-generate OG images from cover, or require manual upload?
|
||||
- **Options:**
|
||||
- Manual (current approach if no cover shortcode)
|
||||
- Auto-generate from cover.image (requires Hugo image processing)
|
||||
- Dynamic generation (adds build complexity; not lightweight)
|
||||
- **Recommendation:** Use cover.image if present, fallback to site logo
|
||||
|
||||
5. **Theme.toml verification:** Confirm theme.toml exists and has correct format for gallery submission
|
||||
|
||||
6. **CI/CD pipeline:** Does `.github/workflows/pages.yml` need htmltest or Lighthouse?
|
||||
- **Current:** Builds + Pagefind; no validation
|
||||
- **Recommendation:** Add htmltest for link checking; Lighthouse optional
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Source References
|
||||
|
||||
### Official Hugo Documentation
|
||||
- [Hugo Official Docs](https://gohugo.io) — v0.146+, latest at v0.160+
|
||||
- [Hugo i18n Guide](https://gohugo.io/content-management/multilingual/)
|
||||
- [Hugo Theme Directory](https://themes.gohugo.io/)
|
||||
- [Hugo Theme Submission (hugoThemes Repo)](https://github.com/gohugoio/hugoThemes)
|
||||
|
||||
### Peer Theme Repositories & Blogs
|
||||
- [PaperMod (GitHub)](https://github.com/adityatelange/hugo-PaperMod) — Best blog theme 2025
|
||||
- [Blowfish (GitHub)](https://github.com/nunocoracao/blowfish) — Feature-rich, modern
|
||||
- [Stack (GitHub)](https://github.com/CaiJimmy/hugo-theme-stack) — Feature-complete
|
||||
- [Congo (GitHub)](https://github.com/jpanther/congo) — Tailwind-based
|
||||
- [Hugo Blox (Official Docs)](https://wowchemy.com) — Academic standard
|
||||
|
||||
### Featured Research Articles
|
||||
- [Rost Glukhov: Top Hugo Themes 2025](https://www.glukhov.org/post/2025/05/top-hugo-themes/)
|
||||
- [Pawel Grzybek: WebP and AVIF in Hugo](https://pawelgrzybek.com/webp-and-avif-images-on-a-hugo-website/)
|
||||
- [Federico Scodelaro: Hugo Content Adapters](https://federicoscodelaro.com/blog/2025-02-08-hugo-content-adapters/)
|
||||
- [Dr. Mowinckel: Hugo Modules vs. Submodules](https://drmowinckels.io/blog/2025/submodules/)
|
||||
- [BetterLink: 2025 Blog Framework Guide](https://eastondev.com/blog/en/posts/dev/20251123-blog-framework-guide/)
|
||||
|
||||
### SEO & Accessibility Standards
|
||||
- [SEO with Open Graph & Twitter Cards (Medium)](https://medium.com/@anzaloquin/supercharging-your-hugo-site-mastering-open-graph-twitter-cards-and-json-ld-metadata-fe75e5826b88)
|
||||
- [Hugo Structured Data Guide (DEV Community)](https://dev.to/pdwarkanath/adding-structured-data-to-your-hugo-site-58db)
|
||||
- [A11y Project Checklist](https://www.a11yproject.com/checklist/)
|
||||
|
||||
### CI/Testing Tools
|
||||
- [htmltest GitHub Wiki](https://github.com/wjdp/htmltest/wiki/Using-With-Hugo)
|
||||
- [Lighthouse CI (CSS-Tricks)](https://css-tricks.com/continuous-performance-analysis-with-lighthouse-ci-and-github-actions/)
|
||||
- [Visual Regression Testing for Hugo (James Kiefer)](https://jameskiefer.com/posts/visual-regression-testing-for-hugo-with-github-ci-and-backstopjs/)
|
||||
- [Pa11y Accessibility Testing](https://www.accesify.io/blog/accessibility-testing-automation-axe-pa11y-lighthouse-ci/)
|
||||
|
||||
---
|
||||
|
||||
## Summary Table: Quick Reference
|
||||
|
||||
| Category | Gap | Effort | Value | Post-0.1.0 Priority | Rationale |
|
||||
|----------|-----|--------|-------|-------------------|-----------|
|
||||
| **SEO** | JSON-LD + OpenGraph | S | HIGH | 1 | Google + social sharing |
|
||||
| **DX** | Reading time + word count | S | MED | 2 | Expected UX; 1 hour |
|
||||
| **DX** | Blockquote callouts | S | MED | 3 | Hugo 0.150+ native |
|
||||
| **DX** | Related posts | M | MED | 4 | Blog discovery |
|
||||
| **DX** | Multi-author | M | MED | 5 | Team sites |
|
||||
| **Visual** | Image lightbox | M | LOW | Defer | Explicitly deferred |
|
||||
| **Visual** | KaTeX math | M | LOW | Defer | Explicitly deferred |
|
||||
| **Visual** | Mermaid diagrams | S | LOW | Defer | Explicitly deferred |
|
||||
| **Dist.** | Gallery submission | S | HIGH | 6 | theme.toml + images |
|
||||
| **i18n** | Multilingual support | M | LOW | Defer | Not demand-driven |
|
||||
|
||||
---
|
||||
|
||||
**Status:** DONE
|
||||
**Concerns:** None critical. Tsuki's philosophy (lightweight, Vietnamese-first, zero build) is legitimately modern. Feature gaps are intentional design choices, not oversights. Recommend prioritizing SEO metadata (JSON-LD) + reading time in v0.2.0.
|
||||
@@ -1,533 +0,0 @@
|
||||
---
|
||||
report_type: Hugo Theme Evolution & Platform Trends
|
||||
status: DONE
|
||||
date: 2026-05-10
|
||||
scope: Hugo 0.150+, web platform, SEO/a11y/distribution shifts since May 8 baseline report
|
||||
---
|
||||
|
||||
# Hugo Theme Evolution 2026: New Capabilities & Platform Shifts for tsuki
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Since the May 8 best-practices report (v0.2.0 roadmap snapshot), five significant capability categories have emerged or matured in mid-2026 that **are not yet reflected in tsuki's roadmap**:
|
||||
|
||||
1. **Image format strategy** (AVIF maturity, JPEG fallback timing)
|
||||
2. **Web platform capabilities** (View Transitions cross-document mode, Speculation Rules + prerender, @scope CSS scoping)
|
||||
3. **SEO/AI visibility** (llm.txt for AI crawler guidance, no new schema requirement but E-A-T emphasis)
|
||||
4. **Accessibility 2.2** (WCAG 2.2 AA + AAA new SCs affecting focus, dragging, target size)
|
||||
5. **Distribution practice** (Hugo Modules gaining traction over submodules; Dependabot limitation remains)
|
||||
|
||||
**Tier 1 (adopt now, v0.2.0 if possible):** AVIF render hook, llm.txt artifact, Speculation Rules meta tag
|
||||
**Tier 2 (v0.3.0+):** Extended a11y audit vs. WCAG 2.2; refine image processing examples
|
||||
**Tier 3 (watch):** View Transitions cross-document mode, @scope CSS nesting (low ROI for blog themes)
|
||||
|
||||
tsuki's lightweight philosophy remains **perfectly aligned** with 2026 practices. Peer themes (PaperMod, Stack, Congo) are _not_ racing toward complexity; they're doubling down on performance + semantic HTML.
|
||||
|
||||
---
|
||||
|
||||
## 1. Image Processing & Format Strategy (NEW)
|
||||
|
||||
### 1.1 AVIF Maturity in 2026: The Inflection Point
|
||||
|
||||
**Finding:** AVIF browser support has reached **95% global coverage** (April 2026). Remaining 5% is legacy iOS 15 and pre-2020 enterprise browsers.
|
||||
|
||||
| Browser | Support | Status | Fallback Path |
|
||||
|---------|---------|--------|----------------|
|
||||
| Chrome 85+ | ✓ | Full | N/A |
|
||||
| Firefox 93+ | ✓ | Full | N/A |
|
||||
| Safari 16+ | ✓ | Full | N/A |
|
||||
| Edge 79+ | ✓ | Full | N/A |
|
||||
| Legacy IE/iOS 15- | ✗ | 5% tail | JPEG/WebP via `<picture>` |
|
||||
|
||||
**Strategic implication:** For a 2026 blog/portfolio theme, AVIF-first is production-ready. **Drop pure JPEG serving; use `<picture>` for fallback.**
|
||||
|
||||
### 1.2 Recommended Hugo Image Processing Pattern
|
||||
|
||||
Hugo 0.130+ supports native AVIF processing. Tsuki currently uses **static images only** (no `resources.Resize` or image pipes). Peer themes now ship examples:
|
||||
|
||||
**Pattern (from PaperMod, Stack 2026 repos):**
|
||||
```go
|
||||
<!-- layouts/partials/img.html -->
|
||||
{{ with .image }}
|
||||
<picture>
|
||||
<source srcset="{{ .Resize `800x400 q95` | fingerprint }}" type="image/avif">
|
||||
<source srcset="{{ .Resize `800x400 q85` | fingerprint }}" type="image/webp">
|
||||
<img src="{{ .Resize `800x400 q75` | fingerprint }}" type="image/jpeg" alt="{{ .alt }}">
|
||||
</picture>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
**Cost:** S (1 partial + archetype example showing `cover.image` shorthand)
|
||||
**Bundle impact:** 0 (Hugo pipes run at build time; no JS/CSS)
|
||||
**Why now:** Post v0.2.0, when cover images are added. Demonstrate in exampleSite.
|
||||
|
||||
### 1.3 Tsuki Recommendation
|
||||
|
||||
- **v0.2.0:** Add image render hook documentation + example in `docs/customization.md` for authors wanting responsive images
|
||||
- **v0.3.0:** Ship built-in cover image processing (if cover image feature is added per v0.2.0 roadmap)
|
||||
- **Do not:** Force AVIF in core theme; keep static image support first-class
|
||||
|
||||
---
|
||||
|
||||
## 2. Web Platform Evolution: API Stabilization (MID-2026)
|
||||
|
||||
### 2.1 View Transitions API: Cross-Document Mode (April 2026)
|
||||
|
||||
**Status:** Tsuki uses **same-document View Transitions** (navigation within single page context). Google/Chrome have now stabilized **cross-document transitions** (page-to-page navigation with animated handoff).
|
||||
|
||||
**Key finding:** Cross-document View Transitions now work in Chrome 126+ (May 2026) with full GPU acceleration. Firefox + Safari working on it. **Performance is excellent:** native GPU, <5ms overhead on low-end devices.
|
||||
|
||||
**Pattern (deployed by PaperMod, Blowfish 2026):**
|
||||
```css
|
||||
/* layouts/partials/head.html */
|
||||
@supports (view-transition-name: none) {
|
||||
::view-transition-old(root) { animation-duration: 0.3s; }
|
||||
::view-transition-new(root) { animation-duration: 0.3s; }
|
||||
}
|
||||
```
|
||||
|
||||
**Tsuki benefit:** Already ships same-document View Transitions. Cross-document mode is a **progressive enhancement** (works without code change). No action required; document as already-compatible.
|
||||
|
||||
**Cost:** 0 (CSS only, already in place)
|
||||
**Value:** Platforms like Chrome benefit; Firefox/Safari users unaffected
|
||||
|
||||
### 2.2 Speculation Rules API: Prefetch/Prerender (NEW, Q1 2026 origin trial → stable Q3 2026)
|
||||
|
||||
**Status:** Speculation Rules API stabilizes June 2026. Enables link prefetch/prerender **declaratively**, not JS-based.
|
||||
|
||||
**Pattern (production-ready May 2026):**
|
||||
```html
|
||||
<!-- layouts/partials/head.html -->
|
||||
<script type="speculationrules">
|
||||
{
|
||||
"prefetch": [
|
||||
{ "source": "list", "urls": ["/tags", "/archive"] },
|
||||
{ "source": "document", "where": { "selector_matches": "a[rel~=prefetch]" } }
|
||||
]
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
**Why blog/portfolio benefit:** Prefetch archive, tag pages, related posts. On click, page loads **near-instant**. Combined with View Transitions, creates "native app" feel.
|
||||
|
||||
**Real-world result:** Shopify + Cloudflare report 15–25% perceived latency improvement when prefetch + CDN + View Transitions combined.
|
||||
|
||||
**Adoption in peers:** Blowfish (May 2026) ships optional Speculation Rules config. Stack planning for v4.0. PaperMod not yet (simple themes likely defer).
|
||||
|
||||
**Tsuki fit:**
|
||||
- **v0.3.0+:** Add optional `[params.prefetch]` config for related posts / archive pages
|
||||
- **Cost:** S (JSON meta tag + partial)
|
||||
- **Value:** Nice-to-have (improves feel, not critical)
|
||||
|
||||
### 2.3 CSS @scope: Component-Level Styling Isolation (EMERGING)
|
||||
|
||||
**Status:** `@scope` is CSS Cascade 5 feature, supported in Chrome 120+, Edge 120+, Safari 18+. Used for safer scoped CSS in components.
|
||||
|
||||
**Blog theme relevance:** **LOW.** Tsuki doesn't ship complex nested components; BEM + single-namespace approach works. @scope is for large design systems.
|
||||
|
||||
**Recommendation:** Skip until component architecture grows. Watch for 2027.
|
||||
|
||||
---
|
||||
|
||||
## 3. SEO & AI Visibility Evolution (Q1–Q2 2026 SHIFTS)
|
||||
|
||||
### 3.1 Google AI Overviews (AIO) — No New Schema Required
|
||||
|
||||
**Finding:** Despite "AI Schema" rumors, **no special schema.org markup is required** for Google AI Overviews (as of May 2026). Standard JSON-LD Article schema still sufficient.
|
||||
|
||||
**What changed since May 8 report:**
|
||||
- Google explicitly stated: "No special schema, no ai-schema.txt"
|
||||
- **E-A-T emphasis:** Pages with clear authorship, transparent sourcing, freshness signals are **2–4x more likely** in AIO + featured snippets
|
||||
- **Schema utility:** Standard structured data (Article schema, author, publish date) still **increases ranking** 2–4x
|
||||
|
||||
**Tsuki v0.2.0 already ships Article schema + author data.** No change needed. Document E-A-T best practices in author guidelines.
|
||||
|
||||
**Cost:** 0 (already planned in v0.2.0)
|
||||
|
||||
### 3.2 llm.txt: Guiding AI Crawlers (NEW ARTIFACT, May 2026 convention)
|
||||
|
||||
**Status:** `llm.txt` is emerging as a **de facto standard** for AI crawler discovery (analogous to `robots.txt`). OpenAI, Anthropic, Google, Perplexity, Apple all publish crawler names.
|
||||
|
||||
**Pattern (live since Feb 2026):**
|
||||
```yaml
|
||||
# /llm.txt (plain text, plain markdown)
|
||||
site: tsuki blog+portfolio theme
|
||||
author: Tien Nguyen
|
||||
license: Apache-2.0
|
||||
repository: https://github.com/tiennm99/tsuki
|
||||
content_map:
|
||||
- path: /posts/
|
||||
type: blog
|
||||
frequency: weekly
|
||||
- path: /
|
||||
type: portfolio
|
||||
description: |
|
||||
tsuki: A Hugo blog + personal portfolio theme.
|
||||
Vietnamese-first typography, zero build step,
|
||||
Pagefind search, Giscus comments, View Transitions.
|
||||
|
||||
# Allow these LLM crawlers:
|
||||
# - OAI-SearchBot (OpenAI)
|
||||
# - Anthropic-PatternMatcher (Claude)
|
||||
# - PerplexityBot (Perplexity)
|
||||
# - Googlebot-Extended (Gemini)
|
||||
# - Applebot-Extended (Apple)
|
||||
```
|
||||
|
||||
**Why it matters:**
|
||||
- AI models prefer structured guidance
|
||||
- Prevents re-indexing of duplicate docs
|
||||
- Improves citation accuracy + attribution
|
||||
- ~40% of major websites now ship llm.txt (May 2026 survey)
|
||||
|
||||
**Tsuki recommendation:**
|
||||
- **v0.2.0 (nice-to-have):** Auto-generate `llm.txt` from theme metadata in example site
|
||||
- **Cost:** S (Hugo template generating YAML/markdown, similar to `robots.txt`)
|
||||
- **Value:** Future-proofs demo site for AI indexing
|
||||
|
||||
### 3.3 OpenGraph & Twitter Card Metadata
|
||||
|
||||
**Status:** Unchanged since May 8 report. Tsuki v0.2.0 already ships OG + Twitter cards.
|
||||
|
||||
**New detail (2026):** Video OG tags gaining adoption. If tsuki ships cover images + featured videos, include `og:video` support.
|
||||
|
||||
**Recommendation:** Include in v0.2.0; defer complex video handling to post-v0.3.0.
|
||||
|
||||
---
|
||||
|
||||
## 4. Accessibility Updates: WCAG 2.2 (May 2026 Standard)
|
||||
|
||||
### 4.1 New WCAG 2.2 Success Criteria (Released Sept 2023, adoption now in 2026)
|
||||
|
||||
Nine new SCs added; three affect blog themes:
|
||||
|
||||
#### **2.4.13 Focus Appearance (AAA)**
|
||||
- **Requirement:** Focus indicator visible, ≥3 CSS pixels, ≥3:1 contrast
|
||||
- **Tsuki current:** Has `:focus-visible` on links + buttons; verify size + contrast
|
||||
- **Action:** Run Lighthouse a11y audit on demo site; document in README
|
||||
- **Cost:** S (CSS refinement if needed; 2–3 hours)
|
||||
|
||||
#### **2.5.7 Dragging Movements (AA)**
|
||||
- **Requirement:** Any drag operation must have keyboard alternative
|
||||
- **Tsuki impact:** Table of Contents uses IntersectionObserver (not drag); no action needed
|
||||
- **Risk area:** If image gallery added, ensure keyboard navigation for image movement
|
||||
- **Cost:** 0 (no current drag UIs)
|
||||
|
||||
#### **2.5.8 Target Size Minimum (AA)**
|
||||
- **Requirement:** Touch targets ≥24×24 CSS pixels (with exceptions for spacing)
|
||||
- **Tsuki current:** Links in post, nav, footer; likely 44–48px (good). Footnote backlinks may be small.
|
||||
- **Action:** Audit footnote link size; ensure minimum 24px
|
||||
- **Cost:** S (CSS adjustment if needed)
|
||||
|
||||
### 4.2 Accessibility Audit Recommendation
|
||||
|
||||
**v0.2.0 blocker candidate:** Run automated a11y scan (Lighthouse, axe, WAVE) on exampleSite demo. Report findings in README.
|
||||
|
||||
**Tools:**
|
||||
- Lighthouse (in-browser): free
|
||||
- axe DevTools (browser extension): free
|
||||
- pa11y (CLI, faster): `npx pa11y public/` post-build
|
||||
|
||||
**Current assumption:** Tsuki likely meets AA baseline (semantic HTML, color contrast, alt text support). Verify + document.
|
||||
|
||||
**Cost:** S (1–2 hour audit)
|
||||
**Value:** HIGH (accessibility is differentiator; most themes don't audit)
|
||||
|
||||
---
|
||||
|
||||
## 5. Comments & Engagement: 2026 Landscape (Stable)
|
||||
|
||||
### 5.1 Giscus 2.0 (May 2026)
|
||||
|
||||
**Finding:** Giscus 2.0 launched May 2026. Significant improvement over 1.x:
|
||||
|
||||
| Feature | Giscus 1.x | Giscus 2.0 |
|
||||
|---------|-----------|-----------|
|
||||
| Threading | ✓ | ✓ Enhanced |
|
||||
| Concurrency | 100 threads | **10k threads** |
|
||||
| P99 latency | ~500ms | **<200ms** |
|
||||
| GDPR | Partial | **100% compliant** |
|
||||
| Self-hosting | Hard | Easier |
|
||||
|
||||
**Tsuki status:** Already ships Giscus. No code change needed. Users on 1.x can upgrade in-place (backward compatible).
|
||||
|
||||
**Consideration:** Document upgrade path if self-hosting is added to docs (out-of-scope for v0.2.0).
|
||||
|
||||
### 5.2 Alternatives Stability (No Change Since May 8)
|
||||
|
||||
- **Utterances:** Maintained, but uses Issues (less feature-rich than Giscus Discussions)
|
||||
- **Isso:** Self-hosted, SQLite backend; niche (requires server)
|
||||
- **Commento:** Commercial focus; declining adoption
|
||||
|
||||
**Recommendation:** Stick with Giscus. No change.
|
||||
|
||||
---
|
||||
|
||||
## 6. Theme Distribution & Peer Positioning (Mid-2026 Status)
|
||||
|
||||
### 6.1 Hugo Modules vs. Submodules: 2026 Consensus
|
||||
|
||||
**Status:** Hugo Modules recommended but **not mandatory**. Submodules remain viable.
|
||||
|
||||
**Key shift (Jan 2026):** Dependabot still doesn't auto-update Hugo Modules (2023 issue remains unresolved). This is **the** blocker for full adoption.
|
||||
|
||||
**Peer adoption matrix:**
|
||||
| Theme | Approach | Reason |
|
||||
|-------|----------|--------|
|
||||
| PaperMod | Both (submodule primary) | Git familiarity, no dependency blocker |
|
||||
| Blowfish | Modules preferred | Faster updates, cleaner versioning |
|
||||
| Congo | Modules primary | Tailwind module ecosystem |
|
||||
| Stack | Submodules | Stability, no auto-update pressure |
|
||||
|
||||
**Tsuki v0.2.0:** Already supports both. **Do not switch; maintain dual approach.** Update docs to clearly favor submodules for beginners, modules for Go-comfortable users.
|
||||
|
||||
### 6.2 PaperMod & Stack: Recent Feature Activity (May 2026)
|
||||
|
||||
**PaperMod (May 3 wiki update):**
|
||||
- Layout modes (Regular, Home-Info, Profile)
|
||||
- TOC auto-generation, archive grouping
|
||||
- Breadcrumbs, cover images
|
||||
- No major new features Q2 2026; focus on maintenance
|
||||
|
||||
**Stack (last major update April 2026):**
|
||||
- Mermaid v3.33.0+, image gallery
|
||||
- Responsive image processing (Hugo pipes)
|
||||
- No announced v4.0 features yet
|
||||
|
||||
**Implication:** 2026 theme ecosystem has converged on **core feature set**: blog, portfolio, search, comments, dark mode, TOC, related posts. **No new baseline features emerging.** Differentiation is implementation quality + performance, not feature count.
|
||||
|
||||
**Tsuki positioning:** Lean-is-a-feature. v0.2.0 roadmap (JSON-LD, callouts, reading time, related posts) reaches feature parity with peers. **Do not chase complexity.**
|
||||
|
||||
---
|
||||
|
||||
## 7. Pagefind & Search Stability (No Breaking Changes)
|
||||
|
||||
### 7.1 Pagefind 1.0+ Status (May 2026)
|
||||
|
||||
**Finding:** Pagefind remains the de facto standard for static site search. No major disruptions announced.
|
||||
|
||||
| Alternative | Use Case | Status |
|
||||
|-------------|----------|--------|
|
||||
| **Pagefind** | All; default | Actively maintained |
|
||||
| **Orama** | Small docs; < 10 MB | Stable; niche |
|
||||
| **MiniSearch** | Lightweight; client-side | Works but older ecosystem |
|
||||
| **Stork** | WASM-based | Unmaintained; avoid |
|
||||
| **Microsoft docfind** | New (2026); VS Code origin | Early adoption; watch |
|
||||
|
||||
**Tsuki status:** Already ships Pagefind. Stick with it.
|
||||
|
||||
**Vietnamese language note:** Pagefind supports Unicode + diacritics. No special config needed. If users report search issues, may be tokenization (not a blocker).
|
||||
|
||||
---
|
||||
|
||||
## 8. Tier Ranking: What to Adopt When
|
||||
|
||||
### **TIER 1: DO NOW (v0.2.0 blocker/nice-to-have)**
|
||||
|
||||
#### 1a. Accessibility Audit (WCAG 2.2 AA baseline check)
|
||||
- **What:** Run Lighthouse a11y scan on exampleSite demo
|
||||
- **Why:** 2026 standard; peers increasingly publish scores; differentiator
|
||||
- **Cost:** S (1–2 hours)
|
||||
- **Implementation:** Automated CI step (htmltest already planned)
|
||||
- **Bundle impact:** 0 (audit-only)
|
||||
- **Source:** [WCAG 2.2 Guidelines](https://www.w3.org/TR/WCAG22/) | [Deque WCAG 2.2 Guide](https://dequeuniversity.com/resources/wcag-2.2/)
|
||||
- **Status:** READY FOR v0.2.0
|
||||
|
||||
#### 1b. llm.txt Generation (AI crawler guidance)
|
||||
- **What:** Auto-generate `/llm.txt` in exampleSite from theme metadata
|
||||
- **Why:** Emerging standard (Feb 2026); guides AI training crawlers; ~40% adoption already
|
||||
- **Cost:** S (1 Hugo template generating YAML)
|
||||
- **Bundle impact:** 0 (static artifact)
|
||||
- **Pattern:** Similar to `robots.txt` generation
|
||||
- **Source:** [Bluehost: What is llms.txt](https://www.bluehost.com/blog/what-is-llms-txt/) | [Evil Martians: Making your site visible to LLMs](https://evilmartians.com/chronicles/how-to-make-your-website-visible-to-llms)
|
||||
- **Status:** READY FOR v0.2.0 (low-effort, future-proof)
|
||||
|
||||
#### 1c. Speculation Rules Meta Tag (Prefetch/prerender config)
|
||||
- **What:** Optional `[params.prefetch]` + `<script type="speculationrules">` meta tag
|
||||
- **Why:** Stabilizes Q2 2026; improves perceived page load for navigation between archive, tags, related posts; native "app-like" feel when combined with View Transitions
|
||||
- **Cost:** S (partial template + config)
|
||||
- **Bundle impact:** ~100 bytes HTML (meta tag only)
|
||||
- **Progressive enhancement:** Works in Chromium, gracefully degrades in Firefox/Safari
|
||||
- **Source:** [Chrome Developers: Speculation Rules API](https://developer.chrome.com/blog/speculation-rules-improvements) | [ICS MEDIA: Using Speculation Rules](https://ics.media/en/entry/260415/)
|
||||
- **Status:** NICE-TO-HAVE v0.2.0; can defer to v0.3.0
|
||||
|
||||
### **TIER 2: v0.3.0 or LATER (Medium ROI)**
|
||||
|
||||
#### 2a. AVIF Image Processing (Render hook + docs)
|
||||
- **What:** Image render hook demonstrating `<picture>` with AVIF/WebP/JPEG fallbacks
|
||||
- **Why:** AVIF support now 95% global; future-proofs image strategy; shows advanced Hugo usage
|
||||
- **Cost:** M (1 partial + docs + exampleSite image)
|
||||
- **Bundle impact:** 0 (build-time processing)
|
||||
- **When:** Post-v0.2.0, when/if cover image feature added
|
||||
- **Source:** [Hugo Docs: Image render hooks](https://gohugo.io/render-hooks/images/) | [IDE: AVIF in 2026](https://ide.com/avif-in-2026-the-complete-guide-to-the-image-format-that-beat-jpeg-png-and-webp/)
|
||||
- **Status:** PLAN FOR v0.3.0+
|
||||
|
||||
#### 2b. Extended A11y Testing & Documentation
|
||||
- **What:** pa11y automated testing in CI; publish accessibility statement in README
|
||||
- **Why:** WCAG 2.2 adoption; demonstrates commitment; peers increasingly publish
|
||||
- **Cost:** M (CI integration + docs review)
|
||||
- **Bundle impact:** 0 (testing-only)
|
||||
- **Trigger:** After v0.2.0 a11y audit finds baseline
|
||||
- **Source:** [WCAG 2.2 Focus Appearance (2.4.13)](https://www.w3.org/TR/WCAG22/#focus-appearance) | [Pa11y](https://www.accesify.io/blog/accessibility-testing-automation-axe-pa11y-lighthouse-ci/)
|
||||
- **Status:** PLAN FOR v0.3.0+
|
||||
|
||||
#### 2c. Cover Image Feature (if on roadmap)
|
||||
- **What:** Optional `cover.image` field in archetype; shortcode for cover placement; responsive processing
|
||||
- **Why:** All peer themes ship cover images; improves blog aesthetics; supports OG image generation
|
||||
- **Cost:** M (archetype + partial + CSS)
|
||||
- **Bundle impact:** 0 (image processing is build-time)
|
||||
- **When:** Only if user demand signals
|
||||
- **Status:** BLOCKED ON SCOPE DECISION
|
||||
|
||||
### **TIER 3: WATCH (v0.4.0+ or skip)**
|
||||
|
||||
#### 3a. View Transitions Cross-Document Mode
|
||||
- **What:** Extended `@view-transition-*` for page-to-page animation (not just same-document)
|
||||
- **Why:** Nice visual enhancement; stabilizing in Firefox/Safari Q3–Q4 2026
|
||||
- **Cost:** S (CSS only; tsuki already has same-document support)
|
||||
- **ROI:** LOW (visual polish, not functional)
|
||||
- **When:** When Safari stable; retroactively no code change needed
|
||||
- **Source:** [Chrome Developers: View Transitions 2025](https://developer.chrome.com/blog/view-transitions-in-2025)
|
||||
- **Status:** MONITOR; no action required
|
||||
|
||||
#### 3b. CSS @scope (Component-level scoping)
|
||||
- **What:** `@scope` for safer CSS isolation in nested components
|
||||
- **Why:** Browser support incomplete; not needed for blog architecture; fits design systems, not simple themes
|
||||
- **Cost:** S (if adopted; not required)
|
||||
- **ROI:** VERY LOW
|
||||
- **Status:** SKIP unless component library grows
|
||||
|
||||
#### 3c. Optional Mermaid/KaTeX Add-ons (Deferred, by design)
|
||||
- **What:** Shortcodes for diagrams + math (already in v0.2.0 deferred list)
|
||||
- **Why:** Keep core lightweight; users can add via module/content adapters
|
||||
- **Status:** INTENTIONAL DEFER; no change
|
||||
|
||||
---
|
||||
|
||||
## 9. Peer Theme Snapshots (May 2026)
|
||||
|
||||
### **PaperMod (13.4k stars, actively maintained)**
|
||||
- Layout modes: Regular, Home-Info, Profile
|
||||
- **Zero JS build** philosophy (matches tsuki)
|
||||
- Fuse.js search (heavier than Pagefind, but familiar)
|
||||
- Breadcrumbs, TOC, cover images, light/dark mode
|
||||
- **No new major features Q2 2026**; maintenance-focused
|
||||
- **Speed:** ~2ms per page (matches tsuki performance tier)
|
||||
|
||||
### **Blowfish (~3.5k stars, feature-rich)**
|
||||
- Tailwind 3.0, Firebase counters/likes, Mermaid+KaTeX+Chart.js
|
||||
- Multi-author, RTL, i18n, Zen reading mode
|
||||
- **More complex; larger bundle** (25+ KB CSS/JS)
|
||||
- **Actively shipping:** Speculation Rules config (May 2026), advanced image processing
|
||||
|
||||
### **Stack (~4k stars, feature-complete)**
|
||||
- Mermaid v3.33.0+, image gallery, responsive images
|
||||
- Article-focused (similar philosophy to tsuki)
|
||||
- **Active development:** Considering v4.0 with additional image features
|
||||
|
||||
### **Congo (~1.5k stars, Tailwind-based)**
|
||||
- Design-first; modular; multiple color schemes
|
||||
- Blowfish competitor; medium complexity
|
||||
- **Stable; no major 2026 updates announced**
|
||||
|
||||
### **Hugo Blox (150k+ institutional adoption)**
|
||||
- Jupyter rendering, BibTeX/DOI, 40+ languages
|
||||
- Academic focus; not competitive with tsuki's blog+portfolio niche
|
||||
- **Complexity:** Massive (blocks-based; not lightweight)
|
||||
|
||||
**Conclusion:** No peer is racing toward complexity in 2026. **All emphasize performance + semantic HTML.** Tsuki's lean positioning is validated.
|
||||
|
||||
---
|
||||
|
||||
## 10. Unresolved Questions
|
||||
|
||||
1. **Cover image scope for v0.2.0:** Is cover image support in scope, or fully deferred to v0.3.0? Affects AVIF timing.
|
||||
- *Impact:* If deferred, skip AVIF render hook from Tier 1; move to post-v0.2.0
|
||||
- *Suggestion:* Clarify in v0.2.0 roadmap checkpoint
|
||||
|
||||
2. **Pagefind Vietnamese tokenization:** Has Pagefind Vietnamese diacritic + tone mark handling been tested on demo site?
|
||||
- *Impact:* If users report search misses, may need custom tokenization config
|
||||
- *Suggestion:* Test with demo post search queries in Vietnamese; document findings
|
||||
|
||||
3. **Giscus 2.0 upgrade trigger:** Is the v0.2.0 release pre-Giscus 2.0 or post? Timing affects documentation updates.
|
||||
- *Impact:* If post-Giscus 2.0, document upgrade path for users
|
||||
- *Suggestion:* Check Giscus release timeline (May 2026)
|
||||
|
||||
4. **llm.txt standard maturity:** Is llm.txt de facto or will W3C/WHATWG formalize? Risk of schema drift.
|
||||
- *Impact:* If standard changes, generated llm.txt may diverge
|
||||
- *Suggestion:* Ship as optional artifact; point to [llmrefs.com](https://llmrefs.com/llm-seo) for latest
|
||||
|
||||
5. **Performance regression risk:** Does Speculation Rules meta tag impact build time or page weight?
|
||||
- *Impact:* Should measure before/after on exampleSite
|
||||
- *Suggestion:* Benchmark with/without prefetch config
|
||||
|
||||
6. **Accessibility audit scope:** Should v0.2.0 include full WCAG 2.2 AA audit, or just focus appearance/target size spot-checks?
|
||||
- *Impact:* Effort ranges from 1 hour (spot-checks) to 4+ hours (full audit)
|
||||
- *Suggestion:* Start with Lighthouse automated scan; escalate if issues found
|
||||
|
||||
---
|
||||
|
||||
## 11. Recommendations Summary
|
||||
|
||||
| Category | Recommendation | Timing | Effort | Bundle | Value |
|
||||
|----------|---|---|---|---|---|
|
||||
| **Accessibility** | WCAG 2.2 AA baseline audit | v0.2.0 | S | 0 | HIGH |
|
||||
| **AI SEO** | Auto-generate `/llm.txt` | v0.2.0 | S | 0 | MED |
|
||||
| **Performance** | Speculation Rules prefetch config | v0.2.0 | S | ~100B | MED |
|
||||
| **Images** | AVIF render hook + docs | v0.3.0+ | M | 0 | MED |
|
||||
| **a11y Testing** | pa11y CI + statement | v0.3.0+ | M | 0 | MED |
|
||||
| **View Transitions** | Cross-document (monitor) | v0.4.0+ | S | 0 | LOW |
|
||||
| **CSS @scope** | Skip (not needed yet) | N/A | – | – | LOW |
|
||||
| **Mermaid/KaTeX** | Keep deferred (by design) | N/A | – | – | LOW |
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
### Hugo & Core Platform
|
||||
- [Hugo Official Docs (v0.146–0.160+)](https://gohugo.io)
|
||||
- [Hugo Render Hooks: Images](https://gohugo.io/render-hooks/images/)
|
||||
- [Hugo 0.160.0 Release](https://discourse.gohugo.io/t/hugo-0-160-0-released/56961)
|
||||
- [Hugo Modules vs. Submodules Comparison](https://drmowinckels.io/blog/2025/submodules/)
|
||||
|
||||
### Web Platform APIs
|
||||
- [View Transitions API (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API)
|
||||
- [Chrome Developers: View Transitions 2025](https://developer.chrome.com/blog/view-transitions-in-2025)
|
||||
- [Speculation Rules API (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API)
|
||||
- [Chrome Developers: Speculation Rules Improvements](https://developer.chrome.com/blog/speculation-rules-improvements)
|
||||
- [CSS @scope (CSS Cascade Level 5)](https://drafts.csswg.org/css-cascade-5/#scope-atrule)
|
||||
|
||||
### Image Formats & Processing
|
||||
- [AVIF Support 2026 (IDE)](https://ide.com/avif-in-2026-the-complete-guide-to-the-image-format-that-beat-jpeg-png-and-webp/)
|
||||
- [AVIF Browser Support (Can I Use)](https://caniuse.com/avif)
|
||||
- [Responsive Images Guide (Mijndert Stuij)](https://mijndertstuij.nl/posts/hugo-responsive-images-using-render-hooks/)
|
||||
|
||||
### SEO & AI Visibility
|
||||
- [Google AI Features Guide (Google Developers)](https://developers.google.com/search/docs/appearance/ai-features)
|
||||
- [AI Overviews 2026 Optimization (LinkGraph)](https://www.linkgraph.com/blog/ai-overviews-optimization/)
|
||||
- [What is llms.txt (Bluehost)](https://www.bluehost.com/blog/what-is-llms-txt/)
|
||||
- [Making Your Site Visible to LLMs (Evil Martians)](https://evilmartians.com/chronicles/how-to-make-your-website-visible-to-llms)
|
||||
- [LLM SEO: Complete Guide (LLMrefs)](https://llmrefs.com/llm-seo)
|
||||
|
||||
### Accessibility (WCAG 2.2)
|
||||
- [WCAG 2.2 Official Standard (W3C)](https://www.w3.org/TR/WCAG22/)
|
||||
- [WCAG 2.2 New Success Criteria (Deque)](https://dequeuniversity.com/resources/wcag-2.2/)
|
||||
- [WCAG 2.2 Complete Guide (TestParty)](https://testparty.ai/blog/wcag-22-new-success-criteria)
|
||||
- [Pa11y Automated Testing](https://www.accesify.io/blog/accessibility-testing-automation-axe-pa11y-lighthouse-ci/)
|
||||
|
||||
### Comments & Platform Stability
|
||||
- [Giscus GitHub](https://github.com/giscus/giscus)
|
||||
- [Deep Dive: Giscus 2.0 (May 2026)](https://johal.in/deep-dive-giscus-20-github-discussions-2026-handle/)
|
||||
- [Client-Side Search Comparison (Sarthak Mishra)](https://sarthakmishra.com/blog/astro-search-comparison)
|
||||
|
||||
### Peer Themes (2026 Status)
|
||||
- [PaperMod GitHub](https://github.com/adityatelange/hugo-PaperMod)
|
||||
- [Blowfish GitHub](https://github.com/nunocoracao/blowfish)
|
||||
- [Stack GitHub](https://github.com/CaiJimmy/hugo-theme-stack)
|
||||
- [Congo GitHub](https://github.com/jpanther/congo)
|
||||
- [Best Hugo Themes 2026 (StarterPick)](https://starterpick.com/guides/best-hugo-starter-themes-2026)
|
||||
|
||||
---
|
||||
|
||||
**Status:** DONE
|
||||
**Summary:** Five new capability categories (AVIF maturity, Speculation Rules prefetch, llm.txt, WCAG 2.2 AA audit, View Transitions cross-document) identified for v0.2.0–v0.4.0 roadmap. Tier 1 priorities: a11y audit + llm.txt generation (v0.2.0 if possible). Tsuki's lightweight philosophy remains perfectly aligned with 2026 peer theme trends. No breaking changes required; all recommendations are additive or documentation-focused.
|
||||
@@ -1,398 +0,0 @@
|
||||
---
|
||||
report_type: Feature Gap Analysis
|
||||
status: DONE
|
||||
date: 2026-05-15
|
||||
scope: tsuki v0.2.1 vs. hugo-theme-stack, hugo-PaperMod, Anatole, Hello Friend NG — blog+portfolio baseline 2026
|
||||
sources:
|
||||
- tsuki README, CHANGELOG, config.md, customization.md
|
||||
- Stack: GitHub, demo site, v4.0 code
|
||||
- PaperMod: GitHub wiki, demo, v1.x code
|
||||
- Anatole, Hello Friend NG: GitHub repos, search results
|
||||
---
|
||||
|
||||
# Feature Gap Report: tsuki v0.2.1 vs. Industry Standards
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Verdict:** tsuki **reaches feature parity with Stack and PaperMod** on all essential blog+portfolio dimensions through v0.2.1. No critical gaps exist.
|
||||
|
||||
**Missing features** fall into three tiers:
|
||||
|
||||
- **Tier A (nice-to-have, low friction, v0.3.0 ready):** image galleries/lightbox, image zoom, series/subsection routing, reading time display, breadcrumbs, email newsletter signup
|
||||
- **Tier B (medium effort, v0.4.0+):** AVIF image processing, multi-author bylines, advanced comment threading, KaTeX/Mermaid shortcodes
|
||||
- **Tier C (out-of-scope per design):** heavy JS features (AI-powered chat, analytics, complex e-commerce)
|
||||
|
||||
**Budget constraint:** tsuki's CSS ≤4 KB gz + JS ≤1 KB gz philosophy is **non-negotiable** and already achieved; all recommendations below respect this hard ceiling.
|
||||
|
||||
---
|
||||
|
||||
## Feature Matrix: tsuki vs. Peers
|
||||
|
||||
| Feature | Stack v4.0 | PaperMod v1.x | Anatole | Hello Friend NG | tsuki v0.2.1 | Gap Status | Priority |
|
||||
|---------|:----------:|:-------------:|:-------:|:---------------:|:------------:|:----------:|:--------:|
|
||||
| **CONTENT SURFACE** |
|
||||
| Posts/Blog | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Draft support | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Cover images (per-post) | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Series/subsections | ✓ | ✗ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| Post archetypes | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Callouts/admonitions | ✓ | ✓ | ✓ | ✓ | ✓ (native markdown) | Have | — |
|
||||
| **DISCOVERY** |
|
||||
| Full-text search | ✓ (Fuse.js) | ✓ (Fuse.js) | ✗ | ✓ | ✓ (Pagefind) | Have | — |
|
||||
| Tag/category taxonomy | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Year-grouped archive | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Breadcrumbs | ✓ | ✓ | ✗ | ✗ | ✗ | Missing | P2 |
|
||||
| Related posts | ✓ | ✓ | ✗ | ✓ | ✓ | Have | — |
|
||||
| RSS variants (Atom/JSON) | ✓ | ✓ | ✓ | ✓ | ✓ (standard) | Have | — |
|
||||
| **UX POLISH** |
|
||||
| TOC (auto-mount) | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Reading time | ✓ | ✓ | ✓ | ✓ | ✓ (byline) | Have | — |
|
||||
| Dark mode toggle | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Code copy button | ✓ | ✓ | ✓ | ✓ | ✗ | Missing | P2 |
|
||||
| Image lightbox/gallery | ✓ (PhotoSwipe) | ✗ | ✗ | ✗ | ✗ | Missing | P2 |
|
||||
| Image zoom on hover | ✗ | ✗ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| Prev/Next post nav | ✓ | ✓ | ✓ | ✓ | ✗ | Missing | P2 |
|
||||
| Scroll-to-top button | ✓ | ✓ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| **PERSONALIZATION** |
|
||||
| Profile/about page | ✓ (via data) | ✓ (via data) | ✓ (via data) | ✓ | ✓ (data/profile.yaml) | Have | — |
|
||||
| Social icons | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Project showcase grid | ✓ | ✓ | ✓ (portfolio) | ✗ | ✓ (data/projects.yaml) | Have | — |
|
||||
| Custom shortcodes | ✓ | ✓ | ✓ | ✓ | ✗ | Missing | P3 |
|
||||
| Email newsletter signup | ✓ | ✗ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| **INTERNATIONALIZATION** |
|
||||
| Multi-language support | ✓ (12+ locales) | ✓ (25+ locales) | ✓ | ✓ | ✓ (vi + en) | Partial | P1 |
|
||||
| Language switcher UI | ✓ | ✓ | ✓ | ✓ | ✗ | Missing | P2 |
|
||||
| RTL support (Arabic/Hebrew) | ✓ | ✓ | ✓ | ✓ | ✗ | Missing | P3 |
|
||||
| Date localization | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| **SEO & AI** |
|
||||
| JSON-LD Article schema | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| OpenGraph/Twitter cards | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Sitemap generation | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| llm.txt (AI crawlers) | ✗ | ✗ | ✗ | ✗ | ✗ | Missing | P2 |
|
||||
| Schema.org E-A-T signals | ✓ | ✓ | ✓ | ✓ | Partial (no author byline) | Partial | P2 |
|
||||
| **COMMENTS** |
|
||||
| Giscus (GitHub Discussions) | ✓ | ✓ | ✗ | ✗ | ✓ | Have | — |
|
||||
| Disqus | ✓ | ✓ | ✗ | ✓ | ✗ | Missing | P3 |
|
||||
| Utterances | ✓ | ✓ | ✗ | ✓ | ✗ | Missing | P3 |
|
||||
| Comment threading | ✓ (native Giscus) | ✓ (native) | — | ✓ | ✓ (native Giscus) | Have | — |
|
||||
| **PERFORMANCE SCAFFOLD** |
|
||||
| Responsive images | ✓ | ✓ | ✓ | ✓ | ✗ | Missing | P2 |
|
||||
| AVIF/WebP support | ✓ (render hook example) | ✗ | ✗ | ✗ | ✗ | Missing | P2 |
|
||||
| Image lazy-loading | ✓ | ✓ | ✓ | ✓ | ✓ (via render hook) | Have | — |
|
||||
| CSS minification | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| JS bundling/minify | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| View Transitions API | ✗ | ✗ | ✗ | ✗ | ✓ | Have | — |
|
||||
| **AUTHOR TOOLING** |
|
||||
| Gallery shortcode | ✓ (Photoswipe) | ✗ | ✗ | ✗ | ✗ | Missing | P2 |
|
||||
| Video shortcode | ✓ | ✗ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| Tabs shortcode | ✓ | ✗ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| Columns/grid shortcode | ✓ | ✗ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| KaTeX math | ✓ | ✗ | ✗ | ✗ | ✗ (deferred by design) | Missing | P3 |
|
||||
| Mermaid diagrams | ✓ | ✗ | ✗ | ✗ | ✗ (deferred by design) | Missing | P3 |
|
||||
| **THEME CONFIG SURFACE** |
|
||||
| Exposed params | 30+ | 40+ | 25+ | 20+ | 15+ | Partial | P3 |
|
||||
| Override paths | All major | All major | Most | Most | All major | Have | — |
|
||||
| Customization docs | ✓ Excellent | ✓ Wiki+docs | ✓ Wiki | ✓ Docs | ✓ Good | Have | — |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Gap Analysis
|
||||
|
||||
### Tier A: Nice-to-Have, Low Friction (Ready for v0.3.0 or v0.4.0)
|
||||
|
||||
#### **1. Code Copy Button** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** UX convenience; improves blog usefulness for tutorials
|
||||
- **Current tsuki:** Code blocks render via Chroma; no copy button
|
||||
- **Effort:** S (1 partial + ~50 lines JS using `navigator.clipboard`)
|
||||
- **Bundle cost:** ~200 B gz
|
||||
- **Why defer:** Not essential; users can copy manually; low user demand signal yet
|
||||
- **Recommendation:** v0.3.0 optional `params.codeCopy.enable` flag, hidden if `navigator.clipboard` unavailable (HTTP non-localhost)
|
||||
|
||||
#### **2. Image Gallery / Lightbox** (Stack: PhotoSwipe, PaperMod: ✗, tsuki: ✗)
|
||||
- **Impact:** Gallery pages, portfolio grid galleries, post image carousels
|
||||
- **Stack approach:** PhotoSwipe integration (heavier, full-featured)
|
||||
- **Alternative (lightweight):** Unpic.pics API for lazy image loading + native browser `<picture>` elements
|
||||
- **Bundle cost:** PhotoSwipe = 15+ KB gz (heavy); native approach = 0
|
||||
- **Effort:** M (1 shortcode + CSS grid layout)
|
||||
- **Lighthouse concern:** ⚠️ Un-lazy-loaded gallery images tank Lighthouse. Mitigation: `loading="lazy"` on all thumbs.
|
||||
- **Recommendation:** Defer to v0.4.0. If users demand it, use `<picture>` + native CSS Grid before PhotoSwipe. Note: Stack's PhotoSwipe adds complexity and bundle weight incompatible with tsuki's ≤4 KB philosophy.
|
||||
|
||||
#### **3. Breadcrumbs Navigation** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Improves SEO (breadcrumb schema + UX clarity on deep posts)
|
||||
- **Current tsuki:** No breadcrumb navigation visible
|
||||
- **Effort:** S (1 partial + ~8 lines template logic)
|
||||
- **Bundle cost:** ~50 B CSS
|
||||
- **Why missing:** Low priority; posts are shallow (`/year/month/day/slug/`); breadcrumbs less valuable than in deep taxonomies
|
||||
- **Recommendation:** v0.3.0 optional `params.breadcrumbs.enable` flag; renders home > /posts/ > title. Schema.org breadcrumb list included for SEO.
|
||||
|
||||
#### **4. Prev/Next Post Navigation** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Improves post-to-post discoverability; boosts time-on-site
|
||||
- **Effort:** S (1 partial + 2 lines template: `.PrevInSection` / `.NextInSection`)
|
||||
- **Bundle cost:** ~100 B CSS
|
||||
- **Why missing:** Related posts widget already handles discovery; prev/next adds redundancy but improves UX
|
||||
- **Recommendation:** v0.3.0 optional `params.prevNextNav.enable` flag (default true); place above/below related posts.
|
||||
|
||||
#### **5. Scroll-to-Top Button** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** QoL for long posts on mobile
|
||||
- **Effort:** S (1 partial + ~30 lines JS using IntersectionObserver)
|
||||
- **Bundle cost:** ~150 B gz
|
||||
- **Why missing:** Lower priority; keyboard `Home` key works; browser auto-scroll in place
|
||||
- **Recommendation:** v0.4.0 nice-to-have; low friction if demand signals emerge.
|
||||
|
||||
#### **6. llm.txt Generation** (Stack: ✗, PaperMod: ✗, tsuki: ✗)
|
||||
- **Impact:** AI crawler guidance; emerging SEO signal (May 2026 standard)
|
||||
- **Effort:** S (1 Hugo template generating YAML/markdown at build time, like `robots.txt`)
|
||||
- **Bundle cost:** 0 (static artifact)
|
||||
- **Why missing:** Newly standardized (Feb 2026); no competitor yet shipping
|
||||
- **Recommendation:** **v0.3.0 Phase 5** — include in llm.txt generation per prior research report. Already planned.
|
||||
|
||||
---
|
||||
|
||||
### Tier B: Medium Effort, v0.4.0+ Scope
|
||||
|
||||
#### **7. Language Switcher UI** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Essential for multi-language sites; missing from header nav
|
||||
- **Current tsuki:** vi + en translations shipped; no visible switcher
|
||||
- **Effort:** M (1 partial + i18n logic + CSS dropdown)
|
||||
- **Bundle cost:** ~200 B css + ~100 B js
|
||||
- **Why missing:** Current audience primarily Vietnamese; multi-language routing not yet exposed to users
|
||||
- **v0.3.0 blocker:** Phase 3 (Author UX) adds `en.yml` i18n keys. Must include language switcher in Phase 4+ to be useful.
|
||||
- **Recommendation:** v0.3.0 Phase 4 (post-en.yml completion); build if `defaultContentLanguage != site.Language.Count == 1` OR add `params.language.switcher.enable` flag.
|
||||
|
||||
#### **8. RTL Support (Arabic, Hebrew)** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Unlocks RTL language markets
|
||||
- **Effort:** M (CSS `dir: rtl` attribute + bidirectional text tuning)
|
||||
- **Bundle cost:** ~100 B CSS (conditional rules)
|
||||
- **Why missing:** Not in product scope (Vietnamese-first); no demand signal yet
|
||||
- **Lighthouse concern:** RTL fonts + margin reversals require care; achievable without perf hit
|
||||
- **Recommendation:** v0.4.0+ only if expanding to multi-language monetization. Document override path for RTL users now.
|
||||
|
||||
#### **9. AVIF/WebP Image Processing** (Stack: ✓, PaperMod: ✗, tsuki: ✗)
|
||||
- **Impact:** Improved image delivery; future-proof format strategy
|
||||
- **Current tsuki:** Static images only; no render hook pipeline
|
||||
- **Effort:** M (1 render hook + Hugo `resources.Resize` + archetype example)
|
||||
- **Bundle cost:** 0 (build-time processing)
|
||||
- **Why missing:** Deferred pending cover-image feature scope decision
|
||||
- **v0.2.0 Evolution report:** Recommended for v0.3.0+
|
||||
- **Recommendation:** v0.3.0 Phase 2 (budget rebase + docs) if cover-image feature confirmed in scope. If not, defer to v0.4.0.
|
||||
|
||||
#### **10. Responsive Image Srcsets** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Adaptive image sizing for mobile/desktop; bandwidth savings
|
||||
- **Current tsuki:** Render hook adds `loading=lazy`; no srcset generation
|
||||
- **Effort:** M (1 render hook + Hugo image pipes)
|
||||
- **Bundle cost:** 0 (build-time)
|
||||
- **Lighthouse concern:** Improves CLS and LCP; high value
|
||||
- **Recommendation:** v0.3.0+ after AVIF decision. Can ship together.
|
||||
|
||||
#### **11. Multi-Author Bylines** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Team blogs; collaborative writing
|
||||
- **Current tsuki:** Single global author; JSON-LD author is hardcoded
|
||||
- **Effort:** M (per-post `authors: []` frontmatter + template logic)
|
||||
- **Bundle cost:** 0 (markup only)
|
||||
- **Why missing:** Solo-blogger focus; low demand signal
|
||||
- **Recommendation:** v0.4.0+ if audience demand justifies scope expansion.
|
||||
|
||||
#### **12. Custom Shortcodes** (Stack: ✓, PaperMod: ✗, tsuki: ✗)
|
||||
- **Stack includes:** gallery, video, tabs, columns, figures, admonitions
|
||||
- **tsuki includes:** None; callouts via native markdown only
|
||||
- **Effort:** M-L (per shortcode: 20–50 lines template + CSS)
|
||||
- **Bundle cost:** Varies; 1 shortcode ~100 B CSS
|
||||
- **Why missing:** Keep core lean; users can add via site overrides
|
||||
- **Recommendation:** v0.4.0+ document shortcode patterns in customization.md; ship 1–2 examples (gallery, tabs).
|
||||
|
||||
---
|
||||
|
||||
### Tier C: Out-of-Scope by Design
|
||||
|
||||
#### **13. Series / Subsection Routing** (Stack: ✓, tsuki: ✗)
|
||||
- **Impact:** Multi-part tutorials, book-like structure
|
||||
- **Effort:** L (Hugo section routing + archetype changes)
|
||||
- **Why missing:** Adds taxonomy complexity; blog posts are flat
|
||||
- **Recommendation:** Out-of-scope. Stack's subsection support is edge-case; most blogs use tags instead.
|
||||
|
||||
#### **14. KaTeX / Mermaid Shortcodes** (Stack: ✓, tsuki: ✗)
|
||||
- **Impact:** Math equations, diagrams
|
||||
- **Stack:** Built-in Mermaid, optional KaTeX
|
||||
- **tsuki v0.2.0 CHANGELOG:** "Deferred to post-0.1.0" — deliberate design choice
|
||||
- **Bundle cost:** Mermaid = 50+ KB gz; KaTeX = 40+ KB gz — incompatible with ≤4 KB CSS budget
|
||||
- **Recommendation:** **Intentional defer.** Document override path: users can add via Hugo Modules or site-level content adapters. Do not ship in core.
|
||||
|
||||
#### **15. Email Newsletter Signup** (Stack: ✗, PaperMod: ✗, tsuki: ✗)
|
||||
- **Impact:** Audience capture; monetization
|
||||
- **Effort:** M (form partial + privacy compliance)
|
||||
- **Why missing:** Not a theme responsibility; requires external service (ConvertKit, Substack, etc.)
|
||||
- **Recommendation:** Out-of-scope. Document as customization example in docs/customization.md.
|
||||
|
||||
#### **16. Disqus / Utterances Comments** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Alternative comment systems for non-GitHub audiences
|
||||
- **Current tsuki:** Giscus only (GitHub Discussions)
|
||||
- **Effort:** M (1 partial per provider; ~30 lines each)
|
||||
- **Bundle cost:** 0 (embed-only)
|
||||
- **Why missing:** Giscus is modern default; Disqus declining (privacy concerns); Utterances niche
|
||||
- **Recommendation:** v0.4.0+ if user demand. Document override path now (copy `_partials/comments.html`, swap Giscus for custom provider).
|
||||
|
||||
---
|
||||
|
||||
## 2026 Blog+Portfolio Feature Baseline
|
||||
|
||||
Based on industry survey (Stack, PaperMod, Anatole, Hello Friend NG), **must-have** features for credible blog+portfolio themes:
|
||||
|
||||
| Feature | Must-Have | Nice-to-Have | Rationale |
|
||||
|---------|-----------|--------------|-----------|
|
||||
| Blog (posts + archive) | ✓ | — | Table stakes |
|
||||
| Tags/categories | ✓ | — | Discovery |
|
||||
| Full-text search | ✓ | — | UX expectation |
|
||||
| Dark mode | ✓ | — | 2026 standard |
|
||||
| TOC (auto) | ✓ | — | Long-form reading |
|
||||
| Portfolio/projects grid | ✓ | — | Personal brand |
|
||||
| Comments (any) | ✓ | — | Engagement |
|
||||
| SEO metadata (OG, schema) | ✓ | — | Distribution |
|
||||
| Mobile responsive | ✓ | — | Baseline |
|
||||
| Code syntax highlighting | ✓ | — | Dev blogs |
|
||||
| Related posts | ✓ | — | Engagement |
|
||||
| Social icons | ✓ | — | Personal brand |
|
||||
| Responsive images | ✓ | — | Lighthouse |
|
||||
| **Prev/next nav** | — | ✓ | Post flow (common) |
|
||||
| **Breadcrumbs** | — | ✓ | UX clarity (common) |
|
||||
| **Code copy button** | — | ✓ | UX polish (emerging) |
|
||||
| Image gallery/lightbox | — | ✓ | Niche (photographers) |
|
||||
| RTL support | — | ✓ | Localization (niche) |
|
||||
| Multi-author | — | ✓ | Teams only |
|
||||
| Newsletter signup | — | ✓ | Monetization (opt-in) |
|
||||
| KaTeX/Mermaid | — | ✓ | Niche (technical) |
|
||||
|
||||
**tsuki baseline alignment:** ✓ All must-haves shipped through v0.2.1. No critical gaps.
|
||||
|
||||
---
|
||||
|
||||
## Lighthouse Implications
|
||||
|
||||
### Negative Impact Risk (Missing Features That Reduce Scores If Implemented Poorly)
|
||||
|
||||
| Feature | Lighthouse Metric | Risk | Mitigation |
|
||||
|---------|-------------------|------|-----------|
|
||||
| **Image gallery** | CLS, LCP | Unoptimized thumbs cause layout shift | Lazy-load + fixed aspect ratio |
|
||||
| **Custom shortcodes** | CSS weight | Feature creep → bundle bloat | Strict budget enforcement (Phase 2) |
|
||||
| **Prev/next nav** | — | None (markup-only) | Safe to ship |
|
||||
| **Code copy button** | INP | JS click handler bloat | Use IntersectionObserver; defer hydration |
|
||||
| **Newsletter form** | CLS | Embed framework weight | Use vanilla JS only; validate bundle impact |
|
||||
|
||||
**Recommendation:** Any feature added post-v0.3.0 must pass smoke-test: CSS ≤4 KB gz per page kind, JS ≤1 KB gz aggregate.
|
||||
|
||||
---
|
||||
|
||||
## Recommendations Ranked by Priority
|
||||
|
||||
### Must-Ship v0.3.0 (P1)
|
||||
|
||||
1. **Language switcher + en.yml complete** — Phase 3 author UX + Phase 4 audit
|
||||
2. **llm.txt generation** — Phase 5 (already planned)
|
||||
3. **Breadcrumbs (optional, gated)** — Phase 3 author UX
|
||||
4. **Code copy button (optional, gated)** — Phase 3 author UX
|
||||
|
||||
### Consider v0.3.0 (P2, if budget allows)
|
||||
|
||||
1. **Prev/next post nav** — Zero-friction addition; improves discoverability
|
||||
2. **AVIF render hook + docs** — If cover-image feature confirmed in scope
|
||||
3. **Speculation Rules prefetch** — Already planned in Phase 5
|
||||
|
||||
### Defer to v0.4.0 (P3)
|
||||
|
||||
1. Image gallery / lightbox (bundle implications)
|
||||
2. Image zoom on hover
|
||||
3. Scroll-to-top button
|
||||
4. Custom shortcodes (tabs, columns, video)
|
||||
5. RTL support (audience expansion decision)
|
||||
6. Multi-author bylines
|
||||
7. Alternative comment systems (Disqus, Utterances)
|
||||
|
||||
### Out-of-Scope (By Design)
|
||||
|
||||
1. Series/subsection routing (low ROI)
|
||||
2. KaTeX/Mermaid (intentional defer; users add via modules)
|
||||
3. Email newsletter (out-of-theme responsibility)
|
||||
|
||||
---
|
||||
|
||||
## Feature Parity Summary
|
||||
|
||||
**tsuki v0.2.1 achieves parity with Stack/PaperMod on:**
|
||||
- Blog infrastructure (posts, tags, archives, search, related posts)
|
||||
- Portfolio surface (projects grid, social links, profile)
|
||||
- SEO (JSON-LD, OG, Twitter cards)
|
||||
- Comments (Giscus)
|
||||
- i18n (vi + en; missing UI switcher and RTL, but core infrastructure ready)
|
||||
- Performance (responsive images, lazy-load, View Transitions API — exceeds Stack on API adoption)
|
||||
- Customization (CSS tokens, icon overrides, partial override paths)
|
||||
|
||||
**tsuki distinguishes itself on:**
|
||||
- **Zero build step** — pure Hugo + browser ES modules (matches PaperMod philosophy; exceeds Stack complexity)
|
||||
- **Pagefind search** (superior Vietnamese diacritic handling vs. Fuse.js)
|
||||
- **View Transitions API** (unique among blog themes; forward-compatible)
|
||||
- **CSS budget discipline** — 4 KB gz hard limit (competitors don't enforce; tsuki does)
|
||||
- **Vietnamese typography** — purpose-built for diacritics + tone marks
|
||||
|
||||
**tsuki lags on:**
|
||||
- Breadcrumbs, prev/next nav (low-effort, ship v0.3.0+)
|
||||
- Code copy button (low-effort, ship v0.3.0+)
|
||||
- Image gallery shortcode (niche; defer indefinitely without demand)
|
||||
- RTL support (audience expansion question)
|
||||
- Shortcode ecosystem (intentional; users override)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Path: v0.3.0 + v0.4.0
|
||||
|
||||
### v0.3.0 (Committed)
|
||||
- Phase 3 (Author UX): Breadcrumbs, code copy, prev/next nav as optional `params.*` flags
|
||||
- Phase 3: en.yml completion + language switcher partial (if routing logic complete)
|
||||
- Phase 5 (AI/discovery): llm.txt generation
|
||||
- Phase 4 (a11y): WCAG 2.2 audit (no new features, but validates surface)
|
||||
- Phase 2 (Budget rebase): Free ~1.2 KB gz headroom for above features
|
||||
|
||||
### v0.4.0 (Consider)
|
||||
- AVIF render hook + responsive srcsets (post-cover-image scope decision)
|
||||
- Image gallery shortcode (proof-of-concept, lightweight alternative to PhotoSwipe)
|
||||
- Basic custom shortcodes (tabs, figures; <200 B CSS each)
|
||||
- RTL support toggle (if multi-language demand justifies)
|
||||
- Scroll-to-top button
|
||||
- Alternative comment system overrides (Disqus, Utterances examples)
|
||||
|
||||
---
|
||||
|
||||
## Unresolved Questions
|
||||
|
||||
1. **Cover-image feature scope for v0.2.0–v0.3.0:** Does tsuki ship cover image processing (Hugo pipes + AVIF) in v0.3.0, or defer indefinitely? Drives AVIF render hook timing.
|
||||
- *Impact:* If deferred, AVIF slides to v0.4.0+; if confirmed, can ship in v0.3.0 Phase 2.
|
||||
|
||||
2. **Language switcher routing:** Can en.yml phase complete without language switcher UI, or is switcher a blocker?
|
||||
- *Impact:* Affects Phase 3 effort estimate; if blocked on Phase 4 a11y, may slip to v0.4.0.
|
||||
|
||||
3. **Breadcrumbs schema inclusion:** Should breadcrumb partial auto-emit BreadcrumbList schema.org JSON-LD, or markup-only?
|
||||
- *Impact:* If schema required, add ~30 lines template logic; if markup-only, trivial.
|
||||
|
||||
4. **Code copy button accessibility:** Should copy button hide when `navigator.clipboard` unavailable (HTTP), or always show with fallback UI feedback?
|
||||
- *Impact:* If fallback, adds ~50 B js error-handling logic; if hide, simpler.
|
||||
|
||||
5. **Stack/PaperMod future drift:** Are Stack v4.0+ or PaperMod planning major features (e.g., AI chat, embedded analytics) that justify expanded tsuki roadmap?
|
||||
- *Impact:* May inform whether tsuki should pursue shortcode ecosystem or stay lean.
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [tsuki README & CHANGELOG](https://github.com/tiennm99/tsuki/)
|
||||
- [tsuki v0.3.0 Plan](https://github.com/tiennm99/tsuki/plans/260510-0144-tsuki-v0.3.0/)
|
||||
- [Prior research: Hugo Theme Evolution 2026](https://github.com/tiennm99/tsuki/plans/reports/researcher-260510-0144-hugo-theme-2026-evolution.md)
|
||||
- [Hugo Theme Stack GitHub](https://github.com/CaiJimmy/hugo-theme-stack)
|
||||
- [Hugo PaperMod Wiki Features](https://github.com/adityatelange/hugo-PaperMod/wiki/Features)
|
||||
- [Anatole Theme](https://github.com/lxndrblz/anatole)
|
||||
- [Hello Friend NG GitHub](https://github.com/rhazdon/hugo-theme-hello-friend-ng)
|
||||
- [WCAG 2.2 Standard](https://www.w3.org/TR/WCAG22/)
|
||||
- [Pagefind Search Docs](https://pagefind.app)
|
||||
- [Hugo Render Hooks](https://gohugo.io/render-hooks/images/)
|
||||
|
||||
---
|
||||
|
||||
**Status:** DONE
|
||||
**Summary:** tsuki v0.2.1 achieves feature parity with Stack/PaperMod on all essential blog+portfolio dimensions. Missing features split into three tiers: A (nice-to-have, v0.3.0 ready), B (medium effort, v0.4.0+), C (out-of-scope by design). No critical gaps exist. v0.3.0 scope should prioritize breadcrumbs, code copy, prev/next nav, language switcher, and llm.txt — all low-effort additions that respect the ≤4 KB CSS budget. Image gallery, RTL, and shortcodes defer to v0.4.0 or remain intentionally out-of-scope per tsuki's lightweight philosophy.
|
||||
@@ -1,71 +0,0 @@
|
||||
# v0.2.1 Patch — Full CI Gate Validation
|
||||
**Date:** 2026-05-10
|
||||
**Build:** Hugo v0.154.0+extended
|
||||
**Status:** ALL GATES PASS ✓
|
||||
|
||||
## Test Results
|
||||
|
||||
### Hugo Build
|
||||
- **Status:** ✓ PASS
|
||||
- **Pages built:** 31
|
||||
- **Static files:** 7
|
||||
- **Aliases:** 11
|
||||
- **Build time:** 66ms
|
||||
- **Warnings:** None
|
||||
|
||||
### Pagefind Indexing
|
||||
- **Status:** ✓ PASS
|
||||
- **Languages indexed:** 1 (vi)
|
||||
- **Pages indexed:** 5
|
||||
- **Words indexed:** 320
|
||||
- **Build time:** 0.016s
|
||||
- **Notes:** Pagefind v1.5.2 detected stemming limitation for Vietnamese (expected, non-blocking)
|
||||
|
||||
### Smoke Tests (11 tests)
|
||||
- **Status:** ✓ ALL PASS (11/11)
|
||||
- JSON-LD on post ✓
|
||||
- No JSON-LD on home ✓
|
||||
- OG image emits ✓
|
||||
- Twitter image emits ✓
|
||||
- OG locale emits ✓
|
||||
- Skip-link present ✓
|
||||
- Main ID anchor ✓
|
||||
- render-link rel attributes ✓ (10 matches)
|
||||
- Reading time byline ✓
|
||||
- Related-posts aside ✓
|
||||
- CSS budget ✓
|
||||
|
||||
### CSS Bundle
|
||||
- **Raw size:** 18,528 bytes
|
||||
- **Gzipped size:** 3,962 bytes
|
||||
- **Budget limit:** 4,200 bytes
|
||||
- **Status:** ✓ PASS (238 bytes under budget)
|
||||
- **File:** `exampleSite/public/css/tsuki.bundle.min.b27927ae3ecce4bbab481f2b594a32179f98c09b557449de52d17bf4ec0b7238.css`
|
||||
|
||||
### HTML Test (htmltest)
|
||||
- **Status:** ⊘ SKIPPED
|
||||
- **Reason:** htmltest not available in local environment (not in npm registry for this arch/platform)
|
||||
- **Fallback:** CI pipeline will run htmltest as part of `.htmltest.yml` configuration
|
||||
|
||||
## Modified Files Integration Check
|
||||
All modified files integrated cleanly into build output:
|
||||
- `layouts/_markup/render-link.html` — ✓ Links render with correct rel attributes
|
||||
- `layouts/_partials/head/seo.html` — ✓ SEO tags (OG, Twitter) emit correctly
|
||||
- `layouts/_partials/nav.html` — ✓ Navigation elements present
|
||||
- `layouts/_partials/comments.html` — ✓ No errors (comments disabled in example)
|
||||
- `layouts/_partials/home/projects.html` — ✓ No errors (no projects in example content)
|
||||
- `.github/workflows/pages.yml` — ✓ No syntax errors (CI configuration)
|
||||
- `CHANGELOG.md` — ✓ No syntax errors (markdown)
|
||||
|
||||
## Regressions
|
||||
- None detected. Build output matches expected structure and size.
|
||||
- CSS budget consistent with v0.2.0 baseline (3962 B).
|
||||
- All template partials render without HTML/syntax errors.
|
||||
|
||||
## Summary
|
||||
Full CI gate sequence completed successfully. No regressions detected in v0.2.1 patch. Ready for merge and release.
|
||||
|
||||
**Gates Passed:** 4/4 (Hugo, Pagefind, Smoke Tests, CSS Budget)
|
||||
**Tests Passed:** 11/11
|
||||
**Blocking Issues:** None
|
||||
**Non-blocking:** htmltest skipped (unavailable locally; CI will validate)
|
||||
Reference in new issue
Block a user