README Badges: Build Status, License, and Version at a Glance
A README badge is a small Markdown image. Build status, license, and version are the three that matter most, and each one points at a service that generates a fresh SVG on every request. You add one the same way you'd add any image: paste a line of Markdown near the top of your README.
Quick answer
Badges belong right after your project's name and one-line description, before Installation or Usage — that's the section order most README templates follow. A visitor sees build health, license, and version before reading anything else. Under the hood, a badge is just  pointed at an image a service regenerates on the fly. Build status usually comes straight from GitHub; license and version usually come from shields.io.
Step-by-step
A badge is a Markdown image, nothing more
Badges don't need special syntax. CommonMark's image rule is  — the same construct you'd use for a screenshot, just with a URL that returns a live-generated image instead of a static file. Wrap it in link syntax, [](target-url), and the badge becomes clickable, pointing at the CI run, the LICENSE file, or the releases page it's reporting on. It's the same pattern GitHub uses for its own Markdown alerts: a convention layered on top of standard Markdown, not a new syntax to learn.
Build status badge
GitHub builds a status badge for every workflow at a predictable URL: github.com/OWNER/REPOSITORY/actions/workflows/WORKFLOW-FILE/badge.svg. Drop that into an image tag and you're done. No third-party service required. Two query parameters scope it further: append ?branch=BRANCH-NAME to show a specific branch's status, or ?event=push to show only push-triggered runs. Don't want to type the URL by hand? GitHub will generate the Markdown for you — open the Actions tab, pick a workflow, open the overflow menu, and choose "Create status badge."
License badge
For license and version, shields.io is the common default. Its badges follow a simple label-message-color URL pattern: img.shields.io/badge/license-MIT-blue renders as a flat badge reading "license: MIT." Point the badge's link target at your repo's LICENSE file so a click confirms the terms directly.
Version badge
Same pattern, two ways to use it. A static badge — img.shields.io/badge/version-1.2.0-blue — is a hand-set string you update on release. A dynamic badge reads a live value from a package registry (npm, PyPI, and others), so it updates itself the moment you publish. Pick static if you tag releases infrequently. Pick dynamic if the project ships to a registry and you'd rather not remember to bump the badge by hand.
Common problems and fixes
Badge shows a "not found" or broken image. Almost always a typo in the owner, repo, or workflow file name in the URL, or the workflow file got renamed after the badge was copied. Rebuild the URL from scratch rather than hunting for the one wrong character.
Badge doesn't render outside GitHub. GitHub's native workflow badges on a private repository aren't accessible to viewers who don't have repo access. That's a private-repo limitation specific to GitHub's own badges, not a shields.io or Markdown issue.
Badge looks frozen on an old status. Usually a browser or CDN caching the SVG response. Most badge services set short cache headers, so a hard refresh (or a cache-busting query string) resolves it without touching the underlying Markdown at all.
The badge row keeps growing. Build status, license, and version answer the three questions a first-time visitor actually has: does this work, can I use it, what version is it. Coverage, download counts, and star counts are fine additions later, but stacking six or seven badges at the top of a well-structured README buries the signal in noise. The README is a file you're editing and re-editing over the project's life, so it's worth keeping it under version control like every other Markdown file in the repo — a badge row you tightened up last month shouldn't quietly drift back to seven badges next month.
Doing this with Carets
A README badge is one line of Markdown among many, and that's exactly the kind of file Carets is built for. Syntax highlighting means a  line at the top of the file and a fenced code block further down are both easy to scan at a glance — you're not squinting at plain text to tell where one ends and the next begins. Files, projects, and tags keep the README next to the rest of a project's docs and snippets instead of scattered across apps, so the badge URLs you reuse project to project stay findable. And because Carets is native and fast on iPhone, iPad, and Mac, pasting in a fresh badge URL and previewing how it reads takes a moment, not a round trip through a web app.
Keep a small file of go-to badge Markdown, the same way you'd label a reusable code block with a file name, and Carets is where that file lives: plain text, portable, ready the next time you start a README from scratch. Download Carets for iPhone, iPad, and Mac.
Frequently Asked Questions
What is a README badge, technically?
It's an ordinary Markdown image —  — pointed at a service that returns a freshly generated SVG on every request. There's no special badge syntax in Markdown or GitHub Flavored Markdown; the "badge" behavior comes entirely from the image being dynamic, not static.
Do I need shields.io, or can I use GitHub's own badges?
For build status, GitHub generates its own badge per workflow at a predictable URL, no third-party service required. For license and version badges, shields.io is the common default because it can read a static value or pull a live one, but any service that returns an image at a stable URL works the same way.
Why doesn't my badge show up outside GitHub?
If the badge points at a private repository's native GitHub Actions badge, it won't render for viewers outside that repo's access. That's specific to GitHub's own private-repo badges, not a general limitation of badges or shields.io.
Where should badges go in a README?
Right after the project name and one-line description, before Installation or Usage. That puts build health, license, and version in front of a visitor before they read any detail — the convention most open-source READMEs and README templates follow.
How many badges is too many?
Enough to answer "does this work, can I use it, what version is it": typically build status, license, and version/release. Stacking six or seven badges turns a README header into noise; keep the row to what a first-time visitor actually needs to decide whether to use the project.
Conclusion
A README badge is nothing more than a Markdown image pointed at a service that regenerates it live. Build status, license, and version cover what a visitor actually needs to know before they read further. Once those three are in place, the same pattern extends to anything else worth surfacing, from test coverage to download counts. Add sparingly, and the badges you do show stay meaningful.