Document usage of official Docker image

Closes gohugoio#2727

content/en/installation/bsd.md

@@ -64,12 +64,59 @@ doas pkg_add hugo
 
 {{% include "installation/_common/04-build-from-source.md" %}}
 
+## Docker container
+
+### Prerequisites
+
+Before running the Docker container locally you must install Docker. See the [installation instructions].
+
+When building your production site in a [CI/CD] workflow, whether you can run the Docker container depends on the service provider. For example, GitHub Pages and GitLab Pages allow you to run the Docker container.
+
+To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists:
+
+```text
+mkdir -p $HOME/.cache/hugo_cache
+```
+
+[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
+[installation instructions]: https://wiki.freebsd.org/Docker
+
+### Commands
+
+To build your site using the latest version:
+
+{{< code copy=true >}}
+docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest build
+{{< /code >}}
+
+To build your site and start the embedded web server using the latest version:
+
+{{< code copy=true >}}
+docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest server --bind="0.0.0.0"
+{{< /code >}}
+
+To use a specific version, in the commands above replace `latest` with any of the [tagged image versions]. For example, to build your site using v0.136.1:
+
+{{< code copy=true >}}
+docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:v0.136.1 build
+{{< /code >}}
+
+[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
+
+### Cache directory
+
+Attaching the host's Hugo cache directory to the container can significantly enhance performance, particularly for large and image-heavy sites. This allows Hugo to reuse previously generated content, reducing the need for repeated processing and transpilation.
+
+If you are using a custom Hugo cache directory, in the commands above replace `$HOME/.cache/hugo_cache` with the absolute path to your cache directory.
+
 ## Comparison
 
-||Prebuilt binaries|Repository packages|Build from source
-:--|:--:|:--:|:--:
-Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
-Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
-Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
-Automatic updates?|:x:|varies|:x:
-Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:
+||Prebuilt binaries|Repository packages|Build&nbsp;from source|Docker container
+:--|:-:|:-:|:-:|:-:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:[^1]
+Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
+Automatic updates?|:x:|varies|:x:|:x:
+Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
+
+[^1]: Docker containers don't require installation. However, installing Docker itself can be complex.

content/en/installation/linux.md

@@ -181,15 +181,62 @@ sudo eopkg install hugo
 
 {{% include "installation/_common/04-build-from-source.md" %}}
 
+## Docker container
+
+### Prerequisites
+
+Before running the Docker container locally you must install Docker Desktop or Docker Engine. See the installation instructions for either [Docker Desktop] or [Docker Engine].
+
+When building your production site in a [CI/CD] workflow, whether you can run the Docker container depends on the service provider. For example, GitHub Pages and GitLab Pages allow you to run the Docker container.
+
+To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists:
+
+```text
+mkdir -p $HOME/.cache/hugo_cache
+```
+
+[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
+[docker desktop]: https://docs.docker.com/desktop/install/linux/
+[docker engine]: https://docs.docker.com/engine/install/
+
+### Commands
+
+To build your site using the latest version:
+
+{{< code copy=true >}}
+docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest build
+{{< /code >}}
+
+To build your site and start the embedded web server using the latest version:
+
+{{< code copy=true >}}
+docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest server --bind="0.0.0.0"
+{{< /code >}}
+
+To use a specific version, in the commands above replace `latest` with any of the [tagged image versions]. For example, to build your site using v0.136.1:
+
+{{< code copy=true >}}
+docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:v0.136.1 build
+{{< /code >}}
+
+[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
+
+### Cache directory
+
+Attaching the host's Hugo cache directory to the container can significantly enhance performance, particularly for large and image-heavy sites. This allows Hugo to reuse previously generated content, reducing the need for repeated processing and transpilation.
+
+If you are using a custom Hugo cache directory, in the commands above replace `$HOME/.cache/hugo_cache` with the absolute path to your cache directory.
+
 ## Comparison
 
-||Prebuilt binaries|Package managers|Repository packages|Build from source
-:--|:--:|:--:|:--:|:--:
-Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
-Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
-Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|varies|:heavy_check_mark:
-Automatic updates?|:x:|varies [^2]|:x:|:x:
-Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
+||Prebuilt binaries|Package managers|Repository packages|Build&nbsp;from source|Docker container
+:--|:-:|:-:|:-:|:-:|:-:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:[^3]
+Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|varies|:heavy_check_mark:|:heavy_check_mark:
+Automatic updates?|:x:|varies [^2]|:x:|:x:|:x:
+Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark:
 
 [^1]: Easy if a previous version is still installed.
 [^2]: Snap packages are automatically updated. Homebrew requires advanced configuration.
+[^3]: Docker containers don't require installation. However, installing Docker itself can be complex.

content/en/installation/macos.md

@@ -32,15 +32,61 @@ sudo port install hugo
 
 {{% include "installation/_common/04-build-from-source.md" %}}
 
+## Docker container
+
+### Prerequisites
+
+Before running the Docker container locally you must install Docker Desktop. See the [installation instructions].
+
+When building your production site in a [CI/CD] workflow, whether you can run the Docker container depends on the service provider. For example, GitHub Pages and GitLab Pages allow you to run the Docker container.
+
+To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists:
+
+```text
+mkdir -p $HOME/Library/Caches/hugo_cache
+```
+
+[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
+[installation instructions]: https://docs.docker.com/desktop/install/mac-install/
+
+### Commands
+
+To build your site using the latest version:
+
+{{< code copy=true >}}
+docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest build
+{{< /code >}}
+
+To build your site and start the embedded web server using the latest version:
+
+{{< code copy=true >}}
+docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest server --bind="0.0.0.0"
+{{< /code >}}
+
+To use a specific version, in the commands above replace `latest` with any of the [tagged image versions]. For example, to build your site using v0.136.1:
+
+{{< code copy=true >}}
+docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:v0.136.1 build
+{{< /code >}}
+
+[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
+
+### Cache directory
+
+Attaching the host's Hugo cache directory to the container can significantly enhance performance, particularly for large and image-heavy sites. This allows Hugo to reuse previously generated content, reducing the need for repeated processing and transpilation.
+
+If you are using a custom Hugo cache directory, in the commands above replace `$HOME/Library/Caches/hugo_cache` with the absolute path to your cache directory.
+
 ## Comparison
 
-||Prebuilt binaries|Package managers|Build from source
-:--|:--:|:--:|:--:
-Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|
-Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
-Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|:heavy_check_mark:
-Automatic updates?|:x:|:x: [^2]|:x:
-Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+||Prebuilt binaries|Package managers|Build&nbsp;from source|Docker container
+:--|:-:|:-:|:-:|:-:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:[^3]
+Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|:heavy_check_mark:|:heavy_check_mark:
+Automatic updates?|:x:|:x: [^2]|:x:|:x:
+Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
 
 [^1]: Easy if a previous version is still installed.
 [^2]: Possible but requires advanced configuration.
+[^3]: Docker containers don't require installation. However, installing Docker itself can be complex.

content/en/installation/windows.md

@@ -59,15 +59,61 @@ winget install Hugo.Hugo.Extended
 See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
 {{% /note %}}
 
+## Docker container
+
+### Prerequisites
+
+Before running the Docker container locally you must install Docker Desktop. See the [installation instructions].
+
+When building your production site in a [CI/CD] workflow, whether you can run the Docker container depends on the service provider. For example, GitHub Pages and GitLab Pages allow you to run the Docker container.
+
+To prevent ownership and permission problems, create the Hugo [cache directory](#cache-directory) and ignore the error if the directory already exists:
+
+```text
+mkdir -f %LocalAppData%/hugo_cache
+```
+
+[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
+[installation instructions]: https://docs.docker.com/desktop/install/windows-install/
+
+### Commands
+
+To build your site using the latest version:
+
+{{< code copy=true >}}
+docker run --rm -v .:/project -v %LocalAppData%/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest build
+{{< /code >}}
+
+To build your site and start the embedded web server using the latest version:
+
+{{< code copy=true >}}
+docker run --rm -v .:/project -v %LocalAppData%/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest server --bind="0.0.0.0"
+{{< /code >}}
+
+To use a specific version, in the commands above replace `latest` with any of the [tagged image versions]. For example, to build your site using v0.136.1:
+
+{{< code copy=true >}}
+docker run --rm -v .:/project -v %LocalAppData%/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:v0.136.1 build
+{{< /code >}}
+
+[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
+
+### Cache directory
+
+Attaching the host's Hugo cache directory to the container can significantly enhance performance, particularly for large and image-heavy sites. This allows Hugo to reuse previously generated content, reducing the need for repeated processing and transpilation.
+
+If you are using a custom Hugo cache directory, in the commands above replace `%LocalAppData%/hugo_cache` with the absolute path to your cache directory.
+
 ## Comparison
 
-||Prebuilt binaries|Package managers|Build from source
-:--|:--:|:--:|:--:
-Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|
-Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
-Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^2]|:heavy_check_mark:
-Automatic updates?|:x:|:x: [^1]|:x:
-Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+||Prebuilt binaries|Package managers|Build&nbsp;from source|Docker container
+:--|:-:|:-:|:-:|:-:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:[^3]
+Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^2]|:heavy_check_mark:|:heavy_check_mark:
+Automatic updates?|:x:|:x: [^1]|:x:|:x:
+Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
 
 [^1]: Possible but requires advanced configuration.
 [^2]: Easy if a previous version is still installed.
+[^3]: Docker containers don't require installation. However, installing Docker itself can be complex.