A badge generator service to count visitors of your markdown file.
Hello every one!
In this post, I will tell you the story of me to creating the github-visitors-badge, it’s a svg image that can count your visitors for your GitHub README.md, issues, PRs in just one line markdown code.
All the story starting from I migrate all my blog posts from Hexo GitHub Pages to a GitHub issue based repository. After a painful migration, I found that there is no visitor tracking for the repository, though basically I myself am the only one visitor in most time 🙁 , I still want a visitor counting service for my every GitHub Issue and the README.
After a lot of searching, brainstorming, prototyping, I put my eye on the little badge in many other repository. Those
badges can show us:
- How much stars of the repository
- How much opened issues
- How much PRs
and all the badges is just a svg image file with a dynamic content in it.
After more searching, I found the
pybadge library which will generate a GitHub badge style dynamically with a very simple api.
So I can setup a python server, receive a svg file request, generate a dynamic svg file, return it, so it will display on the README.md.
What else? A database to store the previous count of each page so that in the next time the same request from the page received, I can increment 1 based on the previous count.
Here it is:
https://countapi.xyz/, a free counting API allows you to create simple numeric counters. IaaS, Integer as a Service.
CountAPI is a perfect chosen for this use case, and it’s easy to use, I don’t need to prepare a database(SQLite, MySQL, etc.), I just send a http request to the API, and can get the incremented number.
Also can avoid concurrent updating issue if too many visitors to your page in the same time, it will count them correctly, because the CountAPI is based on Redis.
So, for now, we have all we needed, just coding:
Why you have to pass a
page_id as a query parameter?
For the first version, I plan to use the
Referrer header in http request which is more convenient but GitHub proxy all the image request via its camo image server:
Your browser -> Github Camo -> My server
But Camo does not pass the Referrer header to my server for some reason, so I change to the query parameter solution.
How to deal with the image cache?
As you know, browser often caches images and in our case GitHub Camo also caches images.
Cache is good for us in most time, but for a badge to count visitor, it is a disaster because if the previous badge image are cached, there is no new request to my server and the count will not have chance the increment until the cache is invalid, that’s not what we want.
We want every time every one visitor our README.md the count will increment 1, so I did a trick thing:
Disable cache by adding a response header:
Set a passed expire time to 10 minutes AGO of current time:
'Expires': <10 minutes ago>
That’s it, after this little tricks every time you visitor the README.md, the browser(and camo) will know that the cached image is invalidated then send a request to my server to get the latest count.
- default style
- customized left text (default is
- customized left text with a space between words
- customzied color
- customized color and left text
- customized color and a space between words in left text
Contributions are very much appreciated!
Pull requests should be based on and submitted to the “main” branch
Please raise an issue to discuss what you plan to implement or change before
you start if it is going to involve a lot of work on your part.
Please keep pull requests specific, do not make many disparate changes or
new features in one request. A separate pull request for each feature change
Please ensure your changes work in Python 3.7+
Please add your github Username to the AUTHORS file
Code released under The GNU General Public License.