Markdown badge generator
Updated
Design a shields.io badge with a live preview and copy it as markdown, HTML, or reStructuredText — or type a repo and package name and pick from a curated set of live badges for version, downloads, license, CI, coverage, and stars.
<img src="https://img.shields.io/badge/build-passing-brightgreen" alt="build: passing">.. image:: https://img.shields.io/badge/build-passing-brightgreen
:alt: build: passinghttps://img.shields.io/badge/build-passing-brightgreenHow does a shields.io badge URL work?
A static badge is just a URL: https://img.shields.io/badge/label-message-color. The three parts are separated by dashes, which is why a real dash inside the text must be doubled (--) and an underscore doubled (__). Spaces are percent-encoded. Options go in the query string: ?style=flat-square&logo=github&logoColor=white. Colors can be shields names (brightgreen, blue, critical), hex without the hash, or CSS names. Dynamic badges use a path per service instead — /npm/v/package, /github/stars/owner/repo, /github/actions/workflow/status/owner/repo/ci.yml — and shields fetches the live value.
Which badges belong in a README?
The useful ones answer a question a visitor has before adopting the project: is it maintained (last commit, CI status), can I trust it (coverage, license), how popular is it (stars, downloads), and which version am I getting (npm, PyPI). Put them on one line directly under the title, order them by importance, and skip badges that state the obvious. The README generator adds a sensible default row automatically; the README templates show where the row sits in a well-structured file.
Can I use these badges outside GitHub?
Yes. The HTML output works on any web page or in a GitLab README; the reStructuredText output is for Python projects whose README is .rst and for Sphinx docs. The raw URL can be dropped into a markdown image anywhere markdown is rendered, including Docs MD share pages.
How do I add a badge to a README?
Paste the markdown output under your title: . Wrap it in a link, [](target-url), to make the badge clickable. GitHub renders the SVG inline.
What is the difference between a static and a dynamic badge?
A static badge shows fixed text you typed, encoded into the URL. A dynamic badge queries a service (npm, GitHub, PyPI, Codecov) each time it is loaded, so the version or star count is always current.
Why does my badge text show dashes or underscores wrong?
In static badge URLs a single dash separates label, message, and color, so a literal dash must be written as a double dash (--) and a literal underscore as a double underscore (__). This tool escapes both for you.
Which logos can I use?
Any icon in the simple-icons set, by its slug: github, npm, python, docker, rust, typescript, and about 3,000 more. Add logoColor to recolor it, for example white on a dark label.
Do badges slow down my README?
Each badge is one small SVG request served by shields.io with caching, and GitHub proxies images through its camo service. A row of five badges is normal; more than six or seven becomes visual noise rather than a performance problem.