Skip to content
Docs
Docs site

Docs site

The site/ folder is a Hugo site using the Hextra theme. It turns the repo’s docs, learning docs, roadmap plan, phase files, diagrams and journals into one browsable site with a landing page and search. The code is not part of the site, so the GitHub repo stays private while the site can be public.

Where content comes from

Nothing is copied into site/. site/hugo.toml mounts the existing folders, so each file keeps one source.

Site sectionSourceNotes
/docs/docs/Includes docs/learning/. docs/learning/README.md is left out because the site lists lessons itself.
/plan/plans/260922-0123-hango-agent-harness-roadmap/plan.md is the section page. Only phase-*.md files are mounted, so plan.html and its generator stay out.
/diagrams/*.svgplans/260922-0123-hango-agent-harness-roadmap/diagrams/Shown on /docs/diagrams/.
/journal/plans/journals/Written by ak journal create.
/, section pagessite/content/Landing page and the _index.md file of each section.

Writing content for the site

  • Start every doc with YAML front matter holding title and weight. The weight sets the sidebar order. A learning doc uses its phase number, so docs/learning/01-foundation-and-observability-spine.md has weight: 1.
  • Keep the # Title line below the front matter for markdown lint and plain reading. site/layouts/_markup/render-heading.html hides an H1 that repeats the page title.
  • Phase files carry weight equal to phase.
  • Link between files with relative .md paths. Hugo rewrites links to pages it knows.

Preview locally 

brew install hugo   # needs Hugo extended 0.146 or later, plus Go for Hugo modules
cd site
hugo server         # http://localhost:1313

Deploy to Cloudflare Pages

Build from the private repo with the Cloudflare Git integration, which works on the free plan:

  1. In the Cloudflare dashboard, open Workers & Pages, create a Pages project, and connect the GitHub repo.
  2. Set the root directory to site, the build command to hugo --gc --minify, and the output directory to public.
  3. Add environment variables HUGO_VERSION=0.168.0 and GO_VERSION=1.27.2. Go is needed to fetch the theme module.
  4. Every push to main deploys. Other branches get preview URLs.

To deploy without the Git integration, build locally and upload the output:

cd site
hugo --gc --minify
npx wrangler pages deploy public --project-name hango

The site is live at hango.phi.me, a custom domain on the hango Pages project. A proxied CNAME from hango to hango-9ju.pages.dev in the phi.me zone points it there. Update baseURL in site/hugo.toml if the domain changes. To limit who can read the site later, put Cloudflare Access in front of it. The free Zero Trust plan covers up to 50 users.

Diagrams