Metadata-Version: 2.1
Name: mkdocs-git-revision-date-localized-plugin
Version: 0.7
Summary: Mkdocs plugin that enables displaying the localized date of the last git modification of a markdown file.
Home-page: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
Author: Tim Vink
Author-email: vinktim@gmail.com
License: MIT
Description: [![Actions Status](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/workflows/pytest/badge.svg)](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/actions)
        ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mkdocs-git-revision-date-localized-plugin)
        ![PyPI](https://img.shields.io/pypi/v/mkdocs-git-revision-date-localized-plugin)
        ![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-git-revision-date-localized-plugin)
        [![codecov](https://codecov.io/gh/timvink/mkdocs-git-revision-date-localized-plugin/branch/master/graph/badge.svg)](https://codecov.io/gh/timvink/mkdocs-git-revision-date-localized-plugin)
        ![GitHub contributors](https://img.shields.io/github/contributors/timvink/mkdocs-git-revision-date-localized-plugin)
        ![PyPI - License](https://img.shields.io/pypi/l/mkdocs-git-revision-date-localized-plugin)
        
        # mkdocs-git-revision-date-localized-plugin
        
        [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).
        
        ![demo](demo_screencast.gif)
        
        (*Example when used together with the [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme*)
        
        ## Setup
        
        Install the plugin using `pip3` with the following command:
        
        ```bash
        pip3 install mkdocs-git-revision-date-localized-plugin
        ```
        
        Next, add the following lines to your `mkdocs.yml`:
        
        ```yaml
        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.
        
        ### 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:
        <details>
          <summary>Change your CI settings</summary>
          
          - github actions: set `fetch_depth` to `0` ([docs](https://github.com/actions/checkout))
          - gitlab runners: set `GIT_DEPTH` to `1000` ([docs](https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone))
          - bitbucket pipelines: set `clone: depth: full` ([docs](https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/))
        </details>
        
        
        ## Usage
        
        ### In supported themes
        
        - [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) offers native support for this plugin, see [setup instructions](https://squidfunk.github.io/mkdocs-material/plugins/revision-date/)
        
        ### In markdown pages
        
        In your markdown files you can use the `{{ git_revision_date_localized }}` tag anywhere you'd like:
        
        ```django hljs
        Last update: {{ git_revision_date_localized }}
        ```
        
        ### In custom themes
        
        When writing your own [custom themes](https://www.mkdocs.org/user-guide/custom-themes/) you can use the `page.meta.git_revision_date_localized` jinja tag:
        
        ```django hljs
        {% if page.meta.git_revision_date_localized %}
          Last update: {{ page.meta.git_revision_date_localized }}
        {% endif %}
        ```
        
        You can style the output using CSS: the date outputs are always wrapped in `<span class='git-revision-date-localized-plugin git-revision-date-localized-plugin-{type}></span>` (where `{type}` is replaced with the `type` option set in the plugin).
        
        ## Options
        
        You can customize the plugin by setting options in `mkdocs.yml`. For example:
        
        ```yml
        plugins:
          - git-revision-date-localized:
              type: timeago
              time_zone: Europe/Amsterdam
              locale: en
              fallback_to_build_date: false
        ```
        
        ### `type`
        
        Default is `date`. To change the date format, set the `type` parameter to one of `date`, `datetime`, `iso_date`, `iso_datetime` or `timeago`. Example outputs:
        
        ```bash
        28 November, 2019           # type: date (default)
        28 November, 2019 13:57:28  # type: datetime
        2019-11-28                  # type: iso_date
        2019-11-28 13:57:26         # type: iso_datetime
        20 hours ago                # type: timeago
        ```
        
        ### `time_zone`
        
        Default is `UTC`. Specify a time zone database name ([reference](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)). This option is especially relevant when using `type: datetime` and `type: iso_datetime`. Note that when using [timeago](http://timeago.yarp.com/) (with `type: timeago`) any difference in time zones between server and client will be handled automatically.
        
        ### `locale`
        
        Default is `None`. 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 not set, this plugin will look for `locale` or `language` options set in your theme. If also not set, the fallback is English (`en`)
        - 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`)
        
        ### `fallback_to_build_date`
        
        Default is `false`. If set to `true` the plugin will use the time at `mkdocs build` instead of the file's last git revision date. This means the revision date is incorrect, but this can be acceptable if you want your project to also successfully build in environments with no access to GIT.
        
        ## Contributing
        
        Contributions are very welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before putting in any work.
Keywords: mkdocs git date timeago babel plugin
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.5
Description-Content-Type: text/markdown
