Is there any way to disable the mailto hyperlink on the author, i.e. have the author name display, but not have it as a clickable link, just have it as plain text.

Also, thanks for the exclude update, works like a charm.

Description

I've noticed a few months ago (sorry for this delayed report) that my site authors list is empty since I've enabled the excellent Macros Plugin of @fralau.

I guess it's a Jinja conflict but I can't figure out where or why (nothing in log). Note that the git_page_authors is working...

How to reproduce

1. Create a new mkdocs site
2. Add git authors plugin and site tags into index.md
3. commit everything
4. mkdocs serve --> authors list is rendered:

5. add macros plugin
6. mkdocs serve --> authors list is not rendered:

mkdocs.yml:

site_name: My Docs

plugins:
  - search
  - git-authors
  - macros

docs/index.md:

# Welcome to MkDocs

For full documentation visit [mkdocs.org](https://www.mkdocs.org).

## Commands

* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.

## Project layout

    mkdocs.yml    # The configuration file.
    docs/
        index.md  # The documentation homepage.
        ...       # Other markdown pages, images and other files.

## Site authors

{{ git_site_authors }}

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.

Whith fallback_to_empty set to true and without a proper Git environment I get the following warning message:

As you can see from the first line in the screenshot the syntax is wrong. (I made the mistake but I don't know how to solve it)

See:

To reproduce, just follow the README section about theme customizations.

Running the mkdocs build/serve, we get a RecursionError (see below for full trace): RecursionError: maximum recursion depth exceeded in comparison

Should use a file named main.html as described in material doc: https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks

Full trace:

INFO    -  Building documentation...
[E 200401 17:07:23 ioloop:909] Exception in callback <bound method LiveReloadHandler.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>>
    Traceback (most recent call last):
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\tornado\ioloop.py", line 907, in 
_run
        return self.callback()
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\livereload\handlers.py", line 69, in poll_tasks
        filepath, delay = cls.watcher.examine()
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\livereload\watcher.py", line 105, in examine
        func()
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\mkdocs\commands\serve.py", line 136, in builder
        build(config, live_server=live_server, dirty=dirty)
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\mkdocs\commands\build.py", line 288, in build
        _build_theme_template(template, env, files, config, nav)
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\mkdocs\commands\build.py", line 114, in _build_theme_template
        output = _build_template(template_name, template, files, config, nav)
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\mkdocs\commands\build.py", line 93, in _build_template
        output = template.render(context)
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\jinja2\environment.py", line 1090, in render
        self.environment.handle_exception()
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\jinja2\environment.py", line 832, in handle_exception
        reraise(*rewrite_traceback_stack(source=source))
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\jinja2\_compat.py", line 28, in reraise
        raise value.with_traceback(tb)
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\material\404.html", line 4, in top-level template code
        {% extends "base.html" %}
      File ".\tests\basic_setup\docs/theme\base.html", line 1, in top-level template code
        {% extends "base.html" %}
      File ".\tests\basic_setup\docs/theme\base.html", line 1, in top-level template code
        {% extends "base.html" %}
      File ".\tests\basic_setup\docs/theme\base.html", line 1, in top-level template code
        {% extends "base.html" %}
      [Previous line repeated 957 more times]
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\jinja2\utils.py", line 377, in get
        return self[key]
      File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\jinja2\utils.py", line 419, in __getitem__
        rv = self._mapping[key]
    RecursionError: maximum recursion depth exceeded in comparison
ERROR   -  Exception in callback <bound method LiveReloadHandler.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>>
Traceback (most recent call last):
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\tornado\ioloop.py", line 907, in _run
    return self.callback()
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\livereload\handlers.py", line 69, in 
poll_tasks
    filepath, delay = cls.watcher.examine()
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\livereload\watcher.py", line 105, in 
examine
    func()
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\mkdocs\commands\serve.py", line 136, 
in builder
    build(config, live_server=live_server, dirty=dirty)
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\mkdocs\commands\build.py", line 288, 
in build
    _build_theme_template(template, env, files, config, nav)
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\mkdocs\commands\build.py", line 114, 
in _build_theme_template
    output = _build_template(template_name, template, files, config, nav)
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\mkdocs\commands\build.py", line 93, in _build_template
    output = template.render(context)
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\jinja2\environment.py", line 1090, in render
    self.environment.handle_exception()
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\jinja2\environment.py", line 832, in 
handle_exception
    reraise(*rewrite_traceback_stack(source=source))
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\jinja2\_compat.py", line 28, in reraise
    raise value.with_traceback(tb)
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\material\404.html", line 4, in top-level template code
    {% extends "base.html" %}
  File ".\tests\basic_setup\docs/theme\base.html", line 1, in top-level template code
    {% extends "base.html" %}
  File ".\tests\basic_setup\docs/theme\base.html", line 1, in top-level template code
    {% extends "base.html" %}
  File ".\tests\basic_setup\docs/theme\base.html", line 1, in top-level template code
    {% extends "base.html" %}
  [Previous line repeated 957 more times]
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\jinja2\utils.py", line 377, in get   
    return self[key]
  File "d:\uzeur\documents\github\external\mkdocs-git-authors-plugin\.venv\lib\site-packages\jinja2\utils.py", line 419, in __getitem__
    rv = self._mapping[key]
RecursionError: maximum recursion depth exceeded in comparison
[I 200401 17:07:29 server:318] Shutting down...

I'd like to add two shields:

• License (MIT)
• Number of contributors

Take them from https://shields.io/

I am trying to use the git-authors plugin with MkDocs in a context where the root of the MkDocs project is not the root of the repository, and this breaks with the following error:

Traceback (most recent call last):
  File "/home/uliska/.local/bin/mkdocs", line 10, in <module>
    sys.exit(cli())
  File "/home/uliska/.local/lib/python3.7/site-packages/click/core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "/home/uliska/.local/lib/python3.7/site-packages/click/core.py", line 717, in main
    rv = self.invoke(ctx)
  File "/home/uliska/.local/lib/python3.7/site-packages/click/core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/uliska/.local/lib/python3.7/site-packages/click/core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/uliska/.local/lib/python3.7/site-packages/click/core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "/home/uliska/.local/lib/python3.7/site-packages/mkdocs/__main__.py", line 162, in build_command
    site_dir=site_dir
  File "/home/uliska/.local/lib/python3.7/site-packages/mkdocs/config/base.py", line 197, in load_config
    errors, warnings = cfg.validate()
  File "/home/uliska/.local/lib/python3.7/site-packages/mkdocs/config/base.py", line 107, in validate
    run_failed, run_warnings = self._validate()
  File "/home/uliska/.local/lib/python3.7/site-packages/mkdocs/config/base.py", line 62, in _validate
    self[key] = config_option.validate(value)
  File "/home/uliska/.local/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 132, in validate
    return self.run_validation(value)
  File "/home/uliska/.local/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 572, in run_validation
    plgins[item] = self.load_plugin(item, cfg)
  File "/home/uliska/.local/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 587, in load_plugin
    plugin = Plugin()
  File "/home/uliska/.local/lib/python3.7/site-packages/mkdocs_git_authors_plugin/plugin.py", line 12, in __init__
    self.util = Util()
  File "/home/uliska/.local/lib/python3.7/site-packages/mkdocs_git_authors_plugin/util.py", line 7, in __init__
    self.repo = Repo(path)
  File "/home/uliska/.local/lib/python3.7/site-packages/git/repo/base.py", line 184, in __init__
    raise InvalidGitRepositoryError(epath)

This is because

• in GitAuthorsPlugin an Util() instance is created without path argument
• which in util.py defaults to '.', i.e. the current working directory.
• in pythongit Repo() expects the root directory.

I think that the GitAuthorsPlugin should make sure to determine the project's root directory, because I don't think it is an invalid case to have the project root differ from the repository root.

Add source of the warning with [git-authors-plugin]:

What is the type argument in Ùtil.get_authors()` supposed to be doing:

The method signature's default value contradicts the docstring, and the argument is not used at all in the method.

It might be much more elegant to use page attributes.

A simple page.git_authors = .. can be used as {{ page.git_authors }}.

It might not be backwards compatible. Perhaps context update could also work
https://www.mkdocs.org/user-guide/plugins/#on_page_context

Design & implement a clean solution to support user avatars.

As a start, a detailed analysis has been done here:
squidfunk/mkdocs-material#1403

We can discuss how to implement a clean design here

PR #12 introduced a number of Git classes - essentially a small subset of Git functionality, just what is needed for the plugin, and dropped the dependency on GitPython.

It should be thoroughly considered whether this should be kept or if we should revert to GitPython. The main factors to consider are:

• small amount of code tailored to our needs
  and
  no dependency
  vs
• mature external library, relaying the responsibility to that domain to someone else

I am running into the problem that configurations beyond the first one (show_contribution: true) are ignored. I set authorship_threshold_percent: 10, but I found contributions of 0.88 %.

Package Versions:

• mkdocs 1.4.2
• mkdocs-git-authors-plugin 0.7.0
• mkdocs-git-revision-date-localized-plugin 1.1.0
• mkdocs-material 9.0.13
• mkdocs-material-extensions 1.1.1
• python 3.10

Relevant parts in mkdocs.yml:

plugins:
  - search:
      lang: en
  - git-revision-date-localized:
      enable_creation_date: true
      fallback_to_build_date: false
      timezone: Europe/Paris
  - git-authors:
      show_contribution: true
      sort_authors_by: contribution
      authorship_threshold_percent: 10

Unit tests do not test dealing with line counts where the line is empty. Let's make sure to be consistent

We are using your plugin in our CI system and the local preview.
unfortunately it slows down the preview on saving a file.

some plugins used an enabled_if_env: entry to disable it, except on CI pipelines.

it would be nice to have this feature on your plugin too

plugins:
  - git-revision-date:
      enabled_if_env: CI
  - git-authors:
      show_contribution: true
      show_line_count: true
      enabled_if_env: CI

I just reformatted docs because people had trailing whitespace in many places. This doesn't mean I should be considered an author, so it would be nice if whitespace changes were ignored. Alternatively, a way to mention in the detailed commit message that it should be excluded from this plugin would work too

I'm still working on the configurability of authors aggregation(#4 (comment), 1.) but had to intermittently leave. This caused some rambling considerations while driving, and I had one more idea [hopefully the last one for now since I really have to do some "content" work].

If I'm going to implement this additional idea it would be good to make some design decisions already for the aggregation code (instead of implementing just that one functionality and the changing the code only afterwards), so I'd like to have your opinion first, @timvink.

I would like to add a ninja template git_authors_book_summary that can be placed on a single page and will produce a summary of all authors present in the book rather than on the current page. This may (configurably) show the number of commits, the contribution percentage and the absolute number of lines the author has modified in the current state of the book (i.e. the aggregated lines count of all pages). In the future this could also provide some information about the book itself, e.g. total number of lines, number of pages, total size in characters (and words?), times of first and last commit etc. Although the latter might better be handled in a separate plugin.

The main design decision for this would be to retrieve the Git information not in on_page_markdown but in on_files. Here basically get_authors() will be called in its current implementation, and its results stored in a global Authors object. In the on_page_markdown we don't have to call Git anymore but just read out the stored data.
The aggregation of data for the book summary will only be done upon request, i.e. if the template is found, so there shouldn't be much overhead in this. There will be more memory usage because the information is stored globally and not only while retrieving the info per page, but I'm sure this is OK.

I can see a page with the same committer appearing twice in the authors provided by this plugin. I can see when hovering over that it is the same email address but some upper case letters in one variant, i.e. [email protected] vs [email protected].

Would it be possible for the plugin to remove duplicate entries by ignoring case?

Thank you for making such a useful plugin.

I am wondering if it is useful to provide an option to link to the user profile (e.g., GitHub profile) instead of email?

For example, return

[
    {
    'name' : 'Jane Doe',
    'email' : '[email protected]',
    'profile': 'https://github.com/jane',
    'last_datetime' : datetime.datetime(),
    'lines' : 200,
    'contribution' : '40.0%'
  }
]

Thanks.

I added the plugin and it worked flawlessly locally, using both mkdocs serve and mkdocs build.
I added the Jinja tags in my template files (I use material theme) and all was good, including the extra options.

Then I pushed my changes to the remote repository, the build system triggered itself and pushed the updated documentation. There, all attribution names were meshed up. Different authors were being assigned to every page and different totals ({{ git_site_authors }}) were being calculated.

I can't provide the means to reproduce the issue, because I do not know them yet, but I can provide my pipeline:

image: squidfunk/mkdocs-material

options:
    docker: true

pipelines:
  branches:
    master:
      - step:
          name: 'Deploy docs'
          caches:
            - docker
            - pip
          script:
            - pip3 install mkdocs-awesome-pages-plugin
            - pip3 install mkdocs-git-revision-date-plugin
            - pip3 install mkdocs-git-authors-plugin
            - mkdocs --version
            - mkdocs -v build
            - pipe: atlassian/rsync-deploy:0.2.0
              variables:
                USER: 'SOME_USER'
                SERVER: 'SOME_SERVER'
                REMOTE_PATH: '/SOME_FOLDER/'
                LOCAL_PATH: 'site'

and my mkdocs.yml (sensitive info removed):

# Project Info
site_name: -
side_description: -
site_url: '-'

# Repository
repo_name: 'SOME_REPO'
repo_url: 'https://bitbucket.org/SOME_REPO'
edit_uri: 'src/master/docs'

# Copyright
copyright: 'Copyright © 2019-2020'

theme:
  name: 'material'
  palette:
    primary: 'light green'
    accent: 'deep purple'
  favicon: assets/favicon.ico
  custom_dir: 'material'
  feature:
    tabs: true
  logo: assets/logo.svg
  extra:
    manifest: 'manifest.webmanifest'

markdown_extensions:
  - admonition
  - footnotes
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  - pymdownx.magiclink
  - codehilite:
      guess_lang: false
  - toc:
      permalink: true
  - meta

plugins:
  - search
  - awesome-pages
  - git-revision-date
  - git-authors:
      show-contribution: true

As discussed in #12 (comment) retrieving the last-modification timestamp for a given page doesn't actually have a use case within the context of the plugin. Dropping support for it (also from the resulting git_author dictionary in the page context) would make implementation more straightforward.

However, if we decide to keep the Git classes proposed in #12 and to merge the plugin with mkdocs-revision-date-localized it makes sense to also determine that value from the git blame data.

So: if the two decisions are not taken support for that value should be removed (from Commit._populate() or probably Page._process_git_blame() by then).

I feel like personal e-mail is not kind of info contributors would like to get exposed on widely viewed pages. I was at first hoping to customize it with git_info, but github usernames are not stored. Could you please make an option to access github usernames instead of emails?

Dependabot couldn't authenticate with https://pypi.python.org/simple/.

You can provide authentication details in your Dependabot dashboard by clicking into the account menu (in the top right) and selecting 'Config variables'.

View the update logs.

v.0.3.0 adds our own Git classes, making it possible to also expose the last updated date of a page or entire site.

Markdown tags

We can add the following markdown tags:

• {{ git_page_last_updated }}
• {{ git_site_last_updated }}

These should output the date or datetime only, and not include the text "Last updated: ". That should be picked up in #14.

Jinja2 variables

For those developing custom themes, we can extend the dict {{ git_info }}. Proposal:

{
    ...,
   'page_last_updated' : {
        'date' : '28 November, 2019',
        'datetime' : '28 November, 2019 13:57:28'
   },
    'site_last_updated' : # same structure
}

Options

We should add two new options:

• type: and support two options: date and datetime (see https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#type).
• locale: (see https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#locale)

Other

• Update README
• Update tests
• Update setup.py to include dependency on babel

This plugins relies on retrieving information from git commands (git blame).

Currently we test:

    strategy:
      matrix: 
        os: [ubuntu-latest, macos-latest, windows-latest]

To improve the unit tests we can upgrade our github workflow and test on older OS and with different versions of GIT.

See this review discussion #12 (comment) and this related stackoverflow question

The fact that this plugin is not tested with py311 prevented it from finding some deprecation runtime warnings:

INFO     -  DeprecationWarning: pathlib.Path.__enter__() is deprecated and scheduled for removal in Python 3.13; Path objects as a context manager is a no-op
              File "/opt/homebrew/lib/python3.11/site-packages/mkdocs_git_authors_plugin/ci.py", line 23, in raise_ci_warnings
                with Path(path):
              File "/opt/homebrew/Cellar/[email protected]/3.11.1/Frameworks/Python.framework/Versions/3.11/lib/python3.11/pathlib.py", line 891, in __enter__
                warnings.warn("pathlib.Path.__enter__() is deprecated and scheduled "
INFO     -  Cleaning site directory

BTW, If you want to avoid having to update the list of python version on GHA, you might find https://github.com/coactions/dynamic-matrix useful.

There are multiple components that would benefit from localization:

• Authors:
• lines
• Uncommitted work

And possibly more in the future.

MkDocs will add a locale option in the future. mkdocs-material already has a language option. And we could add a locale option to the plugin.

We can add localization files and load them according to the set locale.

https://github.com/timvink/mkdocs-git-revision-date-localized-plugin already has localization support, although it is currently partially implemented in the language files of mkdocs-material.

Details here:
squidfunk/mkdocs-material#1350

As part of #12 a new tag git_authors_list has been added, but as discussed in #12 (comment) it is not clear how this really should be achieved in terms of user-facing simplicity and configurability.

The data is there and can be requested from an Author simply by not specifying a target page in Author.lines() or Author.contribution().

For now this is going to be merged as part of the Pull Request, but the question has to be fully resolved before the next release.

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.

While we are already accessing GIT, we could also make available the latest git tag.

Inspired by this plugin: https://github.com/agarthetiger/mkdocs_latest_release_plugin

Note: That plugin has a GNU licence, so ask for permission before copying and changing any code.

I'm starting a new mkdocs project and build is failing because of this line:

I still do not know why it's failing, so I put the full trace below and here is my mkdocs.yml:

# Project information
site_name: New project
site_description: Documentation
site_author: Guts

# advanced options
docs_dir: '.'
site_dir: '../build/mkdocs/site'

# Plugins
plugins:
  - awesome-pages
  - git-authors
  - git-revision-date-localized
  - minify:
      minify_html: true
  - search:
      lang: fr
      prebuild_index: python

# Theme
theme:
  name: 'material'
  feature:
    tabs: true
  font: false
  language: 'fr'
  palette:
    primary: 'blue-grey'
    accent: 'deep-orange'

# Customization
extra:
  manifest: 'manifest.webmanifest'
  version: 1.0

# Extensions to enhance markdown - see: https://squidfunk.github.io/mkdocs-material/getting-started/#extensions
markdown_extensions:
  - admonition  # https://squidfunk.github.io/mkdocs-material/extensions/admonition/
  - codehilite: # https://squidfunk.github.io/mkdocs-material/extensions/codehilite/
      linenums: true
  - meta        # https://squidfunk.github.io/mkdocs-material/extensions/metadata/
  - toc:
      permalink: true # https://squidfunk.github.io/mkdocs-material/extensions/permalinks/

# Navigation - Menu organization
nav:
  - Accueil: index.md
  - Installation:
    - installation/requirements.md
    - installation/install.md
    - installation/configuration.md
  - Usage:
    - usage/main.md
    - usage/subcommands.md
    - usage/version.md
    - usage/check.md
    - usage/listing.md
    - usage/sign.md
    - usage/lookup.md
    - usage/sync.md
    - usage/clean.md
  - Automatiser:
    - schedule/scheduling_windows.md

Trace

ERROR   -  Error building page 'index.md': division by zero 
Traceback (most recent call last):
  File "C:\Users\uzeur\AppData\Local\Programs\Python\Python36\lib\runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "C:\Users\uzeur\AppData\Local\Programs\Python\Python36\lib\runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "D:\uzeur\Documents\GitHub\Isogeo\scan-offline\.venv\Scripts\mkdocs.exe\__main__.py", line 7, in <module>
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\click\core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\click\core.py", line 782, in main
    rv = self.invoke(ctx)
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\click\core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\click\core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\click\core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\mkdocs\__main__.py", line 143, in serve_command     
    **kwargs
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\mkdocs\commands\serve.py", line 141, in serve       
    config = builder()
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\mkdocs\commands\serve.py", line 136, in builder     
    build(config, live_server=live_server, dirty=dirty)
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\mkdocs\commands\build.py", line 295, in build       
    _build_page(file.page, config, files, nav, env, dirty)
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\mkdocs\commands\build.py", line 209, in _build_page 
    'page_context', context, page=page, config=config, nav=nav
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\mkdocs\plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\mkdocs_git_authors_plugin\plugin.py", line 183, in on_page_context
    "site_authors": util.page_authors(self.repo().get_authors(), path),
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\mkdocs_git_authors_plugin\util.py", line 134, in page_authors
    for author in authors
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\mkdocs_git_authors_plugin\util.py", line 134, in <listcomp>
    for author in authors
  File "d:\uzeur\documents\github\isogeo\scan-offline\.venv\lib\site-packages\mkdocs_git_authors_plugin\git\author.py", line 64, in contribution
    result = lines / total_lines
ZeroDivisionError: division by zero

When editing a page with an existing commit but uncommited changes, you see a 'Not Committed Yet' Author:

But when viewing a new uncommitted page, it's empty:

The better behaviour would be to also show the 'Not committed yet' author for new pages.

Hi Tim,

Apologies for a n00b question, but I've not been able to figure this issue out and I'm assuming it's something dumb that I have done?

WARNING - [git-authors-plugin] /tmp/mkdocs_simple_8fyj62vv/MDE.md has not been committed yet. Lines are not counted

Have I missed something in the docs, as this is simply being published to GitHub pages via an Action

Sorry if this was asked before, I could not find anything in the issues search, was wondering if its possible to exclude the author from certain pages, similar to the git-revision-date-localized plugin?

  - git-revision-date-localized: # https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/options/
      type: date
      timezone: Pacific/Auckland
      locale: en
      fallback_to_build_date: false
      enable_creation_date: true
      exclude:
        - index.md
        - tags.md

Great plugins btw.

Below a short version of the roadmap I currently envision for this plugin. This issue will also track progress

Integrate with git-revision-date

mkdocs-git-revision-date-localized-plugin does something very similar to this one, retrieving information from git. There is quite some overlap. Note that development on either plugin is still very valuable and would be re-used.

If we keep the amount of options as low as possible, future integration should be fairly straightforward. Hence the focus on simplicity.

To integrate, high level user api:

• Expose more markdown tags for authors and date #21 #33
• A larger dict with information on both dates and authors of a page called {{ git_info }}
• deprecate both mkdocs-git-revision-date-localized-plugin and mkdocs-git-authors-plugin

The plugin could be called something like git-info and contain all info.

Add native support for mkdocs-material

You can already extend mkdocs-material with this plugin (described in README).
To add native support (see squidfunk/mkdocs-material#1403) we first need to complete clean solutions for:

• #14
• #15

Before proposing native support, it's best to integrate both plugins. That would make it easy for themes to create things like:

Basically just like timvink/mkdocs-git-revision-date-localized-plugin#63

When an author used multiple email addresses to commit to a repo, Git recommends using a .mailmap file to help treat these email addresses as one user. For example:

Jon Smith commits with [email protected], [email protected] and with [email protected]. Using a tool like git-quick-stats, we'll see a Git author summary along the lines of:

Jon <[email protected]> (10%)
Jon Smith <[email protected]> (50%)
Jon Smith <[email protected]> (40%)

If we then add the following .mailmap file to the root of the repo:

Jon Smith <[email protected]> <[email protected]>
Jon Smith <[email protected]> <[email protected]>

Which essentially tells Git:

Preferred Name <preferred-email> <email-to-alias-to-preferred>

After adding this file, we'll see a Git author summary along the lines of:

Jon Smith <[email protected]> (100%)

mkdocs-git-authors-plugin, however, does not seem to take the .mailmap file into account, as the git_page_authors variable still includes an entry for each email address's user:

Jon, Jon Smith, Jon Smith

Is there a way to get mkdocs-git-authors-plugin to take the .mailmap file into account, or is there another way we can tell mkdocs-git-authors-plugin to treat multiple email addresses as one user?

Hi, I am using mkdocstrings to generate the documentation for the projects source.
On-top I use mkdocs-gen-files and mkdocs-literate-nav plugins to auto generate the navigation for the documentation as described in the mkdocstrings documentation https://mkdocstrings.github.io/recipes/.

Unfortunately the git-authors plugin uses the generated file instead of the sources file to get the author. (This applies also to the mkdocs-git-revision-date-localized-plugin)

Is there any possibility to change the path on the fly to point to the source code files for the generated files?

Thanks for your help AND for this and the other wonderful plug-ins and your work.

Daniel

We use config_options.Choice, which was introduced in MkDocs 1.1.

This means we have a requirements on MkDocs 1.1, but that version brings some breaking changes (mkdocs.utils.string_types deprecated). Not all plugins have been updated yet, f.e. pdf-export. I would like to use that with the git-authors plugin, but downgrading is currently not an option.

Solution is to replace config_options.Choice() with a boolean option and downgrade mkdocs version requirement.

Some users have their .git folder inside the docs/ folder. Good to start from there and recursively look up.

We need to ensure (or raise instructional error) that this plugin is defined in mkdocs.yml before the mkdocs-monorepo-plugin, because that plugin alters the docs_dir location. See similar issue timvink/mkdocs-git-revision-date-localized-plugin#34 for details

👏 Great work this new version! 👏

Nevertheless, I'm noticing some minor issue: the authors summary is displayed when the tag is included into the page content, but not in partials.

FYI: it was working fine with the master branch that I've used on past Sunday.

To reproduce:

1. I created a fixture with the Material theme activated and an extended view as described in the README: if you want, check my fork with this test fixture
2. Launch on localhost: mkdocs serve -f .\tests\basic_setup\mkdocs_complete_material.yml

And the result:

Hi Tim,
Hopefully you are doing well and feel happy with your new role. I am still using your developed package ingmarkdowntemplates, but after I reinstalled R I keep getting the message that it is not compatible anymore with this version of R. Do you know what I should do?
Many thanks in advance!!
All the best,
Moniek

As discussed in #12 (comment) it might be a nice idea to provide template partials (like in MkDocs themes) to make the output configurable to users.

Originally posted by @uliska in #16 (comment)

We generate some md files from other sources during CI. When we have a file added to the exclusions but it is not commited (since it was generated), it still shows an error in the logs because no git history for the page can be found.

This error seems to be thrown in git/page.py. Since it is a warning level log always shows up.

To me it seems like the issue is, that a page object is created for every file first plugin.py#on_files, and only after that the exclusions are checked plugin.py#on_page_markdown. This should probably be the other way around / done while the page objects are created.

@uliska Just to let you know I'm working on the unit tests, so we don't do double work.

I'm not comfortable to Include unnecessary emails of contributors on mkdocs pages. It's prone to be fetch easly with bots.
Is it posable to make an option for link to the git profile of the contributor? I think it more responable way to link someone for help

Like https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin#enabled_if_env

It's useful in a CI environment where you don't know if there is a git repository available

I was wondering if there was a way to get a plain text list of authors, i.e.

Turbato Thomas, Elodeon Nick

instead of

<span class="git-page-authors git-authors"><a href="mailto:[email protected]">Turbato Thomas</a> (98.0%), <a href="mailto:[email protected]">Elodeon Nick</a> (2.0%)</span>

In this way one could set the page "author" meta tag without the need to specify authors manually in the markdown file, as MkDocs Material does here:

{% if page and page.meta and page.meta.author %}
  <meta name="author" content="{{ page.meta.author }}">
{% elif config.site_author %}
  <meta name="author" content="{{ config.site_author }}">
{% endif %}

Setting the tag would also make the website appear like this in Firefox reader view: