Markdown Badges for GitHub: The Ultimate Reference

Badges are the small visual chips at the top of a README that instantly communicate a project's health, license, version, and build status. They're powered by shields.io — a service that generates SVG badges on the fly.

Basic Badge Syntax

Every badge is just a markdown image with a URL:

markdown
![Label](https://img.shields.io/badge/label-message-color)

For example:

markdown
![Version](https://img.shields.io/badge/version-1.0.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Status](https://img.shields.io/badge/status-active-brightgreen)

The Most Useful Badges

Build & CI Status

markdown
![GitHub Actions](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)
![CircleCI](https://img.shields.io/circleci/build/github/user/repo/main)

Package Version

markdown
![npm](https://img.shields.io/npm/v/package-name)
![PyPI](https://img.shields.io/pypi/v/package-name)

License

markdown
![License](https://img.shields.io/github/license/user/repo)

Language & Framework

markdown
![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue?logo=typescript)
![Next.js](https://img.shields.io/badge/Next.js-15-black?logo=next.js)
![React](https://img.shields.io/badge/React-18-61DAFB?logo=react)

Stars & Forks

markdown
![GitHub Stars](https://img.shields.io/github/stars/user/repo?style=social)
![GitHub Forks](https://img.shields.io/github/forks/user/repo?style=social)

Badge Styles

Shields.io supports 5 styles via the ?style= parameter:

for-the-badge is popular for visually rich READMEs:

markdown
![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)

Adding Logos

Add any Simple Icons logo with &logo=name:

markdown
![Node.js](https://img.shields.io/badge/Node.js-339933?logo=node.js&logoColor=white)
![PostgreSQL](https://img.shields.io/badge/PostgreSQL-316192?logo=postgresql&logoColor=white)
![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white)

Color Reference

Named colors: brightgreen, green, yellowgreen, yellow, orange, red, blue, lightgrey

Or use any hex: ?color=ff69b4

Linking Badges

Wrap the image in a link to make it clickable:

markdown
[![npm](https://img.shields.io/npm/v/my-package)](https://www.npmjs.com/package/my-package)
[![GitHub Stars](https://img.shields.io/github/stars/user/repo?style=social)](https://github.com/user/repo/stargazers)

Recommended Badge Stack

markdown
[![CI](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/user/repo/actions)
[![npm version](https://img.shields.io/npm/v/package-name.svg)](https://www.npmjs.com/package/package-name)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![codecov](https://codecov.io/gh/user/repo/branch/main/graph/badge.svg)](https://codecov.io/gh/user/repo)

Best Practices

• Less is more — 3–6 badges is the sweet spot
• Put badges above the fold — first lines of the README, before prose
• Use dynamic badges — pull live data where possible
• Keep a consistent style — pick one style and use it throughout
• Link every badge to its relevant page

Ready to build your badge stack? Use MarkGenie's editor to draft and preview your README badges instantly.