# gohugoio/hugo architecture

> Architecture diagram of the GitHub repository gohugoio/hugo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gohugoio/hugo
- Repository: https://github.com/gohugoio/hugo

## Overview

#### Purpose and executable surface
Hugo is a Go static-site generator: it turns project content, templates, assets, configuration, themes/modules, and data into published static files. The executable begins at `main.go`, initializes CLI behavior through `commands/commands.go`, and dispatches build/server/deploy/module/content-creation commands under `commands/`.

#### Command and dependency bootstrap
The command layer converts flags, environment, and working-directory inputs into a configured build. `commands/commandeer.go` is the application coordinator; `commands/hugobuilder.go` creates build execution; `deps/deps.go` assembles shared services and providers. This is the boundary between user-facing CLI/server operations and reusable site-generation internals.

#### Configuration, modules, and unified filesystem
Configuration is loaded, decoded, merged, and environment-aware through `config/allconfig/load.go`, `config/allconfig/allconfig.go`, and `config/configLoader.go`. Hugo Modules resolve and collect reusable themes/content/assets/configuration in `modules/client.go` and `modules/collect.go`. Their mounts feed the layered project filesystem in `hugofs/rootmapping_fs.go`, `hugofs/component_fs.go`, and `hugolib/filesystems/basefs.go`, insulating the build from whether inputs originate locally, in themes, or modules.

#### Site model and build orchestration
`hugolib` is the core domain and orchestration layer. `hugolib/hugo_sites.go` represents one or more sites/languages; `hugolib/hugo_sites_build.go` drives builds; `hugolib/site.go` and `hugolib/page.go` expose site/page behavior. Content discovery and assembly flow through `hugolib/content_map.go`, `hugolib/content_map_page_assembler.go`, and the document-tree structures in `hugolib/doctree/`. This stage derives pages, sections, bundles, taxonomies, navigation, URLs, and output variants before rendering.

#### Parsing and markup transformation
Source files cross a parsing boundary before becoming page content. Front matter and content syntax are handled by `parser/frontmatter.go` and `parser/pageparser/pageparser.go`; the markup abstraction is `markup/converter/converter.go`. Goldmark is the primary Markdown path in `markup/goldmark/convert.go`, including render hooks and table-of-contents handling. Alternate external markup adapters exist under `markup/asciidocext/`, `markup/pandoc/`, and `markup/rst/`.

#### Template rendering and publishing
Templates execute against the page/site/resource model using Hugo’s template implementation: `tpl/tplimpl/templates.go`, `tpl/tplimpl/templatestore.go`, and function registration in `tpl/tplimpl/template_funcs.go`. Project templates override embedded defaults in `tpl/tplimpl/embedded/templates/`. Rendered output crosses into publishing through `hugolib/site_render.go` and `publisher/publisher.go`, which writes final files and applies output-level transforms such as URL and generator metadata injection.

#### Resource/asset pipeline and caching
Resources are modeled and cached by `resources/resource_spec.go`, `resources/resource_cache.go`, and `resources/resource_factories/`. Transform chains include JS/CSS processing, minification, integrity hashing, template execution, and Sass adapters under `resources/resource_transformers/`; JS builds use `internal/js/esbuild/build.go`. Image processing resides in `resources/images/image.go` and `resources/images/process.go`, with WebAssembly-backed WebP/AVIF/KaTeX support in `internal/warpc/`. File and HTTP caches are material performance boundaries in `cache/filecache/` and `cache/httpcache/`.

#### Development and deployment runtimes
`hugo server` combines rebuild orchestration with filesystem notifications from `watcher/` and browser updates from `livereload/livereload.go`. Hugo is primarily a Go CLI/runtime; optional extended builds require CGO/C compiler support for LibSass. The `withdeploy` build tag enables direct publishing through `deploy/deploy.go` to AWS S3/CloudFront (`deploy/cloudfront.go`), Google Cloud Storage (`deploy/google.go`), and Azure Blob Storage (`deploy/deploy_azure.go`). Container execution is supported by `Dockerfile` and `scripts/docker/entrypoint.sh`.

