timvink/mkdocs-git-revision-date-localized-plugin

MkDocs plugin to add a last updated date to your site pages

mkdocs-git-revision-date-localized-plugin

MkDocs plugin that enables displaying the date of the last git modification of a page. The plugin uses babel and timeago.js to provide different localized date formats. Initial fork from mkdocs-git-revision-date-plugin.

(Example when used together with the mkdocs-material theme)

Other MkDocs plugins that use information from git:

• mkdocs-git-authors-plugin for displaying the authors from git
• mkdocs-git-committers-plugin for displaying authors' github user profiles

Setup

Install the plugin using pip3 with the following command:

pip3 install mkdocs-git-revision-date-localized-plugin

Next, add the following lines to your mkdocs.yml:

plugins:
  - search
  - git-revision-date-localized

If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set.

The mkdocs-material theme supports git-revision-date-localized. After installing the plugin and updating your mkdocs.yml you should see the last revision date on the bottom of your pages. Other mkdocs themes require additional customization.

See the documentation on how to fine-tune the appearance and the date format.

Note when using build environments

This plugin needs access to the last commit that touched a specific file to be able to retrieve the date. By default many build environments only retrieve the last commit, which means you might need to:

Change your CI settings

• github actions: set fetch-depth to 0 (docs)
• gitlab runners: set GIT_DEPTH to 0 (docs)
• bitbucket pipelines: set clone: depth: full (docs)

Documentation

See timvink.github.io/mkdocs-git-revision-date-localized-plugin.

Contributing

Contributions are very welcome! Please read CONTRIBUTING.md before putting in any work.

mkdocs-git-revision-date-localized-plugin's Issues

Get raw values, without HTML tags

Hi,

Is there any way to get the plain data value, without the HTML tag ?
Right know the {{ page.meta.git_revision_date_localized }} and {{ page.meta.git_creation_date_localized }} renders in a span tag.

<span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date">2021-11-3</span>

There should be an option to be able to use only the date value.

I need this to be able to create custom meta tags for: article:published_time & article:modified_time properties like this:

<meta property="article:published_time" content="{{ page.meta.git_creation_date_localized }}">
<meta property="article:modified_time" content="{{ page.meta.git_revision_date_localized }}">

Thanks

docker git.exc.InvalidGitRepositoryError: /docs/docs

Here's what happened to me

First

docker run -it -p 9004:8000 --name demo-mkdown9004 --rm  -v ${PWD}:/docs squidfunk/mkdocs-material

And output like this:

INFO    -  Building documentation...
WARNING -  Config value: 'plugins'. Warning: ('allback_to_build_date', 'Unrecognised configuration name: allback_to_build_date')
WARNING -  Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0' suggests a production environment or the use of a proxy to connect to the MkDocs server. However, the MkDocs' server is intended for local development purposes only. Please use a third party production-ready server instead.
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/__main__.py", line 133, in serve_command
    serve.serve(
  File "/usr/local/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 141, in serve
    config = builder()
  File "/usr/local/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 136, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 236, in build
    config = config['plugins'].run_event('config', config)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/mkdocs_git_revision_date_localized_plugin/plugin.py", line 36, in on_config
    self.util = Util(path=config["docs_dir"])
  File "/usr/local/lib/python3.8/site-packages/mkdocs_git_revision_date_localized_plugin/util.py", line 14, in __init__
    git_repo = Repo(path, search_parent_directories=True)
  File "/usr/local/lib/python3.8/site-packages/git/repo/base.py", line 181, in __init__
    raise InvalidGitRepositoryError(epath)
git.exc.InvalidGitRepositoryError: /docs/docs

Why does adding the following configuration cause above error

  - git-revision-date-localized:
      type: date
      fallback_to_build_date: true

When I annotate the configuration "git-revision-date-localized:", it works fine again

plugins:
  - search: # necessary for search to work
      separator: '[\s\-\.]+'
  - awesome-pages
  # - git-revision-date-localized:
  #     type: date
  #     fallback_to_build_date: true

[root@localhost demo-mkdown]# docker run -it -p 9004:8000 --name demo-mkdown9004 --rm  -v ${PWD}:/docs squidfunk/mkdocs-material
INFO    -  Building documentation...
WARNING -  Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0' suggests a production environment or the use of a proxy to connect to the MkDocs server. However, the MkDocs' server is intended for local development purposes only. Please use a third party production-ready server instead.
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.75 seconds
[I 200704 04:47:29 server:334] Serving on http://0.0.0.0:8000
INFO    -  Serving on http://0.0.0.0:8000
[I 200704 04:47:29 handlers:62] Start watching changes
INFO    -  Start watching changes
[I 200704 04:47:29 handlers:64] Start detecting changes
INFO    -  Start detecting changes
[I 200704 04:47:36 handlers:135] Browser Connected: http://192.168.136.40:9004/
INFO    -  Browser Connected: http://192.168.136.40:9004/

[pr discuss] Add {{git_creation_date_localized}}

Hi!

I added the ability for this plugin to add creation dates to pages. (Because I need it for my personal blog) (repo)

Since CONTRIBUTING.md wrote "...That means not extending the functionality of this plugin", I'm wondering whether my pr of adding this functionality will be accepted?

If it won't, I won't bother writing tests for it :)

