Add documentation for Alpine Linux Docker usage

[Copilot]

Alpine Linux doesn't include timezone data by default, causing LookupError: Unknown timezone UTC when babel attempts to resolve timezones.

Changes

• Added docs/howto/use-in-alpine-docker.md explaining the issue and fix
• Updated mkdocs.yml navigation to include new guide

Solution

Install tzdata in Alpine-based Docker images:

RUN apk add --no-cache tzdata

Original prompt

---

This section details on the original issue you should resolve

<issue_title>v1.5.0 breaks builds with alpine</issue_title>
<issue_description>When upgrading to v2.5.0, I get the following error when using an alpine base image

Versions

• alpine 3.22.2
• mkdocs 1.6.1

Stacktrace

Traceback (most recent call last):
  File "/usr/lib/python3.12/site-packages/babel/dates.py", line 248, in get_timezone
verbose: return zoneinfo.ZoneInfo(zone)
verbose: ^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/zoneinfo/_common.py", line 24, in load_tzdata
verbose: raise ZoneInfoNotFoundError(f"No time zone found with key {key}")
zoneinfo._common.ZoneInfoNotFoundError: 'No time zone found with key UTC'
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
  File "/usr/bin/mkdocs", line 8, in <module>
verbose: sys.exit(cli())
verbose: ^^^^^
  File "/usr/lib/python3.12/site-packages/click/core.py", line 1442, in __call__
verbose: return self.main(*args, **kwargs)
verbose: ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/click/core.py", line 1363, in main
verbose: rv = self.invoke(ctx)
verbose: ^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/click/core.py", line 1830, in invoke
verbose: return _process_result(sub_ctx.command.invoke(sub_ctx))
verbose: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/click/core.py", line 1226, in invoke
verbose: return ctx.invoke(self.callback, **ctx.params)
verbose: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/click/core.py", line 794, in invoke
verbose: return callback(*args, **kwargs)
verbose: ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/mkdocs/__main__.py", line 288, in build_command
verbose: build.build(cfg, dirty=not clean)
verbose: File "/usr/lib/python3.12/site-packages/mkdocs/commands/build.py", line 310, in build
verbose: _populate_page(file.page, config, files, dirty)
verbose: File "/usr/lib/python3.12/site-packages/mkdocs/commands/build.py", line 163, in _populate_page
    page.markdown = config.plugins.on_page_markdown(
verbose: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/mkdocs/plugins.py", line 635, in on_page_markdown
verbose: return self.run_event('page_markdown', markdown, page=page, config=config, files=files)
verbose: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/mkdocs/plugins.py", line 566, in run_event
verbose: result = method(item, **kwargs)
verbose: ^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/mkdocs_git_revision_date_localized_plugin/plugin.py", line 317, in on_page_markdown
verbose: revision_dates = self.util.get_date_formats_for_timestamp(
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
verbose: File "/usr/lib/python3.12/site-packages/mkdocs_git_revision_date_localized_plugin/util.py", line 208, in get_date_formats_for_timestamp
verbose: date_formats = get_date_formats(
                   ^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/mkdocs_git_revision_date_localized_plugin/dates.py", line 32, in get_date_formats
verbose: loc_revision_date = utc_revision_date.replace(tzinfo=get_timezone("UTC")).astimezone(get_timezone(time_zone))
verbose: ^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/babel/dates.py", line 252, in get_timezone
verbose: raise LookupError(f"Unknown timezone {zone}") from exc
verbose: LookupError: Unknown timezone UTC

Tried workaround

I tried installing tzdata on system level:

• Installing tzdata package
• Adding TZ=UTC env variable
  Which did not seem to work</issue_description>

<agent_instructions>The user suggested updating the docs on how to use it on alpine docker. See the docs/ folder and add the info in the right spot. Note we use mkdocs-material so you can syntax like code blocks and admonitions. </agent_instructions>

Comments on the Issue (you are @copilot in this section)

@timvink Alpine Linux, being a minimal distribution, often omits the standard timezone information to keep the image small. The Python `babel` library (used by mkdocs_git_revision_date_localized_plugin) relies on this system-level timezone data to function correctly.

You need to add tzdata to your build

# Install timezone data
RUN apk add --no-cache tzdata

You can also try adding the pytz and tzdata python packages, but I think the above will already resolve it. </comment_new>
<comment_new>@timvink
Here are the changes: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/pull/193/files#diff-50c86b7ed8ac2cf95bd48334961bf0530cdc77b5a56f852c5c61b89d735fd711

So installing tzdata should do the trick. Did you manage to fix it?

• Fixes v1.5.0 breaks builds with alpine #197

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.