refactor code and #6 fix timeago bug

Author: timvink

README.md

@@ -4,7 +4,7 @@
 
 # mkdocs-git-revision-date-localized-plugin
 
-[MkDocs](https://www.mkdocs.org/) plugin that enables displaying the localized date of the last git modification of a markdown file. Forked from [mkdocs-git-revision-date-plugin](https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin). The plugin uses [babel](https://github.com/python-babel/babel/tree/master/babel) and [timeago](https://github.com/hustcc/timeago) to provide different localized date formats.
+[MkDocs](https://www.mkdocs.org/) plugin that enables displaying the date of the last git modification of a page. The plugin uses [babel](https://github.com/python-babel/babel/tree/master/babel) and [timeago.js](https://github.com/hustcc/timeago.js) to provide different localized date formats. Initial fork from [mkdocs-git-revision-date-plugin](https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin).
 
 ![example](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/raw/master/example.png)
 
@@ -66,7 +66,12 @@ Set this option to one of `date`, `datetime`, `iso_date`, `iso_datetime` or `tim
 
 ### `locale`
 
-Set this option to a two letter [ISO639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code to use a another language. If you have also set `locale` or `language` in your theme this setting will be ignored. If no locale is set fallback is English (`en`).
+Specify a two letter [ISO639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code to display dates in your preferred language.
+
+- When used in combination with `type: date` or `type: datetime`, translation is done using [babel](https://github.com/python-babel/babel) which supports [these locales](http://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html)
+- When used in combination with `type: timeago` then [timeago.js](https://github.com/hustcc/timeago.js) is added to your website, which supports [these locales](https://github.com/hustcc/timeago.js/tree/master/src/lang). If you specify a locale not supported by timeago.js, the fallback is English (`en`)
+- 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`)
+
 
 ### Example
 

mkdocs_git_revision_date_localized_plugin/plugin.py

@@ -1,12 +1,8 @@
 import re
-from os import environ
-
 from mkdocs.config import config_options
 from mkdocs.plugins import BasePlugin
 from mkdocs.utils import string_types
 from .util import Util
-from datetime import datetime
-
 
 class GitRevisionDateLocalizedPlugin(BasePlugin):
     config_scheme = (
@@ -17,64 +13,109 @@ class GitRevisionDateLocalizedPlugin(BasePlugin):
     def __init__(self):
         self.locale = 'en'
         self.util = Util()
-
+        
     def on_config(self, config):
+        """
+        Determine which locale to use.
+        
+        The config event is the first event called on build and 
+        is run immediately after the user configuration is loaded and validated. 
+        Any alterations to the config should be made here.
+        https://www.mkdocs.org/user-guide/plugins/#on_config
+
+        Args:
+            config (dict): global configuration object
+            
+        Returns:
+            dict: global configuration object 
+        """
 
         # Get locale settings
-        mkdocs_locale = config.get('locale')
+        mkdocs_locale = config.get('locale', '')
         plugin_locale = self.config['locale']
+        theme_locale = vars(config['theme']).get('_vars', {}).get('locale', '')
+        if theme_locale == '':
+            theme_locale = vars(config['theme']).get('_vars', {}).get('language','')
 
-        theme_locale = vars(config['theme']).get('_vars', {}).get('locale')
-        if theme_locale is None:
-            theme_locale = vars(config['theme']).get('_vars', {}).get('language')
-        
-        # First prio: theme
-        if theme_locale:
-            self.locale = theme_locale
-            return
-        
-        # Second prio: plugin locale     
+        # First prio: plugin locale     
         if plugin_locale != '':
             self.locale = plugin_locale
-            return
-        
-        # Third is mkdocs locale setting (might be added in the future)
-        if mkdocs_locale:
+        # Second prio: theme locale
+        elif theme_locale != '':
+            self.locale = theme_locale        
+        # Third prio is mkdocs locale (which might be added in the future)
+        elif mkdocs_locale != '':
             self.locale = mkdocs_locale
+        else:
+            self.locale = 'en'
+            
+        return config
+    
+    def on_post_page(self, output_content, **kwargs):
+        """
+        Add timeago.js as a CDN to the HTML page. 
+        The CDN with latest version timeago.js can be found on 
+        https://cdnjs.com/libraries/timeago.js
         
-        # If none set then english
-        self.locale = 'en'
-        return
+        The `post_template` event is called after the template is rendered, 
+        but before it is written to disc and can be used to alter the output 
+        of the page. If an empty string is returned, the page is skipped 
+        and nothing is written to disc.
         
+        https://www.mkdocs.org/user-guide/plugins/#on_post_page
 
+        Args:
+            output_content (str): output of rendered template as string
+            
+        Returns:
+            str: output of rendered template as string
+        """
+
+        if self.config['type'] != 'timeago':
+            return output_content
+        
+        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>
+            const nodes = document.querySelectorAll('.timeago');
+            const locale = nodes[0].getAttribute('locale');
+            timeago.render(nodes, locale);
+          </script>
+        """
+        idx = output_content.index("</body>")
+        return output_content[:idx] + extra_js + output_content[idx:]
+        
     def on_page_markdown(self, markdown, page, config, files):
+        """
+        Replace jinja2 tags in markdown and templates with the localized dates
+        
+        The page_markdown event is called after the page's markdown is loaded 
+        from file and can be used to alter the Markdown source text. 
+        The meta- data has been stripped off and is available as page.meta 
+        at this point.
+        
+        https://www.mkdocs.org/user-guide/plugins/#on_page_markdown
+        
+        Args:
+            markdown (str): Markdown source text of page as string
+            page: mkdocs.nav.Page instance
+            config: global configuration object
+            site_navigation: global navigation object
+            
+        Returns:
+            str: Markdown source text of page as string
+        """
 
         revision_dates = self.util.get_revision_date_for_file(
             path = page.file.abs_src_path,
             locale = self.locale
         )
         revision_date = revision_dates[self.config['type']] 
-
         page.meta['git_revision_date_localized'] = revision_date
 
-        if 'macros' in config['plugins']:
-            keys = list(config['plugins'].keys())
-            vals = list(config['plugins'].values())
-            if keys.index('macros') > vals.index(self):
-                return '{{% set git_revision_date = \'{}\' %}}\n'.format(revision_date) + markdown
-            else:
-                print('WARNING - macros plugin must be placed AFTER the git-revision-date-localized plugin. Skipping markdown modifications')
-                return markdown
-        else:
-            markdown = re.sub(r"\{\{(\s)*git_revision_date_localized(\s)*\}\}",
-                          revision_date,
-                          markdown,
-                          flags=re.IGNORECASE)
-
-            markdown = re.sub(r"\{\{\s*page\.meta\.git_revision_date_localized\s*\}\}",
-                          revision_date,
-                          markdown,
-                          flags=re.IGNORECASE)
-            
-            return markdown
+        return re.sub(r"\{\{\s*[page\.meta\.]*git_revision_date_localized\s*\}\}",
+                        revision_date,
+                        markdown,
+                        flags=re.IGNORECASE)
 

mkdocs_git_revision_date_localized_plugin/util.py

@@ -1,6 +1,5 @@
 from git import Git
 from datetime import datetime
-import timeago
 from babel.dates import format_date
 
 class Util:
@@ -9,21 +8,30 @@ def __init__(self):
         self.g = Git()
 
     def get_revision_date_for_file(self, path: str, locale: str = 'en'):
+        """
+        Determine localized date variants for a given file
+        
+        Args:
+            path (str): Location of a file that is part of a GIT repository
+            locale (str, optional): Locale code of language to use. Defaults to 'en'.
+        
+        Returns:
+            dict: localized date variants 
+        """
+        
+        unix_timestamp = int(self.g.log(path, n=1, date='short', format='%at'))
+        timestamp_in_ms = unix_timestamp * 1000
 
-        unix_timestamp =  self.g.log(path, n=1, date='short', format='%at')
         if not unix_timestamp:
             revision_date = datetime.now()
             print('WARNING -  %s has no git logs, revision date defaulting to today\'s date' % path)
         else:
-            revision_date = datetime.utcfromtimestamp(int(unix_timestamp))
+            revision_date = datetime.utcfromtimestamp(unix_timestamp)
 
-        # Localized versions
-        revision_dates = {
+        return {
             'date' : format_date(revision_date, format="long", locale=locale), 
             'datetime' : format_date(revision_date, format="long", locale=locale) + ' ' +revision_date.strftime("%H:%M:%S"),
             'iso_date' : revision_date.strftime("%Y-%m-%d"), 
             'iso_datetime' : revision_date.strftime("%Y-%m-%d %H:%M:%S"), 
-            'timeago' : timeago.format(revision_date, locale = locale)
-        }
-    
-        return revision_dates
+            'timeago' : "<span class='timeago' datetime='%s' locale='%s'></span>" % (timestamp_in_ms, locale)
+        }

setup.py

@@ -5,7 +5,7 @@
 
 setup(
     name='mkdocs-git-revision-date-localized-plugin',
-    version='0.4.2',
+    version='0.4.3',
     description='Mkdocs plugin that enables displaying the localized date of the last git modification of a markdown file.',
     long_description=long_description,
     long_description_content_type="text/markdown",
@@ -24,8 +24,7 @@
         'mkdocs>=0.17',
         'GitPython',
         'jinja2',
-        'babel>=2.7.0',
-        'timeago>=1.0.10'
+        'babel>=2.7.0'
     ],
     packages=find_packages(),
     entry_points={