Update timeago.js

Right now, timeago.js is stuck on a release from years ago. It would be nice if it could be upgraded to the latest version.

Setup codecov token on github actions

Builds are failing for PR's from others to this repo with:

HTTP 400
Please provide the repository token to upload reports via `-t :repository-token`
##[error]Codecov failed with the following error: The process 'bash' failed with exit code 1

This is because:

Secrets are not passed to workflows that are triggered by a pull request from a fork.

I need to setup a token instead.

MkDocs can't build or serve when setting plugin locale

Background

Tried out this plugin using MkDocs and Material for MkDocs. Initially it didn't work at all when I set type: date and locale: en. I checked the docs from https://squidfunk.github.io/mkdocs-material/extensions/revision-date/ and used the config as stated there as I wanted date and my theme language was en:

plugins:
  - git-revision-date-localized

Everything worked locally using both mkdocs serve and mkdocs build and I added mkdocs-git-revision-date-localized-plugin==0.3.3 to my requirements.txt that is called through my Jenkinsfile.

The build then failed with the exakt error message as on line 33 from plugin.py, "WARNING - plugin locale setting '{plugin_locale}' will overwrite mkdocs locale '{mkdocs_locale}'". No filled in variables, just the straight error message from the console.

So I decided to try it out more locally and what I found out was that locally the mkdocs_locale = config.get('locale') returns None. So when the mkdocs_locale is None and I set the plugin_locale to anything, including the default en both serve and build fails locally.

I have unfortunately not found any useful info so far on how to set a mkdocs_locale .

System

MkDocs: 1.0.4
Material for MkDocs: 4.6.0
MkDocs Git Revision: 0.3.3

mkdocs.yml

theme:
    language: en
...
plugins:
  - git-revision-date-localized:
      type: date 
      locale: en

Error message

