okf-hugo-site

name	okf-hugo-site
description	Build, preview, troubleshoot, search, and publish HOKF's static Hugo presentation. Use when changing the OKF-to-Hugo adapter, site layouts or assets, Pagefind integration, GitHub Pages workflow, or diagnosing generated-content and deployment failures.

Operate the HOKF Hugo site

Build in dependency order

Install Python and Node dependencies, then validate, generate, render, and index:

python3 -m pip install --only-binary=:all: -r requirements.txt
npm ci --ignore-scripts
python3 tools/okf_validate.py --src okf
python3 tools/okf_hugo_adapter.py --src okf --dst site/content --clean
hugo --source site --destination public --cleanDestinationDir
npm run pagefind

Treat okf/ as canonical. Never hand-edit or commit site/content/; it is disposable shadow content. Do not commit site/public/ or node_modules/.

For a plain local preview, generate content and run:

hugo server --source site

The pages remain usable before Pagefind runs; the search control explains that the index is unavailable. Build and index first when testing search.

Preserve presentation boundaries

Keep templates theme-free and framework-free. Render optional metadata only when present, tolerate unknown types and fields, and read the canonical type from Hugo's native page type. Keep internal URLs base-path aware through the link render hook and Hugo RelPermalink/relURL.

Test project-path behavior with an explicit base URL:

hugo --source site --destination public --cleanDestinationDir \
  --baseURL https://example.github.io/hokf/

Confirm generated links include /hokf/, Pagefind indexes titles, descriptions, tags, and body text, and navigation is excluded where marked.

Diagnose by stage

• Validation failure: fix canonical YAML or reserved-document structure.
• Generation failure: inspect safe YAML parsing and source/destination paths.
• Missing or stale page: regenerate with --clean.
• Template failure: check optional values before dereferencing nested metadata.
• Broken project-path link: use the render hook or Hugo URL functions, not a domain-root literal.
• Empty search: rebuild Hugo, run npm run pagefind, and confirm site/public/pagefind/pagefind-ui.js exists.
• CI or deploy failure: compare local commands with .github/workflows/pages.yml; keep tool versions and the lockfile pinned.

Publishing occurs only through the successful default-branch build and the separate least-privilege GitHub Pages deploy job.