Writing Great README FilesLesson 2.5

Adding badges and metadata to signal project health

shields.io badges, CI status badges, version badges, license badges, coverage badges, badge placement, badge overload, project metadata signals

Badges and Project Metadata

Badges communicate project health at a glance before a developer reads a single word. A passing CI badge, a current version, and a clear license are trust signals. Missing or broken badges signal abandonment.

Essential Badges


[![CI](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/user/repo/actions)


[![npm version](https://badge.fury.io/js/your-package.svg)](https://badge.fury.io/js/your-package)


[![Coverage Status](https://coveralls.io/repos/github/user/repo/badge.svg?branch=main)](https://coveralls.io/github/user/repo)


[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Badge Placement

Badges go immediately after the project title, before the description. This placement puts health signals where developers look first. Never scatter badges throughout the README.

Avoid Badge Overload

More than 6–8 badges becomes noise. Prioritize: build status, version, test coverage, and license. Skip vanity badges — "PRs welcome" and "Awesome" badges signal nothing useful to a developer evaluating your project. Every badge must answer a question a developer has, not advertise enthusiasm.

A broken CI badge is worse than no badge. Only display badges whose underlying services you actively maintain.

Ready to practice?

MCQs · Coding challenges · Mini project