Markdown Badge Generator

What the Markdown Badge Generator does

The Markdown Badge Generator builds the small two-part status labels you see at the top of GitHub README files, such as "build | passing" or "license | MIT". You fill in a few fields, press Generate Badge, and the tool writes a ready-to-paste Markdown image tag that points at a shields.io static badge URL. A live preview shows the badge exactly as shields.io draws it, so you can check the colors and wording before the snippet goes into your repository.

Badges are a tiny detail, but they do real work. A visitor landing on a project page reads them in a second and learns the license, the current version, the language, whether the docs are online, and where to get support. Writing the URL by hand means remembering the shields.io path format, encoding special characters and wrapping everything in the right brackets. This page removes that busywork.

The fields and what each one controls

The Badge Settings card on the left holds six inputs. Every one maps to a specific piece of the generated URL or Markdown.

Because empty fields fall back to defaults, pressing Generate Badge with nothing typed still produces a valid "label | message" badge in blue. That is handy as a quick test, but remember to replace the placeholders before you publish.

What the output looks like

Without a link, the output is a single Markdown image:

![build](https://img.shields.io/badge/build-passing-brightgreen?style=flat&logo=github)

With a link, the image is wrapped inside a Markdown link so that clicking the badge opens your page:

[![build](https://img.shields.io/badge/build-passing-brightgreen?style=flat)](https://example.com)

The label text doubles as the image alt text, which is what screen readers announce and what appears if the image fails to load. Pick a label that makes sense on its own for that reason.

How to create a badge, step by step

1. Type the left-side text into Label, for example license.
2. Type the right-side text into Message, for example MIT.
3. Enter a color name or a hex code in Color. Hex codes go in without the hash sign, such as ff69b4.
4. Choose a look from the Style drop-down.
5. If you want an icon, type its name into Logo optional.
6. If the badge should be clickable, paste a full address starting with http:// or https:// into Link optional.
7. Press Generate Badge. The Badge Preview card shows the rendered badge and the Output Markdown editor fills with the snippet.
8. Press Copy Badge to put the snippet on your clipboard, or Download to save it as markdown-badge.md.
9. Paste it at the top of your README, usually right under the project title.

The two status cards above the preview give quick feedback. Badge status switches from "Not generated yet" to "Badge generated", and Clickable badge reads "No link", "Valid link" or "Check link" depending on what is in the Link field. The footer under the output shows the snippet length and the length of the shields.io URL in characters. Clear resets every field, sets Style back to flat and empties the preview.

How it works behind the scenes

All the building happens in your browser with a few lines of JavaScript. Nothing you type is sent to this site's server. The tool URL-encodes each of the three text parts, joins them with hyphens into the path img.shields.io/badge/LABEL-MESSAGE-COLOR, and appends ?style= plus an optional &logo= parameter.

The preview is a normal image request to img.shields.io, the free badge service that GitHub READMEs rely on. That means your browser contacts shields.io to draw the preview, and anyone who later views your README will load the badge from shields.io too. If shields.io is slow or blocked on your network the preview may stay blank even though the Markdown is correct.

Getting spaces, hyphens and underscores right

This is the one area that trips people up. The shields.io badge path uses single hyphens to separate the label, message and color. The tool converts every space you type into a hyphen, so a label like build status becomes build-status in the URL, and shields.io then reads "build" as the label and "status" as the message. The badge comes out wrong.

The fix is to use the shields.io escape conventions yourself in the input fields:

• Type an underscore where you want a space: build_status renders as "build status".
• Type a double hyphen where you want a literal hyphen: pre--release renders as "pre-release".
• Type a double underscore where you want a literal underscore: snake__case renders as "snake_case".

The live preview is the quickest way to confirm the badge reads the way you expect. If the preview shows text shifted between halves, check for a stray space or single hyphen.

Practical uses

• Open-source projects: license, latest version, supported language version and "PRs welcome" badges in the README header.
• Internal repositories: a "docs | internal" badge linking to the wiki, or a "owner | platform team" badge so people know who to ask.
• Course and template repos: labels such as "level | beginner" or "status | archived" that set expectations at a glance.
• Package pages: badges for npm, Docker or PHP using the matching logo name.
• Profile READMEs: a row of skill or tool badges with logos, each linking to a project.

Tips for clean, readable badges

• Keep labels short. One or two words per half reads best at badge size.
• Use color to mean something. Green for passing or stable, orange for beta or warning, red for failing or deprecated, blue for neutral information.
• Use the same style for every badge in a row. Mixing flat and for-the-badge looks untidy.
• The social style is designed for counters and follow buttons; it does not show your custom color the way the other styles do.
• Check the link status card before copying. "Check link" means the Link field does not start with http or https, and the badge may not click through correctly.
• When you need several badges, generate them one after another and paste each snippet on the same line in your README separated by a space so they sit side by side.

What not to do

• Do not expect a live, auto-updating badge. This tool builds static badges whose text is fixed. A "build | passing" badge made here will say "passing" forever, even if your build breaks. Dynamic badges that read from CI, npm or GitHub need a different shields.io endpoint.
• Do not put secrets, private URLs or internal hostnames in the label or message. The text becomes part of a public image URL that shields.io receives.
• Do not type a # in front of a hex color. It gets encoded and shields.io will not recognise it.
• Do not rely on an unknown logo name. If shields.io does not know the name, the badge simply appears without an icon.

Limitations

• Only static badges in the /badge/ format are produced. There are no options for dynamic data, query-based endpoints or JSON sources.
• The available parameters are style and logo. Options such as logo color, label color, cache seconds or custom width are not exposed in the form, though you can add them to the URL by hand after copying.
• Spaces are converted to hyphens, so you must use underscores for spaces as described above.
• The Link field is checked only for an http or https prefix. The tool does not visit the address to see whether it works.
• The preview depends on img.shields.io being reachable from your browser.
• The output is Markdown only. If your site needs an HTML <img> tag or reStructuredText, you will need to convert it.

Related Markdown tools

Once your README has its badges, the Markdown Link Extractor lists every link in the file and the Markdown Image Extractor lists every image, including your badge URLs, which makes a quick audit easy.

Frequently Asked Questions