PS C:\MkDocs> mkdocs build
WARNING - plugin locale setting 'en' will overwrite mkdocs locale 'None'
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:\MkDocs\site
ERROR   -  Error reading page 'index.md': 'NoneType' object has no attribute 'date_formats'
Traceback (most recent call last):
  File "c:\python36\lib\runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "c:\python36\lib\runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "C:\Python36\Scripts\mkdocs.exe\__main__.py", line 9, in <module>
  File "c:\python36\lib\site-packages\click\core.py", line 722, in __call__
    return self.main(*args, **kwargs)
  File "c:\python36\lib\site-packages\click\core.py", line 697, in main
    rv = self.invoke(ctx)
  File "c:\python36\lib\site-packages\click\core.py", line 1066, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "c:\python36\lib\site-packages\click\core.py", line 895, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "c:\python36\lib\site-packages\click\core.py", line 535, in invoke
    return callback(*args, **kwargs)
  File "c:\python36\lib\site-packages\mkdocs\__main__.py", line 163, in build_command
    ), dirty=not clean)
  File "c:\python36\lib\site-packages\mkdocs\commands\build.py", line 274, in build
    _populate_page(file.page, config, files, dirty)
  File "c:\python36\lib\site-packages\mkdocs\commands\build.py", line 174, in _populate_page
    'page_markdown', page.markdown, page=page, config=config, files=files
  File "c:\python36\lib\site-packages\mkdocs\plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "c:\python36\lib\site-packages\mkdocs_git_revision_date_localized_plugin\plugin.py", line 52, in on_page_markdown
    locale = self.locale
  File "c:\python36\lib\site-packages\mkdocs_git_revision_date_localized_plugin\util.py", line 22, in get_revision_date_for_file
    'date' : format_date(revision_date, format="long", locale=locale),
  File "c:\python36\lib\site-packages\babel\dates.py", line 698, in format_date
    format = get_date_format(format, locale=locale)
  File "c:\python36\lib\site-packages\babel\dates.py", line 378, in get_date_format
    return Locale.parse(locale).date_formats[format]
AttributeError: 'NoneType' object has no attribute 'date_formats'

Detach from fork tree

Since this repository is essentially different from the original, I suggest you contact GitHub support and request for it to be detached as a fork, just so the GH UI doesn’t get confused.

Add dark mode to docs

    palette:
        - media: "(prefers-color-scheme: light)"
          scheme: default
          toggle:
              icon: material/toggle-switch-off-outline
              name: Switch to dark mode
          primary: blue
          accent: blue
        - media: "(prefers-color-scheme: dark)"
          scheme: slate
          toggle:
              icon: material/toggle-switch
              name: Switch to light mode
          primary: blue
          accent: blue

More robust `count_commits()`

Not sure what caused it, but this line:

mkdocs-git-revision-date-localized-plugin/mkdocs_git_revision_date_localized_plugin/ci.py

Line 88 in b6b0d11

refs = [x.split()[0] for x in refs]

Caused a

  File "/usr/local/lib/python3.9/site-packages/mkdocs_git_revision_date_localized_plugin/ci.py", line 88, in <listcomp>
    refs = [x.split()[0] for x in refs]
IndexError: list index out of range

clean install no loader specified

@squidfunk reported in squidfunk/mkdocs-material#1373 the following error

INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
ERROR   -  Error reading page 'customization.md': no loader for this environment specified 
Traceback (most recent call last):
  File "./venv/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/click/core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/click/core.py", line 717, in main
    rv = self.invoke(ctx)
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/click/core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/click/core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/click/core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/mkdocs/__main__.py", line 134, in serve_command
    livereload=livereload
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/mkdocs/commands/serve.py", line 119, in serve
    config = builder()
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/mkdocs/commands/serve.py", line 114, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/mkdocs/commands/build.py", line 274, in build
    _populate_page(file.page, config, files, dirty)
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/mkdocs/commands/build.py", line 174, in _populate_page
    'page_markdown', page.markdown, page=page, config=config, files=files
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/mkdocs_git_revision_date_localized_plugin/plugin.py", line 67, in on_page_markdown
    return Template(markdown).render({'git_revision_date_localized': revision_date})
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/jinja2/asyncsupport.py", line 76, in render
    return original_render(self, *args, **kwargs)
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/jinja2/environment.py", line 1008, in render
    return self.environment.handle_exception(exc_info, True)
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/jinja2/environment.py", line 780, in handle_exception
    reraise(exc_type, exc_value, tb)
  File "/Users/squidfunk/Desktop/General/Sources/mkdocs-material/venv/lib/python3.7/site-packages/jinja2/_compat.py", line 37, in reraise
    raise value.with_traceback(tb)
  File "<template>", line 137, in top-level template code
TypeError: no loader for this environment specified

After a clean install:

virtualenv venv
. venv/bin/activate
pip install -r requirements.txt
pip install mkdocs-git-revision-date-localized-plugin
mkdocs serve