Main entry points: [`hugolib/content_map.go`](https://github.com/gohugoio/hugo/blob/master/hugolib/content_map.go) (Content assembly), [`commands/commandeer.go`](https://github.com/gohugoio/hugo/blob/master/commands/commandeer.go) (Application coordinator), [`commands/hugobuilder.go`](https://github.com/gohugoio/hugo/blob/master/commands/hugobuilder.go) (Build executor), [`resources/resource_spec.go`](https://github.com/gohugoio/hugo/blob/master/resources/resource_spec.go) (Resource pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI &amp; bootstrap"]
  node_main(("Hugo executable<br/>Go entrypoint<br/>[main.go]"))
  node_commands["Command surface<br/>Cobra commands<br/>[commands.go]"]
  node_commandeer["Application coordinator<br/>command bootstrap<br/>[commandeer.go]"]
  node_builder["Build executor<br/>build setup<br/>[hugobuilder.go]"]
  node_dependencies["Shared dependencies<br/>service assembly<br/>[deps.go]"]
end

subgraph group_inputs["Inputs &amp; filesystem"]
  node_config["Configuration loader<br/>config merge<br/>[load.go]"]
  node_modules["Modules &amp; themes<br/>module resolver<br/>[client.go]"]
  node_filesystems["Layered project filesystem<br/>virtual filesystem<br/>[rootmapping_fs.go]"]
end

subgraph group_core["Site build"]
  node_sites["Site model<br/>multi-site domain<br/>[hugo_sites.go]"]
  node_build["Build orchestration<br/>site build"]
  node_content["Content assembly<br/>content map<br/>[content_map.go]"]
  node_parser["Content parser<br/>front matter &amp; syntax<br/>[frontmatter.go]"]
end

subgraph group_render["Rendering &amp; assets"]
  node_markup["Markup conversion<br/>converter abstraction<br/>[converter.go]"]
  node_goldmark["Markdown renderer<br/>Goldmark converter<br/>[convert.go]"]
  node_templates["Template engine<br/>template store &amp; functions<br/>[templates.go]"]
  node_resources["Resource pipeline<br/>asset transforms<br/>[resource_spec.go]"]
  node_esbuild["JavaScript builds<br/>esbuild adapter<br/>[build.go]"]
  node_publish["Static publisher<br/>output writer<br/>[publisher.go]"]
end

subgraph group_runtime["Development &amp; delivery"]
  node_caches[("File &amp; HTTP caches<br/>performance cache")]
  node_server["Development server<br/>watch &amp; live reload"]
  node_deploy["Deployment providers<br/>tagged deploy runtime<br/>[deploy.go]"]
  node_container["Container entrypoint<br/>Docker runtime"]
end

node_main -->|"initializes"| node_commands
node_commands -->|"dispatches"| node_commandeer
node_commandeer -->|"configures"| node_builder
node_commandeer -->|"loads"| node_config
node_builder -->|"assembles"| node_dependencies
node_config -->|"configures"| node_modules
node_modules -->|"mounts inputs"| node_filesystems
node_dependencies -->|"provides"| node_filesystems
node_builder -->|"creates"| node_sites
node_sites -->|"builds"| node_build
node_filesystems -->|"supplies content"| node_content
node_build -->|"assembles"| node_content
node_content -->|"parses sources"| node_parser
node_parser -->|"converts body"| node_markup
node_markup -->|"Markdown path"| node_goldmark
node_content -->|"page model"| node_templates
node_goldmark -->|"rendered content"| node_templates
node_resources -->|"builds JS"| node_esbuild
node_templates -->|"rendered outputs"| node_publish
node_resources -->|"processed assets"| node_publish
node_caches -.->|"caches transforms"| node_resources
node_server -->|"triggers rebuilds"| node_build
node_publish -->|"publishes output"| node_deploy
node_container -->|"runs"| node_main

click node_main "https://github.com/gohugoio/hugo/blob/master/main.go"
click node_commands "https://github.com/gohugoio/hugo/blob/master/commands/commands.go"
click node_commandeer "https://github.com/gohugoio/hugo/blob/master/commands/commandeer.go"
click node_builder "https://github.com/gohugoio/hugo/blob/master/commands/hugobuilder.go"
click node_dependencies "https://github.com/gohugoio/hugo/blob/master/deps/deps.go"
click node_config "https://github.com/gohugoio/hugo/blob/master/config/allconfig/load.go"
click node_modules "https://github.com/gohugoio/hugo/blob/master/modules/client.go"
click node_filesystems "https://github.com/gohugoio/hugo/blob/master/hugofs/rootmapping_fs.go"
click node_sites "https://github.com/gohugoio/hugo/blob/master/hugolib/hugo_sites.go"
click node_build "https://github.com/gohugoio/hugo/blob/master/hugolib/hugo_sites_build.go"
click node_content "https://github.com/gohugoio/hugo/blob/master/hugolib/content_map.go"
click node_parser "https://github.com/gohugoio/hugo/blob/master/parser/frontmatter.go"
click node_markup "https://github.com/gohugoio/hugo/blob/master/markup/converter/converter.go"
click node_goldmark "https://github.com/gohugoio/hugo/blob/master/markup/goldmark/convert.go"
click node_templates "https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/templates.go"
click node_resources "https://github.com/gohugoio/hugo/blob/master/resources/resource_spec.go"
click node_esbuild "https://github.com/gohugoio/hugo/blob/master/internal/js/esbuild/build.go"
click node_publish "https://github.com/gohugoio/hugo/blob/master/publisher/publisher.go"
click node_deploy "https://github.com/gohugoio/hugo/blob/master/deploy/deploy.go"
click node_container "https://github.com/gohugoio/hugo/blob/master/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_commands,node_commandeer,node_builder,node_dependencies toneBlue
class node_config,node_modules,node_filesystems toneAmber
class node_sites,node_build,node_content,node_parser toneMint
class node_markup,node_goldmark,node_templates,node_resources,node_esbuild,node_publish toneRose
class node_caches,node_server,node_deploy,node_container toneIndigo
```

## Components

### CLI & bootstrap

- [Hugo executable](https://github.com/gohugoio/hugo/blob/master/main.go): Go entrypoint · `main.go`
- [Command surface](https://github.com/gohugoio/hugo/blob/master/commands/commands.go): Cobra commands · `commands/commands.go`
- [Application coordinator](https://github.com/gohugoio/hugo/blob/master/commands/commandeer.go): command bootstrap · `commands/commandeer.go`
- [Build executor](https://github.com/gohugoio/hugo/blob/master/commands/hugobuilder.go): build setup · `commands/hugobuilder.go`
- [Shared dependencies](https://github.com/gohugoio/hugo/blob/master/deps/deps.go): service assembly · `deps/deps.go`

### Inputs & filesystem

- [Configuration loader](https://github.com/gohugoio/hugo/blob/master/config/allconfig/load.go): config merge · Loads decoded, merged, environment-aware configuration. · `config/allconfig/load.go`
- [Modules & themes](https://github.com/gohugoio/hugo/blob/master/modules/client.go): module resolver · `modules/client.go`
- [Layered project filesystem](https://github.com/gohugoio/hugo/blob/master/hugofs/rootmapping_fs.go): virtual filesystem · Presents local, theme, and module inputs as unified components. · `hugofs/rootmapping_fs.go`

### Site build

- [Site model](https://github.com/gohugoio/hugo/blob/master/hugolib/hugo_sites.go): multi-site domain · Owns sites and language variants. · `hugolib/hugo_sites.go`
- [Build orchestration](https://github.com/gohugoio/hugo/blob/master/hugolib/hugo_sites_build.go): site build · `hugolib/hugo_sites_build.go`
- [Content assembly](https://github.com/gohugoio/hugo/blob/master/hugolib/content_map.go): content map · Derives pages, sections, bundles, taxonomies, navigation, and URLs. · `hugolib/content_map.go`
- [Content parser](https://github.com/gohugoio/hugo/blob/master/parser/frontmatter.go): front matter & syntax · `parser/frontmatter.go`

### Rendering & assets

- [Markup conversion](https://github.com/gohugoio/hugo/blob/master/markup/converter/converter.go): converter abstraction · Selects Markdown and alternate markup adapters. · `markup/converter/converter.go`
- [Markdown renderer](https://github.com/gohugoio/hugo/blob/master/markup/goldmark/convert.go): Goldmark converter · Handles render hooks and table of contents. · `markup/goldmark/convert.go`
- [Template engine](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/templates.go): template store & functions · Project templates override embedded defaults. · `tpl/tplimpl/templates.go`
- [Resource pipeline](https://github.com/gohugoio/hugo/blob/master/resources/resource_spec.go): asset transforms · Caches and transforms JS, CSS, images, and generated resources. · `resources/resource_spec.go`
- [JavaScript builds](https://github.com/gohugoio/hugo/blob/master/internal/js/esbuild/build.go): esbuild adapter · `internal/js/esbuild/build.go`
- [Static publisher](https://github.com/gohugoio/hugo/blob/master/publisher/publisher.go): output writer · Writes files and applies output-level transforms. · `publisher/publisher.go`

### Development & delivery

- **File & HTTP caches**: performance cache
- **Development server**: watch & live reload · Rebuilds on filesystem changes and updates browsers.
- [Deployment providers](https://github.com/gohugoio/hugo/blob/master/deploy/deploy.go): tagged deploy runtime · Enabled by the withdeploy build tag for cloud publishing. · `deploy/deploy.go`
- [Container entrypoint](https://github.com/gohugoio/hugo/blob/master/Dockerfile): Docker runtime · `Dockerfile`

## Connections

- Hugo executable → Command surface: initializes
- Command surface → Application coordinator: dispatches
- Application coordinator → Build executor: configures
- Application coordinator → Configuration loader: loads
- Build executor → Shared dependencies: assembles
- Configuration loader → Modules & themes: configures
- Modules & themes → Layered project filesystem: mounts inputs
- Shared dependencies → Layered project filesystem: provides
- Build executor → Site model: creates
- Site model → Build orchestration: builds
- Layered project filesystem → Content assembly: supplies content
- Build orchestration → Content assembly: assembles
- Content assembly → Content parser: parses sources
- Content parser → Markup conversion: converts body
- Markup conversion → Markdown renderer: Markdown path
- Content assembly → Template engine: page model
- Markdown renderer → Template engine: rendered content
- Resource pipeline → JavaScript builds: builds JS
- Template engine → Static publisher: rendered outputs
- Resource pipeline → Static publisher: processed assets
- File & HTTP caches → Resource pipeline: caches transforms
- Development server → Build orchestration: triggers rebuilds
- Static publisher → Deployment providers: publishes output
- Container entrypoint → Hugo executable: runs
