build date into footer (alternative to "git-revision-date-localized")

[buhtz]

I am aware of the "git-revision-date-localized" plugin and its fallback_to_build_date option.

I want to have the build date (execution of mkdocs build) in the footer (or somewhere else) of each HTML page. The fallback_to_build_date only works if there is no git repo. But in my case there is one.

EDIT:
Accidentialy found this discussion recommending build_date_utc.

But I don't understand how to use "build_date_utc". Is this an option I can activate in the config file?

[kamilkrzyskow]

Hello @buhtz,
as per the documentation build_date_utc is under the Global context section.

The context is generated and passed to the templates with set variables, and it can be modified by plugins in events:

• https://www.mkdocs.org/dev-guide/plugins/#on_page_context
• https://www.mkdocs.org/dev-guide/plugins/#on_template_context

You can use template overrides to create a modified version of the partials/footer.html template:

• https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme
• Raw source
• Minified version

To access and print the variable use the Jinja2 syntax:
{{ build_date_utc }}

To detect changes during mkdocs serve in your overrides use the --watch-theme flag.

[buhtz]

Thank you for explaining that. That was not mentioned in the docs about "build_date_utc". From my users perspective this is kind of hacking (manipulate templates) and not configuration. Because of that I won't use that feature.

[alexvoss]

Please note that it is impossible to make everything configurable, so customizing the theme is normal, expected usage. The build_date_utc variables is also documented, so there is little chance that anything in the suggestion would cause any problems. The problem behind all this is that the documentation of Material for MkDocs needs to be read in conjunction with the documentation of MkDocs, which it builds on.

[kamilkrzyskow]

MkDocs provides the option to override the templates to your liking by default:

• https://www.mkdocs.org/user-guide/configuration/#custom_dir

This is made like this by design, so I'm not sure this comes even close to "hacking" 🤔
Of course customizing a template adds a bit of overhead when updating the theme, because you'd need to make sure no new version of the modified template came out, and if it did, you'd need to sync your changes to the new version*. However, I doubt that the footer.html partial would update that often, last functional update was over a year ago.

Good practice of managing packages is to pin their version in your requirements.txt or other management file, and only update them periodically on your own terms:

• mkdocs-material==9.5.42 would keep the same version
• mkdocs-material~=9.5.42 would allow for patch updates to be automatically installed

I believe any "structural" template changes would require at least a minor version update, but I'm not sure 🤔

* I've once written a hook that would dynamically inject the wanted changes to the templates as long they're compatible, even though they have updated. But this is hacking, as the hook influences the default behaviour during runtime:

• How to dynamically override templates with hooks? #5060