GitHub README Badge Generator — shields.io-style, 50+ presets, Markdown/HTML/AsciiDoc/RST output

Real-world use cases

• Ship a static "License MIT" badge without depending on shields.io

  Your README has eight badges across the top. Three of them never change (license MIT, made-with-typescript, code style prettier). For each shields.io URL in that group, you pay one DNS lookup + one HTTPS round trip per page view, per visitor, and a 503 on shields.io makes your badges show as broken-image icons. Pick the "license MIT" preset, copy the SVG, save it to `assets/badge-license.svg`, and swap the shields.io URL in your README for the relative path. The badge now loads from the same origin as the README, no external dependency, no rate limit.

• Match shields.io style exactly across a custom + live mix

  Your README has six live badges from shields.io (build, npm version, downloads, etc.) and you want to add a custom "Made by Acme" badge. Generating it elsewhere usually produces a 2-3 pixel height mismatch and a slightly off color — Acme looks "cheap" next to shields.io's row. This tool's `flat` style ships the same 20-pixel height, same Verdana-ish font width, same color palette as shields.io, so your custom badge sits in the row pixel-flush. Use the for-the-badge style if your existing row uses that; mix and match are both fine.

• Batch-generate 30 badges for a monorepo with one paste

  A monorepo with 30 packages, each needing a "npm @scope/foo v1.x.x" badge plus a "license" badge. Switch to Batch mode, write one badge spec per line in the format `label|message|color`, paste 30 lines, and the tool emits 30 SVGs + 30 Markdown snippets at once. Drop them in the monorepo's docs site or root README in one commit, no per-package round trip.

• Embed in AsciiDoc / Antora docs for a Java project

  Most Java open-source projects use AsciiDoc (Antora, Asciidoctor) for docs. The shields.io URL works in AsciiDoc but the syntax is `image:url[alt,link=...]` rather than markdown's `![]()`. This tool's AsciiDoc output formats correctly out of the box: `image:badge.svg[License MIT,link=https://...]`. Drop straight into an `index.adoc` or any chapter file; Antora picks it up without you remembering the syntax.

• Build a "tech stack" row for a personal site without 12 HTTP requests

  Your developer portfolio's homepage lists "Stack:" with 12 brand badges (React, Node, Postgres, Docker, AWS, ...). With shields.io, that's 12 SVG URLs each making a network round trip — visible flicker on slow connections, Largest Contentful Paint penalty in Lighthouse. Use the brand presets here, save 12 SVGs to your `/public/badges/` folder, reference them as local images. LCP drops 200-400ms, Lighthouse Performance score climbs 5-10 points, and the badges still look identical to shields.io.

• Render reStructuredText badges for a Python package on PyPI

  PyPI's README rendering supports reStructuredText, and most established Python projects (Django, Flask, numpy) use RST. The syntax for a clickable badge in RST is three lines: `.. image::`, `:target:`, `:alt:`. This tool's RST output gets those three lines right, including indentation. Paste into `README.rst`, run `python -m build`, and the badge renders correctly on PyPI's package page — markdown badges silently don't render there.

Common pitfalls

• Forgetting to URL-encode spaces in your message as `_` (underscore) and underscores as `__` (double underscore). The tool encodes automatically when you click Copy, but if you hand-edit the URL afterwards and add literal spaces, the badge will break on shields.io-style consumers that expect the encoded form.

• Using bright neon colors for the right (message) block. shields.io's design language uses muted greens (`#4c1` for passing) and reds (`#e05d44` for failing) — bright colors visually scream "this is a custom one-off" and don't sit well next to the rest of your README. Stick to the muted palette unless intentional.

• Hardcoding GitHub-proxied URLs (`camo.githubusercontent.com/...`) instead of the raw badge URL. GitHub's image proxy rewrites your image src on render, but the camo URL is GitHub-specific — paste it into a non-GitHub README and the image breaks. Always use the original SVG path.

• Mixing styles within one badge row (for-the-badge next to flat-square). Each style has a different height (28px vs 20px) and the row becomes visually noisy. Pick one style per row.

• Embedding too many badges. Eight is a soft cap — past that, the badge row pushes your project description below the fold on most screens and visitors bounce before reading what your project actually does.

Privacy