Moving the revision date to be below the header

I couldn't find reference material on how to move a revision date to be below the header instead of being at the footer to make it more obvious. Is there a way to do this without having to add it directly in markdown on every page?

Thanks for the great plugin!

Broken with latest MkDocs

Hello! I'm pinning a newer commit of MkDocs to include an unreleased fix for Windows mkdocs/mkdocs#1885

It seems when they release https://github.com/mkdocs/mkdocs/milestone/11 soon that this will be incompatible:

ofek@ozone ~\Desktop $ ddev docs build
Traceback (most recent call last):
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\runpy.py", line 193, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\__main__.py", line 199, in <module>
    cli()
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\click\core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\click\core.py", line 717, in main
    rv = self.invoke(ctx)
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\click\core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\click\core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\click\core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\__main__.py", line 159, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\config\base.py", line 197, in load_config
    errors, warnings = cfg.validate()
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\config\base.py", line 107, in validate
    run_failed, run_warnings = self._validate()
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\config\base.py", line 62, in _validate
    self[key] = config_option.validate(value)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\config\config_options.py", line 130, in validate
    return self.run_validation(value)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\config\config_options.py", line 591, in run_validation
    plgins[item] = self.load_plugin(item, cfg)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\config\config_options.py", line 599, in load_plugin
    Plugin = self.installed_plugins[name].load()
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\pkg_resources\__init__.py", line 2444, in load
    return self.resolve()
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\pkg_resources\__init__.py", line 2450, in resolve
    module = __import__(self.module_name, fromlist=['__name__'], level=0)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs_git_revision_date_localized_plugin\plugin.py", line 4, in <module>
    from mkdocs.utils import string_types
ImportError: cannot import name 'string_types' from 'mkdocs.utils' (C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\utils\__init__.py)

source-date was renamed to source-file

https://github.com/squidfunk/mkdocs-material/blob/409d1510440b3d1488a33213f12049a985161313/src/partials/source-date.html#L23-L24

Incompatibility with mkdocs-monorepo-plugin

Hello,

I'm opening this issue to let you know that spotify/mkdocs-monorepo-plugin seems to be incompatible with this plugin. I opened an issue on their project:

backstage/mkdocs-monorepo-plugin#12

Not all pages show the revision date

Working on a local site for myself as well as an internal docs site at work. Both get random pages that don't show a last updated timestamp even when changes have been pushed to git and released to the actual docs site.

Sometimes the timestamp shows, but if I browse to a different page then come back, it's no longer there.

Support disabling on certain pages

This would be nice as a front matter attribute or just an HTML comment, so that in cases such as a homepage, you aren't forced to have it.

Custom meta variable for date of publish of article

Hello,

thank you very much for your plugin. is very useful for me and it works.

but I have one little problem, because it automatically generate at end of article information about last update.

I have my custom meta variable PublishedDate like

---
template: overrides/main.html
PublishedDate: 01.12.2020
---

it is possible add of support of this variable from your side? because I would like to avoid editing the template, if is possible.

and if is possible define of possition of update information in article (top/end), it will be great. :)

thank you very much for your help.

Add build_date

Current behaviour is that if git is not available (due to new projects, or shallow clones in CI), there is an error advising to enable fallback_to_build_date.

