PSA: Linking to Package Documentation in GitHub Repos

If you maintain a package, I’d like a minute of your time.

Thanks to Documenter.jl, the vast majority of packages I’ve found have documentation. Due to GitHub’s utter dominance of the repo hosting landscape, and the default workflow for Documenter, these are usually hosted on GitHub pages.

However, many packages don’t link to that documentation in the About box, which appears in the right sidebar of the repo homepage. That’s the expected place for these links.

For the default case, this is very easy to change. Just click the gear :gear: icon next to About on the homepage, and check the box which says “Use Your GitHub Pages website”. Done! Now the documentation is immediately available in the expected place. One minute out of your day. If the documentation is hosted in some other way, you’d need to paste in the link yourself.

While you’re in there, feel free to add a few tags describing what your package is all about. It can’t hurt. :wink:

Thanks for all your various contributions to Julia’s ecosystem, it’s hard work, and you should know that it’s appreciated.


Typically most packages add the readme badges that link to the documentation, as is suggested by Documenter. Perhaps this suggestion may be added to its own docs


Really? I always thought the “standard” location was the README badge … but I guess YMMV

1 Like

A docs badge is a good thing to have, I’ve added Documenter{GitHubActions}() to my standard PkgTemplate so all that nice stuff gets auto-generated whenever I start a package. Most packages (not all) have a badge like that, or a link in the README which goes through to the documentation. These are all good things.

The GitHub About sidebar has a field for a link, and a checkbox to immediately populate that link with the home directory of GitHub Pages for the repo. If a package is doing something else with that link, like linking it to their company, or a wiki, or anything else, I take it for granted that they know what they’re doing.

But if there’s no link there right now, why not open it, click the checkmark, and have it link to the documentation? It’s more discoverable, for one thing: the GitHub badges all kind of blend together, it isn’t so obvious that among various buttons showing CI status, Aqua results, and so on, there’s also something to click to get to the documentation. The sidebar link is above the fold, directly under the blurb, and self-evidently a link.

People who are new to the community might not immediately learn that the badge at the top of the readme which says “docs: stable” can be clicked to get to the documentation, and isn’t just doing what the other badges do, informing you that the docs are “stable”. But someone can be on their first visit to GitHub, and they’ll understand that the link in the about box can be followed to learn more about the repo.

Across ecosystems, this is the standard place to put the documentation link, which is why GitHub makes it very easy to do that. I consider the docs badges to be complementary to that, rather than a replacement for it.