mirror of
https://github.com/zeon-studio/hugoplate.git
synced 2026-09-10 07:06:19 -04:00
chore: support generic package manager and tighten checks in Agents
This commit is contained in:
Rubel Hossain
parent
fa59cb0197
commit
efeff9b865
|
|
@ -7,22 +7,25 @@ description: Use whenever you need to understand how this theme works — adding
|
|||
|
||||
Handbook for this theme (Hugo Extended + Tailwind v4 + Hugo Modules), 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 `pnpm project-setup` first (see `references/detect-mode.md`) before using anything below.
|
||||
> 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` |
|
||||
| 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` |
|
||||
| pnpm/Node scripts, generators, module updates | `references/script-usage.md` |
|
||||
| Tailwind v4, dark mode, design tokens (`data/theme.json`) | `references/styling-and-theming.md` |
|
||||
| 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` |
|
||||
| Tailwind v4, dark mode, design tokens (`data/theme.json`) | `references/styling-and-theming.md` |
|
||||
|
||||
## Steps
|
||||
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ There are three distinct things you'll be asked for — pick the matching recipe
|
|||
Hugo's union filesystem makes root take precedence over the theme for the **same relative path**. This is the standard Hugo way to customize a theme without forking it, and it's how this theme stays upgradeable:
|
||||
|
||||
- **New templates, template overrides, new sections, new partials/components** → create them under root `layouts/` at the same relative path the theme would use (e.g. `layouts/about.html`, `layouts/_partials/components/my-card.html`).
|
||||
- **Never create or edit files directly under `themes/<theme>/layouts/`** — those are vendored and reset/overwritten on theme updates (`pnpm update:theme` etc.).
|
||||
- **Never create or edit files directly under `themes/<theme>/layouts/`** — those are vendored and reset/overwritten on theme updates (`<pm> update-theme` etc.).
|
||||
- To override an existing theme template/partial, copy it from `themes/<theme>/layouts/...` to the identical path under root `layouts/...`, then edit the copy.
|
||||
- To add something brand new (a new partial, a new template, a new shortcode), just create it under root `layouts/...` directly — no theme copy needed.
|
||||
|
||||
|
|
|
|||
|
|
@ -16,15 +16,15 @@ If all of the following are true:
|
|||
- `exampleSite/hugo.toml` is the active Hugo config
|
||||
- `themes/<theme>/layouts/home.html` does **not** exist
|
||||
|
||||
then treat the repository as **theme-setup**, not **project-setup**. So Before running `pnpm project-setup` or `pnpm dev` ask user if they want to delete the `themes/` directory and run `pnpm project-setup` to convert to project-setup, deleting `themes/` is required otherwise when running `pnpm project-setup`, it will detect current mode as `project-setup` which is false.
|
||||
then treat the repository as **theme-setup**, not **project-setup**. So Before running `<pm> project-setup` or `<pm> dev` ask user if they want to delete the `themes/` directory and run `<pm> project-setup` to convert to project-setup, deleting `themes/` is required otherwise when running `<pm> project-setup`, it will detect current mode as `project-setup` which is false.
|
||||
|
||||
## Always work in `project-setup` mode
|
||||
|
||||
If the repo or project is currently in theme-setup, run `pnpm project-setup` **before** editing or reading any content, config, layout, or style file — this is non-negotiable.
|
||||
If the repo or project is currently in theme-setup, run `<pm> project-setup` **before** editing or reading any content, config, layout, or style file — this is non-negotiable.
|
||||
|
||||
- **Idempotent** — logs "Project already setup" and no-ops if already converted, so it's always safe to run.
|
||||
- **Never move files between modes by hand** — only `pnpm project-setup` / `pnpm theme-setup` (reverse) do this correctly.
|
||||
- `dev:example` / `build:example` / `preview:example` scripts exist only for theme-setup (run against `exampleSite/`). Once converted via `pnpm project-setup`, they no longer apply — don't reach for them as a shortcut to avoid converting.
|
||||
- **Never move files between modes by hand** — only `<pm> project-setup` / `<pm> theme-setup` (reverse) do this correctly.
|
||||
- `dev:example` / `build:example` / `preview:example` scripts exist only for theme-setup (run against `exampleSite/`). Once converted via `<pm> project-setup`, they no longer apply — don't reach for them as a shortcut to avoid converting.
|
||||
|
||||
## After conversion
|
||||
|
||||
|
|
|
|||
|
|
@ -13,23 +13,23 @@ Hugo Modules (`https://github.com/gethugothemes/hugo-modules`) provide most non-
|
|||
|
||||
Module names are paths under `github.com/gethugothemes/hugo-modules/` (e.g. `search`, `pwa`, `icons/themify-icons`, `seo-tools/plausible-analytics`, `components/crisp-chat`).
|
||||
|
||||
2. Run `pnpm update-modules` to fetch the module and rewrite `go.mod`/`go.sum`.
|
||||
3. Restart the dev server (`npx kill-port 1313 -y && pnpm dev`).
|
||||
2. Run `<pm> update-modules` to fetch the module and rewrite `go.mod`/`go.sum`.
|
||||
3. Restart the dev server (`npx kill-port 1313 -y && <pm> dev`).
|
||||
4. Use the partials/shortcodes/config the module adds — check the module's source (URL is the `path` value) for its partial names, shortcode names, and any `params`/`config` block it expects in `config/_default/params.toml` or similar and what kind of data it expects accoding to its docs (e.g. `images` module's `image` partial expects a dict with `Src`, `Alt`, `Loading`, `Class`, and `DisplayXL` keys).
|
||||
|
||||
## Disable or delete a module
|
||||
|
||||
1. Delete or comment out its `[[imports]]` block in `config/_default/module.toml`.
|
||||
2. Remove anything in the site that depends on it — `partial`/`partialCached` calls, shortcodes used in content, and any related config block (e.g. `[search]` in `params.toml`). Leaving these in place causes build errors ("partial not found") once the module is gone.
|
||||
3. Run `pnpm update-modules`.
|
||||
3. Run `<pm> update-modules`.
|
||||
4. Restart the dev server.
|
||||
|
||||
## Currently available but disabled (commented out in `module.toml`)
|
||||
|
||||
`icons/themify-icons`, `components/valine-comment`, `components/crisp-chat`, `seo-tools/baidu-analytics`, `seo-tools/matomo-analytics`, `seo-tools/plausible-analytics`, `seo-tools/counter-analytics` — uncomment + `pnpm update-modules` to enable.
|
||||
`icons/themify-icons`, `components/valine-comment`, `components/crisp-chat`, `seo-tools/baidu-analytics`, `seo-tools/matomo-analytics`, `seo-tools/plausible-analytics`, `seo-tools/counter-analytics` — uncomment + `<pm> update-modules` to enable.
|
||||
|
||||
## DO NOT
|
||||
|
||||
- Hand-edit `go.mod` / `go.sum` — they're regenerated by `pnpm update-modules`.
|
||||
- Hand-edit `go.mod` / `go.sum` — they're regenerated by `<pm> update-modules`.
|
||||
- Edit a module's files under the Go module cache or `themes/<theme>/` — modules are read-only dependencies; override their partials via root `layouts/_partials/` instead (see `references/component-usage.md`).
|
||||
- Remove an `[[imports]]` block while partials/shortcodes from that module are still referenced — fix or remove those usages first.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ Multilingual via Hugo's standard system. Mirrors an existing language (`en`) —
|
|||
| Menu | `config/_default/menus.<xx>.toml` |
|
||||
| i18n strings | `i18n/<xx>.yaml` |
|
||||
| Content | `content/<langdir>/` |
|
||||
| Build/verify | `pnpm dev` / `pnpm build` |
|
||||
| Build/verify | `<pm> dev` / `<pm> build` |
|
||||
|
||||
## Adding New Language Checklist
|
||||
|
||||
|
|
@ -32,9 +32,9 @@ Multilingual via Hugo's standard system. Mirrors an existing language (`en`) —
|
|||
|
||||
## Verify
|
||||
|
||||
Build with `pnpm build` — **never bare `hugo`**
|
||||
Build with `<pm> build` — **never bare `hugo`**
|
||||
|
||||
## DO NOT
|
||||
|
||||
- Don't translate paths/filenames in `content/<langdir>/` — Hugo matches translations by identical relative path.
|
||||
- Don't run `pnpm remove-multilang` to "reset" — it's destructive and permanent.
|
||||
- Don't run `<pm> remove-multilang` to "reset" — it's destructive and permanent.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,16 @@
|
|||
# Pre-flight Checks
|
||||
|
||||
**Even for a plain "run/build/preview the project" request**, verify all of these first — before `<pm> install` / `<pm> dev` / `<pm> build` / `<pm> preview`:
|
||||
|
||||
1. **Setup mode** — project-setup; if not, run `<pm> project-setup` first (see `references/detect-mode.md`).
|
||||
2. **Node** — `node -v` succeeds.
|
||||
3. **Hugo Extended, version matches the project's pin** — if `netlify.toml` exists, read `[build.environment].HUGO_VERSION` and require `hugo version` to report `extended` AND that **exact** version (not just `>=`). No pin found → require `extended` and a reasonably recent version.
|
||||
4. **Package manager** — detect `<pm>` (see `references/script-usage.md`); confirm `<pm> -v` succeeds.
|
||||
|
||||
## If any check fails
|
||||
|
||||
**Stop and ask the user to install/upgrade — don't work around it.** Recommend [mise](https://mise.jdx.dev/):
|
||||
|
||||
- Install mise if missing (see mise's install docs for the OS).
|
||||
- `mise use hugo-extended@<version>` — pin the exact extended Hugo build (use `HUGO_VERSION` from `netlify.toml` if present).
|
||||
- `mise use node@lts` and `mise use <pm>@latest` (or the user's existing version manager).
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
This theme = **Hugo Extended (0.158+)** + **Tailwind v4** + **Hugo Modules**.
|
||||
|
||||
This reference assumes the **project-setup** layout: site files at root, theme vendored in `themes/<theme>/`. If `exampleSite/hugo.toml` exists instead, run `pnpm project-setup` first (see `references/detect-mode.md`).
|
||||
This reference assumes the **project-setup** layout: site files at root, theme vendored in `themes/<theme>/`. If `exampleSite/hugo.toml` exists instead, run `<pm> project-setup` first (see `references/detect-mode.md`).
|
||||
|
||||
## Folder Structure
|
||||
|
||||
|
|
@ -47,7 +47,7 @@ Much functionality (search, SEO, images, PWA, shortcodes, announcement…) comes
|
|||
|
||||
## Build Pipeline
|
||||
|
||||
`pnpm dev` / `pnpm build` →
|
||||
`<pm> dev` / `<pm> build` →
|
||||
|
||||
1. `themeGenerator.js` reads `data/theme.json` → writes `themes/<theme>/assets/css/generated-theme.css` (`--watch` in dev).
|
||||
2. Hugo build; `[build.buildStats]` writes `hugo_stats.json` which Tailwind scans (`@source "hugo_stats.json"`) for class detection.
|
||||
|
|
|
|||
|
|
@ -1,14 +1,35 @@
|
|||
# Script Usage
|
||||
|
||||
Package manager is **`pnpm`**. This reference assumes project-setup (see `references/detect-mode.md` for the one-time `pnpm project-setup` conversion).
|
||||
This reference assumes project-setup (see `references/detect-mode.md` for the one-time project-setup conversion).
|
||||
|
||||
## Package Manager
|
||||
|
||||
**Detect before running anything — don't assume `pnpm`.**
|
||||
|
||||
1. `package.json` → `"packageManager"` field (e.g. `"pnpm@9.x"`), if present — authoritative.
|
||||
2. Otherwise, check the project root for a lock file:
|
||||
|
||||
| Lock file | Package manager |
|
||||
| ------------------------ | --------------- |
|
||||
| `pnpm-lock.yaml` | `pnpm` |
|
||||
| `package-lock.json` | `npm` |
|
||||
| `yarn.lock` | `yarn` |
|
||||
| `bun.lock` / `bun.lockb` | `bun` |
|
||||
|
||||
3. No lock file (deps not installed yet) → default to `yarn`.
|
||||
|
||||
Everything below uses `<pm>` for whatever you detected. Run syntax differs:
|
||||
|
||||
- `pnpm` / `yarn` / `bun`: `<pm> <script>` (e.g. `pnpm dev`, `yarn dev`, `bun dev`)
|
||||
- `npm`: `npm run <script>` — npm requires `run` for custom scripts
|
||||
|
||||
## Dev & Build
|
||||
|
||||
| Command | Does |
|
||||
| ---------------- | ----------------------------------------------------------- |
|
||||
| `pnpm dev` | `themeGenerator.js --watch` + `hugo server` concurrently |
|
||||
| `pnpm build` | `themeGenerator.js` then `hugo --gc --minify` |
|
||||
| `pnpm preview` | production-flavored local server |
|
||||
| Command | Does |
|
||||
| -------------- | -------------------------------------------------------- |
|
||||
| `<pm> dev` | `themeGenerator.js --watch` + `hugo server` concurrently |
|
||||
| `<pm> build` | `themeGenerator.js` then `hugo --gc --minify` |
|
||||
| `<pm> preview` | production-flavored local server |
|
||||
|
||||
**Never run bare `hugo server`** — it skips `themeGenerator.js`, leaving `generated-theme.css` stale and colors/fonts broken.
|
||||
|
||||
|
|
@ -16,21 +37,17 @@ Package manager is **`pnpm`**. This reference assumes project-setup (see `refere
|
|||
|
||||
| Command | Does |
|
||||
| ----------------------- | -------------------------------------------------------------------- |
|
||||
| `pnpm update-modules` | `clearModules.js` + `hugo mod clean --all` / `get -u ./...` / `tidy` |
|
||||
| `pnpm update-theme` | pull latest theme updates from upstream |
|
||||
| `pnpm remove-darkmode` | **permanently** strips dark mode, then `pnpm format` |
|
||||
| `pnpm remove-multilang` | **permanently** strips multilingual scaffolding |
|
||||
| `pnpm format` | Prettier (Go-template + Tailwind plugins) |
|
||||
| `<pm> update-modules` | `clearModules.js` + `hugo mod clean --all` / `get -u ./...` / `tidy` |
|
||||
| `<pm> update-theme` | pull latest theme updates from upstream |
|
||||
| `<pm> remove-darkmode` | **permanently** strips dark mode, then `<pm> format` |
|
||||
| `<pm> remove-multilang` | **permanently** strips multilingual scaffolding |
|
||||
| `<pm> format` | Prettier (Go-template + Tailwind plugins) |
|
||||
|
||||
`remove-*` are destructive and not cleanly reversible — confirm + commit first.
|
||||
|
||||
## `scripts/`
|
||||
|
||||
`themeGenerator.js` (theme.json → generated-theme.css, `--watch`; never bypass) · `projectSetup.js`/`themeSetup.js` (mode switches, see `references/detect-mode.md`) · `themeUpdate.js` · `clearModules.js` · `removeDarkmode.js`/`removeMultilang.js`.
|
||||
|
||||
## DO NOT
|
||||
|
||||
- Run `hugo server` directly — use `pnpm dev`.
|
||||
- Run `hugo server` directly — use `<pm> dev`.
|
||||
- Hand-edit `generated-theme.css` / `hugo_stats.json` — edit `data/theme.json`, let the generator run.
|
||||
- Move files between modes manually — use `pnpm project-setup` / `pnpm theme-setup`.
|
||||
- Move files between modes manually — use `<pm> project-setup` / `<pm> theme-setup`.
|
||||
- Run `remove-darkmode`/`remove-multilang` casually — they rewrite source permanently.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
## Tokens (`data/theme.json`)
|
||||
|
||||
Colors, fonts, type scale live here. **Read it before editing** (schema may be customized). `scripts/themeGenerator.js` reads it → writes `generated-theme.css` (a Tailwind `@theme` block); runs automatically in `pnpm dev`/`build`.
|
||||
Colors, fonts, type scale live here. **Read it before editing** (schema may be customized). `scripts/themeGenerator.js` reads it → writes `generated-theme.css` (a Tailwind `@theme` block); runs automatically in `<pm> dev`/`build`.
|
||||
|
||||
```json
|
||||
"colors": {
|
||||
|
|
@ -20,7 +20,7 @@ Colors, fonts, type scale live here. **Read it before editing** (schema may be c
|
|||
- Colors → utilities: `default` → `--color-primary` → `text-primary`, `bg-body`; `darkmode` → `--color-darkmode-*` → use via `dark:` (`dark:bg-darkmode-body`).
|
||||
- Fonts: Google syntax `Family:wght@weights`, `_type` = fallback. `base`→`--text-base` (px); `scale`→ heading sizes `--text-h1…h6`. Stray spaces/bad weights break the font request.
|
||||
|
||||
**Change flow:** edit `data/theme.json` → `pnpm dev` (generator watches) → verify in browser.
|
||||
**Change flow:** edit `data/theme.json` → `<pm> dev` (generator watches) → verify in browser.
|
||||
|
||||
## Tailwind v4 (`themes/<theme>/assets/css/main.css`)
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ CSS files (in `themes/<theme>/assets/css/`): `generated-theme.css` (**DO NOT EDI
|
|||
|
||||
## Dark Mode
|
||||
|
||||
`.dark` on `<html>` activates `darkmode` tokens via the `dark:` variant. Toggle/default in `params.toml` (`theme_switcher`, `theme_default`). Remove entirely with `pnpm remove-darkmode`.
|
||||
`.dark` on `<html>` activates `darkmode` tokens via the `dark:` variant. Toggle/default in `params.toml` (`theme_switcher`, `theme_default`). Remove entirely with `<pm> remove-darkmode`.
|
||||
|
||||
## DO NOT
|
||||
|
||||
|
|
|
|||
48
AGENTS.md
48
AGENTS.md
|
|
@ -9,6 +9,18 @@ Treat <https://gohugo.io/documentation/> as truth. Two project specifics your tr
|
|||
|
||||
<!-- END:hugo-agent-rules -->
|
||||
|
||||
<!-- BEGIN:package-manager-rules -->
|
||||
|
||||
# Detect the package manager — don't assume pnpm
|
||||
|
||||
Commands below use `<pm>` as a placeholder for this project's package manager:
|
||||
|
||||
1. `package.json` → `"packageManager"` field, if present — authoritative.
|
||||
2. Otherwise, a lock file in the project root: `pnpm-lock.yaml` → `pnpm`, `package-lock.json` → `npm`, `yarn.lock` → `yarn`, `bun.lock`/`bun.lockb` → `bun`.
|
||||
3. No lock file yet (deps not installed) → default to **yarn**.
|
||||
|
||||
<!-- END:package-manager-rules -->
|
||||
|
||||
<!-- BEGIN:setup-mode-detection-rules -->
|
||||
|
||||
# Detect setup mode, then convert to project-setup FIRST before changing or reading anything, after project-setup check the edge case rules
|
||||
|
|
@ -27,9 +39,9 @@ If all of the following are true:
|
|||
- `exampleSite/hugo.toml` is the active Hugo config
|
||||
- `themes/<theme>/layouts/home.html` does **not** exist
|
||||
|
||||
then treat the repository as **theme-setup**, not **project-setup**. So Before running `pnpm project-setup` or `pnpm dev` ask user if they want to delete the `themes/` directory and run `pnpm project-setup` to convert to project-setup, deleting `themes/` is required otherwise when running `pnpm project-setup`, it will detect current mode as `project-setup` which is false.
|
||||
then treat the repository as **theme-setup**, not **project-setup**. So Before running `<pm> project-setup` or `<pm> dev` ask user if they want to delete the `themes/` directory and run `<pm> project-setup` to convert to project-setup, deleting `themes/` is required otherwise when running `<pm> project-setup`, it will detect current mode as `project-setup` which is false.
|
||||
|
||||
**Always work in project-setup.** If the repo is currently in theme-setup, run `pnpm project-setup` BEFORE editing any content, config, layout, or style file — this is non-negotiable. The script is idempotent (it logs "Project already setup" and no-ops if already converted), so it's always safe to run. Never move files between modes by hand — only `pnpm project-setup` / `pnpm theme-setup` (reverse).
|
||||
**Always work in project-setup.** If the repo is currently in theme-setup, run `<pm> project-setup` BEFORE editing any content, config, layout, or style file — this is non-negotiable. The script is idempotent (it logs "Project already setup" and no-ops if already converted), so it's always safe to run. Never move files between modes by hand — only `<pm> project-setup` / `<pm> theme-setup` (reverse).
|
||||
|
||||
Full detail and path-resolution table: `template-guidance` skill → `references/detect-mode.md`.
|
||||
|
||||
|
|
@ -37,20 +49,20 @@ Full detail and path-resolution table: `template-guidance` skill → `references
|
|||
|
||||
<!-- BEGIN:preflight-checks-rules -->
|
||||
|
||||
# Pre-flight checks before running, starting or reading the project
|
||||
# Pre-flight checks before running, starting or reading the project in **project-setup**
|
||||
|
||||
Before `pnpm install` / `pnpm dev` / `pnpm build` / `pnpm preview` (or any other request to run/build/preview the project), verify all of:
|
||||
Before `<pm> install` / `<pm> dev` / `<pm> build` / `<pm> preview` (or any other request to run/build/preview the project), verify all of:
|
||||
|
||||
1. **Setup mode** — project-setup (see above); run `pnpm project-setup` first if not.
|
||||
1. **Setup mode** — project-setup (see above); run `<pm> project-setup` first if not.
|
||||
2. **Node** — `node -v` succeeds.
|
||||
3. **Hugo Extended ≥ 0.158.0** — run `hugo version`; output must contain `extended` and a version `>= 0.158.0`
|
||||
4. **pnpm** — `pnpm -v` succeeds.
|
||||
3. **Hugo Extended, version == `HUGO_VERSION` in `netlify.toml`** — read `[build.environment].HUGO_VERSION` from `netlify.toml`; run `hugo version` and confirm output contains `extended` AND the version matches **exactly** (not just `>=`).
|
||||
4. **Package manager (`<pm>`)** — see package-manager detection above; confirm `<pm> -v` succeeds.
|
||||
|
||||
If any check fails — tool missing, Hugo not the extended build, or Hugo older than 0.158.0 — **stop and ask the user to install/upgrade it**; don't try to work around it. Recommend [mise](https://mise.jdx.dev/):
|
||||
If any check fails — tool missing, Hugo not the extended build, or Hugo version doesn't match `HUGO_VERSION` from `netlify.toml` — **stop and ask the user to install/upgrade it**; don't try to work around it. Recommend [mise](https://mise.jdx.dev/):
|
||||
|
||||
- Install mise if missing (see mise's install docs for the OS).
|
||||
- `mise use hugo-extended@0.161.1` — installs and pins the correct extended Hugo build for this project.
|
||||
- Node/pnpm: `mise use node@lts` and `mise use pnpm@latest` (or the user's existing version manager).
|
||||
- Version mismatch (wrong version or not extended) → `mise use hugo-extended@<HUGO_VERSION>` using the value from `netlify.toml` (currently `mise use hugo-extended@0.160.0`) — installs and pins the exact build this project requires.
|
||||
- Node and package manager: `mise use node@lts` and `mise use <pm>@latest` (or the user's existing version manager).
|
||||
|
||||
<!-- END:preflight-checks-rules -->
|
||||
|
||||
|
|
@ -58,25 +70,25 @@ If any check fails — tool missing, Hugo not the extended build, or Hugo older
|
|||
|
||||
# Running the project
|
||||
|
||||
**Even for a plain "run/build/preview the project" request**: run the pre-flight checks above first. If the repo is in theme-setup, run `pnpm project-setup` first, then use the project-setup commands below — don't reach for the `:example` scripts as a shortcut to avoid converting.
|
||||
**Even for a plain "run/build/preview the project" request**: run the pre-flight checks above first. If the repo is in theme-setup, run `<pm> project-setup` first, then use the project-setup commands below — don't reach for the `:example` scripts as a shortcut to avoid converting.
|
||||
|
||||
Package manager is **pnpm**. Always use these scripts — never run bare `hugo`/`hugo server`, since that skips `themeGenerator.js` and leaves `generated-theme.css` (Tailwind tokens) stale.
|
||||
Package manager is `<pm>` (see package-manager detection above). Always use these scripts — never run bare `hugo`/`hugo server`.
|
||||
|
||||
| Command | Use |
|
||||
| -------------- | ----------------------------------------------------------------- |
|
||||
| `pnpm install` | install dependencies (first run / after pulling) |
|
||||
| `pnpm dev` | dev server with live theme regen, default `http://localhost:1313` |
|
||||
| `pnpm build` | production build to `public/` |
|
||||
| `pnpm preview` | production-flavored local server |
|
||||
| `<pm> install` | install dependencies (first run / after pulling) |
|
||||
| `<pm> dev` | dev server with live theme regen, default `http://localhost:1313` |
|
||||
| `<pm> build` | production build to `public/` |
|
||||
| `<pm> preview` | production-flavored local server |
|
||||
|
||||
The `dev:example` / `build:example` / `preview:example` variants exist only for theme-setup (running against `exampleSite/`) — once converted via `pnpm project-setup`, they no longer apply.
|
||||
The `dev:example` / `build:example` / `preview:example` variants exist only for theme-setup (running against `exampleSite/`) — once converted via `<pm> project-setup`, they no longer apply.
|
||||
|
||||
## Restart the dev server after changes
|
||||
|
||||
After changing content, code, or layouts etc., restart it:
|
||||
|
||||
```sh
|
||||
npx kill-port 1313 -y && pnpm dev
|
||||
npx kill-port 1313 -y && <pm> dev
|
||||
```
|
||||
|
||||
<!-- END:running-the-project-rules -->
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
"source": "zeon-studio/template-skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/hugo-template-guidance/SKILL.md",
|
||||
"computedHash": "278bdf77224514cbc13907f45042c3b7c8a369c3b69365f229d08ff79a3c661a"
|
||||
"computedHash": "6f9b02912f034b8c662274b06da77194d4968792aaeade69b45833638dde5c5e"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue