Documenter.jl: Add a "Star on GitHub" button along with Edit on GitHub in the docs

[logankilpatrick]

Hey all, @tlienart had the great suggestion of adding a "Star on GitHub" button to drive more stars (a typical metric to assess the use of a package across OSS) to our Julia packages. The example is given (which is very telling IMO) is that Documenter only has 294 stars but is very widely used across the ecosystem.

[guilhermebodin]

I would be happy to help in this one.

Should it be something in the direction of https://joshday.github.io/OnlineStats.jl/latest/ ?

[logankilpatrick]

Yes, maybe not that blatant but it's the exact idea.

[mortenpi]

I'd say it should probably go into either the header (with the "Edit" links etc) or the sidebar. MkDocs' Material theme is a good example in my opinion.

[guilhermebodin]

To make it like this I think we need to make a request as in https://github.com/squidfunk/mkdocs-material/blob/4848c7dd41996db053c93c108f5a5be589d0cda3/src/assets/javascripts/patches/source/github/index.ts

Is this possible on Documenter.jl?

[mortenpi]

Yep, you can include arbitrary JS in Documenter sites. Specifically, this loop

https://github.com/JuliaDocs/Documenter.jl/blob/567f200319a842db162a4c99b8d9d2b795d469e4/src/Writers/HTMLWriter.jl#L577-L581

gathers up the JS assets and outputs them into the documenter.js file, which then gets loaded with RequireJS.

[guilhermebodin]

Nice, I got this script working

// libraries: jquery
// arguments: $

function round(value) {
  if (value > 999) {
    const digits = +((value - 950) % 1000 > 99)
    return `${((value + 1) / 1000).toFixed(digits)}k`
  } else {
    return value.toString()
  }
}

$(document).ready(function(){
  $.getJSON( "https://api.github.com/repos/JuliaDocs/Documenter.jl", function( data ) {
      console.log(`${round(data.stargazers_count || 0)} Stars`)
      console.log(`${round(data.forks_count || 0)} Forks`)
  });
});

Now I am not so sure if this is a good solution because everytime the document is ready it tries to get the json.
And I am also not sure how this can be passed to the render_navbar Julia function.

[mortenpi]

Now I am not so sure if this is a good solution because everytime the document is ready it tries to get the json.

Perhaps not such a big deal. However, it would be an option to cache it on the client side, say so that it would only be re-checked once an hour or so. It could be stored in window.localStorage. The theme selector already stores stuff there.

And I am also not sure how this can be passed to the render_navbar Julia function.

For that you'd need to update render_navbar and make it emit some extra HTML, like a <div> with a unique ID, and then have the JS update the contents of the div. For inspiration, you can look at how we do it for the search, which also needs to send updates to the DOM.

[guilhermebodin]

I submitted a PR with the first iteration, it is still pretty raw.