Build date and revision date are actually two separate things. The correct behaviour for revision_date should be to throw an error, and then optionally silence it with parameters. (as discussed in #26)

Additionally a new build_date tag can be made available, where is it advised to also silence git errors.

Create weekly github action that runs tests against latest versions of dependencies

Basically it's a unit test run on a cronjob.

Here's an example:
https://github.com/ing-bank/probatus/blob/main/.github/workflows/cronjob_unit_tests.yml

Multiple/wrong warnings printed in CI

When I built my site in our GitLabi CI setup, I got the following output multiple times:

WARNING:root:
                [git-revision-date-localized-plugin] Running on a GitLab runner might lead to wrong
                Git revision dates due to a shallow git fetch depth.
                Make sure to set GIT_DEPTH to 1000 in your .gitlab-ci.yml file
                (see https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone).
                
WARNING:root:
                [git-revision-date-localized-plugin] Running on bitbucket pipelines might lead to wrong
                Git revision dates due to a shallow git fetch depth.
                Try setting "clone: depth" to "full" in your pipeline
                (see https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/
                and search 'depth').

I understand the reason for this and have already made my adjustments. But the note regarding BitBucket is wrong, as I'm not on BitBucket. Maybe the different cases could be separated by switch-case or elseif statements to show only a single one.

Also, the README of this project says to use GIT_DEPTH = 0. The warning says GIT_DEPTH = 1000. This can be confusing to new users. IMHO GIT_DEPTH = 0 is the safe default.

Remove Unable to find a git directory and/or git is not installed warning on local only builds

When working on a local only docs site, is there a way to not let this warning show up? When you get to having many pages it becomes a useless nuisance as we already know there is no git configuration set.

Newly created file: Python error when trying to get timestamp

This happens to a newly created md file, which is not yet under version control:

      File "/usr/local/lib/python3.7/site-packages/mkdocs_git_revision_date_localized_plugin/util.py", line 22, in get_revision_date_for_file
        unix_timestamp = int(self.g.log(path, n=1, date='short', format='%at'))
    ValueError: invalid literal for int() with base 10: ''

After a git commit mkdocs serve works as usual.

timeago is static

I optimistically added the type: timeago option, but only now realise this is fixed after building and thus quite static (unless you rebuild your website very regularly..)

Either I should remove the type, or update README to explain how to use timeago.js with mkdocs.

Py2/3 issue with MkDocs

I'm stumbling over Python2/3 with MkDocs and want to ask you @timvink about your idea to go forward.

[Context/situation:]

I had installed mkdocs through pip3 giving me version 1.04.
Since then (i.e. on current master)) The config_options module includes the Choice type (
https://github.com/mkdocs/mkdocs/blob/c9032bd6bfde09ead2f4f879e85590d7cd6e68a6/mkdocs/config/config_options.py#L160-L186) which is exactly what I'd want to use for the aggregate_authors_on option discussed in timvink/mkdocs-git-authors-plugin#4 (comment) .

Consequentially Python3 balked at importing config_options.Choice, which is not present in MkDocs 1.04.

When I switched MkDocs to use current master git-revision-date-localized-plugin failed to import string_types from mkdocs.utils.

Further investigation reveals that MkDocs dropped Python2 support in https://github.com/openlilylib-resources/mkdocs/commit/c9032bd6bfde09ead2f4f879e85590d7cd6e68a6, removing (the need for) string_types.

That means that this plugin will break with the next MkDocs release. I suggest you take the opportunity and drop support for Python2 as well.

Until I hear from you I will stop work on the aggregation option. But I do need it. As you can see here it does make a difference when the name is identical but not the email ...

... and I know this case happens all the time, especially with longer-running projects.

Error when document has no .timeago class

Can be simulated using a template in markdown

---
template: landingpage.html
title: Gestão da Cafeicultura
---

Error:

Uncaught TypeError: Cannot read properties of undefined (reading 'getAttribute')
    at timeago_mkdocs_material.js:7
    at Object.next (bundle.d9c629a2.min.js:3)
    at t._next (bundle.d9c629a2.min.js:3)
    at t.next (bundle.d9c629a2.min.js:3)
    at bundle.d9c629a2.min.js:3
    at Ge (bundle.d9c629a2.min.js:3)
    at t.next (bundle.d9c629a2.min.js:3)
    at t.next (bundle.d9c629a2.min.js:3)
    at Object.next (bundle.d9c629a2.min.js:3)
    at t._next (bundle.d9c629a2.min.js:3)

Formatted date is not localized

Reproduce

Lets' use the fixtures used in tests, just moving from nl to fr to see more obvious difference:

1. set locale in config:

site_name: test gitrevisiondatelocalized_plugin
use_directory_urls: true

locale: fr

plugins:
    - search
    - git-revision-date-localized

2. Serve site : mkdocs serve -f .\tests\basic_setup\mkdocs_locale.yml
3. Date is not localized:

Expected result

Debug

The error is located in this line:

mkdocs-git-revision-date-localized-plugin/mkdocs_git_revision_date_localized_plugin/util.py

Line 81 in 2f8dc73

return self._date_formats(unix_timestamp)

Should pass the inherited locale:

return self._date_formats(unix_timestamp=unix_timestamp, locale=locale)

Issue with commit count?

Running mkdocs-git-revision-date-localized-plugin (0.5.2) and seeing the following error.

[Container] 2021/01/07 19:59:22 Running command poetry run mkdocs build
Traceback (most recent call last):
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/mkdocs/__main__.py", line 152, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/mkdocs/commands/build.py", line 236, in build
    config = config['plugins'].run_event('config', config)
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/mkdocs_git_revision_date_localized_plugin/plugin.py", line 36, in on_config
    self.util = Util(path=config["docs_dir"])
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/mkdocs_git_revision_date_localized_plugin/util.py", line 20, in __init__
    n_commits = commit_count(self.repo)
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/mkdocs_git_revision_date_localized_plugin/util.py", line 156, in commit_count
    refs = repo.for_each_ref().split("\n")
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/git/cmd.py", line 542, in <lambda>
    return lambda *args, **kwargs: self._call_process(name, *args, **kwargs)
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/git/cmd.py", line 1006, in _call_process
    return self.execute(call, **exec_kwargs)
  File "/codebuild/output/src095207431/src/github.com/tr/hx-site/.venv/lib/python3.8/site-packages/git/cmd.py", line 823, in execute
    raise GitCommandError(command, status, stderr_value, stdout_value)
git.exc.GitCommandError: Cmd('git') failed due to: exit code(128)
  cmdline: git for-each-re

Plugin incompatible with Python 3.5

This line makes use of an f-string which is only available with Python 3.6.

Sadly I can't have a newer Python version in my CI for now.

$ mkdocs -V
mkdocs, version 1.0.4 from /usr/local/lib/python3.5/dist-packages/mkdocs (Python 3.5)
$ mkdocs build
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 11, in <module>
    sys.exit(cli())
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 717, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/__main__.py", line 162, in build_command
    site_dir=site_dir
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/config/base.py", line 197, in load_config
    errors, warnings = cfg.validate()
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/config/base.py", line 107, in validate
    run_failed, run_warnings = self._validate()
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/config/base.py", line 62, in _validate
    self[key] = config_option.validate(value)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/config/config_options.py", line 132, in validate
    return self.run_validation(value)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/config/config_options.py", line 572, in run_validation
    plgins[item] = self.load_plugin(item, cfg)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/config/config_options.py", line 580, in load_plugin
    Plugin = self.installed_plugins[name].load()
  File "/usr/local/lib/python3.5/dist-packages/pkg_resources/__init__.py", line 2443, in load
    return self.resolve()
  File "/usr/local/lib/python3.5/dist-packages/pkg_resources/__init__.py", line 2449, in resolve
    module = __import__(self.module_name, fromlist=['__name__'], level=0)
  File "/usr/local/lib/python3.5/dist-packages/mkdocs_git_revision_date_localized_plugin/plugin.py", line 33
    print(f"WARNING - plugin locale setting '{plugin_locale}' will overwrite mkdocs locale '{mkdocs_locale}'")
                                                                                                            ^
SyntaxError: invalid syntax

我在使用过程中，有时区问题

Question

我在使用过程中，有时区问题
I have time zone problems during use（from Google Translate）

---

我来自**，Github 的时区是 +0 时区，但是**应该是 +8。
I’m from China. Github’s time zone is +0, but China should be +8.（from Google Translate）

---

示例：

• https://flc.io/blog/
  
• https://github.com/flc1125/docs/commits/master/docs/blog/index.md
  

Inserting javascript and css

Currently, I do this:

mkdocs-git-revision-date-localized-plugin/mkdocs_git_revision_date_localized_plugin/plugin.py

Lines 116 to 126 in fd2781d

	extra_js = """
	<script src="https://cdnjs.cloudflare.com/ajax/libs/timeago.js/4.0.0-beta.2/timeago.min.js"></script>
	<script src="https://cdnjs.cloudflare.com/ajax/libs/timeago.js/4.0.0-beta.2/timeago.locales.min.js"></script>
	<script>
	var nodes = document.querySelectorAll('.timeago');
	var locale = nodes[0].getAttribute('locale');
	timeago.render(nodes, locale);
	</script>
	"""
	idx = output_content.index("</body>")
	output_content = output_content[:idx] + extra_js + output_content[idx:]

But this can be done more elegantly config. Two examples in mkdocs plugins I found:

• https://github.com/andyoakley/mkdocs-nbconvert/blob/e11091cc685eb8ce9e5149dd7cf4ca2979343497/mkdocs_nbconvert/nbconvert.py#L22-L24
• https://github.com/greenape/mknotebooks/blob/a08d6c6b939af17672ae36e83c79dd9170fefb65/mknotebooks/plugin.py#L119

Add most recent update date to main page

I find it usefull to see a 'updated by' date at the bottom of each page. However, I'm looking for a way to add an overall 'last updated' date to the main page, for example to the header.

Do you have a suggestion how to do that?

'locale' is not a valid option at the mkdocs configuration level

According to the README, locale value can be set in two hierarchical ways:

1. plugins/git-revision-date-localized configuration
2. if not, fallback to the theme section

When not set, this plugin will look for locale or language options set in your theme. If also not set, the fallback is English (en)

But in fact, the plugin is also looking for a locale option at the mkdocs level:

mkdocs-git-revision-date-localized-plugin/mkdocs_git_revision_date_localized_plugin/plugin.py

Line 41 in b6647ef

mkdocs_locale = config.get("locale", "")

Problem: this option is not an accepted one in MkDocs configuration.

Sp, plugin should not look at this option.

why does timeago type need cloudflare

hi, i have noticed that when using type: timeago it requests js files from cdnjs.cloudflare.com.
could this be replaced with local files? is this really necessary ?

Roadmap / Vision

There are multiple mkdocs plugins that use information from the local git repo.

In order to simplify user experience and maintenance, I intend to merge functionality in this plugin with mkdocs-git-authors-plugin. See timvink/mkdocs-git-authors-plugin#16 for a similar roadmap issue with more details.

That means I won't be adding new functionality, but aim to create a simple, stable release that can go into 'maintenance mode'. If users want more information extracted from GIT, they can go to mkdocs-git-authors-plugin.

Reference custom translations in the docs

See https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#custom-translations

`timezone` appears not to work

Maybe I'm misinterpreting the setting, but the time when type: datetime always shows the same time regardless of timezone

I've tried setting timezone: America/Los_Angeles, timezone: US/Pacific, timezone: UTC, and timezone: Europe/Amsterdam

Time displayed doesn't change.

Compatibility with mknotebooks and type: timeago

When inserting jupyter notebooks, the revisiondate remains blank when using type: timeago:

The info is there:

<div class="md-source-date"> 
<small> Last update: <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago"><span class="timeago" datetime="2020-07-14T14:18:15+00:00" locale="en"></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date">2020-07-14</span> </small>
</div>

But it looks like the javascript injection does not work properly. Possibly #39 might fix this

Add localization for 'Last Updated'

Currently, the localization is implemented in mkdocs-material. For those not using that theme, this plugin should offer the same functionality.

Basically we move the same functionality into the plugin. We then add an option to add a localized 'Last updated: ' text.

Initially by default that option should be turned off (backward compatible). Then we can discuss mkdocs-material to remove the localization, and release a version of the plugin that sets that option to True by default.

README Dead Link Update

Hi, I noticed that the "Change your CI Settings" section has a dead link in relation to GitLab Runners (in reference to the GIT_DEPTH variable.)

The link should likely be updated to one of the following below:

• Number of Changes to Fetch during Clone
• Shallow Cloning: GIT_DEPTH

This is something minor, but easy to fix and figured I would mention it. Thanks!

`... has no git logs, using current timestamp`

I'm looking to resolve getting warnings that git logs cannot be found for any files.

I thought it was my directory structure, which is non-standard, where we have MkDocs nested one level.

root/
  .git/
  ...
  docs/    <-- Where the MkDocs builds go
  docs-source/   <--  Where the MkDocs source is
    mkdocs.yml
    src/
    theme/

I tried copying root/.git to docs-source to test this, but got the same result.

Any advice? Thanks.

In material theme does not work with navigation.instant enabled

https://squidfunk.github.io/mkdocs-material/reference/data-tables/#customization

Use only document$ in

mkdocs-git-revision-date-localized-plugin/mkdocs_git_revision_date_localized_plugin/js/timeago_mkdocs_material.js

Lines 3 to 9 in 9c6dd76

	if (
	typeof app !== "undefined" &&
	typeof app.document$ !== "undefined"
	) {
	app.document$.subscribe(function() {
	var nodes = document.querySelectorAll('.timeago');

Fix fetch-depth

Context

• GitHub action fix in the collapsible block: https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/index.html#note-when-using-build-environments

Issue

• Should be fix-depth, not fix_depth

Evidence

• Warning when running the workflow: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/actions/runs/1579704317

Revision-date updates all files.

Hi, first of all, thanks for your plugin.

I'm deploying my wiki with this github workflow. And if I change one file of the whole repository, the date get's changed in all the files.

So for example, this commit triggered this job which produced this gh-pages commit.

As you can see, the timestamp is modified in all files:

- Last update: <span class=timeago datetime=1581529194000 locale=en></span>
+ Last update: <span class=timeago datetime=1581529388000 locale=en></span>

Do you know why is this happening?

Thanks

Add type hinting to functions

mkdocs supports python 3.5, which introduced type hinting, f.e.:

def annotated(x: int, y: str) -> bool:
    return x < y

Let's add type hinting at least to the functions. And then add mypy to the github actions CI.

Add unit tests

Enabling some CI with unittests can improve the plugin quality.

mkdocs search plugin has some nice examples of how this can be done:
https://github.com/mkdocs/mkdocs/blob/master/mkdocs/tests/search_tests.py

'last_update' in PDF version not working

When building PDF versions of the website, the last updated date does not display.

Perhaps we can hide it somehow when printing PDF.

Add shields to README

I'd like to add two shields:

• License (MIT)
• Number of contributors

Take them from https://shields.io/

Partial translation

I have this test site:

• https://github.com/jrappen/recipes
• https://jrappen.github.io/recipes

where my last commit to main was built with:

and pages with the German language have footers of this plugin only partially translated:

Any feedback as to why this happens?

Unable to find a git directory and/or git is not installed

Pretty sure this is user error, but I receiving the following error.

ERROR    -  [git-revision-date-localized-plugin] Unable to find a git directory and/or git is not installed. To ignore this error, set option  'fallback_to_build_date: true'

Problem is, git is installed :

$ git status

On branch amf-userguide
Your branch is up to date with 'aforsythe/amf-userguide'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   mkdocs.yml

no changes added to commit (use "git add" and/or "git commit -a")

Had this running fine on another test instance, but can't figure out what's going wrong here. Any suggestions would be greatly appreciated.

Raise error when mkdocs-monorepo-plugin is loaded before this plugin

This plugin uses the config["docs_dir"] to find the .git folder. The monorepo plugin changes the docs_dir to a temporary folder. More context here backstage/mkdocs-monorepo-plugin#13 (comment)

We should raise an instructional error to change the plugin order in mkdocs.yml, so this plugin is always loaded first.

Examples:

Good:

plugins:
  - git-revision-date-localized
  - monorepo

Bad:

plugins:
  - monorepo
  - git-revision-date-localized