README Badge Generator

Stop Copying Badge URLs From a Gist

You want a badge with your own label. Every result is a static list of somebody else's badges, so you copy one and edit the URL by hand — and the hyphen in your text silently breaks it. This shields.io badge generator builds the URL correctly and shows you the result as you type.

Static labels or live repository data. Both render in the preview before you commit anything.

How to Make a Custom Badge in Four Clicks

1. Pick static or live. Static shows fixed text; live reads real repo data.
2. Fill in the content. Left text, right text, colour — or a repo and a data source.
3. Choose a style and logo. The logo field takes a Simple Icons slug.
4. Copy the Markdown. Or linked Markdown, HTML, or the raw URL.

The preview is the point. A badge that is going to render grey and say invalid does it here, not after you have pushed a commit.

The Hyphen Rule That Breaks Hand-Built Badges

Shields.io reads a static badge URL as three parts separated by hyphens: label, message, colour.

https://img.shields.io/badge/build-passing-brightgreen

So a hyphen inside your own text splits the URL in the wrong place. Write "code-coverage" and shields.io reads "code" as the label and "coverage" as the message.

The fix is to double it — code--coverage. Underscores work the same way, and a space becomes an underscore or %20.

We handle all of that for you. It is the single most common reason a hand-edited badge comes out wrong, and nothing in the URL tells you what happened.

GitHub README Badges That Update Themselves

A static badge saying "v2.1.0" is a lie the moment you ship v2.2.0. Live badges read the real value each time someone loads your README.

That last row is worth thinking about. A last-commit badge is great while you are active and broadcasts "abandoned" the moment you stop.

The build badge needs the exact workflow filename. Point it at ci.yml when your file is build.yml and it renders invalid — the same way a typo does.

Why Your Badges Disappear Sometimes

You load your repository and half the badges are grey boxes. An hour later they are fine. Nothing changed on your side.

Shields.io makes unauthenticated GitHub API calls shared across every badge it serves. At busy times that hits the rate limit and badges fail until it resets.

There is no fix available to you. Self-hosting shields.io is possible and is a real service to run, which is rarely worth it for one repository.

There is also a caching layer you cannot see. GitHub proxies every README image through its own Camo service, so an updated badge can take minutes to appear even after shields.io serves the new value. That proxy is good for reader privacy and confusing for you.

How Many Badges Is Too Many?

Three or four. Past that they stop being information and become decoration.

The test we use: would a stranger deciding whether to install this actually check it? Licence, version and build health pass. Star count does not.

Every badge also pushes your install command further down the page. A twelve-badge header means the one line people came for is below the fold.

Building a full README rather than a single badge? The GitHub README generator adds the common ones automatically. For your profile page, the profile README maker handles social badges.

Where Badges Fit in the Rest of the File

Badges go directly under the title, on one line, before the description. That is the convention and it is worth following.

Wrap each in a link if the badge is actionable — a build badge should open the workflow, a version badge should open the releases page. Our output includes a linked Markdown option for exactly that.

Writing the rest of the file? Our guide on what belongs in a README covers the sections worth keeping, and the markdown image syntax reference explains how GitHub renders them.

Editing markdown freehand? The markdown preview editor gives you a live pane for the whole document.

Frequently Asked Questions

The Short Version

Pick your content, check the preview, copy the Markdown. A shields.io badge generator saves you the URL escaping, and the preview catches the failures before you push.

Then keep three or four. The rest is decoration that costs you your install command.