diff --git a/docs/howto/use-in-alpine-docker.md b/docs/howto/use-in-alpine-docker.md new file mode 100644 index 0000000..1a0da96 --- /dev/null +++ b/docs/howto/use-in-alpine-docker.md @@ -0,0 +1,36 @@ +# Use in Alpine Linux Docker + +When using this plugin in a Docker container based on Alpine Linux, you may encounter the following error: + +```text +LookupError: Unknown timezone UTC +``` + +This happens because Alpine Linux, being a minimal distribution, does not include timezone data by default. The [babel](https://github.com/python-babel/babel) library used by this plugin requires timezone information to function correctly. + +## Solution + +Install the `tzdata` package in your Alpine-based Docker image: + +```dockerfile +# Install timezone data +RUN apk add --no-cache tzdata +``` + +!!! example "Example Dockerfile" + + ```dockerfile + FROM python:3.12-alpine + + # Install timezone data for babel/mkdocs-git-revision-date-localized-plugin + RUN apk add --no-cache tzdata git + + # Install MkDocs and plugins + RUN pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin + + WORKDIR /docs + ``` + +!!! tip "Why this is needed" + + The Python `zoneinfo` module relies on system-level timezone data to resolve timezone names like "UTC". Without the `tzdata` package installed, Alpine Linux does not have this data available, causing the `LookupError`. diff --git a/mkdocs.yml b/mkdocs.yml index 5859daa..a4550bf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,6 +10,7 @@ nav: - howto/specify-locale.md - howto/custom-styling.md - howto/override-a-theme.md + - howto/use-in-alpine-docker.md - options.md theme: