Markdown Badge Generator (shields.io)
Free badge generator for GitHub READMEs. Build shields.io badges with custom labels, colors and logos, then copy markdown or HTML. No signup.
Image URL
https://img.shields.io/badge/build-passing-brightgreen?logo=github&logoColor=white
Markdown
[](https://github.com/owner/repo/actions)
Click Add to row to collect several badges into one line.
What Are GitHub Badges?
GitHub badges are small SVG images, usually served by shields.io, that show a project fact such as the build status, license, version or star count at the top of a README. Each one is an image link: the image URL encodes the label, message and colour, and the link points to the page with more detail. This badge generator builds that URL for you, previews the result and prints the markdown, HTML, reStructuredText or AsciiDoc to paste.
The shields.io badge generator on this page covers two kinds of badge. Static badges show fixed text you type. Dynamic badges read live data from GitHub or the npm registry, so a stars badge updates as the repository is starred. Everything is assembled in your browser; only the preview image is loaded from img.shields.io.
How to Make README Badges
- Choose Static badge and enter a label and message, or Dynamic badges and enter your owner/repo or npm package.
- Pick a colour from the palette or type a hex value such as #4c1, and a style: flat, flat-square, plastic, for-the-badge or social.
- Optionally add a simple-icons logo slug and a link URL.
- Check the live preview, then copy the markdown or another format.
- Click Add to row for each badge you want in the header and copy the whole row at once.
shields.io Static Badge Syntax
A static badge URL is https://img.shields.io/badge/LABEL-MESSAGE-COLOR. Because dashes and underscores separate the parts, they have to be escaped in the text:
| Character you type | In the URL | Example |
|---|---|---|
| space | _ | made_with |
| - | -- | Apache--2.0 |
| _ | __ | snake__case |
| % and other symbols | percent-encoded | 100%25 |
Colours can be one of the named values (brightgreen, green, yellow, orange, red, blue, lightgrey, success, important, critical, informational, inactive) or a hex value without the hash. Query parameters add style, logo, logoColor and labelColor.
Dynamic Badge Presets
The dynamic tab takes an owner/repo (or a full github.com URL) and a package name and fills in the shields.io endpoints: /github/license, /github/stars, /github/forks, /github/issues, /github/last-commit, /npm/v, /npm/dm and /github/actions/workflow/status/OWNER/REPO/FILE.yml for the build badge. The coverage preset is a static placeholder coloured by the percentage you type; replace it with a Codecov or Coveralls badge once coverage is reported by CI. Each preset also links the badge to the matching GitHub or npm page.
Where to Put GitHub Badges
Keep github badges on one line directly under the title, ordered by how often readers act on them: build status and coverage first, then version and downloads, then license and social counts. Four to six is plenty; a wall of badges hides the description. The markdown badge generator output also works in GitLab, Bitbucket, Gitea and docs sites, since it is plain image-link markdown. For a full README skeleton with the badge line already placed, use the README generator.
Frequently Asked Questions
How do I add github badges to a README?
Build the badge, copy the markdown and paste it directly under the H1 of README.md. The markdown is an image link: [](https://link). GitHub renders the image from shields.io on every page view, so dynamic badges always show the current value.
Static or dynamic badge, which should I use?
Use a static badge when the text never changes, such as 'made with TypeScript' or a platform label. Use a dynamic preset for anything that changes: license, stars, forks, open issues, last commit, npm version, downloads and GitHub Actions build status all update automatically.
Why does my badge show 'invalid' or 'not found'?
The owner/repo or package name is wrong, the repository is private, or the workflow file name does not match a file in .github/workflows. Check the image URL shown under the preview and open it in a new tab; shields.io explains the error in the badge itself.
Can the badge generator add a logo?
Yes. Type a simple-icons slug in the Logo field, such as github, npm, python or docker, and optionally a logo colour. shields.io draws the icon on the left of the badge. Slugs are lowercase and match the names on simpleicons.org.
What formats can I copy?
Markdown for READMEs and wikis, HTML for web pages and GitHub profile READMEs that need alignment, reStructuredText for Python projects on PyPI, and AsciiDoc for docs built with Antora. The badge row collector joins several badges in whichever format is selected.