Roadmap / Vision [status]

[timvink]

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 Make output configurable through template partials #21 Add last updated date #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:

• Add localization #14
• Add support for github and gitlab avatars #15

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

[uliska]

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.

[Guts]

FIY I just released a plugin to generate RSS plugin using git log too: https://github.com/Guts/mkdocs-rss-plugin. I used (sometimes roughly copied/pasted) code from your plugins, as mentioned in the credits.

By the way, I am convinced by your approach described above to have a common base for everything that uses git logic.

This could be done by using the possibility of having several entry points in the same codebase: https://www.mkdocs.org/user-guide/plugins/#entry-point. In this way, the options should not be too many, but keep them separated.

[timvink]

Cool plugin! Don't forget to list in the list of all mkdocs plugins

Thanks for pointing out the possibility of multiple entry points, indeed can help in the design

[uliska]

Actually that's what I had in mind already (but I'm not sure if I have mentioned it at any point). A repository can have all the common code in modules/packages, and the different user-facing plugin interfaces in independent files.

All this could be deployed as something like git-plugins while the user can add individual parts in the config files.

[Guts]

So, we're in agreement ^^.

On the other hand, , I think it's better to create a new repository than to use this one. This way, we start over on a fresh codebase and it'll be clearer for end-users of the existing plugins. I suggest that @timvink be the new repository's owner, adding us as contributors. Same for the PyPi project.

---

Cool plugin! Don't forget to list in the list of all mkdocs plugins

Thanks for the tip, I will.

[timvink]

Small update, > two years later. Both mkdocs-git-authors-plugin and mkdocs-git-revision-date-localized-plugin are quite popular, and they have a nice & easy user interface for adding authors and dates respectively.

But there are more advanced users that would like to have more information from git. Things like tags, numbers of lines, summaries from the entire site (rather than on a page level), etc.

@uliska was right back in 2020:

A repository can have all the common code in modules/packages, and the different user-facing plugin interfaces in independent files.

So the roadmap should be to build a separate mkdocs-git-info-plugin that extracts all the potentially relevant information.

We would add the git info as a dict as an extra attribute to a page during the on_page event. The new mkdocs 1.4 functionality event priorities allows us to ensure that is run before one of the 'user interfacing plugins'.

I'm not planning on spending time on this currently, but maybe in the future. So the honor is up for grabs in case anyone wants to have a go at it (and keep maintaining it of course).

mkdocs-git-authors-plugin uses it's own implementation around git (very elegantly written by @uliska), making it light weight on dependencies. mkdocs-git-revision-date-localized-plugin however uses GitPython, and several other large dependencies like babel, so is not lightweight. Both options have worked fine over the last several years, so both can work for mkdocs-git-info-plugin. Re-using the git module from this plugin will make things very lightweight, but re-using GitPython might make it easier to run and parse more complex git commands (faster to implement, quicker to read).