MkDocs plugin for setting revision date from git per markdown file

Terry Zhao

Last update: Jan 6, 2023

Related tags

Documentation mkdocs-git-revision-date-plugin

Overview

mkdocs-git-revision-date-plugin

MkDocs plugin that displays the last revision date of the current page of the documentation based on Git. The revision date will be displayed in ISO format (YYYY-mm-dd). If you need other date formats check out timvink's fork

Setup

Install the plugin using pip:

pip install mkdocs-git-revision-date-plugin

Activate the plugin in mkdocs.yml:

plugins:
  - search
  - git-revision-date

Note: 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, but now you have to enable it explicitly.

More information about plugins in the MkDocs documentation.

Usage

Templates - `page.meta.revision_date`:

Example

{% block footer %}
<hr>
<p>{% if config.copyright %}
<small>{{ config.copyright }}<br></small>
{% endif %}
<small>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a>.</small>
{% if page.meta.revision_date %}
<small><br><i>Updated {{ page.meta.revision_date }}</i></small>
{% endif %}
</p>
{% endblock %}

More information about templates here.

More information about blocks here.

Markdown - `{{ git_revision_date }}`:

Example

Page last revised on: {{ git_revision_date }}

If using mkdocs_macro_plugin, it must be included after our plugin.

i.e., mkdocs.yml:

plugins:
  - search
  - git-revision-date
  - macros

Options

`enabled_if_env`

Setting this option will enable the build only if there is an environment variable set to 1. Default is not set.

`modify_md`

Setting this option to false will disable the use of {{ git_revision_date }} in markdown files. Default is true.

`as_datetime`

Setting this option to True will output git_revision_date as a python datetime. This means you can use jinja2 date formatting, for example as {{ git_revision_date.strftime('%d %B %Y') }}. Default is false.

Comments

Error with mkdocs 1.1: "ImportError: cannot import name 'string_types'"

Hi,

I am using Travis CI to build my site. After mkdocs updating to version 1.1 from 1.0.4 build failed with the following error:

File "/home/travis/virtualenv/python3.6.7/lib/python3.6/site-packages/mkdocs_git_revision_date_plugin/plugin.py", line 6, in from mkdocs.utils import string_types ImportError: cannot import name 'string_types'

Full log is there: https://travis-ci.com/alperyazar/www/builds/150195520

If I forced Travis CI to use mkdocs version 1.0.4 everything works fine. (https://travis-ci.com/alperyazar/www/builds/150197448)

Is an update required to work with mkdocs 1.1?

Thank you.

opened by alperyazar 3

cannot run mkdocs build

Is this plugin work with private github repository ?

When I try to build mkdocs, I have this message :

jinja2.exceptions.UndefinedError: 'secrets' is undefined

Full log :

ERROR   -  Error reading page 'deviens.dev---hébergement.md': 'secrets' is undefined 
Traceback (most recent call last):
  File "/home/profy/.ve-mkdocs-python3/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/click/core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/click/core.py", line 717, in main
    rv = self.invoke(ctx)
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/click/core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/click/core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/click/core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/mkdocs/__main__.py", line 163, in build_command
    ), dirty=not clean)
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/mkdocs/commands/build.py", line 274, in build
    _populate_page(file.page, config, files, dirty)
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/mkdocs/commands/build.py", line 174, in _populate_page
    'page_markdown', page.markdown, page=page, config=config, files=files
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/mkdocs_git_revision_date_plugin/plugin.py", line 59, in on_page_markdown
    return md_template.render({'git_revision_date': revision_date})
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/jinja2/asyncsupport.py", line 76, in render
    return original_render(self, *args, **kwargs)
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/jinja2/environment.py", line 1008, in render
    return self.environment.handle_exception(exc_info, True)
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/jinja2/environment.py", line 780, in handle_exception
    reraise(exc_type, exc_value, tb)
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/jinja2/_compat.py", line 37, in reraise
    raise value.with_traceback(tb)
  File "<template>", line 103, in top-level template code
  File "/home/profy/.ve-mkdocs-python3/lib/python3.6/site-packages/jinja2/environment.py", line 430, in getattr
    return getattr(obj, attribute)
jinja2.exceptions.UndefinedError: 'secrets' is undefined

opened by profy12 3

${{ page.meta.revision_date }} should be type String$

{{ page.meta.revision_date }} should be type String

Currently it is impossible to edit {{ page.meta.revision_date }} using Javascript because it is a number (typeof=number). I would like to change the displaying format from YYYY-MM-DD to something more user friendly such as a text like 25 January 2019 but for that {{ page.meta.revision_date }} should be a String in order to perform some operations such as split() and concat().

