IMPORTANT: Developer documentation for the current development branch. This content is unreleased, may change without notice, and must not be treated as Buildish release documentation.

Website Development Documentation

Unreleased contributor documentation for rendering and maintaining the Buildish website.

The Website component consumes the reusable site-pipeline staging package from the sibling buildish-site-pipeline repository and then renders the staged contract with Hugo + Docsy.

This unreleased development documentation keeps only Buildish-specific consumer notes. Canonical generic pipeline documentation lives under the dedicated site-pipeline component.

Buildish-owned concerns

Buildish owns the parts that are specific to this consumer site:

  • Hugo + Docsy as the renderer and theme stack
  • site/Makefile as the main developer entrypoint
  • the Buildish-derived builder image layered on top of the generic site-pipeline base image
  • renderer-specific navigation, shortcodes, styling, and publication behavior
  • final search, indexing, and publishing policy for the public Buildish site

Authoring helpers

Buildish-specific Hugo shortcodes and partials are documented separately:

Common workflows

From site/:

  • make serve / make serve-local — live restaging plus Hugo preview
  • make build / make build-local — fresh staged and rendered site output
  • make render / make render-local — rerun Hugo against the current stage root
  • make stage / make stage-local — refresh only site/.stage/ and site/.preview/
  • make check — run clean, tests, and build-local

Host-tool workflows expect uv, Hugo extended, and Node via nvm using .nvmrc.

Containerized Buildish workflow

Buildish keeps a pinned consumer-specific build image so contributors can work without installing the full local toolchain.

  • the generic site-pipeline base image lives in the sibling repository
  • Buildish layers its own renderer tooling on top in ../tools/site-build-image/
  • site/Makefile remains the main entrypoint for both containerized and native workflows

The main generated paths remain:

  • site/.stage/
  • site/.preview/
  • site/.public/

Canonical Site Pipeline docs

For pipeline behavior, workspace semantics, and the reusable component contract, use the site-pipeline docs:

Buildish-specific notes

The interactive workflow intentionally keeps Hugo focused on staged sources. make serve and make serve-local keep site/.stage/ current while Hugo runs without regenerating every derived output on each change.

The current development-only limitations are consumer-facing rather than pipeline-contract issues. For example, route removals can linger briefly in an already-running Hugo session until the server is restarted.

Hugo Helpers

Buildish-specific Hugo shortcodes and partials used by page authors and site maintainers.

Buildish Threat Model

Project: Buildish.