Build without the deploy feature by default

Build tags setup changed to: * !nodeploy => withdeploy * nodeploy => !withdeploy Also move the deploy feature out into its own release archives. See #12994 for the primary motivation for this change. But this also greatly reduces the number of dependencies in Hugo when you don't need this feature and cuts the binary size greatly. Fixes #12994
deps: Upgrade github.com/bep/lazycache v0.6.0 => v0.7.0
2026-08-25 15:58:53 +00:00 · 2024-10-30 10:45:40 +01:00 · 2024-10-27 12:43:36 +01:00 · 2024-10-26 18:27:10 +02:00 · 2024-10-24 12:41:02 +00:00 · 2024-10-24 12:26:27 +00:00
283 changed files with 6601 additions and 3518 deletions
@@ -4,7 +4,7 @@ parameters:
 defaults: &defaults
  resource_class: large
  docker:
-      - image: bepsays/ci-hugoreleaser:1.22200.20501
+      - image: bepsays/ci-hugoreleaser:1.22300.20200
 environment: &buildenv
      GOMODCACHE: /root/project/gomodcache
 version: 2
@@ -14,9 +14,7 @@ jobs:
    environment: &buildenv
        GOMODCACHE: /root/project/gomodcache
    steps:
-      - &remote-docker
-        setup_remote_docker: 
-          version: 20.10.14
+      - setup_remote_docker
      - checkout: 
          path: hugo
      - &git-config
@@ -60,7 +58,7 @@ jobs:
    environment:
        <<: [*buildenv]
    docker:
-    - image: bepsays/ci-hugoreleaser-linux-arm64:1.22200.20501
+    - image: bepsays/ci-hugoreleaser-linux-arm64:1.22300.20200
    steps:
      - *restore-cache
      - &attach-workspace
@@ -1,14 +1,9 @@
 name: Build Docker image

 on:
-  push:
-    tags:
-      - "*"
-    paths:
-      - Dockerfile
-      - .github/workflows/image.yml
-    branches:
-      - master
+  release:
+    types: [published]
+  pull_request:
 permissions:
  packages: write

@@ -18,18 +13,8 @@ env:
 jobs:
  build:
    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        platform:
-          - linux/amd64
-          - linux/arm64
-    steps:
-      - name: Prepare
-        run: |
-          platform=${{ matrix.platform }}
-          echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV

+    steps:
      - name: Checkout
        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7

@@ -39,9 +24,6 @@ jobs:
        with:
          images: ${{ env.REGISTRY_IMAGE }}

-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@49b3bc8e6bdd4a60e6116a5414239cba5943d3cf # v3.2.0
-
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@988b5a0280414f521da01fcc63a27aeeb4b104db # v3.6.1

@@ -53,69 +35,14 @@ jobs:
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}

-      - name: Build and push by digest
+      - name: Build and push
        id: build
        uses: docker/build-push-action@16ebe778df0e7752d2cfcbd924afdbbd89c1a755 # v6.6.1
        with:
          context: .
