mirror of https://github.com/tiennm99/tsuki.git synced 2026-05-26 16:01:46 +00:00

Files

T

tiennm99 25f36aec12 feat: docs, changelog, expanded examples for v0.1.0 (Phase 8)

- docs/config.md: full params reference (required + optional + per-post
  frontmatter); explains why theme defaults don't deep-merge into
  consumer sites
- docs/data-schemas.md: profile.yaml + projects.yaml field tables
- docs/customization.md: layout overrides, design token override via
  custom CSS, font self-hosting, per-page color overrides, kill switches
- docs/migrating-from-stack.md: submodule swap, drop list, Stack-to-tsuki
  param mapping, frontmatter compat, gotchas (heading id changes break
  inbound anchor links)
- CHANGELOG.md: complete 0.1.0 entry covering all phases
- README.md: drop "under construction"; add full params snippet, search
  + comments + browser support sections, links to all docs
- exampleSite/data/projects.yaml: +tsuki, +penny-pincher (6 total)

Screenshots, miti99 migration, and v0.1.0 tag are user-driven actions
recorded in phase-08 plan.

2026-05-07 22:20:44 +07:00

2.8 KiB

Raw Blame History

Configuration

Reference for hugo.yaml keys that tsuki reads. All settings below are set in your site's hugo.yaml, not in the theme. The theme ships defaults for documentation only — Hugo does not deep-merge nested config from themes.

Required

languageCode: vi
defaultContentLanguage: vi
theme: tsuki

pagination:
  pagerSize: 10
  path: page

taxonomies:
  category: categories
  tag: tags

permalinks:
  post: /:year/:month/:day/:contentbasename/

markup:
  goldmark:
    renderer:
      unsafe: true
    parser:
      autoHeadingIDType: github-ascii  # ASCII slugs for vi diacritics
  tableOfContents:
    startLevel: 2
    endLevel: 4

Theme params

params:
  description: "Site description used in <meta>, falls back to site.Title."

  search:
    enable: true            # mounts /search/ + header search button

  home:
    recentPostsCount: 5     # how many post-cards on the homepage

  toc:
    enable: true            # gate at template level (currently informational)
    minWordCount: 400       # post must exceed this to render TOC

  comments:
    giscus:
      enable: false         # opt-in
      repo: "<owner>/<repo>"
      repoId: "R_kgDO..."
      category: "Announcements"
      categoryId: "DIC_kwDO..."
      mapping: "pathname"   # pathname | url | title | og:title
      strict: "0"
      reactionsEnabled: "1"
      inputPosition: "bottom"  # top | bottom
      theme: "preferred_color_scheme"
      lang: "vi"

Generate Giscus values at giscus.app. Only enable: true activates the partial; missing IDs are ignored.

Profile and projects

The homepage portfolio reads from data files, not params:

data/profile.yaml — bio, avatar, links. See data-schemas.md.
data/projects.yaml — featured projects grid. See data-schemas.md.

Per-post frontmatter

---
title: "Tiêu đề bài viết"
date: 2026-05-07T19:00:00+07:00
draft: false
description: "Tóm tắt 1-2 câu (dùng cho meta + post-card)."
tags: ["hugo", "viet"]
categories: ["ghi-chu"]
toc: false        # opt out of TOC for this post (default: render if WordCount > 400)
comments: false   # opt out of comments for this post (default: enabled if giscus.enable)
image: "img/cover.jpg"  # OG image override
---

Optional

menus:
  main:
    - name: "Bài viết"
      url: /post/
      weight: 10
    - name: "Lưu trữ"
      url: /archives/
      weight: 20
    - name: "Thẻ"
      url: /tags/
      weight: 30

Why theme defaults don't merge

Hugo's config-merging strategy for nested keys (markup, permalinks, pagination) is "none" by default. The theme ships a complete hugo.yaml for reference, but consumer sites must duplicate the keys above. See exampleSite/hugo.yaml for a working example.

2.8 KiB Raw Blame History