hugo-theme-creator

A Claude Code skill for building Hugo themes that ship with a working example site and install with a single git clone.

This skill extends huashu-design for design direction. huashu-design owns the design taste: brand-asset capture, the design-philosophy library, the junior-designer workflow, anti-AI-slop rules. This skill owns the Hugo-specific mechanics: directory layout, Go template translation, asset pipeline, exampleSite, distribution. If huashu-design isn’t installed alongside, the skill falls back to a conservative neutral default and says so.

The design system is always yours. The skill ships a neutral placeholder palette and never imposes a typeface, icon set, or colour — and never commits licensed fonts or paid icon kits into a distributable theme.

What you get

Run the skill, describe what you want, and end up with a directory like:

my-theme/
├── archetypes/default.md
├── assets/
│   ├── scss/{main.scss,_design-tokens.scss}
│   ├── js/main.js
│   ├── fonts/                       # self-hosted webfonts, no CDN
│   └── og/base.png                  # canvas for generated Open Graph cards
├── i18n/en.toml
├── layouts/
│   ├── {baseof,home,single,list,taxonomy,term,404}.html
│   ├── {home.json,rss.xml,sitemap.xml,robots.txt}
│   ├── _markup/{render-image,render-link}.html
│   ├── _partials/{head,header,footer,seo,og-image,fonts,search,theme-toggle,post-card,pagination}.html
│   └── _shortcodes/figure.html
├── static/
├── exampleSite/
│   ├── content/{_index.md,about.md,posts/...}
│   ├── data/social.toml
│   └── hugo.toml
├── images/{screenshot.png,tn.png}
├── theme.toml
├── LICENSE
├── README.md
└── .github/workflows/hugo.yml       # or .forgejo/workflows/, or both

That layout is the Hugo v0.146+ template system — flat layouts/, with only structural directories underscore-prefixed. The pre-0.146 shape (layouts/_default/, partials/, shortcodes/) still builds on current Hugo without warnings, so you’ll meet it constantly in older themes and tutorials; the skill knows the difference and writes the modern one.

Install in any Hugo site:

git clone <repo-url> themes/my-theme
echo 'theme = "my-theme"' >> hugo.toml
hugo server

What the generated theme does

• Responsive, semantic markup with an accessibility baseline that ships regardless: lang, alt text, skip link, focus styles, landmarks, prefers-reduced-motion
• Dark mode — follows the OS, with an optional toggle that remembers the choice and doesn’t flash white on load
• Client-side search — no external service; the index isn’t fetched until someone actually searches
• Open Graph images, including auto-generated title cards for posts with no cover art
• Full-content RSS, custom sitemap, environment-aware robots.txt
• Responsive WebP images via Markdown render hooks
• Self-hosted fonts through the asset pipeline — nothing loaded from a third-party origin
• SEO partial: Open Graph, Twitter cards, JSON-LD BlogPosting
• i18n-ready, taxonomies, pagination

How it’s laid out

hugo-theme-creator/
├── SKILL.md                  ← the workflow Claude follows
├── references/               ← deep-dive docs Claude reads when needed
│   ├── theme-structure.md
│   ├── go-templates.md
│   ├── lookup-order.md
│   ├── modern-features.md
│   ├── example-site.md
│   ├── distribution.md
│   ├── huashu-design-bridge.md
│   ├── claude-design-bridge.md
│   └── verification.md
├── assets/
│   ├── templates/            ← Hugo template stubs (copied into new themes)
│   └── exampleSite/          ← demo site content (copied into new themes)
└── scripts/
    ├── scaffold.sh           ← creates a new theme from templates
    └── verify.sh             ← builds exampleSite, fails on WARN/ERROR

Scaffolding by hand

scripts/scaffold.sh <theme-name> <target-dir> [author-name] [git-user] [forge]
#   forge: github (default) | forgejo | both

The forge argument picks the CI workflow. Forgejo and GitHub Actions are close but not interchangeable — runner labels differ, and most Forgejo instances can’t fetch actions from GitHub’s marketplace — so the theme gets the one matching where it’s hosted.

Requirements

• Claude Code (this is a Claude Code skill)

• Hugo extended ≥ 0.146

• Dart Sass — Hugo extended bundles libsass, not Dart Sass, and generated themes default to the latter:

  brew install sass/sass/sass     # macOS
  npm i -g sass                   # anywhere with node
  

  The bundled libsass still works (sassTranspiler = "libsass") but was deprecated in Hugo v0.153 and warns on every build — and verify.sh treats WARN as failure.

• Optional: huashu-design installed in the same project for design direction

• Optional: a WCAG skill such as wcag-accessibility-local, if you want the accessibility audit step

On accessibility

The generated theme ships an accessibility baseline because it costs nothing and needs no decision from you. A full WCAG 2.2 AA audit is offered, not imposed — it has a real cost and a real owner, so the skill suggests it once and takes your answer. If a dedicated accessibility skill is installed, it hands off rather than reimplementing the standard.

License

MIT — see LICENSE.