-          push: ${{ startsWith(github.ref, 'refs/tags') }}
-          platforms: ${{ matrix.platform }}
+          provenance: mode=max
+          sbom: true
+          push: ${{ github.event_name != 'pull_request' }}
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
-          outputs: type=image,name=${{ env.REGISTRY_IMAGE }},push-by-digest=true,name-canonical=true,push=true
-
-      - name: Export digest
-        run: |
-          mkdir -p /tmp/digests
-          digest="${{ steps.build.outputs.digest }}"
-          touch "/tmp/digests/${digest#sha256:}"
-
-      - name: Upload digest
-        uses: actions/upload-artifact@834a144ee995460fba8ed112a2fc961b36a5ec5a # v4.3.6
-        with:
-          name: digests-${{ env.PLATFORM_PAIR }}
-          path: /tmp/digests/*
-          if-no-files-found: error
-          retention-days: 1
-
-  merge:
-    runs-on: ubuntu-latest
-    needs:
-      - build
-    steps:
-      - name: Download digests
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
-        with:
-          path: /tmp/digests
-          pattern: digests-*
-          merge-multiple: true
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@988b5a0280414f521da01fcc63a27aeeb4b104db # v3.6.1
-
-      - name: Docker meta
-        id: meta
-        uses: docker/metadata-action@8e5442c4ef9f78752691e2d8f8d19755c6f78e81 # v5.5.1
-        with:
-          images: ${{ env.REGISTRY_IMAGE }}
-
-          flavor: |
-            latest=false
-
-      - name: Login to GHCR
-        uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.3.0
-        with:
-          registry: ghcr.io
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Create manifest list and push
-        if: ${{ startsWith(github.ref, 'refs/tags') }}
-        working-directory: /tmp/digests
-        run: |
-          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
-            $(printf '${{ env.REGISTRY_IMAGE }}@sha256:%s ' *)
-
-      - name: Inspect image
-        if: ${{ startsWith(github.ref, 'refs/tags') }}
-        run: |
-          docker buildx imagetools inspect ${{ env.REGISTRY_IMAGE }}:${{ steps.meta.outputs.version }}
@@ -16,8 +16,8 @@ jobs:
  test:
    strategy:
      matrix:
-        go-version: [1.21.x, 1.22.x]
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        go-version: [1.22.x, 1.23.x]
+        os: [ubuntu-latest, windows-latest] # macos disabled for now because of disk space issues.
    runs-on: ${{ matrix.os }}
    steps:
      - if: matrix.os == 'ubuntu-latest'
@@ -112,17 +112,17 @@ jobs:
          sass --version;
          mage -v check;
        env:
-          HUGO_BUILD_TAGS: extended
+          HUGO_BUILD_TAGS: extended,withdeploy
      - if: matrix.os == 'windows-latest'
        # See issue #11052. We limit the build to regular test (no -race flag) on Windows for now.
        name: Test
        run: |
          mage -v test;
        env:
-          HUGO_BUILD_TAGS: extended
+          HUGO_BUILD_TAGS: extended,withdeploy
      - name: Build tags
        run: |
-          go install -tags extended,nodeploy
+          go install -tags extended
      - if: matrix.os == 'ubuntu-latest'
        name: Build for dragonfly
        run: |
@@ -1,3 +1,5 @@

 *.test
-imports.*
+imports.*
+dist/
+public/
@@ -2,44 +2,98 @@
 # Twitter:      https://twitter.com/gohugoio
 # Website:      https://gohugo.io/

-FROM golang:1.21-alpine AS build
+ARG GO_VERSION="1.23.2"
+ARG ALPINE_VERSION="3.20"
+ARG DART_SASS_VERSION="1.79.3"

-# Optionally set HUGO_BUILD_TAGS to "extended" or "nodeploy" when building like so:
-#   docker build --build-arg HUGO_BUILD_TAGS=extended .
-ARG HUGO_BUILD_TAGS
+FROM --platform=$BUILDPLATFORM tonistiigi/xx:1.5.0 AS xx
+FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine${ALPINE_VERSION} AS gobuild
+FROM golang:${GO_VERSION}-alpine${ALPINE_VERSION} AS gorun

-ARG CGO=1
-ENV CGO_ENABLED=${CGO}
-ENV GOOS=linux
-ENV GO111MODULE=on
+
+FROM gobuild AS build
+
+RUN apk add clang lld
+
+# Set up cross-compilation helpers
+COPY --from=xx / /
+
+ARG TARGETPLATFORM
+RUN xx-apk add musl-dev gcc g++ 
+
+# Optionally set HUGO_BUILD_TAGS to "none" or "withdeploy" when building like so:
+# docker build --build-arg HUGO_BUILD_TAGS=withdeploy .
+#
+# We build the extended version by default.
+ARG HUGO_BUILD_TAGS="extended"
+ENV CGO_ENABLED=1
+ENV GOPROXY=https://proxy.golang.org
+ENV GOCACHE=/root/.cache/go-build
+ENV GOMODCACHE=/go/pkg/mod
+ARG TARGETPLATFORM

 WORKDIR /go/src/github.com/gohugoio/hugo

-COPY . /go/src/github.com/gohugoio/hugo/
+# For  --mount=type=cache the value of target is the default cache id, so
+# for the go mod cache it would be good if we could share it with other Go images using the same setup,
+# but the go build cache needs to be per platform.
+# See this comment: https://github.com/moby/buildkit/issues/1706#issuecomment-702238282
+RUN --mount=target=. \
+    --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/root/.cache/go-build,id=go-build-$TARGETPLATFORM <<EOT
+    set -ex
+    xx-go build -tags "$HUGO_BUILD_TAGS" -ldflags "-s -w -X github.com/gohugoio/hugo/common/hugo.vendorInfo=docker" -o /usr/bin/hugo
+    xx-verify /usr/bin/hugo
+EOT

-# gcc/g++ are required to build SASS libraries for extended version
-RUN apk update && \
-    apk add --no-cache gcc g++ musl-dev git && \
-    go install github.com/magefile/mage
+# dart-sass downloads the dart-sass runtime dependency
+FROM alpine:${ALPINE_VERSION} AS dart-sass
+ARG TARGETARCH
+ARG DART_SASS_VERSION
+ARG DART_ARCH=${TARGETARCH/amd64/x64}
+WORKDIR /out
+ADD https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-${DART_ARCH}.tar.gz .
+RUN tar -xf dart-sass-${DART_SASS_VERSION}-linux-${DART_ARCH}.tar.gz

-RUN mage hugo && mage install
+FROM gorun AS final

-# ---
+COPY --from=build /usr/bin/hugo /usr/bin/hugo

-FROM alpine:3.18
+# libc6-compat  are required for extended libraries (libsass, libwebp).
+RUN apk add --no-cache \
+    libc6-compat \
+    git \
+    runuser \
+    nodejs \
+    npm

-COPY --from=build /go/bin/hugo /usr/bin/hugo
+RUN mkdir -p /var/hugo/bin /cache && \
+    addgroup -Sg 1000 hugo && \
+    adduser -Sg hugo -u 1000 -h /var/hugo hugo && \
+    chown -R hugo: /var/hugo /cache && \
+    # For the Hugo's Git integration to work.
+    runuser -u hugo -- git config --global --add safe.directory /project && \ 
+    # See https://github.com/gohugoio/hugo/issues/9810
+    runuser -u hugo -- git config --global core.quotepath false

-# libc6-compat & libstdc++ are required for extended SASS libraries
-# ca-certificates are required to fetch outside resources (like Twitter oEmbeds)
-RUN apk update && \
-    apk add --no-cache ca-certificates libc6-compat libstdc++ git
+USER hugo:hugo
+VOLUME /project
+WORKDIR /project
+ENV HUGO_CACHEDIR=/cache
+ENV PATH="/var/hugo/bin:$PATH"

-VOLUME /site
-WORKDIR /site
+COPY scripts/docker/entrypoint.sh /entrypoint.sh
+COPY --from=dart-sass /out/dart-sass /var/hugo/bin/dart-sass
+
+# Update PATH to reflect the new dependencies.
+# For more complex setups, we should probably find a way to
+# delegate this to the script itself, but this will have to do for now.
+# Also, the dart-sass binary is a little special, other binaries can be put/linked
+# directly in /var/hugo/bin.
+ENV PATH="/var/hugo/bin/dart-sass:$PATH"

 # Expose port for live server
 EXPOSE 1313

-ENTRYPOINT ["hugo"]
+ENTRYPOINT ["/entrypoint.sh"]
 CMD ["--help"]
@@ -430,12 +430,25 @@ func (p *Partition[K, V]) doGetOrCreateWitTimeout(key K, duration time.Duration,
 	errch := make(chan error, 1)

 	go func() {
-		v, _, err := p.c.GetOrCreate(key, create)
-		if err != nil {
-			errch <- err
-			return
-		}
-		resultch <- v
+		var (
+			v   V
+			err error
+		)
+		defer func() {
+			if r := recover(); r != nil {
+				if rerr, ok := r.(error); ok {
+					err = rerr
+				} else {
+					err = fmt.Errorf("panic: %v", r)
+				}
+			}
+			if err != nil {
+				errch <- err
+			} else {
+				resultch <- v
+			}
+		}()
+		v, _, err = p.c.GetOrCreate(key, create)
 	}()

 	select {
@@ -14,8 +14,11 @@
 package dynacache

 import (
+	"errors"
+	"fmt"
 	"path/filepath"
 	"testing"
+	"time"

 	qt "github.com/frankban/quicktest"
 	"github.com/gohugoio/hugo/common/loggers"
@@ -165,6 +168,58 @@ func TestClear(t *testing.T) {
 	cache.adjustCurrentMaxSize()
 }

+func TestPanicInCreate(t *testing.T) {
+	t.Parallel()
+	c := qt.New(t)
+	cache := newTestCache(t)
+
+	p1 := GetOrCreatePartition[string, testItem](cache, "/aaaa/bbbb", OptionsPartition{Weight: 30, ClearWhen: ClearOnRebuild})
+
+	willPanic := func(i int) func() {
+		return func() {
+			p1.GetOrCreate(fmt.Sprintf("panic-%d", i), func(key string) (testItem, error) {
+				panic(errors.New(key))
+			})
+		}
+	}
+
+	// GetOrCreateWitTimeout needs to recover from panics in the create func.
+	willErr := func(i int) error {
+		_, err := p1.GetOrCreateWitTimeout(fmt.Sprintf("error-%d", i), 10*time.Second, func(key string) (testItem, error) {
+			return testItem{}, errors.New(key)
+		})
+		return err
+	}
+
+	for i := 0; i < 3; i++ {
+		for j := 0; j < 3; j++ {
+			c.Assert(willPanic(i), qt.PanicMatches, fmt.Sprintf("panic-%d", i))
+			c.Assert(willErr(i), qt.ErrorMatches, fmt.Sprintf("error-%d", i))
+		}
+	}
+
+	// Test the same keys again without the panic.
+	for i := 0; i < 3; i++ {
+		for j := 0; j < 3; j++ {
+			v, err := p1.GetOrCreate(fmt.Sprintf("panic-%d", i), func(key string) (testItem, error) {
+				return testItem{
+					name: key,
+				}, nil
+			})
+			c.Assert(err, qt.IsNil)
+			c.Assert(v.name, qt.Equals, fmt.Sprintf("panic-%d", i))
+
+			v, err = p1.GetOrCreateWitTimeout(fmt.Sprintf("error-%d", i), 10*time.Second, func(key string) (testItem, error) {
+				return testItem{
+					name: key,
+				}, nil
+			})
+			c.Assert(err, qt.IsNil)
+			c.Assert(v.name, qt.Equals, fmt.Sprintf("error-%d", i))
+		}
+	}
+}
+
 func TestAdjustCurrentMaxSize(t *testing.T) {
 	t.Parallel()
 	c := qt.New(t)
@@ -42,6 +42,7 @@ import (
 	"github.com/gohugoio/hugo/common/hugo"
 	"github.com/gohugoio/hugo/common/loggers"
 	"github.com/gohugoio/hugo/common/paths"
+	"github.com/gohugoio/hugo/common/types"
 	"github.com/gohugoio/hugo/config"
 	"github.com/gohugoio/hugo/config/allconfig"
 	"github.com/gohugoio/hugo/deps"
@@ -66,6 +67,12 @@ func Execute(args []string) error {
 	}
 	args = mapLegacyArgs(args)
 	cd, err := x.Execute(context.Background(), args)
+	if cd != nil {
+		if closer, ok := cd.Root.Command.(types.Closer); ok {
+			closer.Close()
+		}
+	}
+
 	if err != nil {
 		if err == errHelp {
 			cd.CobraCommand.Help()
@@ -88,6 +95,11 @@ type commonConfig struct {
 	fs      *hugofs.Fs
 }

+type configKey struct {
+	counter                    int32
+	ignoreModulesDoesNotExists bool
+}
+
 // This is the root command.
 type rootCommand struct {
 	Printf  func(format string, v ...interface{})
@@ -101,8 +113,8 @@ type rootCommand struct {

 	// Some, but not all commands need access to these.
 	// Some needs more than one, so keep them in a small cache.
-	commonConfigs *lazycache.Cache[int32, *commonConfig]
-	hugoSites     *lazycache.Cache[int32, *hugolib.HugoSites]
+	commonConfigs *lazycache.Cache[configKey, *commonConfig]
+	hugoSites     *lazycache.Cache[configKey, *hugolib.HugoSites]

 	// changesFromBuild received from Hugo in watch mode.
 	changesFromBuild chan []identity.Identity
@@ -144,6 +156,18 @@ func (r *rootCommand) isVerbose() bool {
 	return r.logger.Level() <= logg.LevelInfo
 }

+func (r *rootCommand) Close() error {
+	if r.hugoSites != nil {
+		r.hugoSites.DeleteFunc(func(key configKey, value *hugolib.HugoSites) bool {
+			if value != nil {
+				value.Close()
+			}
+			return false
+		})
+	}
+	return nil
+}
+
 func (r *rootCommand) Build(cd *simplecobra.Commandeer, bcfg hugolib.BuildCfg, cfg config.Provider) (*hugolib.HugoSites, error) {
 	h, err := r.Hugo(cfg)
 	if err != nil {
@@ -160,17 +184,18 @@ func (r *rootCommand) Commands() []simplecobra.Commander {
 	return r.commands
 }

-func (r *rootCommand) ConfigFromConfig(key int32, oldConf *commonConfig) (*commonConfig, error) {
-	cc, _, err := r.commonConfigs.GetOrCreate(key, func(key int32) (*commonConfig, error) {
+func (r *rootCommand) ConfigFromConfig(key configKey, oldConf *commonConfig) (*commonConfig, error) {
+	cc, _, err := r.commonConfigs.GetOrCreate(key, func(key configKey) (*commonConfig, error) {
 		fs := oldConf.fs
 		configs, err := allconfig.LoadConfig(
 			allconfig.ConfigSourceDescriptor{
-				Flags:       oldConf.cfg,
-				Fs:          fs.Source,
-				Filename:    r.cfgFile,
-				ConfigDir:   r.cfgDir,
-				Logger:      r.logger,
-				Environment: r.environment,
+				Flags:                    oldConf.cfg,
+				Fs:                       fs.Source,
+				Filename:                 r.cfgFile,
+				ConfigDir:                r.cfgDir,
+				Logger:                   r.logger,
+				Environment:              r.environment,
+				IgnoreModuleDoesNotExist: key.ignoreModulesDoesNotExists,
 			},
 		)
 		if err != nil {
@@ -193,11 +218,11 @@ func (r *rootCommand) ConfigFromConfig(key int32, oldConf *commonConfig) (*commo
 	return cc, err
 }

-func (r *rootCommand) ConfigFromProvider(key int32, cfg config.Provider) (*commonConfig, error) {
+func (r *rootCommand) ConfigFromProvider(key configKey, cfg config.Provider) (*commonConfig, error) {
 	if cfg == nil {
 		panic("cfg must be set")
 	}
-	cc, _, err := r.commonConfigs.GetOrCreate(key, func(key int32) (*commonConfig, error) {
+	cc, _, err := r.commonConfigs.GetOrCreate(key, func(key configKey) (*commonConfig, error) {
 		var dir string
 		if r.source != "" {
 			dir, _ = filepath.Abs(r.source)
@@ -220,12 +245,13 @@ func (r *rootCommand) ConfigFromProvider(key int32, cfg config.Provider) (*commo
 		// Load the config first to allow publishDir to be configured in config file.
 		configs, err := allconfig.LoadConfig(
 			allconfig.ConfigSourceDescriptor{
-				Flags:       cfg,
-				Fs:          hugofs.Os,
-				Filename:    r.cfgFile,
-				ConfigDir:   r.cfgDir,
-				Environment: r.environment,
-				Logger:      r.logger,
+				Flags:                    cfg,
+				Fs:                       hugofs.Os,
+				Filename:                 r.cfgFile,
+				ConfigDir:                r.cfgDir,
+				Environment:              r.environment,
+				Logger:                   r.logger,
+				IgnoreModuleDoesNotExist: key.ignoreModulesDoesNotExists,
 			},
 		)
 		if err != nil {
@@ -307,7 +333,8 @@ func (r *rootCommand) ConfigFromProvider(key int32, cfg config.Provider) (*commo
 }

 func (r *rootCommand) HugFromConfig(conf *commonConfig) (*hugolib.HugoSites, error) {
-	h, _, err := r.hugoSites.GetOrCreate(r.configVersionID.Load(), func(key int32) (*hugolib.HugoSites, error) {
+	k := configKey{counter: r.configVersionID.Load()}
+	h, _, err := r.hugoSites.GetOrCreate(k, func(key configKey) (*hugolib.HugoSites, error) {
 		depsCfg := r.newDepsConfig(conf)
 		return hugolib.NewHugoSites(depsCfg)
 	})
@@ -315,7 +342,12 @@ func (r *rootCommand) HugFromConfig(conf *commonConfig) (*hugolib.HugoSites, err
 }

 func (r *rootCommand) Hugo(cfg config.Provider) (*hugolib.HugoSites, error) {
-	h, _, err := r.hugoSites.GetOrCreate(r.configVersionID.Load(), func(key int32) (*hugolib.HugoSites, error) {
+	return r.getOrCreateHugo(cfg, false)
+}
+
+func (r *rootCommand) getOrCreateHugo(cfg config.Provider, ignoreModuleDoesNotExist bool) (*hugolib.HugoSites, error) {
+	k := configKey{counter: r.configVersionID.Load(), ignoreModulesDoesNotExists: ignoreModuleDoesNotExist}
+	h, _, err := r.hugoSites.GetOrCreate(k, func(key configKey) (*hugolib.HugoSites, error) {
 		conf, err := r.ConfigFromProvider(key, cfg)
 		if err != nil {
 			return nil, err
@@ -418,11 +450,11 @@ func (r *rootCommand) PreRun(cd, runner *simplecobra.Commandeer) error {

 	r.changesFromBuild = make(chan []identity.Identity, 10)

-	r.commonConfigs = lazycache.New(lazycache.Options[int32, *commonConfig]{MaxEntries: 5})
+	r.commonConfigs = lazycache.New(lazycache.Options[configKey, *commonConfig]{MaxEntries: 5})
 	// We don't want to keep stale HugoSites in memory longer than needed.
-	r.hugoSites = lazycache.New(lazycache.Options[int32, *hugolib.HugoSites]{
+	r.hugoSites = lazycache.New(lazycache.Options[configKey, *hugolib.HugoSites]{
 		MaxEntries: 1,
-		OnEvict: func(key int32, value *hugolib.HugoSites) {
+		OnEvict: func(key configKey, value *hugolib.HugoSites) {
 			value.Close()
 			runtime.GC()
 		},
@@ -475,7 +507,7 @@ func (r *rootCommand) createLogger(running bool) (loggers.Logger, error) {
 	return loggers.New(optsLogger), nil
 }

-func (r *rootCommand) Reset() {
+func (r *rootCommand) resetLogs() {
 	r.logger.Reset()
 	loggers.Log().Reset()
 }
@@ -486,16 +518,26 @@ func (r *rootCommand) IsTestRun() bool {
 }

 func (r *rootCommand) Init(cd *simplecobra.Commandeer) error {
+	return r.initRootCommand("", cd)
+}
+
+func (r *rootCommand) initRootCommand(subCommandName string, cd *simplecobra.Commandeer) error {
 	cmd := cd.CobraCommand
-	cmd.Use = "hugo [flags]"
-	cmd.Short = "hugo builds your site"
-	cmd.Long = `hugo is the main command, used to build your Hugo site.
+	commandName := "hugo"
+	if subCommandName != "" {
+		commandName = subCommandName
+	}
+	cmd.Use = fmt.Sprintf("%s [flags]", commandName)
+	cmd.Short = "Build your site"
+	cmd.Long = `COMMAND_NAME is the main command, used to build your Hugo site.

 Hugo is a Fast and Flexible Static Site Generator
 built with love by spf13 and friends in Go.

 Complete documentation is available at https://gohugo.io/.`

+	cmd.Long = strings.ReplaceAll(cmd.Long, "COMMAND_NAME", commandName)
+
 	// Configure persistent flags
 	cmd.PersistentFlags().StringVarP(&r.source, "source", "s", "", "filesystem path to read files relative from")
 	_ = cmd.MarkFlagDirname("source")
@@ -14,6 +14,8 @@
 package commands

 import (
+	"context"
+
 	"github.com/bep/simplecobra"
 )

@@ -21,6 +23,7 @@ import (
 func newExec() (*simplecobra.Exec, error) {
 	rootCmd := &rootCommand{
 		commands: []simplecobra.Commander{
+			newHugoBuildCmd(),
 			newVersionCmd(),
 			newEnvCommand(),
 			newServerCommand(),
@@ -38,3 +41,33 @@ func newExec() (*simplecobra.Exec, error) {

 	return simplecobra.New(rootCmd)
 }
+
+func newHugoBuildCmd() simplecobra.Commander {
+	return &hugoBuildCommand{}
+}
+
+// hugoBuildCommand just delegates to the rootCommand.
+type hugoBuildCommand struct {
+	rootCmd *rootCommand
+}
+
+func (c *hugoBuildCommand) Commands() []simplecobra.Commander {
+	return nil
+}
+
+func (c *hugoBuildCommand) Name() string {
+	return "build"
+}
+
+func (c *hugoBuildCommand) Init(cd *simplecobra.Commandeer) error {
+	c.rootCmd = cd.Root.Command.(*rootCommand)
+	return c.rootCmd.initRootCommand("build", cd)
+}
+
+func (c *hugoBuildCommand) PreRun(cd, runner *simplecobra.Commandeer) error {
+	return c.rootCmd.PreRun(cd, runner)
+}
+
+func (c *hugoBuildCommand) Run(ctx context.Context, cd *simplecobra.Commandeer, args []string) error {
+	return c.rootCmd.Run(ctx, cd, args)
+}
@@ -58,7 +58,7 @@ func (c *configCommand) Name() string {
 }

 func (c *configCommand) Run(ctx context.Context, cd *simplecobra.Commandeer, args []string) error {
-	conf, err := c.r.ConfigFromProvider(c.r.configVersionID.Load(), flagsToCfg(cd, nil))
+	conf, err := c.r.ConfigFromProvider(configKey{counter: c.r.configVersionID.Load()}, flagsToCfg(cd, nil))
 	if err != nil {
 		return err
 	}
@@ -110,8 +110,8 @@ func (c *configCommand) Run(ctx context.Context, cd *simplecobra.Commandeer, arg
 func (c *configCommand) Init(cd *simplecobra.Commandeer) error {
 	c.r = cd.Root.Command.(*rootCommand)
 	cmd := cd.CobraCommand
-	cmd.Short = "Print the site configuration"
-	cmd.Long = `Print the site configuration, both default and custom settings.`
+	cmd.Short = "Display site configuration"
+	cmd.Long = `Display site configuration, both default and custom settings.`
 	cmd.Flags().StringVar(&c.format, "format", "toml", "preferred file format (toml, yaml or json)")
 	_ = cmd.RegisterFlagCompletionFunc("format", cobra.FixedCompletions([]string{"toml", "yaml", "json"}, cobra.ShellCompDirectiveNoFileComp))
 	cmd.Flags().StringVar(&c.lang, "lang", "", "the language to display config for. Defaults to the first language defined.")
@@ -209,7 +209,7 @@ func (c *configMountsCommand) Name() string {

 func (c *configMountsCommand) Run(ctx context.Context, cd *simplecobra.Commandeer, args []string) error {
 	r := c.configCmd.r
-	conf, err := r.ConfigFromProvider(r.configVersionID.Load(), flagsToCfg(cd, nil))
+	conf, err := r.ConfigFromProvider(configKey{counter: c.r.configVersionID.Load()}, flagsToCfg(cd, nil))
 	if err != nil {
 		return err
 	}
@@ -105,8 +105,8 @@ func (c *convertCommand) Run(ctx context.Context, cd *simplecobra.Commandeer, ar

 func (c *convertCommand) Init(cd *simplecobra.Commandeer) error {
 	cmd := cd.CobraCommand
-	cmd.Short = "Convert your content to different formats"
-	cmd.Long = `Convert your content (e.g. front matter) to different formats.
+	cmd.Short = "Convert front matter to another format"
+	cmd.Long = `Convert front matter to another format.

 See convert's subcommands toJSON, toTOML and toYAML for more information.`

@@ -11,21 +11,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.

-//go:build !nodeploy
-// +build !nodeploy
-
-// Copyright 2024 The Hugo Authors. All rights reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
+//go:build withdeploy
+// +build withdeploy

 package commands

@@ -42,8 +29,8 @@ import (
 func newDeployCommand() simplecobra.Commander {
 	return &simpleCommand{
 		name:  "deploy",
-		short: "Deploy your site to a Cloud provider.",
-		long: `Deploy your site to a Cloud provider.
+		short: "Deploy your site to a cloud provider",
+		long: `Deploy your site to a cloud provider

 See https://gohugo.io/hosting-and-deployment/hugo-deploy/ for detailed
 documentation.
@@ -11,8 +11,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.

-//go:build nodeploy
-// +build nodeploy
+//go:build !withdeploy
+// +build !withdeploy

 // Copyright 2024 The Hugo Authors. All rights reserved.
 //
@@ -31,6 +31,7 @@ package commands

 import (
 	"context"
+	"errors"

 	"github.com/bep/simplecobra"
 	"github.com/spf13/cobra"
@@ -40,7 +41,7 @@ func newDeployCommand() simplecobra.Commander {
 	return &simpleCommand{
 		name: "deploy",
 		run: func(ctx context.Context, cd *simplecobra.Commandeer, r *rootCommand, args []string) error {
-			return nil
+			return errors.New("deploy not supported in this version of Hugo; install a release with 'withdeploy' in the archive filename or build yourself with the 'withdeploy' build tag. Also see https://github.com/gohugoio/hugo/pull/12995")
 		},
 		withc: func(cmd *cobra.Command, r *rootCommand) {
 			cmd.Hidden = true
@@ -25,8 +25,8 @@ import (
 func newEnvCommand() simplecobra.Commander {
 	return &simpleCommand{
 		name:  "env",
-		short: "Print Hugo version and environment info",
-		long:  "Print Hugo version and environment info. This is useful in Hugo bug reports",
+		short: "Display version and environment info",
+		long:  "Display version and environment info. This is useful in Hugo bug reports",
 		run: func(ctx context.Context, cd *simplecobra.Commandeer, r *rootCommand, args []string) error {
 			r.Printf("%s\n", hugo.BuildVersionString())
 			r.Printf("GOOS=%q\n", runtime.GOOS)
@@ -61,8 +61,8 @@ func newVersionCmd() simplecobra.Commander {
 			r.Println(hugo.BuildVersionString())
 			return nil
 		},
-		short: "Print Hugo version and environment info",
-		long:  "Print Hugo version and environment info. This is useful in Hugo bug reports.",
+		short: "Display version",
+		long:  "Display version and environment info. This is useful in Hugo bug reports.",
 		withc: func(cmd *cobra.Command, r *rootCommand) {
 			cmd.ValidArgsFunction = cobra.NoFileCompletions
 		},
@@ -273,7 +273,8 @@ func (c *genCommand) Run(ctx context.Context, cd *simplecobra.Commandeer, args [

 func (c *genCommand) Init(cd *simplecobra.Commandeer) error {
 	cmd := cd.CobraCommand
-	cmd.Short = "A collection of several useful generators."
+	cmd.Short = "Generate documentation and syntax highlighting styles"
+	cmd.Long = "Generate documentation for your project using Hugo's documentation engine, including syntax highlighting for various programming languages."

 	cmd.RunE = nil
 	return nil
@@ -27,7 +27,6 @@ import (
 	"sync/atomic"
 	"time"

-	"github.com/bep/logg"
 	"github.com/bep/simplecobra"
 	"github.com/fsnotify/fsnotify"
 	"github.com/gohugoio/hugo/common/herrors"
@@ -136,10 +135,6 @@ func (e *hugoBuilderErrState) wasErr() bool {
 	return e.waserr
 }

-func (c *hugoBuilder) errCount() int {
-	return c.r.logger.LoggCount(logg.LevelError) + loggers.Log().LoggCount(logg.LevelError)
-}
-
 // getDirList provides NewWatcher() with a list of directories to watch for changes.
 func (c *hugoBuilder) getDirList() ([]string, error) {
 	h, err := c.hugo()
@@ -345,7 +340,6 @@ func (c *hugoBuilder) newWatcher(pollIntervalStr string, dirList ...string) (*wa
 		for {
 			select {
 			case changes := <-c.r.changesFromBuild:
-				c.errState.setBuildErr(nil)
 				unlock, err := h.LockBuild()
 				if err != nil {
 					c.r.logger.Errorln("Failed to acquire a build lock: %s", err)
@@ -358,7 +352,7 @@ func (c *hugoBuilder) newWatcher(pollIntervalStr string, dirList ...string) (*wa
 				}
 				if c.s != nil && c.s.doLiveReload {
 					doReload := c.changeDetector == nil || len(c.changeDetector.changed()) > 0
-					doReload = doReload || c.showErrorInBrowser && c.errCount() > 0
+					doReload = doReload || c.showErrorInBrowser && c.errState.buildErr() != nil
 					if doReload {
 						livereload.ForceRefresh()
 					}
@@ -372,7 +366,7 @@ func (c *hugoBuilder) newWatcher(pollIntervalStr string, dirList ...string) (*wa
 					return
 				}
 				c.handleEvents(watcher, staticSyncer, evs, configSet)
-				if c.showErrorInBrowser && c.errCount() > 0 {
+				if c.showErrorInBrowser && c.errState.buildErr() != nil {
 					// Need to reload browser to show the error
 					livereload.ForceRefresh()
 				}
@@ -419,11 +413,17 @@ func (c *hugoBuilder) build() error {
 }

 func (c *hugoBuilder) buildSites(noBuildLock bool) (err error) {
-	h, err := c.hugo()
+	defer func() {
+		c.errState.setBuildErr(err)
+	}()
+
+	var h *hugolib.HugoSites
+	h, err = c.hugo()
 	if err != nil {
-		return err
+		return
 	}
-	return h.Build(hugolib.BuildCfg{NoBuildLock: noBuildLock})
+	err = h.Build(hugolib.BuildCfg{NoBuildLock: noBuildLock})
+	return
 }

 func (c *hugoBuilder) copyStatic() (map[string]uint64, error) {
@@ -619,6 +619,9 @@ func (c *hugoBuilder) fullRebuild(changeType string) {
 			// Set the processing on pause until the state is recovered.
 			c.errState.setPaused(true)
 			c.handleBuildErr(err, "Failed to reload config")
+			if c.s.doLiveReload {
+				livereload.ForceRefresh()
+			}
 		} else {
 			c.errState.setPaused(false)
 		}
@@ -779,6 +782,7 @@ func (c *hugoBuilder) handleEvents(watcher *watcher.Batcher,
 		istemp := strings.HasSuffix(ext, "~") ||
 			(ext == ".swp") || // vim
 			(ext == ".swx") || // vim
+			(ext == ".bck") || // helix
 			(ext == ".tmp") || // generic temp file
 			(ext == ".DS_Store") || // OSX Thumbnail
 			baseName == "4913" || // vim
@@ -1046,7 +1050,7 @@ func (c *hugoBuilder) loadConfig(cd *simplecobra.Commandeer, running bool) error
 		"fastRenderMode": c.fastRenderMode,
 	})

-	conf, err := c.r.ConfigFromProvider(c.r.configVersionID.Load(), flagsToCfg(cd, cfg))
+	conf, err := c.r.ConfigFromProvider(configKey{counter: c.r.configVersionID.Load()}, flagsToCfg(cd, cfg))
 	if err != nil {
 		return err
 	}
@@ -1080,42 +1084,49 @@ func (c *hugoBuilder) printChangeDetected(typ string) {
 	c.r.logger.Println(htime.Now().Format(layout))
 }

-func (c *hugoBuilder) rebuildSites(events []fsnotify.Event) error {
+func (c *hugoBuilder) rebuildSites(events []fsnotify.Event) (err error) {
+	defer func() {
+		c.errState.setBuildErr(err)
+	}()
 	if err := c.errState.buildErr(); err != nil {
 		ferrs := herrors.UnwrapFileErrorsWithErrorContext(err)
 		for _, err := range ferrs {
 			events = append(events, fsnotify.Event{Name: err.Position().Filename, Op: fsnotify.Write})
 		}
 	}
-	c.errState.setBuildErr(nil)
-	h, err := c.hugo()
+	var h *hugolib.HugoSites
+	h, err = c.hugo()
 	if err != nil {
-		return err
+		return
 	}
-
-	return h.Build(hugolib.BuildCfg{NoBuildLock: true, RecentlyVisited: c.visitedURLs, ErrRecovery: c.errState.wasErr()}, events...)
+	err = h.Build(hugolib.BuildCfg{NoBuildLock: true, RecentlyVisited: c.visitedURLs, ErrRecovery: c.errState.wasErr()}, events...)
+	return
 }

-func (c *hugoBuilder) rebuildSitesForChanges(ids []identity.Identity) error {
-	c.errState.setBuildErr(nil)
-	h, err := c.hugo()
+func (c *hugoBuilder) rebuildSitesForChanges(ids []identity.Identity) (err error) {
+	defer func() {
+		c.errState.setBuildErr(err)
+	}()
+
+	var h *hugolib.HugoSites
+	h, err = c.hugo()
 	if err != nil {
-		return err
+		return
 	}
 	whatChanged := &hugolib.WhatChanged{}
 	whatChanged.Add(ids...)
 	err = h.Build(hugolib.BuildCfg{NoBuildLock: true, WhatChanged: whatChanged, RecentlyVisited: c.visitedURLs, ErrRecovery: c.errState.wasErr()})
-	c.errState.setBuildErr(err)
-	return err
+
+	return
 }

 func (c *hugoBuilder) reloadConfig() error {
-	c.r.Reset()
+	c.r.resetLogs()
 	c.r.configVersionID.Add(1)

 	if err := c.withConfE(func(conf *commonConfig) error {
 		oldConf := conf
-		newConf, err := c.r.ConfigFromConfig(c.r.configVersionID.Load(), conf)
+		newConf, err := c.r.ConfigFromConfig(configKey{counter: c.r.configVersionID.Load()}, conf)
 		if err != nil {
 			return err
 		}
@@ -90,8 +90,8 @@ func (c *importCommand) Run(ctx context.Context, cd *simplecobra.Commandeer, arg

 func (c *importCommand) Init(cd *simplecobra.Commandeer) error {
 	cmd := cd.CobraCommand
-	cmd.Short = "Import your site from others."
-	cmd.Long = `Import your site from other web site generators like Jekyll.
+	cmd.Short = "Import a site from another system"
+	cmd.Long = `Import a site from another system.

 Import requires a subcommand, e.g. ` + "`hugo import jekyll jekyll_root_path target_path`."

@@ -199,8 +199,8 @@ func (c *listCommand) Run(ctx context.Context, cd *simplecobra.Commandeer, args

 func (c *listCommand) Init(cd *simplecobra.Commandeer) error {
 	cmd := cd.CobraCommand
-	cmd.Short = "Listing out various types of content"
-	cmd.Long = `Listing out various types of content.
+	cmd.Short = "List content"
+	cmd.Long = `List content.

 List requires a subcommand, e.g. hugo list drafts`

@@ -94,7 +94,7 @@ so this may/will change in future versions of Hugo.
 					applyLocalFlagsBuildConfig(cmd, r)
 				},
 				run: func(ctx context.Context, cd *simplecobra.Commandeer, r *rootCommand, args []string) error {
-					h, err := r.Hugo(flagsToCfg(cd, nil))
+					h, err := r.getOrCreateHugo(flagsToCfg(cd, nil), true)
 					if err != nil {
 						return err
 					}
@@ -102,7 +102,11 @@ so this may/will change in future versions of Hugo.
 					if len(args) >= 1 {
 						initPath = args[0]
 					}
-					return h.Configs.ModulesClient.Init(initPath)
+					c := h.Configs.ModulesClient
+					if err := c.Init(initPath); err != nil {
+						return err
+					}
+					return nil
 				},
 			},
 			&simpleCommand{
@@ -115,7 +119,7 @@ so this may/will change in future versions of Hugo.
 					cmd.Flags().BoolVarP(&clean, "clean", "", false, "delete module cache for dependencies that fail verification")
 				},
 				run: func(ctx context.Context, cd *simplecobra.Commandeer, r *rootCommand, args []string) error {
-					conf, err := r.ConfigFromProvider(r.configVersionID.Load(), flagsToCfg(cd, nil))
+					conf, err := r.ConfigFromProvider(configKey{counter: r.configVersionID.Load()}, flagsToCfg(cd, nil))
 					if err != nil {
 						return err
 					}
@@ -135,7 +139,7 @@ Note that for vendored modules, that is the version listed and not the one from
 					cmd.Flags().BoolVarP(&clean, "clean", "", false, "delete module cache for dependencies that fail verification")
 				},
 				run: func(ctx context.Context, cd *simplecobra.Commandeer, r *rootCommand, args []string) error {
-					conf, err := r.ConfigFromProvider(r.configVersionID.Load(), flagsToCfg(cd, nil))
+					conf, err := r.ConfigFromProvider(configKey{counter: r.configVersionID.Load()}, flagsToCfg(cd, nil))
 					if err != nil {
 						return err
 					}
@@ -271,7 +275,7 @@ Run "go help get" for more information. All flags available for "go get" is also

 								cfg := config.New()
 								cfg.Set("workingDir", dir)
-								conf, err := r.ConfigFromProvider(r.configVersionID.Add(1), flagsToCfg(cd, cfg))
+								conf, err := r.ConfigFromProvider(configKey{counter: r.configVersionID.Add(1)}, flagsToCfg(cd, cfg))
 								if err != nil {
 									return err
 								}
@@ -284,7 +288,7 @@ Run "go help get" for more information. All flags available for "go get" is also
 						})
 						return nil
 					} else {
-						conf, err := r.ConfigFromProvider(r.configVersionID.Load(), flagsToCfg(cd, nil))
+						conf, err := r.ConfigFromProvider(configKey{counter: r.configVersionID.Load()}, flagsToCfg(cd, nil))
 						if err != nil {
 							return err
 						}
@@ -313,7 +317,7 @@ func (c *modCommands) Name() string {
 }

 func (c *modCommands) Run(ctx context.Context, cd *simplecobra.Commandeer, args []string) error {
-	_, err := c.r.ConfigFromProvider(c.r.configVersionID.Load(), nil)
+	_, err := c.r.ConfigFromProvider(configKey{counter: c.r.configVersionID.Load()}, nil)
 	if err != nil {
 		return err
 	}
@@ -324,7 +328,7 @@ func (c *modCommands) Run(ctx context.Context, cd *simplecobra.Commandeer, args

 func (c *modCommands) Init(cd *simplecobra.Commandeer) error {
 	cmd := cd.CobraCommand
-	cmd.Short = "Various Hugo Modules helpers."
+	cmd.Short = "Manage modules"
 	cmd.Long = `Various helpers to help manage the modules in your project's dependency graph.
 Most operations here requires a Go version installed on your system (>= Go 1.12) and the relevant VCS client (typically Git).
 This is not needed if you only operate on modules inside /themes or if you have vendored them via "hugo mod vendor".
@@ -40,7 +40,7 @@ func newNewCommand() *newCommand {
 			&simpleCommand{
 				name:  "content",
 				use:   "content [path]",
-				short: "Create new content for your site",
+				short: "Create new content",
 				long: `Create a new content file and automatically set the date and title.
 It will guess which kind of file to create based on the path provided.

@@ -93,7 +93,7 @@ Use ` + "`hugo new [contentPath]`" + ` to create new content.`,
 					cfg.Set("workingDir", createpath)
 					cfg.Set("publishDir", "public")

-					conf, err := r.ConfigFromProvider(r.configVersionID.Load(), flagsToCfg(cd, cfg))
+					conf, err := r.ConfigFromProvider(configKey{counter: r.configVersionID.Load()}, flagsToCfg(cd, cfg))
 					if err != nil {
 						return err
 					}
@@ -136,7 +136,7 @@ according to your needs.`,
 					cfg := config.New()
 					cfg.Set("publishDir", "public")

-					conf, err := r.ConfigFromProvider(r.configVersionID.Load(), flagsToCfg(cd, cfg))
+					conf, err := r.ConfigFromProvider(configKey{counter: r.configVersionID.Load()}, flagsToCfg(cd, cfg))
 					if err != nil {
 						return err
 					}
@@ -181,7 +181,7 @@ func (c *newCommand) Run(ctx context.Context, cd *simplecobra.Commandeer, args [

 func (c *newCommand) Init(cd *simplecobra.Commandeer) error {
 	cmd := cd.CobraCommand
-	cmd.Short = "Create new content for your site"
+	cmd.Short = "Create new content"
 	cmd.Long = `Create a new content file and automatically set the date and title.
 It will guess which kind of file to create based on the path provided.

@@ -508,7 +508,7 @@ func (c *serverCommand) Run(ctx context.Context, cd *simplecobra.Commandeer, arg

 func (c *serverCommand) Init(cd *simplecobra.Commandeer) error {
 	cmd := cd.CobraCommand
-	cmd.Short = "A high performance webserver"
+	cmd.Short = "Start the embedded web server"
 	cmd.Long = `Hugo provides its own webserver which builds and serves the site.
 While hugo server is high performance, it is a webserver with limited options.

@@ -648,9 +648,8 @@ func (c *serverCommand) setServerInfoInConfig() error {
 }

 func (c *serverCommand) getErrorWithContext() any {
-	errCount := c.errCount()
-
-	if errCount == 0 {
+	buildErr := c.errState.buildErr()
+	if buildErr == nil {
 		return nil
 	}

@@ -659,7 +658,7 @@ func (c *serverCommand) getErrorWithContext() any {
 	m["Error"] = cleanErrorLog(c.r.logger.Errors())

 	m["Version"] = hugo.BuildVersionString()
-	ferrors := herrors.UnwrapFileErrorsWithErrorContext(c.errState.buildErr())
+	ferrors := herrors.UnwrapFileErrorsWithErrorContext(buildErr)
 	m["Files"] = ferrors

 	return m
@@ -830,22 +829,25 @@ func (c *serverCommand) fixURL(baseURLFromConfig, baseURLFromFlag string, port i
 	return u.String(), nil
 }

-func (c *serverCommand) partialReRender(urls ...string) error {
+func (c *serverCommand) partialReRender(urls ...string) (err error) {
 	defer func() {
 		c.errState.setWasErr(false)
 	}()
-	c.errState.setBuildErr(nil)
 	visited := types.NewEvictingStringQueue(len(urls))
 	for _, url := range urls {
 		visited.Add(url)
 	}

-	h, err := c.hugo()
+	var h *hugolib.HugoSites
+	h, err = c.hugo()
 	if err != nil {
-		return err
+		return
 	}
+
 	// Note: We do not set NoBuildLock as the file lock is not acquired at this stage.
-	return h.Build(hugolib.BuildCfg{NoBuildLock: false, RecentlyVisited: visited, PartialReRender: true, ErrRecovery: c.errState.wasErr()})
+	err = h.Build(hugolib.BuildCfg{NoBuildLock: false, RecentlyVisited: visited, PartialReRender: true, ErrRecovery: c.errState.wasErr()})
+
+	return
 }

 func (c *serverCommand) serve() error {
@@ -1012,10 +1014,6 @@ func (c *serverCommand) serve() error {
 		c.r.Println("Error:", err)
 	}

-	if h := c.hugoTry(); h != nil {
-		h.Close()
-	}
-
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
 	wg2, ctx := errgroup.WithContext(ctx)
@@ -137,7 +137,7 @@ var nilPointerErrRe = regexp.MustCompile(`at <(.*)>: error calling (.*?): runtim

 const deferredPrefix = "__hdeferred/"

-var deferredStringToRemove = regexp.MustCompile(`executing "__hdeferred/.*" `)
+var deferredStringToRemove = regexp.MustCompile(`executing "__hdeferred/.*?" `)

 // ImproveRenderErr improves the error message for rendering errors.
 func ImproveRenderErr(inErr error) (outErr error) {
@@ -14,6 +14,7 @@
 package hugo

 import (
+	"context"
 	"fmt"
 	"html/template"
 	"os"
@@ -29,6 +30,7 @@ import (
 	"github.com/mitchellh/mapstructure"

 	"github.com/bep/godartsass/v2"
+	"github.com/gohugoio/hugo/common/hcontext"
 	"github.com/gohugoio/hugo/common/hexec"
 	"github.com/gohugoio/hugo/common/loggers"
 	"github.com/gohugoio/hugo/hugofs/files"
@@ -69,6 +71,9 @@ type HugoInfo struct {

 	conf ConfigProvider
 	deps []*Dependency
+
+	// Context gives access to some of the context scoped variables.
+	Context Context
 }

 // Version returns the current version as a comparable version string.
@@ -127,6 +132,26 @@ func (i HugoInfo) IsMultilingual() bool {
 	return i.conf.IsMultilingual()
 }

+type contextKey string
+
+var markupScope = hcontext.NewContextDispatcher[string](contextKey("markupScope"))
+
+type Context struct{}
+
+func (c Context) MarkupScope(ctx context.Context) string {
+	return GetMarkupScope(ctx)
+}
+
+// SetMarkupScope sets the markup scope in the context.
+func SetMarkupScope(ctx context.Context, s string) context.Context {
+	return markupScope.Set(ctx, s)
+}
+
+// GetMarkupScope gets the markup scope from the context.
+func GetMarkupScope(ctx context.Context) string {
+	return markupScope.Get(ctx)
+}
+
 // ConfigProvider represents the config options that are relevant for HugoInfo.
 type ConfigProvider interface {
 	Environment() string
@@ -276,7 +301,7 @@ func GetDependencyListNonGo() []string {
 	if IsExtended {
 		deps = append(
 			deps,
-			formatDep("github.com/sass/libsass", "3.6.5"),
+			formatDep("github.com/sass/libsass", "3.6.6"),
 			formatDep("github.com/webmproject/libwebp", "v1.3.2"),
 		)
 	}
@@ -14,6 +14,7 @@
 package hugo

 import (
+	"context"
 	"fmt"
 	"testing"

@@ -64,6 +65,19 @@ func TestDeprecationLogLevelFromVersion(t *testing.T) {
 	c.Assert(deprecationLogLevelFromVersion(ver.String()), qt.Equals, logg.LevelError)
 }

+func TestMarkupScope(t *testing.T) {
+	c := qt.New(t)
+
+	conf := testConfig{environment: "production", workingDir: "/mywork", running: false}
+	info := NewInfo(conf, nil)
+
+	ctx := context.Background()
+
+	ctx = SetMarkupScope(ctx, "foo")
+
+	c.Assert(info.Context.MarkupScope(ctx), qt.Equals, "foo")
+}
+
 type testConfig struct {
 	environment  string
 	running      bool
@@ -17,7 +17,7 @@ package hugo
 // This should be the only one.
 var CurrentVersion = Version{
 	Major:      0,
-	Minor:      133,
+	Minor:      137,
 	PatchLevel: 0,
 	Suffix:     "-DEV",
 }
@@ -110,7 +110,7 @@ func New(opts Options) Logger {
 		logHandler = newStopHandler(logOnce, logHandler)
 	}

-	if opts.SuppressStatements != nil && len(opts.SuppressStatements) > 0 {
+	if len(opts.SuppressStatements) > 0 {
 		logHandler = newStopHandler(newSuppressStatementsHandler(opts.SuppressStatements), logHandler)
 	}

@@ -153,7 +153,7 @@ func (pp *PathParser) doParse(component, s string, p *Path) (*Path, error) {
 				} else {
 					high = len(p.s)
 				}
-				id := types.LowHigh{Low: i + 1, High: high}
+				id := types.LowHigh[string]{Low: i + 1, High: high}
 				if len(p.identifiers) == 0 {
 					p.identifiers = append(p.identifiers, id)
 				} else if len(p.identifiers) == 1 {
@@ -260,7 +260,7 @@ type Path struct {
 	component  string
 	bundleType PathType

-	identifiers []types.LowHigh
+	identifiers []types.LowHigh[string]

 	posIdentifierLanguage int
 	disabled              bool
@@ -13,8 +13,24 @@

 package hstring

-type RenderedString string
+import (
+	"html/template"

-func (s RenderedString) String() string {
+	"github.com/gohugoio/hugo/common/types"
+)
+
+var _ types.PrintableValueProvider = HTML("")
+
+// HTML is a string that represents rendered HTML.
+// When printed in templates it will be rendered as template.HTML and considered safe so no need to pipe it into `safeHTML`.
+// This type was introduced as a wasy to prevent a common case of inifinite recursion in the template rendering
+// when the `linkify` option is enabled with a common (wrong) construct like `{{ .Text | .Page.RenderString }}` in a hook template.
+type HTML string
+
+func (s HTML) String() string {
 	return string(s)
 }
+
+func (s HTML) PrintableValue() any {
+	return template.HTML(s)
+}
@@ -25,6 +25,6 @@ func TestRenderedString(t *testing.T) {
 	c := qt.New(t)

 	// Validate that it will behave like a string in Hugo settings.
-	c.Assert(cast.ToString(RenderedString("Hugo")), qt.Equals, "Hugo")
-	c.Assert(template.HTML(RenderedString("Hugo")), qt.Equals, template.HTML("Hugo"))
+	c.Assert(cast.ToString(HTML("Hugo")), qt.Equals, "Hugo")
+	c.Assert(template.HTML(HTML("Hugo")), qt.Equals, template.HTML("Hugo"))
 }
@@ -107,12 +107,20 @@ func Unwrapv(v any) any {
 	return v
 }

-// LowHigh is typically used to represent a slice boundary.
-type LowHigh struct {
+// LowHigh represents a byte or slice boundary.
+type LowHigh[S ~[]byte | string] struct {
 	Low  int
 	High int
 }

+func (l LowHigh[S]) IsZero() bool {
+	return l.Low < 0 || (l.Low == 0 && l.High == 0)
+}
+
+func (l LowHigh[S]) Value(source S) S {
+	return source[l.Low:l.High]
+}
+
 // This is only used for debugging purposes.
 var InvocationCounter atomic.Int64

@@ -27,3 +27,25 @@ func TestKeyValues(t *testing.T) {
 	c.Assert(kv.KeyString(), qt.Equals, "key")
 	c.Assert(kv.Values, qt.DeepEquals, []any{"a1", "a2"})
 }
+
+func TestLowHigh(t *testing.T) {
+	c := qt.New(t)
+
+	lh := LowHigh[string]{
+		Low:  2,
+		High: 10,
+	}
+
+	s := "abcdefghijklmnopqrstuvwxyz"
+	c.Assert(lh.IsZero(), qt.IsFalse)
+	c.Assert(lh.Value(s), qt.Equals, "cdefghij")
+
+	lhb := LowHigh[[]byte]{
+		Low:  2,
+		High: 10,
+	}
+
+	sb := []byte(s)
+	c.Assert(lhb.IsZero(), qt.IsFalse)
+	c.Assert(lhb.Value(sb), qt.DeepEquals, []byte("cdefghij"))
+}
@@ -182,6 +182,9 @@ type Config struct {
 	// Pagination configuration.
 	Pagination config.Pagination `mapstructure:"-"`

+	// Page configuration.
+	Page config.PageConfig `mapstructure:"-"`
+
 	// Privacy configuration.
 	Privacy privacy.Config `mapstructure:"-"`

@@ -378,12 +381,12 @@ func (c *Config) CompileConfig(logger loggers.Logger) error {

 	// Legacy paginate values.
 	if c.Paginate != 0 {
-		hugo.Deprecate("site config key paginate", "Use paginator.pagerSize instead.", "v0.128.0")
+		hugo.Deprecate("site config key paginate", "Use pagination.pagerSize instead.", "v0.128.0")
 		c.Pagination.PagerSize = c.Paginate
 	}

 	if c.PaginatePath != "" {
-		hugo.Deprecate("site config key paginatePath", "Use paginator.path instead.", "v0.128.0")
+		hugo.Deprecate("site config key paginatePath", "Use pagination.path instead.", "v0.128.0")
 		c.Pagination.Path = c.PaginatePath
 	}

@@ -806,7 +809,7 @@ func (c *Configs) Init() error {
 	}

 	if len(c.Modules) == 0 {
-		return errors.New("no modules loaded (ned at least the main module)")
+		return errors.New("no modules loaded (need at least the main module)")
 	}

 	// Apply default project mounts.
@@ -103,31 +103,7 @@ suffixes = ["html", "xhtml"]
 	b.Assert(contentTypes.Markdown.Suffixes(), qt.DeepEquals, []string{"md", "mdown", "markdown"})
 }

-func TestPaginationConfigOld(t *testing.T) {
-	files := `
-- hugo.toml --
- [languages.en]
- weight = 1
- paginatePath = "page-en"
- 
- [languages.de]
- weight = 2
- paginatePath = "page-de"
- paginate = 20
-`
-
-	b := hugolib.Test(t, files)
-
-	confEn := b.H.Sites[0].Conf.Pagination()
-	confDe := b.H.Sites[1].Conf.Pagination()
-
-	b.Assert(confEn.Path, qt.Equals, "page-en")
-	b.Assert(confEn.PagerSize, qt.Equals, 10)
-	b.Assert(confDe.Path, qt.Equals, "page-de")
-	b.Assert(confDe.PagerSize, qt.Equals, 20)
-}
-
-func TestPaginationConfigNew(t *testing.T) {
+func TestPaginationConfig(t *testing.T) {
 	files := `
 -- hugo.toml --
 [languages.en]
@@ -184,3 +160,18 @@ title: "p3"
 	b.AssertFileExists("public/page/1/index.html", false)
 	b.AssertFileContent("public/page/2/index.html", "pagination-default")
 }
+
+func TestMapUglyURLs(t *testing.T) {
+	files := `
+-- hugo.toml --
+[uglyurls]
+  posts = true
+`
+
+	b := hugolib.Test(t, files)
+
+	c := b.H.Configs.Base
+
+	b.Assert(c.C.IsUglyURLSection("posts"), qt.IsTrue)
+	b.Assert(c.C.IsUglyURLSection("blog"), qt.IsFalse)
+}
@@ -327,6 +327,25 @@ var allDecoderSetups = map[string]decodeWeight{
 			return err
 		},
 	},
+	"page": {
+		key: "page",
+		decode: func(d decodeWeight, p decodeConfig) error {
+			p.c.Page = config.PageConfig{
+				NextPrevSortOrder:          "desc",
+				NextPrevInSectionSortOrder: "desc",
+			}
+			if p.p.IsSet(d.key) {
+				if err := mapstructure.WeakDecode(p.p.Get(d.key), &p.c.Page); err != nil {
+					return err
+				}
+			}
+
+			return nil
+		},
+		getCompiler: func(c *Config) configCompiler {
+			return &c.Page
+		},
+	},
 	"pagination": {
 		key: "pagination",
 		decode: func(d decodeWeight, p decodeConfig) error {
@@ -400,6 +419,8 @@ var allDecoderSetups = map[string]decodeWeight{
 				p.c.UglyURLs = vv
 			case string:
 				p.c.UglyURLs = vv == "true"
+			case maps.Params:
+				p.c.UglyURLs = cast.ToStringMapBool(maps.CleanConfigStringMap(vv))
 			default:
 				p.c.UglyURLs = cast.ToStringMapBool(v)
 			}
@@ -64,7 +64,7 @@ func LoadConfig(d ConfigSourceDescriptor) (*Configs, error) {
 		return nil, fmt.Errorf("failed to create config from result: %w", err)
 	}

-	moduleConfig, modulesClient, err := l.loadModules(configs)
+	moduleConfig, modulesClient, err := l.loadModules(configs, d.IgnoreModuleDoesNotExist)
 	if err != nil {
 		return nil, fmt.Errorf("failed to load modules: %w", err)
 	}
@@ -116,6 +116,9 @@ type ConfigSourceDescriptor struct {

 	// Defaults to os.Environ if not set.
 	Environ []string
+
+	// If set, this will be used to ignore the module does not exist error.
+	IgnoreModuleDoesNotExist bool
 }

 func (d ConfigSourceDescriptor) configFilenames() []string {
@@ -453,7 +456,7 @@ func (l *configLoader) loadConfigMain(d ConfigSourceDescriptor) (config.LoadConf
 	return res, l.ModulesConfig, err
 }

-func (l *configLoader) loadModules(configs *Configs) (modules.ModulesConfig, *modules.Client, error) {
+func (l *configLoader) loadModules(configs *Configs, ignoreModuleDoesNotExist bool) (modules.ModulesConfig, *modules.Client, error) {
 	bcfg := configs.LoadingInfo.BaseConfig
 	conf := configs.Base
 	workingDir := bcfg.WorkingDir
@@ -487,17 +490,18 @@ func (l *configLoader) loadModules(configs *Configs) (modules.ModulesConfig, *mo
 	}

 	modulesClient := modules.NewClient(modules.ClientConfig{
-		Fs:                 l.Fs,
-		Logger:             l.Logger,
-		Exec:               ex,
-		HookBeforeFinalize: hook,
-		WorkingDir:         workingDir,
-		ThemesDir:          themesDir,
-		PublishDir:         publishDir,
-		Environment:        l.Environment,
-		CacheDir:           conf.Caches.CacheDirModules(),
-		ModuleConfig:       conf.Module,
-		IgnoreVendor:       ignoreVendor,
+		Fs:                       l.Fs,
+		Logger:                   l.Logger,
+		Exec:                     ex,
+		HookBeforeFinalize:       hook,
+		WorkingDir:               workingDir,
+		ThemesDir:                themesDir,
+		PublishDir:               publishDir,
+		Environment:              l.Environment,
+		CacheDir:                 conf.Caches.CacheDirModules(),
+		ModuleConfig:             conf.Module,
+		IgnoreVendor:             ignoreVendor,
+		IgnoreModuleDoesNotExist: ignoreModuleDoesNotExist,
 	})

 	moduleConfig, err := modulesClient.Collect()
@@ -422,3 +422,18 @@ type Pagination struct {
 	// Whether to disable generation of alias for the first pagination page.
 	DisableAliases bool
 }
+
+// PageConfig configures the behavior of pages.
+type PageConfig struct {
+	// Sort order for Page.Next and Page.Prev. Default "desc" (the default page sort order in Hugo).
+	NextPrevSortOrder string
+
+	// Sort order for Page.NextInSection and Page.PrevInSection. Default "desc".
+	NextPrevInSectionSortOrder string
+}
+
+func (c *PageConfig) CompileConfig(loggers.Logger) error {
+	c.NextPrevInSectionSortOrder = strings.ToLower(c.NextPrevInSectionSortOrder)
+	c.NextPrevSortOrder = strings.ToLower(c.NextPrevSortOrder)
+	return nil
+}
@@ -1,5 +0,0 @@
-+++
-title = '{{ replace .File.ContentBaseName "-" " " | title }}'
-date = {{ .Date }}
-draft = true
-+++
@@ -76,6 +76,11 @@ func CreateSite(createpath string, sourceFs afero.Fs, force bool, format string)
 		return err
 	}

+	err = newSiteCreateArchetype(sourceFs, createpath, format)
+	if err != nil {
+		return err
+	}
+
 	return copyFiles(createpath, sourceFs, siteFs)
 }

@@ -109,3 +114,19 @@ func newSiteCreateConfig(fs afero.Fs, createpath string, format string) (err err

 	return helpers.WriteToDisk(filepath.Join(createpath, "hugo."+format), &buf, fs)
 }
+
+func newSiteCreateArchetype(fs afero.Fs, createpath string, format string) (err error) {
+	in := map[string]any{
+		"title": "{{ replace .File.ContentBaseName \"-\" \" \" | title }}",
+		"date":  "{{ .Date }}",
+		"draft": true,
+	}
+
+	var buf bytes.Buffer
+	err = parser.InterfaceToFrontMatter(in, metadecoders.FormatFromString(format), &buf)
+	if err != nil {
+		return err
+	}
+
+	return helpers.WriteToDisk(filepath.Join(createpath, "archetypes", "default.md"), &buf, fs)
+}
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="{{ or site.Language.LanguageCode }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
+<html lang="{{ site.Language.LanguageCode }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
 <head>
  {{ partial "head.html" . }}
 </head>
@@ -11,8 +11,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.

-//go:build !nodeploy
-// +build !nodeploy
+//go:build withdeploy
+// +build withdeploy

 package deploy

@@ -11,8 +11,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.

-//go:build !nodeploy
-// +build !nodeploy
+//go:build withdeploy
+// +build withdeploy

 package deploy

@@ -11,8 +11,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.

-//go:build !solaris && !nodeploy
-// +build !solaris,!nodeploy
+//go:build !solaris && withdeploy
+// +build !solaris,withdeploy

 package deploy

@@ -11,8 +11,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.

-//go:build !nodeploy
-// +build !nodeploy
+//go:build withdeploy
+// +build withdeploy

 package deploy

@@ -11,8 +11,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.

-//go:build !nodeploy
-// +build !nodeploy
+//go:build withdeploy
+// +build withdeploy

 package deployconfig

@@ -11,8 +11,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.

-//go:build !nodeploy
-// +build !nodeploy
+//go:build withdeploy
+// +build withdeploy

 package deploy

@@ -98,6 +98,8 @@ type Deps struct {
 	// TODO(bep) rethink this re. a plugin setup, but this will have to do for now.
 	WasmDispatchers *warpc.Dispatchers

+	isClosed bool
+
 	*globalErrHandler
 }

@@ -345,6 +347,11 @@ func (d *Deps) TextTmpl() tpl.TemplateParseFinder {
 }

 func (d *Deps) Close() error {
+	if d.isClosed {
+		return nil
+	}
+	d.isClosed = true
+
 	if d.MemCache != nil {
 		d.MemCache.Stop()
 	}
@@ -1,4 +1,4 @@
 {{ define "main" }}
-{{ $section_to_display := (.Site.Taxonomies.categories.fundamentals).Pages | lang.Merge (.Sites.First.Taxonomies.categories.fundamentals).Pages }}
+{{ $section_to_display := (.Site.Taxonomies.categories.fundamentals).Pages | lang.Merge (.Sites.Default.Taxonomies.categories.fundamentals).Pages }}
  {{ partial "pagelayout.html" (dict "context" . "section_to_display" $section_to_display ) }}
 {{ end }}
@@ -1,5 +1,5 @@
 {{ define "main" }}
-  {{ $paginator := .Paginate (.Pages | lang.Merge (where .Sites.First.RegularPages "Section" .Section)) }}
+  {{ $paginator := .Paginate (.Pages | lang.Merge (where .Sites.Default.RegularPages "Section" .Section)) }}
  {{ $section_to_display :=  .Sections | default $paginator.Pages }}
  {{ partial "pagelayout.html" (dict "context" . "section_to_display" $section_to_display ) }}
 {{ end }}
@@ -1,5 +1,6 @@
 {{ $text := `
-Most of the commands for **Hugo Modules** require a newer version of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads/ ). If you have an "older" site running on Netlify, you may have to set GO_VERSION to 1.12 in your Environment settings.
+Most of the commands for **Hugo Modules** require a newer version (>= 1.18) of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads/ ).
+If you have an "older" site running on Netlify, you may have to set GO_VERSION to 1.19 or newer in your Environment settings.

 For more information about Go Modules, see:

@@ -1 +1 @@
-# github.com/gohugoio/gohugoioTheme v0.0.0-20240728210410-d42c342ce472
+# github.com/gohugoio/gohugoioTheme v0.0.0-20240815082608-66ccd383a90f
@@ -49,7 +49,7 @@ toc: true
 : Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.

 [Markdown render hooks]
-: Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element.
+: Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, links, and tables. For example, render every standalone image as an HTML `figure` element.

 [Diagrams]
 : Use fenced code blocks and Markdown render hooks to include diagrams in your content.
@@ -5,7 +5,7 @@ url: /commands/hugo/
 ---
 ## hugo

-hugo builds your site
+Build your site

 ### Synopsis

@@ -70,16 +70,17 @@ hugo [flags]

 ### SEE ALSO

+* [hugo build](/commands/hugo_build/)	 - Build your site
 * [hugo completion](/commands/hugo_completion/)	 - Generate the autocompletion script for the specified shell
-* [hugo config](/commands/hugo_config/)	 - Print the site configuration
-* [hugo convert](/commands/hugo_convert/)	 - Convert your content to different formats
-* [hugo deploy](/commands/hugo_deploy/)	 - Deploy your site to a Cloud provider.
-* [hugo env](/commands/hugo_env/)	 - Print Hugo version and environment info
-* [hugo gen](/commands/hugo_gen/)	 - A collection of several useful generators.
-* [hugo import](/commands/hugo_import/)	 - Import your site from others.
-* [hugo list](/commands/hugo_list/)	 - Listing out various types of content
-* [hugo mod](/commands/hugo_mod/)	 - Various Hugo Modules helpers.
-* [hugo new](/commands/hugo_new/)	 - Create new content for your site
-* [hugo server](/commands/hugo_server/)	 - A high performance webserver
-* [hugo version](/commands/hugo_version/)	 - Print Hugo version and environment info
+* [hugo config](/commands/hugo_config/)	 - Display site configuration
+* [hugo convert](/commands/hugo_convert/)	 - Convert front matter to another format
+* [hugo deploy](/commands/hugo_deploy/)	 - Deploy your site to a cloud provider
+* [hugo env](/commands/hugo_env/)	 - Display version and environment info
+* [hugo gen](/commands/hugo_gen/)	 - Generate documentation and syntax highlighting styles
+* [hugo import](/commands/hugo_import/)	 - Import a site from another system
+* [hugo list](/commands/hugo_list/)	 - List content
+* [hugo mod](/commands/hugo_mod/)	 - Manage modules
+* [hugo new](/commands/hugo_new/)	 - Create new content
+* [hugo server](/commands/hugo_server/)	 - Start the embedded web server
+* [hugo version](/commands/hugo_version/)	 - Display version

@@ -0,0 +1,74 @@
+---
+title: "hugo build"
+slug: hugo_build
+url: /commands/hugo_build/
+---
+## hugo build
+
+Build your site
+
+### Synopsis
+
+build is the main command, used to build your Hugo site.
+
+Hugo is a Fast and Flexible Static Site Generator
+built with love by spf13 and friends in Go.
+
+Complete documentation is available at https://gohugo.io/.
+
+```
+hugo build [flags]
+```
+
+### Options
+
+```
+  -b, --baseURL string             hostname (and path) to the root, e.g. https://spf13.com/
+  -D, --buildDrafts                include content marked as draft
+  -E, --buildExpired               include expired content
+  -F, --buildFuture                include content with publishdate in the future
+      --cacheDir string            filesystem path to cache directory
+      --cleanDestinationDir        remove files from destination not found in static directories
+      --clock string               set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+      --config string              config file (default is hugo.yaml|json|toml)
+      --configDir string           config dir (default "config")
+  -c, --contentDir string          filesystem path to content directory
+      --debug                      debug output
+  -d, --destination string         filesystem path to write files to
+      --disableKinds strings       disable different kind of pages (home, RSS etc.)
+      --enableGitInfo              add Git revision, date, author, and CODEOWNERS info to the pages
+  -e, --environment string         build environment
+      --forceSyncStatic            copy all files when static is changed.
+      --gc                         enable to run some cleanup tasks (remove unused cache files) after the build
+  -h, --help                       help for build
+      --ignoreCache                ignores the cache directory
+      --ignoreVendorPaths string   ignores any _vendor for module paths matching the given Glob pattern
+  -l, --layoutDir string           filesystem path to layout directory
+      --logLevel string            log level (debug|info|warn|error)
+      --minify                     minify any supported output format (HTML, XML etc.)
+      --noBuildLock                don't create .hugo_build.lock file
+      --noChmod                    don't sync permission mode of files
+      --noTimes                    don't sync modification time of files
+      --panicOnWarning             panic on first WARNING log
+      --poll string                set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes
+      --printI18nWarnings          print missing translations
+      --printMemoryUsage           print memory usage to screen at intervals
+      --printPathWarnings          print warnings on duplicate target paths etc.
+      --printUnusedTemplates       print warnings on unused templates.
+      --quiet                      build in quiet mode
+      --renderSegments strings     named segments to render (configured in the segments config)
+  -M, --renderToMemory             render to memory (mostly useful when running the server)
+  -s, --source string              filesystem path to read files relative from
+      --templateMetrics            display metrics about template executions
+      --templateMetricsHints       calculate some improvement hints when combined with --templateMetrics
+  -t, --theme strings              themes to use (located in /themes/THEMENAME/)
+      --themesDir string           filesystem path to themes directory
+      --trace file                 write trace to file (not useful in general)
+  -v, --verbose                    verbose output
+  -w, --watch                      watch filesystem for changes and recreate as needed
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/)	 - Build your site
+
@@ -39,7 +39,7 @@ See each sub-command's help for details on how to use the generated script.

 ### SEE ALSO

-* [hugo](/commands/hugo/)	 - hugo builds your site
+* [hugo](/commands/hugo/)	 - Build your site
 * [hugo completion bash](/commands/hugo_completion_bash/)	 - Generate the autocompletion script for bash
 * [hugo completion fish](/commands/hugo_completion_fish/)	 - Generate the autocompletion script for fish
 * [hugo completion powershell](/commands/hugo_completion_powershell/)	 - Generate the autocompletion script for powershell
@@ -5,11 +5,11 @@ url: /commands/hugo_config/
 ---
 ## hugo config

-Print the site configuration
+Display site configuration

 ### Synopsis

-Print the site configuration, both default and custom settings.
+Display site configuration, both default and custom settings.

 ```
 hugo config [command] [flags]
@@ -48,6 +48,6 @@ hugo config [command] [flags]

 ### SEE ALSO

-* [hugo](/commands/hugo/)	 - hugo builds your site
+* [hugo](/commands/hugo/)	 - Build your site
 * [hugo config mounts](/commands/hugo_config_mounts/)	 - Print the configured file mounts

@@ -42,5 +42,5 @@ hugo config mounts [flags] [args]

 ### SEE ALSO

-* [hugo config](/commands/hugo_config/)	 - Print the site configuration
+* [hugo config](/commands/hugo_config/)	 - Display site configuration

@@ -5,11 +5,11 @@ url: /commands/hugo_convert/
 ---
 ## hugo convert

-Convert your content to different formats
+Convert front matter to another format

 ### Synopsis

-Convert your content (e.g. front matter) to different formats.
+Convert front matter to another format.

 See convert's subcommands toJSON, toTOML and toYAML for more information.

@@ -41,7 +41,7 @@ See convert's subcommands toJSON, toTOML and toYAML for more information.

 ### SEE ALSO

-* [hugo](/commands/hugo/)	 - hugo builds your site
+* [hugo](/commands/hugo/)	 - Build your site
 * [hugo convert toJSON](/commands/hugo_convert_tojson/)	 - Convert front matter to JSON
 * [hugo convert toTOML](/commands/hugo_convert_totoml/)	 - Convert front matter to TOML
 * [hugo convert toYAML](/commands/hugo_convert_toyaml/)	 - Convert front matter to YAML
@@ -44,5 +44,5 @@ hugo convert toJSON [flags] [args]

 ### SEE ALSO

-* [hugo convert](/commands/hugo_convert/)	 - Convert your content to different formats
+* [hugo convert](/commands/hugo_convert/)	 - Convert front matter to another format

@@ -44,5 +44,5 @@ hugo convert toTOML [flags] [args]

 ### SEE ALSO

-* [hugo convert](/commands/hugo_convert/)	 - Convert your content to different formats
+* [hugo convert](/commands/hugo_convert/)	 - Convert front matter to another format

@@ -44,5 +44,5 @@ hugo convert toYAML [flags] [args]

 ### SEE ALSO

-* [hugo convert](/commands/hugo_convert/)	 - Convert your content to different formats
+* [hugo convert](/commands/hugo_convert/)	 - Convert front matter to another format

@@ -5,11 +5,11 @@ url: /commands/hugo_deploy/
 ---
 ## hugo deploy

-Deploy your site to a Cloud provider.
+Deploy your site to a cloud provider

 ### Synopsis

-Deploy your site to a Cloud provider.
+Deploy your site to a cloud provider

 See https://gohugo.io/hosting-and-deployment/hugo-deploy/ for detailed
 documentation.
@@ -52,5 +52,5 @@ hugo deploy [flags] [args]

 ### SEE ALSO

-* [hugo](/commands/hugo/)	 - hugo builds your site
+* [hugo](/commands/hugo/)	 - Build your site

@@ -5,11 +5,11 @@ url: /commands/hugo_env/
 ---
 ## hugo env

-Print Hugo version and environment info
+Display version and environment info

 ### Synopsis

-Print Hugo version and environment info. This is useful in Hugo bug reports
+Display version and environment info. This is useful in Hugo bug reports

 ```
 hugo env [flags] [args]
@@ -41,5 +41,5 @@ hugo env [flags] [args]

 ### SEE ALSO

-* [hugo](/commands/hugo/)	 - hugo builds your site
+* [hugo](/commands/hugo/)	 - Build your site

@@ -5,7 +5,11 @@ url: /commands/hugo_gen/
 ---
 ## hugo gen

-A collection of several useful generators.
+Generate documentation and syntax highlighting styles
+
+### Synopsis
+
+Generate documentation for your project using Hugo's documentation engine, including syntax highlighting for various programming languages.

 ### Options

@@ -33,7 +37,7 @@ A collection of several useful generators.

 ### SEE ALSO

-* [hugo](/commands/hugo/)	 - hugo builds your site
+* [hugo](/commands/hugo/)	 - Build your site
 * [hugo gen chromastyles](/commands/hugo_gen_chromastyles/)	 - Generate CSS stylesheet for the Chroma code highlighter
 * [hugo gen doc](/commands/hugo_gen_doc/)	 - Generate Markdown documentation for the Hugo CLI.
 * [hugo gen man](/commands/hugo_gen_man/)	 - Generate man pages for the Hugo CLI
@@ -47,5 +47,5 @@ hugo gen chromastyles [flags] [args]

 ### SEE ALSO

-* [hugo gen](/commands/hugo_gen/)	 - A collection of several useful generators.
+* [hugo gen](/commands/hugo_gen/)	 - Generate documentation and syntax highlighting styles

@@ -47,5 +47,5 @@ hugo gen doc [flags] [args]

 ### SEE ALSO

-* [hugo gen](/commands/hugo_gen/)	 - A collection of several useful generators.
+* [hugo gen](/commands/hugo_gen/)	 - Generate documentation and syntax highlighting styles

@@ -44,5 +44,5 @@ hugo gen man [flags] [args]

 ### SEE ALSO

-* [hugo gen](/commands/hugo_gen/)	 - A collection of several useful generators.
+* [hugo gen](/commands/hugo_gen/)	 - Generate documentation and syntax highlighting styles

@@ -5,11 +5,11 @@ url: /commands/hugo_import/
 ---
 ## hugo import

-Import your site from others.
+Import a site from another system

 ### Synopsis

-Import your site from other web site generators like Jekyll.
+Import a site from another system.

 Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_path`.

@@ -39,6 +39,6 @@ Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_p

 ### SEE ALSO

-* [hugo](/commands/hugo/)	 - hugo builds your site
+* [hugo](/commands/hugo/)	 - Build your site
 * [hugo import jekyll](/commands/hugo_import_jekyll/)	 - hugo import from Jekyll

@@ -44,5 +44,5 @@ hugo import jekyll [flags] [args]

 ### SEE ALSO

-* [hugo import](/commands/hugo_import/)	 - Import your site from others.
+* [hugo import](/commands/hugo_import/)	 - Import a site from another system

@@ -5,11 +5,11 @@ url: /commands/hugo_list/
 ---
 ## hugo list

-Listing out various types of content
+List content

 ### Synopsis

-Listing out various types of content.
+List content.

 List requires a subcommand, e.g. hugo list drafts

@@ -39,7 +39,7 @@ List requires a subcommand, e.g. hugo list drafts

 ### SEE ALSO

-* [hugo](/commands/hugo/)	 - hugo builds your site
+* [hugo](/commands/hugo/)	 - Build your site
 * [hugo list all](/commands/hugo_list_all/)	 - List all content
 * [hugo list drafts](/commands/hugo_list_drafts/)	 - List draft content
 * [hugo list expired](/commands/hugo_list_expired/)	 - List expired content
@@ -41,5 +41,5 @@ hugo list all [flags] [args]

 ### SEE ALSO

-* [hugo list](/commands/hugo_list/)	 - Listing out various types of content
+* [hugo list](/commands/hugo_list/)	 - List content

@@ -41,5 +41,5 @@ hugo list drafts [flags] [args]

 ### SEE ALSO

-* [hugo list](/commands/hugo_list/)	 - Listing out various types of content
+* [hugo list](/commands/hugo_list/)	 - List content

@@ -41,5 +41,5 @@ hugo list expired [flags] [args]

 ### SEE ALSO

-* [hugo list](/commands/hugo_list/)	 - Listing out various types of content
+* [hugo list](/commands/hugo_list/)	 - List content

@@ -41,5 +41,5 @@ hugo list future [flags] [args]

 ### SEE ALSO

-* [hugo list](/commands/hugo_list/)	 - Listing out various types of content
+* [hugo list](/commands/hugo_list/)	 - List content

@@ -41,5 +41,5 @@ hugo list published [flags] [args]

 ### SEE ALSO

-* [hugo list](/commands/hugo_list/)	 - Listing out various types of content
+* [hugo list](/commands/hugo_list/)	 - List content

@@ -5,7 +5,7 @@ url: /commands/hugo_mod/
 ---
 ## hugo mod

-Various Hugo Modules helpers.
+Manage modules

 ### Synopsis

@@ -48,7 +48,7 @@ See https://gohugo.io/hugo-modules/ for more information.

 ### SEE ALSO

-* [hugo](/commands/hugo/)	 - hugo builds your site
+* [hugo](/commands/hugo/)	 - Build your site
 * [hugo mod clean](/commands/hugo_mod_clean/)	 - Delete the Hugo Module cache for the current project.
 * [hugo mod get](/commands/hugo_mod_get/)	 - Resolves dependencies in your current Hugo Project.
 * [hugo mod graph](/commands/hugo_mod_graph/)	 - Print a module dependency graph.
@@ -48,5 +48,5 @@ hugo mod clean [flags] [args]

 ### SEE ALSO

-* [hugo mod](/commands/hugo_mod/)	 - Various Hugo Modules helpers.
+* [hugo mod](/commands/hugo_mod/)	 - Manage modules

@@ -72,5 +72,5 @@ hugo mod get [flags] [args]

 ### SEE ALSO

-* [hugo mod](/commands/hugo_mod/)	 - Various Hugo Modules helpers.
+* [hugo mod](/commands/hugo_mod/)	 - Manage modules

@@ -49,5 +49,5 @@ hugo mod graph [flags] [args]

 ### SEE ALSO

-* [hugo mod](/commands/hugo_mod/)	 - Various Hugo Modules helpers.
+* [hugo mod](/commands/hugo_mod/)	 - Manage modules

@@ -53,5 +53,5 @@ hugo mod init [flags] [args]

 ### SEE ALSO

-* [hugo mod](/commands/hugo_mod/)	 - Various Hugo Modules helpers.
+* [hugo mod](/commands/hugo_mod/)	 - Manage modules

@@ -41,6 +41,6 @@ hugo mod npm [command] [flags]

 ### SEE ALSO

-* [hugo mod](/commands/hugo_mod/)	 - Various Hugo Modules helpers.
+* [hugo mod](/commands/hugo_mod/)	 - Manage modules
 * [hugo mod npm pack](/commands/hugo_mod_npm_pack/)	 - Experimental: Prepares and writes a composite package.json file for your project.

@@ -42,5 +42,5 @@ hugo mod tidy [flags] [args]

 ### SEE ALSO

-* [hugo mod](/commands/hugo_mod/)	 - Various Hugo Modules helpers.
+* [hugo mod](/commands/hugo_mod/)	 - Manage modules

@@ -48,5 +48,5 @@ hugo mod vendor [flags] [args]

 ### SEE ALSO

-* [hugo mod](/commands/hugo_mod/)	 - Various Hugo Modules helpers.
+* [hugo mod](/commands/hugo_mod/)	 - Manage modules

@@ -47,5 +47,5 @@ hugo mod verify [flags] [args]

 ### SEE ALSO

-* [hugo mod](/commands/hugo_mod/)	 - Various Hugo Modules helpers.
+* [hugo mod](/commands/hugo_mod/)	 - Manage modules

@@ -5,7 +5,7 @@ url: /commands/hugo_new/
 ---
 ## hugo new

-Create new content for your site
+Create new content

 ### Synopsis

@@ -44,8 +44,8 @@ Ensure you run this within the root directory of your site.

 ### SEE ALSO

-* [hugo](/commands/hugo/)	 - hugo builds your site
-* [hugo new content](/commands/hugo_new_content/)	 - Create new content for your site
+* [hugo](/commands/hugo/)	 - Build your site
+* [hugo new content](/commands/hugo_new_content/)	 - Create new content
 * [hugo new site](/commands/hugo_new_site/)	 - Create a new site (skeleton)
 * [hugo new theme](/commands/hugo_new_theme/)	 - Create a new theme (skeleton)

@@ -5,7 +5,7 @@ url: /commands/hugo_new_content/
 ---
 ## hugo new content

-Create new content for your site
+Create new content

 ### Synopsis

@@ -56,5 +56,5 @@ hugo new content [path] [flags]

 ### SEE ALSO

-* [hugo new](/commands/hugo_new/)	 - Create new content for your site
+* [hugo new](/commands/hugo_new/)	 - Create new content

@@ -45,5 +45,5 @@ hugo new site [path] [flags]

 ### SEE ALSO

-* [hugo new](/commands/hugo_new/)	 - Create new content for your site
+* [hugo new](/commands/hugo_new/)	 - Create new content

@@ -44,5 +44,5 @@ hugo new theme [name] [flags]

 ### SEE ALSO

-* [hugo new](/commands/hugo_new/)	 - Create new content for your site
+* [hugo new](/commands/hugo_new/)	 - Create new content

@@ -5,7 +5,7 @@ url: /commands/hugo_server/
 ---
 ## hugo server

-A high performance webserver
+Start the embedded web server

 ### Synopsis

@@ -94,6 +94,6 @@ hugo server [command] [flags]

 ### SEE ALSO

-* [hugo](/commands/hugo/)	 - hugo builds your site
+* [hugo](/commands/hugo/)	 - Build your site
 * [hugo server trust](/commands/hugo_server_trust/)	 - Install the local CA in the system trust store.

@@ -38,5 +38,5 @@ hugo server trust [flags] [args]

 ### SEE ALSO

-* [hugo server](/commands/hugo_server/)	 - A high performance webserver
+* [hugo server](/commands/hugo_server/)	 - Start the embedded web server

@@ -5,11 +5,11 @@ url: /commands/hugo_version/
 ---
 ## hugo version

-Print Hugo version and environment info
+Display version

 ### Synopsis

-Print Hugo version and environment info. This is useful in Hugo bug reports.
+Display version and environment info. This is useful in Hugo bug reports.

 ```
 hugo version [flags] [args]
@@ -41,5 +41,5 @@ hugo version [flags] [args]

 ### SEE ALSO

-* [hugo](/commands/hugo/)	 - hugo builds your site
+* [hugo](/commands/hugo/)	 - Build your site

@@ -125,7 +125,7 @@ Set any [front matter field] in the map passed to the [`AddPage`](#addpage) meth

 This table describes the fields most commonly passed to the `AddPage` method.

-Key|Descripion|Required
+Key|Description|Required
 :--|:--|:-:
 `content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.|&nbsp;
 `content.value`|The content value as a string.|&nbsp;
@@ -148,7 +148,7 @@ When setting the `path`, Hugo transforms the given string to a logical path. For

 Construct the map passed to the [`AddResource`](#addresource) method using the fields below.

-Key|Descripion|Required
+Key|Description|Required
 :--|:--|:-:
 `content.mediaType`|The content [media type].|:heavy_check_mark:
 `content.value`|The content value as a string or resource.|:heavy_check_mark:
@@ -21,15 +21,22 @@ This is the default language configuration:

 In the above, `en` is the language key.

-{{% note %}}
-Each language key must conform to the syntax described in [RFC 5646]. You must use hyphens to separate subtags. For example:
+
+Language keys must conform to the syntax described in [RFC 5646]. For example:

 - `en`
- `en-GB`
- `pt-BR`
+- `en-US`
+
+Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7] are also supported. Omit the `art-x-` prefix from the language key. For example:
+
+- `hugolang`
+
+{{% note %}}
+Private use subtags must not exceed 8 alphanumeric characters.
+{{% /note %}}

 [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
-{{% /note %}}
+[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7

 This is an example of a site configuration for a multilingual project. Any key not defined in a `languages` object will fall back to the global value in the root of your site configuration.

@@ -1,6 +1,6 @@
 ---
 title: Page resources
-description: Page resources -- images, other pages, documents, etc. -- have page-relative URLs and their own metadata.
+description: Use page resources to logically associate assets with a page.
 categories: [content management]
 keywords: [bundle,content,resources]
 menu:
@@ -37,82 +37,83 @@ content
        └── index.md (root of page bundle)
 ```

-## Properties
+## Examples

-ResourceType
-: The main type of the resource's [Media Type](/templates/output-formats/#media-types). For example, a file of MIME type `image/jpeg` has the ResourceType `image`. A `Page` will have `ResourceType` with value `page`.
+Use any of these methods on a `Page` object to capture page resources:

-Name
-: Default value is the file name (relative to the owning page). Can be set in front matter.
+ - [`Resources.ByType`]
+ - [`Resources.Get`]
+ - [`Resources.GetMatch`]
+ - [`Resources.Match`]

-Title
-: Default value is the same as `.Name`. Can be set in front matter.
+ Once you have captured a resource, use any of the applicable [`Resource`] methods to return a value or perform an action. 

-Permalink
-: The absolute URL to the resource. Resources of type `page` will have no value.
+[`Resource`]: /methods/resource
+[`Resources.ByType`]: /methods/page/resources#bytype
+[`Resources.GetMatch`]: /methods/page/resources#getmatch
+[`Resources.Get`]: /methods/page/resources#get
+[`Resources.Match`]: /methods/page/resources#match

-RelPermalink
-: The relative URL to the resource. Resources of type `page` will have no value.
+The following examples assume this content structure:

-Content
-: The content of the resource itself. For most resources, this returns a string
-with the contents of the file. Use this to create inline resources.
+```text
+content/
+└── example/
+    ├── data/
+    │  └── books.json   <-- page resource
+    ├── images/
+    │  ├── a.jpg        <-- page resource
+    │  └── b.jpg        <-- page resource
+    ├── snippets/
+    │  └── text.md      <-- page resource
+    └── index.md
+```
+
+Render a single image, and throw an error if the file does not exist:

 ```go-html-template
-{{ with .Resources.GetMatch "script.js" }}
-  <script>{{ .Content | safeJS }}</script>
-{{ end }}
-
-{{ with .Resources.GetMatch "style.css" }}
-  <style>{{ .Content | safeCSS }}</style>
-{{ end }}
-
-{{ with .Resources.GetMatch "img.png" }}
-  <img src="data:{{ .MediaType.Type }};base64,{{ .Content | base64Encode }}">
+{{ $path := "images/a.jpg" }}
+{{ with .Resources.Get $path }}
+  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ else }}
+  {{ errorf "Unable to get page resource %q" $path }}
 {{ end }}
 ```

-MediaType.Type
-: The media type (formerly known as a MIME type) of the resource (e.g., `image/jpeg`).
-
-MediaType.MainType
-: The main type of the resource's media type (e.g., `image`).
-
-MediaType.SubType
-: The subtype of the resource's type (e.g., `jpeg`). This may or may not correspond to the file suffix.
-
-MediaType.Suffixes
-: A slice of possible file suffixes for the resource's media type (e.g., `[jpg jpeg jpe jif jfif]`).
-
-## Methods
-
-ByType
-: Returns the page resources of the given type.
+Render all images, resized to 300 px wide:

 ```go-html-template
-{{ .Resources.ByType "image" }}
+{{ range .Resources.ByType "image" }}
+  {{ with .Resize "300x" }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ end }}
+{{ end }}
 ```
-Match
-: Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive.
+
+Render the markdown snippet:

 ```go-html-template
-{{ .Resources.Match "images/*" }}
+{{ with .Resources.Get "snippets/text.md" }}
+  {{ .Content }}
+{{ end }}
 ```

-GetMatch
-: Same as `Match` but will return the first match.
+List the titles in the data file, and throw an error if the file does not exist.

-### Pattern matching
-
-```go
-// Using Match/GetMatch to find this images/sunset.jpg ?
-.Resources.Match "images/sun*" ✅
-.Resources.Match "**/sunset.jpg" ✅
-.Resources.Match "images/*.jpg" ✅
-.Resources.Match "**.jpg" ✅
-.Resources.Match "*" 🚫
-.Resources.Match "sunset.jpg" 🚫
-.Resources.Match "*sunset.jpg" 🚫
+```go-html-template
+{{ $path := "data/books.json" }}
+{{ with .Resources.Get $path }}
+  {{ with . | transform.Unmarshal }}
+    <p>Books:</p>
+    <ul>
+      {{ range . }}
+        <li>{{ .title }}</li>
+      {{ end }}
+    </ul>
+  {{ end }}
+{{ else }}
+  {{ errorf "Unable to get page resource %q" $path }}
+{{ end }}
 ```

 ## Metadata