Is there any way to change the date-format using your plugin? Have you think about changing the type of variable from number to String?

Thanks!

opened by angelobanse 3
Display relative time ago
When using revision-date in templates we could offer the possibility to display it relatively using the timeago package and implementing as a custom jinja2 filter, like so:

Updated {{ page.meta.revision_date }} Updated {{ page.meta.revision_date | totimeago }} Updated {{ page.meta.revision_date | totimeago('nl') }}

Example output:

Updated 2019-11-28 Updated 20 hours ago Updated 20 uren geleden

Would like to offer a PR!
opened by timvink 2
4 as datetime
Adds option to output git-revision-datetime as python datetime object

Consistent output as str when there is no revision_date (was datetime)

Updated README
opened by timvink 2

jinja2.exceptions.UndefinedError: 'None' has no attribute 'meta'

I followed the instructions in the README, but got 'None' has no attribute 'meta' error during build.

Full log (click to expand):

$ mkdocs build
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: app/templates/docs
Traceback (most recent call last):
  File "env/bin/mkdocs", line 11, in <module>
    sys.exit(cli())
  File "env/lib/python3.6/site-packages/click/core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "env/lib/python3.6/site-packages/click/core.py", line 717, in main
    rv = self.invoke(ctx)
  File "env/lib/python3.6/site-packages/click/core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "env/lib/python3.6/site-packages/click/core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "env/lib/python3.6/site-packages/click/core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "env/lib/python3.6/site-packages/mkdocs/__main__.py", line 163, in build_command
    ), dirty=not clean)
  File "env/lib/python3.6/site-packages/mkdocs/commands/build.py", line 288, in build
    _build_theme_template(template, env, files, config, nav)
  File "env/lib/python3.6/site-packages/mkdocs/commands/build.py", line 117, in _build_theme_template
    output = _build_template(template_name, template, files, config, nav)
  File "env/lib/python3.6/site-packages/mkdocs/commands/build.py", line 96, in _build_template
    output = template.render(context)
  File "env/lib/python3.6/site-packages/jinja2/asyncsupport.py", line 76, in render
    return original_render(self, *args, **kwargs)
  File "env/lib/python3.6/site-packages/jinja2/environment.py", line 1008, in render
    return self.environment.handle_exception(exc_info, True)
  File "env/lib/python3.6/site-packages/jinja2/environment.py", line 780, in handle_exception
    reraise(exc_type, exc_value, tb)
  File "env/lib/python3.6/site-packages/jinja2/_compat.py", line 37, in reraise
    raise value.with_traceback(tb)
  File "env/lib/python3.6/site-packages/mkdocs/themes/readthedocs/search.html", line 1, in top-level template code
    {% extends "base.html" %}
  File "env/lib/python3.6/site-packages/mkdocs/themes/readthedocs/base.html", line 118, in top-level template code
    {%- block footer %}
  File "env/lib/python3.6/site-packages/mkdocs/themes/readthedocs/base.html", line 119, in block "footer"
    {% include "footer.html" %}
  File "markdown/custom_theme/footer.html", line 27, in top-level template code
    <br><i>Updated {{ page.meta.revision_date }}</i>
  File "env/lib/python3.6/site-packages/jinja2/environment.py", line 430, in getattr
    return getattr(obj, attribute)
jinja2.exceptions.UndefinedError: 'None' has no attribute 'meta'

As can be sean from stack trace, I am using readthedocs theme and have footer.html file in custom_theme dir:

plugins:
  - search
  - git-revision-date
theme:
  name: readthedocs
  custom_dir: custom_theme/

footer.html (click to expand):

<footer>
  {%- block next_prev %}
  {% if config.theme.prev_next_buttons_location|lower in ['bottom', 'both']
        and page and (page.next_page or page.previous_page) %}
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      {% if page.next_page %}
        <a href="{{ page.next_page.url|url }}" class="btn btn-neutral float-right" title="{{ page.next_page.title }}">Next <span class="icon icon-circle-arrow-right"></span></a>
      {% endif %}
      {% if page.previous_page %}
        <a href="{{ page.previous_page.url|url }}" class="btn btn-neutral" title="{{ page.previous_page.title }}"><span class="icon icon-circle-arrow-left"></span> Previous</a>
      {% endif %}
    </div>
  {% endif %}
  {%- endblock %}

  <hr/>

  <div role="contentinfo">
    <!-- Copyright etc -->
    {% if config.copyright %}
      <p><small>{{ config.copyright }}</small></p>
    {% endif %}
  </div>

  <small>
    Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
    <br><i>Updated {{ page.meta.revision_date }}</i>
  </small>
</footer>

Where am I doing wrong?

readthedocs theme

opened by ozbek 2

