# Hugo - Drafts and PaperMod Upkeep Hugo site failures around drafts, scheduled posts, and frontmatter are predictable and locally verifiable before push. Each failure has a cheap mechanical check. Build drafts and future posts explicitly, flip draft flags and inbound links in the same push, and predict the Netlify build with a local `yq` parse. ## Key points - `hugo --buildDrafts --buildFuture` verifies that draft and future-dated posts build clean before pushing a scheduled series. - A published talk page that links a series page plus nine `draft: true` posts is a broken production build waiting. Without `--buildDrafts`, the build emits only the talk page. The Related block then holds dead links. Flip the draft flags and the inbound links from published pages in the same push. - A folded block scalar such as `description: >` with its continuation line at column 0 is invalid frontmatter and fails the Netlify deploy. `yq` uses the same `go-yaml` parser as Hugo, so a local `yq` parse predicts the site build. A control `hugo` run exits 0 after a two-space indent, which confirms the fix mechanically. - PaperMod author metadata defined via `params.author` in config is a `maps.Params` value. A layout partial must type-assert the value or use `.Get` instead of direct string interpolation. - PaperMod submodule drift shows as a `+` prefix in `git submodule status`. The checked-out commit differs from the pinned SHA. Header layout regressions after a theme upgrade usually come from CSS class renames in the theme's `layouts/partials/header.html`. - `hugo --minify` strips the quotes from every `href` attribute in the built site. A verification grep for `href="..."` therefore never matches. Verify links against the source markdown, or use a quoteless pattern. Confirm the served path first. A `features.md` page served at `/docs/<repo>/features/` needs `../custom-trace/#anchor` for a sibling anchor. A `./custom-trace/` link points to the wrong path. ## How to apply 1. Build a scheduled series locally: `hugo --buildDrafts --buildFuture`. Zero errors means the drafts and the future-dated posts build clean. 2. Publish drafts in one push: remove `draft: true` from each post and update the links from published pages in the same commit. 3. Predict the Netlify deploy with a local `yq` parse of the page frontmatter. The `yq` parser matches the Hugo parser, so a local failure predicts the deploy failure. 4. Indent folded block scalars: put the continuation line of `description: >` at a two-space indent. Column 0 breaks the frontmatter. 5. Check theme drift: `git submodule status`. A `+` prefix means the checked-out theme commit differs from the pinned SHA. After a theme upgrade, inspect the header partial for renamed CSS classes. 6. Read author metadata in a PaperMod layout partial: use `.Get` or a type assertion on the `maps.Params` value. 7. Verify links: grep the source markdown, or grep the minified output with a quoteless `href` pattern. Confirm the served path first. ## Observations - [static-site] `hugo --buildDrafts --buildFuture` verifies scheduled content before a push. #hugo (source: agent sessions, 2026-08) - [frontmatter] A folded block scalar needs a two-space indent for its continuation line. Column 0 fails the deploy. #yaml (source: agent sessions, 2026-08) - [static-site] Draft flags and inbound links from published pages must flip in the same push. #hugo (source: agent sessions, 2026-10) - [verification] Minify strips quotes from every `href` attribute. Verify links against the source markdown or with a quoteless pattern. #hugo (source: agent sessions, 2026-10) ## Relations - relates_to [[resources/documentation/Marp - Themes, Export, and Deck QA]] (both pipelines generate output from frontmatter-heavy markdown and verify it locally before publish) - relates_to [[resources/documentation/Git Configuration]] (theme drift and pinned submodules are git state) ## Sources Personal agent-session notes, February 2026 to October 2026