@@ -124,21 +125,21 @@ Resources of type `page` get `Title` etc. from their own front matter.
 {{% /note %}}

 name
-: Sets the value returned in `Name`.
+: (`string`) Sets the value returned in `Name`.

 {{% note %}}
 The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources.
 {{% /note %}}

 title
-: Sets the value returned in `Title`
+: (`string`) Sets the value returned in `Title`

 params
-: A map of custom key-value pairs.
+: (`map`) A map of custom key-value pairs.

 ### Resources metadata example

-{{< code-toggle >}}
+{{< code-toggle file=content/example.md fm=true >}}
 title: Application
 date : 2018-01-25
 resources :
@@ -173,7 +174,7 @@ From the example above:
 - Every docx in the bundle will receive the `word` icon.

 {{% note %}}
-The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
+The order matters; only the first set values of the `title`, `name` and `params` keys will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
 {{% /note %}}

 ### The `:counter` placeholder in `name` and `title`
@@ -92,11 +92,11 @@ Note that the `summaryLength` is an approximate number of words.

 Each summary type has different characteristics:

-Type|Precedence|Renders markdown|Renders shortcodes|Strips HTML tags|Wraps single lines with `<p>`
-:--|:-:|:-:|:-:|:-:|:-:
-Manual|1|:heavy_check_mark:|:heavy_check_mark:|:x:|:heavy_check_mark:
-Front&nbsp;matter|2|:heavy_check_mark:|:x:|:x:|:x:
-Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:
+Type|Precedence|Renders markdown|Renders shortcodes|Wraps single lines with `<p>`
+:--|:-:|:-:|:-:|:-:
+Manual|1|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Front&nbsp;matter|2|:heavy_check_mark:|:x:|:x:
+Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:

 ## Rendering