Update plugin.py

Fixes a Regression, cleans up unused import

ImportError: cannot import name 'string_types' from 'mkdocs.utils' (/Users/munagekar/../lib/python3.8/site-packages/mkdocs/utils/__init__.py)

opened by munagekar 1

Add option for document expiration
If the published date is older than a predefined interval, then mkdocs build should fail, and a warning message issues for the offending document.

For example, here is a snippet from an article

--- date: 2001-07-19 --- # Article Title

And here is the option in my mkdocs.yml file:

extra: expiration_period: 2Y

Then during the build phase:

mkdocs build Error: documentation has not been update since July, 2001.
opened by oxr463 1
fix mkdocs 1.1 compatibility

mkdocs 1.1 removed util.string_types and recommends to use str directly

Fixes: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin/issues/12

opened by NeroBurner 1
help with material

Hi! I use material theme and would like to keep the footer as it is plus revision date and not completly replace it. How would I do that?

Also, I am wondering if it would be possible to add the date at the top-right of every page? As it says in the documentation:

content: Contains the page content and table of contents for the page.

So I have to insert it somewhere there?
invalid

opened by berot3 1
How can I add this to markdown
I don't want to mess with theme files because then upgrading theme later might be problematic.

I have a header/footer system via mkdocs-include. Is it possible to add this in markdown directly, i.e.

footer.md

Last changed: {{revision_date}}
opened by majkinetor 1
git error when building docs with the git-revision-date plugin
A recent change in Git impacts our GitHub build. We have the error described here:

ERROR - Error reading page 'index.md': Cmd('git') failed due to: exit code(128) cmdline: git log -n 1 --date=short --format=%ad /docs/docs/index.md stderr: 'fatal: unsafe repository ('/docs' is owned by someone else)

Using the workaround didn't work as we are using mkdocs within a container (docker run --rm -t -v ${PWD}:/docs squidfunk/mkdocs-material build).

Until a solution is found, we have removed the plugin from our project. Let us know if you have a workaround or recommendations to use your plugin within GitHub actions.
opened by jeromevdl 0

`mkdocs build` will fail when `as_datetime` is `true`

Hi I'm facing the problem below, please let me know if there is some workaround to build document with as_datetime setting is enabled.

Description

When if as_datetime: true as the plugin setting, then the command mkdocs build will fail by the following error:

ERROR   -  Error reading page 'index.md': decoding to str: need a bytes-like object, datetime.datetime found 
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 152, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 271, in build
    _populate_page(file.page, config, files, dirty)
  File "/usr/local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 167, in _populate_page
    page.markdown = config['plugins'].run_event(
  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_plugin/plugin.py", line 57, in on_page_markdown
    markdown = re.sub(r"\{\{(\s)*git_revision_date(\s)*\}\}",
  File "/usr/local/lib/python3.8/re.py", line 210, in sub
    return _compile(pattern, flags).sub(repl, string, count)
  File "/usr/local/lib/python3.8/re.py", line 327, in _subx
    template = _compile_repl(template, pattern)
  File "/usr/local/lib/python3.8/re.py", line 318, in _compile_repl
    return sre_parse.parse_template(repl, pattern)
  File "/usr/local/lib/python3.8/sre_parse.py", line 972, in parse_template
    s = Tokenizer(source)
  File "/usr/local/lib/python3.8/sre_parse.py", line 228, in __init__
    string = str(string, 'latin1')
TypeError: decoding to str: need a bytes-like object, datetime.datetime found

Steps to reproduce the bug

The problem can be reproduced by using the simple project below with the package versions below: https://github.com/hitsumabushi845/git-revision-issue-reproduction

Package versions

Python: 3.8.6
MkDocs: 1.1.2
git-revision-plugin: 0.3.1

opened by hitsumabushi845 1

can't use curly braces in my doc

Hi, I'm having an issue trying to render curly braces in documentation (doc for jinja2 templates)

I'm looking to render something simple like:

{{ define "main" }}

I found 4 ways for that:

1. {% raw %} {{ define "main" }} {% endraw %} 
2. <!-- {% raw %} --> {{ define "main" }}   <!-- {% endraw %} --> 
3. {\{ define "main" }}
4. {{ define "main" }}

Problem is:

Online

on gitlab pages :

method 1 renders {% raw%} {{ define "main" }} (hiding {% endraw %})
method 2 & 3 & 4 work

on my computer (Debian 10)

(with mkdocs installed via pip3 and requirements via requirements.txt):

method 1, 2 and 3 work ,
method 4 breaks build:

ERROR   -  Error reading page 'raw_test.md': expected token 'end of print statement', got 'string' 
  Traceback (most recent call last):
    File "/home/makayabou/.local/bin/mkdocs", line 10, in <module>
      sys.exit(cli())
    File "/home/makayabou/.local/lib/python3.7/site-packages/click/core.py", line 829, in __call__
      return self.main(*args, **kwargs)
    File "/home/makayabou/.local/lib/python3.7/site-packages/click/core.py", line 782, in main
      rv = self.invoke(ctx)
    File "/home/makayabou/.local/lib/python3.7/site-packages/click/core.py", line 1259, in invoke
      return _process_result(sub_ctx.command.invoke(sub_ctx))
    File "/home/makayabou/.local/lib/python3.7/site-packages/click/core.py", line 1066, in invoke
      return ctx.invoke(self.callback, **ctx.params)
    File "/home/makayabou/.local/lib/python3.7/site-packages/click/core.py", line 610, in invoke
      return callback(*args, **kwargs)
    File "/home/makayabou/.local/lib/python3.7/site-packages/mkdocs/__main__.py", line 136, in serve_command
      **kwargs
    File "/home/makayabou/.local/lib/python3.7/site-packages/mkdocs/commands/serve.py", line 141, in serve
      config = builder()
    File "/home/makayabou/.local/lib/python3.7/site-packages/mkdocs/commands/serve.py", line 136, in builder
      build(config, live_server=live_server, dirty=dirty)
    File "/home/makayabou/.local/lib/python3.7/site-packages/mkdocs/commands/build.py", line 271, in build
      _populate_page(file.page, config, files, dirty)
    File "/home/makayabou/.local/lib/python3.7/site-packages/mkdocs/commands/build.py", line 168, in _populate_page
      'page_markdown', page.markdown, page=page, config=config, files=files
    File "/home/makayabou/.local/lib/python3.7/site-packages/mkdocs/plugins.py", line 94, in run_event
      result = method(item, **kwargs)
    File "/home/makayabou/.local/lib/python3.7/site-packages/mkdocs_git_revision_date_plugin/plugin.py", line 57, in on_page_markdown
      md_template = Template(markdown)
    File "/home/makayabou/.local/lib/python3.7/site-packages/jinja2/environment.py", line 1031, in __new__
      return env.from_string(source, template_class=cls)
    File "/home/makayabou/.local/lib/python3.7/site-packages/jinja2/environment.py", line 941, in from_string
      return cls.from_code(self, self.compile(source), globals, None)
    File "/home/makayabou/.local/lib/python3.7/site-packages/jinja2/environment.py", line 638, in compile
      self.handle_exception(source=source_hint)
    File "/home/makayabou/.local/lib/python3.7/site-packages/jinja2/environment.py", line 832, in handle_exception
      reraise(*rewrite_traceback_stack(source=source))
    File "/home/makayabou/.local/lib/python3.7/site-packages/jinja2/_compat.py", line 28, in reraise
      raise value.with_traceback(tb)
    File "<unknown>", line 16, in template
  jinja2.exceptions.TemplateSyntaxError: expected token 'end of print statement', got 'string'

Files

Here is my mkdocs.yml :

site_name: Garage Num Doc
site_url: https://garagenum.gitlab.io/doc
site_dir: public
theme: 
    name: material
    custom_dir: overrides
    features:
        - navigation.instant
        - navigation.expand
        - navigation.tabs
plugins:
    - search:
        min_search_length: 2
    - add-number:
        order: 2
        excludes:
            - divers/cmd/
        includes:
            - divers/cmd/screen
    - git-authors  
    - git-revision-date
markdown_extensions:
    - admonition
    - pymdownx.tabbed
    - pymdownx.details
    - pymdownx.superfences:
        custom_fences:
          - name: mermaid
            class: mermaid
            format: !!python/name:pymdownx.superfences.fence_div_format
    - pymdownx.highlight:
        use_pygments: false
        linenums_style: pymdownx.inline
    - pymdownx.inlinehilite
    - pymdownx.keys
    - footnotes
    - toc:
        permalink: true
    - attr_list

and here is my requirements.txt

mkdocs>=1.1.2
mkdocs-material>=5.4.0
Pygments
git+https://github.com/pugong/mkdocs-mermaid-plugin
mkdocs-git-authors-plugin
mkdocs-git-revision-date-plugin
mkdocs-add-number-plugin

Maybe you will also need my .gitlab-ci.yml:

image: python:3.8-buster

before_script:
  - pip install -r requirements.txt

pages:
  stage: deploy
  script:
  - mkdocs build --strict --verbose
  only:
  - master

I had reported that to mkdocs but they pointed me to you as says traceback . https://github.com/mkdocs/mkdocs/issues/2275

thanks

opened by makayabou 1