README Badge Generator
Build shields.io badges for your README — custom text badges or live repo stats
Fetched live from img.shields.io for an accurate preview.
<img src="https://img.shields.io/badge/build-passing-brightgreen?style=flat" alt="build passing" />
About this tool
The README Badge Generator builds shields.io badge URLs and ready-to-paste Markdown/HTML — either a fully custom badge (any label, message, color, and style) or one of several common "live" badges that pull real data from npm, GitHub, or PyPI, like a package's current version, weekly download count, or star count. Custom badges use shields.io's static badge endpoint directly, so you get full control over the label and message text. The live badges use shields.io's service-specific endpoints for npm, GitHub, and PyPI, which means the badge image updates on its own as the underlying data changes — the version badge always shows the current published version, the star count badge always shows the current count, without regenerating anything. Both Markdown and HTML output are provided, since most READMEs are Markdown but some project documentation sites render badges via raw HTML.
When to use it
- →Adding a build-status, license, or version badge to a new project's README
- →Generating a live npm version or download-count badge that stays accurate without manual updates
- →Building a custom badge for something project-specific, like a coverage percentage or a deployment environment label
- →Getting both Markdown and HTML badge snippets for a documentation site that needs the HTML form
Tips
- ◆Live badges (npm version, GitHub stars, etc.) update automatically as the underlying data changes — you never need to regenerate or replace them after adding them once.
- ◆For custom badges, a literal hyphen in your label or message text is automatically escaped correctly — you don't need to work around shields.io's `-` segment separator yourself.
- ◆The for-the-badge style reads better at a glance in a README's top badge row; flat or flat-square tends to look better inline with body text.
Frequently asked questions
Do the live badges (npm version, GitHub stars) need to be regenerated when the data changes?
No — that's the point of using shields.io's live endpoints instead of a static image. The badge URL always points at shields.io, which fetches current data from npm or GitHub's API every time the image is requested, so it reflects the current value automatically whenever your README is viewed.
What's the difference between the Markdown and HTML output?
They render identically — both just wrap the same shields.io image URL, optionally linking it to a URL. Markdown () is what nearly all README.md files use; HTML (<img src=...>) is for documentation sites or platforms that render raw HTML instead of Markdown, or where you need HTML-only attributes shields.io's Markdown form doesn't cover.
Can I use any color name, or only the presets shown?
The color presets cover the common shields.io named colors, but you can type any valid CSS color name or hex code (without the #) into the color field directly — the presets are just a shortcut for the most commonly used ones.