@@ -48,7 +48,7 @@ For a complete guide to contributing to Hugo, see the [Contribution Guide].
 To build the extended edition of Hugo from source you must:

 1. Install [Git]
-1. Install [Go] version 1.20 or later
+1. Install [Go] version 1.23.0 or later
 1. Install a C compiler, either [GCC] or [Clang]
 1. Update your `PATH` environment variable as described in the [Go documentation]

@@ -2,4 +2,6 @@
 # Do not remove front matter.
 ---

-In Go templates, the falsy values are `false`, `0`, any nil pointer or interface value, and any array, slice, map, or string of length zero. Everything else is truthy.
+The falsy values are `false`, `0`, any `nil` pointer or interface value, any array, slice, map, or string of length zero, and zero `time.Time` values.
+
+Everything else is truthy.
@@ -34,7 +34,7 @@ Use with the [`else`] statement:
 {{ end }}
 ```

-Use `else if` to check multiple conditions.
+Use `else if` to check multiple conditions:

 ```go-html-template
 {{ $var := 12 }}
@@ -36,6 +36,20 @@ Use with the [`else`] statement:
 {{ end }}
 ```

+Use `else with` to check multiple conditions:
+
+```go-html-template
+{{ $v1 := 0 }}
+{{ $v2 := 42 }}
+{{ with $v1 }}
+  {{ . }}
+{{ else with $v2 }}
+  {{ . }} → 42
+{{ else }}
+  {{ print "v1 and v2 are falsy" }}
+{{ end }}
+```
+
 Initialize a variable, scoped to the current block:

 ```go-html-template
