Let's briefly talk about badges
A few notes about the small labels that sit at the top of almost every README.md file
I have always seen badges in several GitHub repositories without fully understanding how and when they are used. These are a few notes on the topic. This post should not be understood as comprehensive guide on the subject.
What Are Badges
Badges are small labels or images — usually near the top of a project’s README.md — that quickly show useful project information.
They can update automatically as the project changes. Since they are free and easy to include in GitHub repositories, these labels have become widely popular in the programming world.
For instance, this badge
signals that this website — Monograph — is up and running.
Obtaining Badges
The most common tool for creating badges is Shields.io. It offers a wide range of badges, including support for custom generation. It uses Simple Icons for logos and is the standard option for obtaining badges.
Embed Formats
Shields.io offers five embed formats for the same badge. Each one represents a different way to embed it.
| Format | Typical use |
|---|---|
| URL | Raw image URL for browsers or <img> tags |
| Markdown | Blogs, GitHub READMEs, and documentation |
| reStructuredText | Python library documentation |
| AsciiDoc | Technical manuals and long-form documentation |
| HTML | Web pages and structured web content |
The URL, Markdown, and HTML variants are the most frequently encountered. The same badge appears as follows in each format:
URL
https://img.shields.io/badge/example-format-red?style=for-the-badgeMarkdown
HTML
<img alt="Static Badge" src="https://img.shields.io/badge/example-format-blue?style=for-the-badge">Static Badges
The simplest type is the static badge. The three main fields are SUBJECT, STATUS, and color, with optional logo and color customization.

Dynamic Badges
Dynamic badges update automatically from an external source. Instead of hard-coded subject and status, Shields.io points at npm, GitHub, or a live website, and the badge reflects the current state.
Three examples:
1. npm version — queries the npm registry on every load and shows the latest published version:

2. License — reads the license field from the npm registry and reflects license changes on new publishes:

3. Website status — pings a public URL and reflects whether the site is up:

Outro
Another tool to consider for creating badges is For The Badge. It generates custom SVG badges with full control over the design.