Document usage of official Docker image

jmooring · jmooring · commit 6d89b4d1affb · 2026-02-14T13:37:28.000-08:00
diff --git a/content/en/installation/bsd.md b/content/en/installation/bsd.md
@@ -16,8 +16,6 @@ weight: 40
 
 Most BSD derivatives maintain a repository for commonly installed applications. Please note that these repositories may not contain the [latest release].
 
-[latest release]: https://github.com/gohugoio/hugo/releases/latest
-
 ### DragonFly BSD
 
 [DragonFly BSD] includes Hugo in its package repository. To install the extended edition of Hugo:
@@ -26,8 +24,6 @@ Most BSD derivatives maintain a repository for commonly installed applications.
 sudo pkg install gohugo
 ```
 
-[DragonFly BSD]: https://www.dragonflybsd.org/
-
 ### FreeBSD
 
 [FreeBSD] includes Hugo in its package repository. To install the extended edition of Hugo:
@@ -36,8 +32,6 @@ sudo pkg install gohugo
 sudo pkg install gohugo
 ```
 
-[FreeBSD]: https://www.freebsd.org/
-
 ### NetBSD
 
 [NetBSD] includes Hugo in its package repository. To install the extended edition of Hugo:
@@ -46,8 +40,6 @@ sudo pkg install gohugo
 sudo pkgin install go-hugo
 ```
 
-[NetBSD]: https://www.netbsd.org/
-
 ### OpenBSD
 
 [OpenBSD] includes Hugo in its package repository. This will prompt you to select which edition of Hugo to install:
@@ -56,8 +48,6 @@ sudo pkgin install go-hugo
 doas pkg_add hugo
 ```
 
-[OpenBSD]: https://www.openbsd.org/
-
 {{% include "/_common/installation/04-build-from-source.md" %}}
 
 ## Comparison
diff --git a/content/en/installation/linux.md b/content/en/installation/linux.md
@@ -172,6 +172,46 @@ sudo xbps-install -S hugo
 
 {{% include "/_common/installation/04-build-from-source.md" %}}
 
+## Docker container
+
+### Prerequisites {#docker-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](g) 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
+```
+
+### Commands
+
+To build your site using the latest version:
+
+```sh {copy=true}
+docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
+```
+
+To build your site and start the embedded web server using the latest version:
+
+```sh {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"
+```
+
+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:
+
+```sh {copy=true}
+docker run --rm -v .:/project -v $HOME/.cache/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
+```
+
+### 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
 
 &nbsp;|Prebuilt binaries|Package managers|Repository packages|Build from source
@@ -190,6 +230,8 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_ch
 [Calculate Linux]: https://www.calculate-linux.org/
 [CentOS]: https://www.centos.org/
 [Debian]: https://www.debian.org/
+[Docker Desktop]: https://docs.docker.com/desktop/setup/install/linux/
+[Docker Engine]: https://docs.docker.com/engine/install/
 [elementary OS]: https://elementary.io/
 [EndeavourOS]: https://endeavouros.com/
 [Exherbo]: https://www.exherbolinux.org/
@@ -210,6 +252,7 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_ch
 [Pop!_OS]: https://pop.system76.com/
 [Red Hat Enterprise Linux]: https://www.redhat.com/
 [Solus]: https://getsol.us/
+[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
 [Ubuntu]: https://ubuntu.com/
 [USE]: https://packages.gentoo.org/packages/www-apps/hugo
 [Void Linux]: https://voidlinux.org/
diff --git a/content/en/installation/macos.md b/content/en/installation/macos.md
@@ -24,10 +24,48 @@ weight: 10
 sudo port install hugo
 ```
 
-[MacPorts]: https://www.macports.org/
-
 {{% include "/_common/installation/04-build-from-source.md" %}}
 
+## Docker container
+
+### Prerequisites {#docker-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](g) 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
+```
+
+### Commands
+
+To build your site using the latest version:
+
+```sh {copy=true}
+docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
+```
+
+To build your site and start the embedded web server using the latest version:
+
+```sh {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"
+```
+
+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:
+
+```sh {copy=true}
+docker run --rm -v .:/project -v $HOME/Library/Caches/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
+```
+
+### 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
 
 &nbsp;|Prebuilt binaries|Package managers|Build from source
@@ -40,3 +78,7 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mar
 
 [^1]: Easy if a previous version is still installed.
 [^2]: Possible but requires advanced configuration.
+
+[installation instructions]: https://docs.docker.com/desktop/install/mac-install/
+[MacPorts]: https://www.macports.org/
+[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
diff --git a/content/en/installation/windows.md b/content/en/installation/windows.md
@@ -52,6 +52,49 @@ winget uninstall --name "Hugo (Extended)"
 > [!note]
 > See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
 
+## Docker container
+
+> [!note]
+> Run the commands in this section from [PowerShell] or a Linux terminal such as WSL or Git Bash. Do not use the Command Prompt.
+
+### Prerequisites {#docker-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](g) 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 $Env:LocalAppData/hugo_cache
+```
+
+### Commands
+
+To build your site using the latest version:
+
+```sh {copy=true}
+docker run --rm -v .:/project -v $Env:LocalAppData/hugo_cache:/cache ghcr.io/gohugoio/hugo:latest build
+```
+
+To build your site and start the embedded web server using the latest version:
+
+```sh {copy=true}
+docker run --rm -v .:/project -v $Env:LocalAppData/hugo_cache:/cache -p 1313:1313 ghcr.io/gohugoio/hugo:latest server --bind="0.0.0.0"
+```
+
+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:
+
+```sh {copy=true}
+docker run --rm -v .:/project -v $Env:LocalAppData/hugo_cache:/cache ghcr.io/gohugoio/hugo:v0.136.1 build
+```
+
+### 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
 
 &nbsp;|Prebuilt binaries|Package managers|Build from source
@@ -66,5 +109,8 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mar
 [^2]: Easy if a previous version is still installed.
 
 [Chocolatey]: https://chocolatey.org/
+[installation instructions]: https://docs.docker.com/desktop/install/windows-install/
+[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
 [Scoop]: https://scoop.sh/
+[tagged image versions]: https://github.com/gohugoio/hugo/pkgs/container/hugo/versions?filters%5Bversion_type%5D=tagged
 [Winget]: https://learn.microsoft.com/en-us/windows/package-manager/
