How gohugoio/hugo works
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: content_map.go Content assembly · commandeer.go Application coordinator · hugobuilder.go Build executor · resource_spec.go Resource pipeline
Components 22
CLI & bootstrap
- Hugo executable
main.go - Command surface
commands/commands.go - Application coordinator
commands/commandeer.go - Build executor
commands/hugobuilder.go - Shared dependencies
deps/deps.go
Inputs & filesystem
- Configuration loader · Loads decoded, merged, environment-aware configuration.
config/allconfig/load.go - Modules & themes
modules/client.go - Layered project filesystem · Presents local, theme, and module inputs as unified components.
hugofs/rootmapping_fs.go
Site build
- Site model · Owns sites and language variants.
hugolib/hugo_sites.go - Build orchestration
hugolib/hugo_sites_build.go - Content assembly · Derives pages, sections, bundles, taxonomies, navigation, and URLs.
hugolib/content_map.go - Content parser
parser/frontmatter.go
Rendering & assets
- Markup conversion · Selects Markdown and alternate markup adapters.
markup/converter/converter.go - Markdown renderer · Handles render hooks and table of contents.
markup/goldmark/convert.go - Template engine · Project templates override embedded defaults.
tpl/tplimpl/templates.go - Resource pipeline · Caches and transforms JS, CSS, images, and generated resources.
resources/resource_spec.go - JavaScript builds
internal/js/esbuild/build.go - Static publisher · Writes files and applies output-level transforms.
publisher/publisher.go
Development & delivery
- File & HTTP caches
- Development server · Rebuilds on filesystem changes and updates browsers.
- Deployment providers · Enabled by the withdeploy build tag for cloud publishing.
deploy/deploy.go - Container entrypoint
Dockerfile
Connections 24
- 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