@@ -0,0 +1,112 @@
+---
+title: transform.ToMath
+description: Renders a math expression using KaTeX.
+categories: []
+keywords: []
+action:
+  aliases: []
+  related:
+    - content-management/mathematics
+  returnType: types.Result[template.HTML]
+  signatures: ['transform.ToMath EXPRESSION [OPTIONS]']
+aliases: [/functions/tomath]
+toc: true
+---
+
+{{< new-in "0.132.0" >}}
+
+{{% note %}}
+This feature was introduced in Hugo 0.132.0 and is marked as experimental.
+
+This does not mean that it's going to be removed, but this is our first use of WASI/Wasm in Hugo, and we need to see how it [works in the wild](https://github.com/gohugoio/hugo/issues/12736) before we can set it in stone.
+{{% /note %}}
+
+## Arguments
+
+EXPRESSION
+: The math expression to render using KaTeX.
+
+OPTIONS
+: A map of zero or more options.
+
+## Options
+
+These are a subset of the [KaTeX options].
+
+output
+: (`string`). Determines the markup language of the output. One of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
+
+    <!-- Indent to prevent spliting the description list. -->
+
+    With `html` and `htmlAndMathml` you must include KaTeX CSS within the `head` element of your base template. For example:
+
+    ```html
+    <head>
+      ...
+      <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">
+      ...
+    </head>
+    ```
+
+displayMode
+: (`bool`) If `true` render in display mode, else render in inline mode. Default is `false`.
+
+leqno
+: (`bool`) If `true` render with the equation numbers on the left. Default is `false`.
+
+fleqn
+: (`bool`) If `true` render flush left with a 2em left margin. Default is `false`.
+
+minRuleThickness
+: (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`.
+
+macros
+: (`map`) A map of macros to be used in the math expression. Default is `{}`.
+
+throwOnError
+: (`bool`) If `true` throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTex. See [error handling]. Default is `true`.
+
+errorColor
+: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`.
+
+## Examples
+
+### Basic
+
+```go-html-template
+{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}
+```
+
+### Macros
+
+```go-html-template
+{{ $macros := dict 
+    "\\addBar" "\\bar{#1}"
+    "\\bold" "\\mathbf{#1}"
+}}
+{{ $opts := dict "macros" $macros }}
+{{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}
+```
+
+## Error handling
+
+There are 3 ways to handle errors from KaTeX:
+
+1. Let KaTeX throw an error and make the build fail. This is the default behavior.
+1. Handle the error in your template. See the render hook example below.
+1. Set the `throwOnError` option to `false` to make KaTeX render the expression as an error instead of throwing an error. See [options].
+
+{{< code file=layouts/_default/_markup/render-passthrough-inline.html copy=true >}}
+{{ with transform.ToMath .Inner }}
+  {{ with .Err }}
+    {{ errorf "Failed to render KaTeX: %q. See %s" . $.Position }}
+  {{ else }}
+    {{ . }}
+  {{ end }}
+{{ end }}
+{{- /* chomp trailing newline */ -}}
+{{< /code >}}
+
+[error handling]: #error-handling
+[KaTeX options]: https://katex.org/docs/options.html
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
@@ -238,7 +238,7 @@ This is the default configuration for the AsciiDoc renderer:

 ###### attributes

-(`map`) A map of key-value pairs, each a document attributes,See Asciidoctor’s [attributes].
+(`map`) A map of key-value pairs, each a document attributes. See Asciidoctor’s [attributes].

 [attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions

@@ -302,6 +302,51 @@ To mitigate security risks, entries in the extension array may not contain forwa
        my-attribute-name = "my value"
 {{< /code-toggle >}}

+### AsciiDoc syntax highlighting
+
+Follow the steps below to enable syntax highlighting.
+
+Step 1
+: Set the `source-highlighter` attribute in your site configuration. For example:
+
+{{< code-toggle file=hugo >}}
+[markup.asciidocExt.attributes]
+source-highlighter = 'rouge'
+{{< /code-toggle >}}
+
+Step 2
+: Generate the highlighter CSS. For example:
+
+```text
+rougify style monokai.sublime > assets/css/syntax.css
+```
+
+Step 3
+: In your base template add a link to the CSS file:
+
+{{< code file=layouts/_default/baseof.html >}}
+<head>
+  ...
+  {{ with resources.Get "css/syntax.css" }}
+    <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+  {{ end }}
+  ...
+</head>
+{{< /code >}}
+
+Then add the code to be highlighted to your markup:
+
+```text
+[#hello,ruby]
+----
+require 'sinatra'
+
+get '/hi' do
+  "Hello World!"
+end
+----
+```
+
 ### AsciiDoc troubleshooting

 Run `hugo --logLevel debug` to examine Hugo's call to the Asciidoctor executable:
--- a/Show More
+++ b/Show More