Advertisement
Guide
About the README Badge Generator
Badges are the small status pills at the top of a README — license, build status, version, package downloads. They give a repository instant credibility and let visitors read its state at a glance.
Most are served by shields.io, which builds an SVG from a URL. Getting that URL right means remembering the escaping rules and query parameters, so this generator does it for you and hands back ready-to-paste Markdown.
The escaping rule that trips people up
shields.io separates the label, message, and color with dashes — so a literal dash in your text must be doubled (--), an underscore doubled (__), and a space written as _ or %20. This tool escapes all of that automatically, which is usually the reason a hand-written badge renders wrong.
Styles and logos
Five styles are available: flat (the default), flat-square, plastic, for-the-badge (large and uppercase), and social. You can also add an icon using any simple-icons slug — for example github, npm, or typescript.
Static vs dynamic badges
These are staticbadges — the text is fixed until you change the URL. shields.io also offers dynamic badges that read live data, such as your latest npm version or CI status, by pointing at a service endpoint instead. Use static badges for things like license and "PRs welcome", and dynamic ones for anything that changes.
How to use it
- 1Pick a preset like License or Build, or type your own label and message.
- 2Choose a color and style, and optionally add a logo slug.
- 3Add a link if the badge should be clickable.
- 4Copy the Markdown and paste it at the top of your README.
Frequently asked questions
Why does my badge text look wrong?
Almost always escaping. shields.io treats dashes as separators, so literal dashes must be doubled and spaces written as underscores. This tool handles that automatically.
How do I add an icon to a badge?
Enter a simple-icons slug in the Logo field — for example github, npm, docker, or typescript. The icon appears on the left of the badge.
Can I make the badge clickable?
Yes. Add a URL in the Link field and the generated Markdown wraps the image in a link, which is how license and build badges usually behave.
Are these badges live or static?
These are static — the text is fixed in the URL. For live data like CI status or npm version, use shields.io dynamic endpoints instead.
Does the badge image load from a server?
The badge image itself is served by shields.io, since that is what renders it. The URL and Markdown are built entirely in your browser.