---
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.