Any idea how to retrieve Git repo stats (stars, forks, latest tag) in a multi-repo MkDocs site? #8386

pismy · 2025-08-10T12:32:56Z

pismy
Aug 10, 2025

Hey

We're using mkdocs-material for our opensource project to-be-continuous:

The website skeleton is managed in the main repo: https://gitlab.com/to-be-continuous/doc
But the website also aggregates other repositories documentation (every template documentation page under Templates Reference)
You can see the repository name (and hyperlink) change when navigating from one page to another
We managed to support this behavior with the following:
- page metas repo_name and repo_url are added to documentation pages related to another repo than the main one
- we've overridden the source.html partial to take this into account

But so far we didn't find any proper way of adapting the mkdocs-material/src/assets/javascripts/components/source/facts/github/index.ts function to retrieve the Git repo stats (stars, forks, latest tag) from the right repository (b.t.w. I don't even know which repo stats it is currently displaying 😅)

Any idea how to deal with it?

Thanks for your help.
And thanks for this marvelous project 🙏 (producing beautiful documentation is a mandatory requirement for producing good documentation).

Answered by pismy

Aug 13, 2025

Works like charm ! (navigate around templates)
I didn't even have to override extra.js (everything is done in the source component)

View full answer

kamilkrzyskow · 2025-08-10T13:33:17Z

kamilkrzyskow
Aug 10, 2025
Collaborator

Hi @pismy,
nice tinkering so far, your issue is the "scope", which is used for caching the stats:
https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#scope

You can delete the cache value from the sessionStorage and you'll see it will update the stars according to the link set in the source.html partial.

The scope affects palette and other stuff too, so you might prefer to adjust the scope change only in the sources part:

mkdocs-material/src/assets/javascripts/components/source/_/index.ts

Line 84 in cbbef98

const cached = __md_get<SourceFacts>("__source", sessionStorage)

However, modifying the TypeScript would require you to do a rebuild of the theme and future maintenance.

One alternative could be to set up your own extra.js to track the last repoUrl in the source component, and remove the cached value, or do a similar thing with local page.meta value to override the extra: scope temporarily, but both could lead to constant fetching if the user explores the website.

Another alternative could be using a hook and modify the final minified bundle.js, you could do that because the __source string is rather unique, I've done something similar here:

Disabling media pause when switching content tabs. #6844 (reply in thread)
You could add a function to fetch the source component and add the repoUrl suffix to the scope id.

As a side note, you can define variables in the source.html, so you don't have to use 2 exact HTML structures, instead use the conditional to set a variable and have a single HTML tree that would use the variable contents.

4 replies

pismy Aug 11, 2025
Author

Thank you so much for the swift answer 🙏

As a side note, you can define variables in the source.html, so you don't have to use 2 exact HTML structures, instead use the conditional to set a variable and have a single HTML tree that would use the variable contents.

I actually realized this when pointing to our project source code and added it on my TODO 😅

pismy Aug 13, 2025
Author

Works like charm ! (navigate around templates)
I didn't even have to override extra.js (everything is done in the source component)

Answer selected by kamilkrzyskow

kamilkrzyskow Aug 13, 2025
Collaborator

Good idea with the sessionStorage injection before the bundle.js is loaded and thanks for sharing 👍
One way how you could improve it:

md_src_key could be loaded the same way it's done in the bundle.js, because the __md_scope is defined in the <head> element:

mkdocs-material/src/templates/partials/javascripts/base.html

Line 30 in 08fd869

__md_scope = new URL("{{ config.extra.scope | d(base_url) }}", location)

mkdocs-material/src/templates/partials/javascripts/base.html

Line 36 in 08fd869

__md_get = (key, storage = localStorage, scope = __md_scope) => (

At least that's my impression that it always loads /to-be-continuous/doc/.__source
Or you could also use other Material builtins __md_get and __md_set to have the same API.

The last thing would be to enclose the code in a self executing function to not expose the variables to global scope, but these are just minor nitpicks, so no pressure ✌️

pismy Aug 13, 2025
Author

Thanks for the suggestions 🙏

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Any idea how to retrieve Git repo stats (stars, forks, latest tag) in a multi-repo MkDocs site? #8386

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 1 comment 4 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Any idea how to retrieve Git repo stats (stars, forks, latest tag) in a multi-repo MkDocs site? #8386

Uh oh!

Uh oh!

pismy Aug 10, 2025

Replies: 1 comment · 4 replies

Uh oh!

Uh oh!

kamilkrzyskow Aug 10, 2025 Collaborator

Uh oh!

pismy Aug 11, 2025 Author

Uh oh!

pismy Aug 13, 2025 Author

Uh oh!

Uh oh!

kamilkrzyskow Aug 13, 2025 Collaborator

Uh oh!

pismy Aug 13, 2025 Author

pismy
Aug 10, 2025

Replies: 1 comment 4 replies

kamilkrzyskow
Aug 10, 2025
Collaborator

pismy Aug 11, 2025
Author

pismy Aug 13, 2025
Author

kamilkrzyskow Aug 13, 2025
Collaborator

pismy Aug 13, 2025
Author