Building the Documentation Site

The site uses Nanosite's standard sitegen.BuildWith publication pipeline. The configuration in site/config.json controls Markdown sources, defaults, front matter, record indexes, navigation, paging and search; use the installed Nanosite skill as the field-by-field authoring reference. HFF's standard_driver supplies the landing page, Playground integration and theme adapter. Site-specific styles and browser assets are published from site/public/. Source Markdown remains unchanged during publication.

The website's public URL is hff.ornew.net.

Netlify deployment

The repository's netlify.toml builds the site with sh site/build.sh and publishes site/dist/. It pins Go 1.27.1, compatible with the generator's Go module. Browser scripts and styles are served locally; the configuration includes a Content Security Policy and response headers.

Connect the repository to Netlify, use main as the production branch, and configure hff.ornew.net as the custom domain with its required DNS records. Once configured, commits pushed to that branch trigger deployment. The domain is documented here ahead of the first publication; a local build does not configure Netlify or verify a production deployment.

Build and preview

Use Go 1.27.1, from the repository root:

sh site/build.sh
sh site/build.sh -serve localhost:8080

The wrapper uses the repository's pinned Nanosite revision and configuration. The second command builds, then serves the generated site. Stop it with Ctrl-C. The server does not watch source files: after editing Markdown, stop the server, rerun the command to rebuild and serve, then reload the page in the browser.

The output defaults to site/dist/. It is generated and ignored by Git. Open site/dist/index.html directly or serve the directory with any static server. Nanosite resolves links and assets for configured subpath hosting. Build commands do not publish the site or provision hosting.

To select a different output directory:

sh site/build.sh -out /tmp/hff-site

The generator refuses source directories and unrelated nonempty directories. A directory generated by HFF contains .hff-site; a subsequent build replaces that output, including old pages. Do not store hand-written files in generated output directories.

Generated Design Records introduction

The entire docs/design/README.md is generated from the numbered records; do not edit it directly. Each record must have a level-one heading and adjacent metadata lines in this form:

# 015. Record title

- **Status**: Proposed
- **Author**: @ornew
- **Date**: 2026-10-12

The generator uses the heading and those three metadata values for the Record, Status, Date, and Author columns. It excludes 000-template.md and preserves the introduction text from the generated index template. After changing a record, regenerate the checked-in introduction from the repository root:

sh hack/generate-design-index.sh

hack/check.sh runs the same generator and verifies that docs/design/README.md has no uncommitted differences. To check that artifact alone, run:

git -c core.fsmonitor=false diff --exit-code -- docs/design/README.md

Generated Go API reference

The site generates the package pages under /docs/reference/go/ from the build-selected Go source and examples listed in site/go_reference.go. Public Go documentation comments are the source of truth; do not hand-author generated package or symbol pages. When adding or removing a public package, update referencePackages and the Go-reference navigation/fixture coverage, then run the site tests and build to verify the generated pages and links.

Rendering and link checks

The site includes a README-derived landing page, top navigation, and a sidebar ordered Overview, Tutorials, Guides, Cookbook, Backends, Reference, Specification, Design Records, and Development. Backends groups local and PostgreSQL pages in expandable subsections. Section introductions appear first, and adjacent-page links stay within the current section. Design Records and Development use collapsible groups. Small screens use a modal navigation drawer instead of a horizontally scrolling menu. Color mode cycles between system, light, and dark, storing the choice locally. Dark mode uses neutral near-black surfaces with green accents. Markdown tables and fenced code blocks are rendered directly. Source Markdown is the single authoring surface; generated HTML must not be edited.

Search runs locally over a generated search-index.js, including page text and headings, with no remote service. Open it with the search button, /, or Ctrl/Cmd-K. Arrow keys move between results, Enter opens a result, and Escape closes the dialog. Search, theme controls, and the drawer use browser JavaScript; the documentation itself remains static HTML. The script-based index also works when HTML files are opened directly.

Repository Markdown links are rewritten to published routes. Before writing output, the shared pipeline rejects missing internal pages and heading fragments. External URLs are preserved; their remote availability is not checked. HFF-specific public assets are served from site/public/; generated design-index source remains maintained by hack/generate-design-index.sh, while the published design index is generated from the configured record source. Raw Markdown HTML remains disabled by configuration.

Verification

From site/:

go test ./...
go vet ./...

Build the actual documentation as well as running tests. Tests cover link rewriting and fragments, stale-output removal, refusing unrelated output directories, section grouping and order, section-local paging, and local redirects for moved documentation pages. Redirect aliases are not included in search. Build failures preserve existing output when source links are invalid.