---

name: hugo-template-guidance description: Use whenever you need to understand how this theme works — adding pages, managing content, configuring the site, using partials/components/modules, project architecture, scripts, or styling/theming (Tailwind v4, Bootstrap 5, or a hybrid — verify which). Use for ANY question about the structure, usage, or customization of the template or theme.

Template Guidance

Handbook for this theme (Hugo Extended + Hugo Modules; styling is Tailwind v4, Bootstrap 5, or a hybrid — verify before assuming), assuming the standard project-setup layout (site at root, theme vendored in themes/<theme>/ — the single folder under themes/; see references/detect-mode.md to find its name). Progressive disclosure: read the matching references/ file before acting.

If exampleSite/hugo.toml exists, the repo is still in theme-setup — run <pm> project-setup first (see references/detect-mode.md) before using anything below.

Package manager: <pm> is a placeholder for this project's package manager. Detect it from a lock file (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lock/bun.lockb) or package.json's packageManager field before running any command below — don't assume pnpm. Details: references/script-usage.md.

Routing Guide

Request	Read
Detect or convert setup mode (theme-setup vs project-setup)	references/detect-mode.md
pre-flight checks (Node, Hugo version, package manager)	references/preflight-checks.md
Architecture, folder layout, data flow	references/project-architecture.md
Add a page, route, or homepage section	references/adding-new-pages.md
Partials, components, shortcodes, Hugo Modules	references/component-usage.md
Add, remove, or enable a Hugo Module (module.toml)	references/hugo-modules.md
Markdown content, frontmatter, taxonomies	references/content-management.md
Add/configure a new language, multilingual, i18n, translate	references/i18n-guidance.md
Site config, menus, social, feature toggles, SEO	references/page-configuration.md
Package manager detection, scripts, generators, module updates	references/script-usage.md
Styling/theming (Tailwind v4, Bootstrap 5, or hybrid — verify first), dark mode, design tokens	references/styling-and-theming.md

Steps

1. Read the matching reference.
2. Follow it.