Live badges and widgets for your README
In short: a README badge is just an image in Markdown, so pointing one at a live endpoint gives you a permanently up-to-date chart or counter. The star history image below is exactly that — one line, no key, no build step.
Static badges go stale the moment you paste them. Anything served from an endpoint stays correct without you doing anything, which is why live badges have largely replaced screenshots of charts.
A live star history chart
The endpoint returns SVG at 1200×630, renders on a transparent background and follows your repository's colour scheme with a theme parameter:
Comparing several repositories
Repeat the parameter to overlay up to six projects — useful for a monorepo, or for comparing a project against a dependency:
Line-of-code badges with Shields.io
Charts are images, but a single number works well as a badge. Shields.io can call the LOC endpoint and format the result:
The badge endpoint returns just the number, so the badge stays small and readable. Call the full API yourself if you need the per-language breakdown rather than a single total.
A few good badges for any repository
- Licence — a link to the licence file.
- Latest release — shields pulls it from the GitHub releases API.
- Contributors — number of people who have committed.
- Activity — commits in the last month, which says more than raw total.
Keep images small
Charts are the heaviest element on most READMEs. A few habits keep it fast:
- Use SVG rather than PNG — it scales and compresses better.
- Give the image explicit dimensions so the page does not shift while it loads.
- Do not stack three charts above the fold; one is plenty.
What to avoid
Badges that query a rate-limited API on every page render become your problem, because every visitor to your repository triggers a request. A cached endpoint like the star chart is safe precisely because the heavy work happens once every six hours, not once per view.
Other places these work
The same image URL works anywhere Markdown is rendered: GitHub Gists, GitLab READMEs, documentation sites, or a project homepage. Because it is a plain HTTPS image with no session or key, there is nothing to configure on the embedding side.
Frequently asked questions
How do I add a star history chart to my GitHub README?
Add one Markdown image line pointing at the SVG endpoint: . It renders at 1200x630, updates automatically and needs no key or build step.
Do README badges need an API key?
Not with these endpoints. A badge is just an image in Markdown, so it can point at any HTTPS URL. The star history and line-of-code endpoints accept plain GET requests with no authentication.
Will a live badge slow down my repository page?
Only if it queries a rate-limited API on every render, because each visitor triggers a request. A cached endpoint is safe because the expensive work runs once every six hours rather than once per page view.
Can I compare multiple repositories in one badge or chart?
Yes. Repeat the github parameter up to six times on the star history chart endpoint, for example /v1/stars/chart?github=org/one&github=org/two, and each series gets its own colour.