Open timvink opened 4 years ago
As discussed in https://github.com/timvink/mkdocs-git-authors-plugin/pull/12#discussion_r387023642 it might be a nice idea to provide template partials (like in MkDocs themes) to make the output configurable to users.
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.
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
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.
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.
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).
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:
dict
with information on both dates and authors of a page called{{ git_info }}
mkdocs-git-revision-date-localized-plugin
andmkdocs-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 https://github.com/squidfunk/mkdocs-material/issues/1403) we first need to complete clean solutions for:Before proposing native support, it's best to integrate both plugins. That would make it easy for themes to create things like: