Page Contributors

[Aetherinox]

I've tried searching far and wide, and I can't seem to get this working.

On the demo site of any page: https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/

There is a list of authors linked from Github with their avatars. I cannot seem to get this to show at all. I've linked Github through all my settings, and other github plugins like simply showing the text name seem to work, but not the avatar one.

I've also ensured my config is set up:

  - git-committers:
      repository: username/repo
      branch: main
      token: Github_PAT_here

Any help would be awesome; I've tried just about everything.

I also tried manually installing https://github.com/ojacques/mkdocs-git-committers-plugin-2 and even v1, but when I use those, it messes up. I see the word "Contributors" down in the very bottom left of my screen, obviously not where it's supposed to be.

And from what I've read, the material theme should work out of box with v2.

To add, terminal is reporting that it's running

INFO    -  Building documentation...
INFO    -  git-committers plugin ENABLED
INFO    -  Documentation built in 10.42 seconds
INFO    -  [13:19:41] Reloading browsers

[kamilkrzyskow]

Hello @Aetherinox,
I haven't used the committers feature yet, but I can help you in the debug process.

1. This repository uses the mkdocs-git-committers-plugin-2:
   

   mkdocs-material/pyproject.toml

   Lines 61 to 63 in 2f1b2e9

   	git = [
   	"mkdocs-git-committers-plugin-2~=1.1",
   	"mkdocs-git-revision-date-localized-plugin~=1.2,>=1.2.4"

2. This is the configuration from the Insiders repo:

- git-committers:
    repository: squidfunk/mkdocs-material
    token: !ENV GH_TOKEN # Set in GitHub Actions

3. The template which renders the committers is here:
   https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/source-file.html
   

   mkdocs-material/src/templates/partials/source-file.html

   Lines 105 to 108 in 2f1b2e9

   	<img
   	src="{{ author.avatar }}{{ separator }}size=72"
   	alt="{{ author.name or 'GitHub user' }}"
   	/>

4. The code that adds the "committers" to the page context is here:
   https://github.com/ojacques/mkdocs-git-committers-plugin-2/blob/ab15c14b0aa03acf28ca649b128546fa05a371ce/mkdocs_git_committers_plugin_2/plugin.py#L196-L197

You could use the theme customization to override the template and print debug the committers on the rendered page.

• https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme

Or you can access your site-packages and modify the mkdocs_git_committers_plugin_2/plugin.py file to see the contents of the committers in the console log.

• pip show mkdocs-git-committers-plugin-2 -> Location: is the site-packages directory.

Maybe you have an older version of the theme? pip install mkdocs-material --upgrade

[Aetherinox]

Thanks for the help, very much appreciate it.

So, I did some debugging, and I found out what's going on. and I'm not sure how to resolve it.

My docs are hosted in main branch, so technically the path to the yml config file is:

root/docs/mkdocs.yml

And the path to my actual md files + stylesheet, etc would be:

root/docs/docs/

In my mkdocs.yml config, I have it set up to my repo, and the branch.

  - git-committers:
      repository: username/repo
      branch: main
      token: Github_PAT_here

So to test, I moved the mkdoc files from my main branch, to a new docs branch, and booted it up, and it worked.

I tried to append /docs to the end of the repository URL, but that doesn't work. mkdocs halts, and I have to set it back for it to work.

So I'm not sure if there's a way to give it that path, or if I should just migrate my docs to another branch. I just launched mkdocs with the new branch, and it threw out:

INFO    -  git-committers: fetching contributors for docs/index.md
INFO    -  git-committers: fetching contributors for docs/changelog.md
INFO    -  git-committers: fetching contributors for docs/tags.md
INFO    -  git-committers: fetching contributors for docs/blog/index.md

Which is the first time I've seen that, and I see my avatar on the pages now. This is my first time playing with mkdocs, but I'm wondering if it would be better to just use another branch. Only issue is checking out all the time to go back and forth.

[kamilkrzyskow]

Good job on the debug, the plugin has a docs_path option:
https://github.com/ojacques/mkdocs-git-committers-plugin-2/blob/ab15c14b0aa03acf28ca649b128546fa05a371ce/mkdocs_git_committers_plugin_2/plugin.py#L22-L33
maybe that's the solution.

It's the base for the git_path:
https://github.com/ojacques/mkdocs-git-committers-plugin-2/blob/ab15c14b0aa03acf28ca649b128546fa05a371ce/mkdocs_git_committers_plugin_2/plugin.py#L194

[Aetherinox]

I'll try that out. If that is the solution, I'll feel pretty damn stupid. I've been reading through the material theme documentation for two hours trying to solve this....

Appreciate the help here. I was getting desperate lol. The "try a new branch" thing came to mind when I was sitting here in "defeated mode", looking at the config, and I noticed the path wasn't pointed directly at the folder.

[Aetherinox]

You're a saint.

In the code you sent, I noticed the default path, so I changed mine to

docs_path: docs/docs/

and presto

INFO    -  git-committers plugin ENABLED
INFO    -  git-committers: found page authors cache file - loading it
INFO    -  git-committers: fetching contributors for docs/docs/index.md
INFO    -  git-committers: fetching contributors for docs/docs/changelog.md
INFO    -  git-committers: fetching contributors for docs/docs/tags.md
INFO    -  git-committers: fetching contributors for docs/docs/blog/index.md

Can't believe I missed that.... two hours of my life over 4 letters and a forward slash.

Really, thank you again. I was questioning all my years in computers. It was a royal pain. I can't believe I missed that in the docs... I was even searching through the repo code.

[kamilkrzyskow]

No worries, such stuff happens, and years of experience in C#/TypeScript doesn't directly translate into Python or MkDocs ^^, also I've seen better documentation of plugins like the Minify plugin that has a whole YML config with all defaults set, or even better docs with whole websites like https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/options/ I would likely also miss the mention of docs_path in the README file 😅

Also you found a valid issue with the plugin, you can report upstream, that the plugin lacks proper docs_path/git_path validation. There was no warning or info about not found path. Also using docs/ as default might be too simplistic, there is the config.docs_dir absolute path they could have used instead and get a relative path from current working directory/mkdocs.yml parent directory, so there is definitely room for improvement there and reconsideration of that approach.

[Aetherinox]

Yeah, at the very least, an error message would have helped. When I was using my root path, it was acting like everything was fine. But then when I added /docs to the end prior to docs_path, it just threw a stack-trace. Mind you, I've worked with python, however, I've got about 5 minutes of experience with it compared to other languages; so diagnosing an issue would be like trying to parachute down to grab a hair floating in the wind.

But I prefer this more (mkdocs). I've been a Gitbook user for a long time, even have a open-source license with them, but the performance of Gitbook has dramatically declined. To the point where if you're in it more than 20 minutes, you have to kill your browser and restart. It becomes slow and choppy. Even with 32GB memory, I still can't combat Gitbook.

Thanks again for the help. I may have been here another two hours lol