Hugo Site Build Lifecycle

Hugo builds a site from configuration, mounted files, content metadata, templates, and resources. File placement is part of the data model because it determines page kind, bundle boundaries, and template lookup.

Select the Build Configuration #

The hugo command performs a production build and writes to public/ unless --destination changes the target. hugo server serves a development build and watches its dependencies:

hugo --environment production
hugo server --environment development

The environment defaults differ: hugo uses production, while hugo server uses development. --environment or HUGO_ENVIRONMENT selects an explicit environment. A project can use one configuration file such as hugo.toml, a comma-separated --config list, or layered files under config/_default/ and config/<environment>/. Later and more specific settings override earlier ones, so build diagnostics should record the command and environment rather than only the repository revision.

Module mounts are resolved before content collection. A mount can combine several source directories into the virtual content, assets, static, or layouts trees; inspecting only the physical content/ directory can therefore miss build inputs.

Classify Pages, Sections, Taxonomies, and Resources #

Hugo derives page kinds from filenames and directory structure:

• content/_index.md supplies content and metadata for the home page.
• A section directory can contain _index.md, which creates a branch bundle for that section.
• A directory containing index.md is a leaf bundle. Markdown files below it are page resources rather than independent pages.
• Other content files become regular pages within their containing section.
• Configured taxonomies generate taxonomy and term pages from front matter.

A branch bundle can contain child pages and sections. A leaf bundle represents one page plus its resources, such as images, data, or generated files:

content/
  posts/
    _index.md
    canvas/
      index.md
      diagram.svg

The page at posts/canvas/ can resolve diagram.svg through .Page.Resources. Files under static/ follow a different path: Hugo copies them to the destination without exposing them as processable page or global resources.

Construct Pages from Front Matter and Cascades #

Front matter supplies fields such as title, date, draft, outputs, layout, type, taxonomies, and custom parameters. Hugo combines those values with defaults inferred from the path, language, site configuration, and Git metadata.

A cascade in site configuration or a branch bundle’s _index.md provides front matter defaults to descendants:

cascade:
  type: docs
  params:
    audience: developers

Descendant front matter can override cascaded values. Cascades may also use target selectors for a path, page kind, environment, or language. Because the resulting page object reflects every applicable layer, a surprising .Type or .Params value should be traced through both the content file and its ancestor cascades.

Hugo also associates translations, aliases, page resources, taxonomy terms, and section ancestry during page construction. Templates consume the completed page graph rather than parsing files independently.

Transform Content and Render Outputs #

The conceptual build path is:

1. Load configuration, modules, data, translations, templates, and mounted files.
2. Build the page and resource graph, including sections and taxonomies.
3. Parse content, expand shortcodes, and invoke Markdown render hooks.
4. Render each enabled output format through the matching template.
5. Process requested assets and publish rendered and static files.

Template evaluation can request content or asset transformations lazily, so these phases are dependencies rather than a promise about internal goroutine order. A shortcode runs while .Content is produced; the surrounding page template then places that result in an HTML, RSS, JSON, or other output.

Output formats are configured per site and page kind. A page can emit several files from the same content:

outputs:
  home:
    - HTML
    - RSS
    - JSON

Template lookup considers the page kind, type, section, layout, language, and output format. A format-specific template such as an HTML single-page layout does not automatically serve an RSS output. Run Hugo with template metrics or warnings when diagnosing an unexpected fallback instead of assuming one hard-coded filename.

Account for Caches and Development Builds #

Hugo caches downloaded modules, remote resources, and processed assets. Asset fingerprints make valid cached results reusable, while template or source changes invalidate their dependents. Generated files under resources/_gen/ can be committed or restored in CI when a project deliberately uses that cache, but they are derived artifacts rather than source content.

hugo server keeps the dependency graph in memory, watches for changes, and uses fast render behavior to rebuild the pages needed for interactive development. It normally serves from memory instead of reproducing the exact files in public/. Use --disableFastRender when a complete development re-render is needed, and --renderToDisk only when inspecting server output on disk.

A clean production build remains the release check because development caches and incremental rendering can hide an undeclared dependency:

hugo --gc --cleanDestinationDir --environment production

--cleanDestinationDir removes files in the destination that Hugo does not produce in the current build, while --gc removes unused cache entries. Neither option repairs incorrect content classification or template lookup; those follow from the project structure and configuration.