Search Monograph

Let's briefly talk about badges

A few notes about the small labels that sit at the top of almost every README.md file

Badges are cool

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 Monograph website status 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.

FormatTypical use
URLRaw image URL for browsers or <img> tags
MarkdownBlogs, GitHub READMEs, and documentation
reStructuredTextPython library documentation
AsciiDocTechnical manuals and long-form documentation
HTMLWeb 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:

Static Badge

URL

https://img.shields.io/badge/example-format-red?style=for-the-badge

Markdown

![Static Badge](https://img.shields.io/badge/example-format-blue?style=for-the-badge)

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.

Generic badge

![Generic badge](https://img.shields.io/badge/<SUBJECT>-<STATUS>-<COLOR>.svg)

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:

npm version

![npm version](https://img.shields.io/npm/v/astro?style=for-the-badge)

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

license

![license](https://img.shields.io/npm/l/astro?style=for-the-badge)

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

website status

![website status](https://img.shields.io/website?url=https%3A%2F%2Fastro.build%2F&style=for-the-badge)

Outro

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

Keep reading