This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Rules Hugo

Bazel rules for Hugo sites
  • 1:
  • 2:

rules_hugo builds Hugo sites with a registered Hugo toolchain. It keeps the site archive in the target configuration and the Hugo binary in the execution configuration so site sources are not rebuilt for the execution platform.

al_hugo_site wraps a site source archive and its PostCSS tooling. al_hugo_run_binary builds the site with the registered Hugo toolchain and al_hugo_binary exposes a runnable Hugo command for a site. The optional al_hugo_worker rule runs the build through a persistent worker.

bazel_dep(name = "rules_hugo", version = "<VERSION>")

The Hugo toolchain is generated by the al_hugo_extension module extension, not declared in @rules_hugo//pkg/bzl. Declare the extension in the root module, request the toolchain archives for the Hugo version, and register the generated toolchain repository:

al_hugo_extension = use_extension(
    "@rules_hugo//pkg/bzl:al_hugo_extension.bzl",
    "al_hugo_extension",
)
al_hugo_extension.toolchains(
    name = "my_hugo_toolchain",
    version = "0.165.0",
)
use_repo(
    al_hugo_extension,
    "my_hugo_toolchain_os_linux_cpu_x86_64",
)
register_toolchains("@my_hugo_toolchain_os_linux_cpu_x86_64")

The generated repository name is "<name>_<os>_<cpu>" for each platform in the requested version’s archive set. See projects/alwaldend.com/include.MODULE.bazel for a complete example that also wires the Hugo lock file and remote themes.

1 -

project-dns Specification

Record the retirement of rules_hugo landing infrastructure while preserving its reusable Bazel module.

The module SHALL follow the tools boundary and SHALL have no dedicated landing DNS declarations, Terraform root, or operational source exports.

  • WHEN the module is consumed from tools/rules_hugo
  • THEN its reusable Bazel rules remain available without landing infrastructure.

2 -

Rules Hugo

Build and run Hugo sites with registered Bazel toolchains, site source archives, and declared PostCSS tooling. This source baseline was observed on 2026-09-08 at revision 550d7e79b1f5fdbc2b6017b75178471d6914082f.

Sources: project description, site provider rule, build rule, toolchain extension, and worker rule.

al_hugo_site SHALL retain the .tar site archive in the target configuration and resolve its executable PostCSS dependency in the execution configuration. Build rules SHALL obtain Hugo from the registered Hugo toolchain.

  • WHEN Bazel analyzes a Hugo site build for distinct target and execution platforms
  • THEN the site archive remains a target input and Hugo and PostCSS are selected as execution tools.

al_hugo_run_binary SHALL unpack the site archive, make its PostCSS executable available to Hugo, and invoke Hugo with --destination pointing to the declared output directory.

  • WHEN a caller supplies out_dir and additional Hugo arguments
  • THEN the action appends the declared destination to those arguments and exposes the output directory through DefaultInfo.

The Hugo module extension SHALL create toolchain repositories from the archive set associated with the requested version, carrying each archive’s declared integrity and execution-platform constraints.

  • WHEN a toolchain tag requests that version under a repository name prefix
  • THEN the extension creates the corresponding <name>_os_linux_cpu_x86_64 repository with a Hugo toolchain constrained to that platform.

al_hugo_worker SHALL serialize site inputs, arguments, tools, environment, and output location into a flag file and invoke its worker with Bazel’s protobuf worker protocol requirements.

  • WHEN a site is built with al_hugo_worker
  • THEN Bazel receives a worker-capable HugoSite action whose declared output directory is <target>.dest.