97 lines
3.5 KiB
Markdown
97 lines
3.5 KiB
Markdown
# Hugo static sites in Castle
|
|
|
|
> **This is a stack — creation-time guidance for writing _new_ sites.**
|
|
> A stack is a template + conventions, not a runtime requirement. `castle program
|
|
> create --stack hugo` scaffolds from it (via Hugo's own `hugo new site`) and seeds
|
|
> the program's default build verb. An existing Hugo site adopted with `castle
|
|
> program add` doesn't need this stack — it declares its own `commands:` /
|
|
> `build:`. See @docs/registry.md for `commands:`, `stack:` (optional), and `repo:`.
|
|
|
|
How to build, serve, and manage [Hugo](https://gohugo.io) sites as castle programs.
|
|
|
|
## Stack
|
|
|
|
- Generator: Hugo (extended recommended — needed for SCSS/asset processing)
|
|
- Build: `hugo --gc --minify` → `public/`
|
|
- Served: `manager: caddy` static deployment, in place at `<name>.<gateway.domain>`
|
|
- Package manager (only if a theme needs an asset pipeline): pnpm
|
|
|
|
Hugo has one meaningful dev verb — **build**. It has no native lint/test/type-check,
|
|
so the stack advertises only `build` / `install` / `uninstall`; `castle check` and
|
|
friends aren't offered (a site can still declare its own, e.g. an HTML linter, under
|
|
`commands:` — a declared verb always wins over the stack).
|
|
|
|
## Create a new site
|
|
|
|
```bash
|
|
castle program create my-site --stack hugo --description "My site"
|
|
cd /data/repos/my-site
|
|
castle program build my-site # hugo --gc --minify -> public/
|
|
castle apply my-site # serve at my-site.<gateway.domain>
|
|
```
|
|
|
|
The scaffold delegates the canonical skeleton to `hugo new site` (archetypes/,
|
|
content/, layouts/, static/, themes/, hugo.toml) and overlays the pieces a bare
|
|
skeleton lacks: minimal `layouts/` so the site **builds and serves without a
|
|
theme**, an example `content/posts/hello.md`, a castle-flavored `hugo.toml`
|
|
(`baseURL = "/"`, so assets resolve at the root of the site's own subdomain), and a
|
|
`.gitignore` for the regenerated `public/` and `resources/`.
|
|
|
|
Develop with the live server:
|
|
|
|
```bash
|
|
hugo server -D # http://localhost:1313, rebuilds on save
|
|
```
|
|
|
|
## Adding a theme
|
|
|
|
Drop a theme under `themes/` (usually a git submodule) and set `theme` in
|
|
`hugo.toml`:
|
|
|
|
```bash
|
|
git submodule add https://github.com/<owner>/<theme>.git themes/<theme>
|
|
```
|
|
|
|
Themes with an **asset pipeline** (e.g. Blowfish + Tailwind) need a pre-build step
|
|
before `hugo`. Declare it as a two-step `build` in `programs/<name>.yaml` — a
|
|
declared `build.commands` overrides the stack's single-step default:
|
|
|
|
```yaml
|
|
build:
|
|
commands:
|
|
- [pnpm, build] # compile the theme's CSS/JS
|
|
- [hugo, --gc, --minify] # render the site -> public/
|
|
outputs: [public]
|
|
```
|
|
|
|
One-time setup those themes expect (run once in the source tree):
|
|
|
|
```bash
|
|
git submodule update --init --recursive
|
|
cd themes/<theme> && pnpm install
|
|
```
|
|
|
|
## Deployment shape
|
|
|
|
`castle program create --stack hugo` writes:
|
|
|
|
- **`programs/<name>.yaml`** — `source`, `stack: hugo`, `build.outputs: [public]`.
|
|
- **`deployments/statics/<name>.yaml`** — `manager: caddy`, `root: public`,
|
|
`reach: internal` (flip to `public` to also expose over the tunnel).
|
|
|
|
The gateway serves `<source>/public` in place — no copy, no Node/Hugo process at
|
|
runtime. `castle program build` regenerates `public/`; `castle apply` renders the
|
|
route and reloads the gateway.
|
|
|
|
## Adopting an existing Hugo site
|
|
|
|
No stack needed — adopt the repo and declare how it builds:
|
|
|
|
```bash
|
|
castle program add /path/to/site --name my-site
|
|
```
|
|
|
|
Then set `build.commands` (as above) and add a `manager: caddy` deployment. This is
|
|
how a site with a bespoke build (submodule theme + Tailwind) is wired without the
|
|
scaffold. See @docs/registry.md.
|