Skip to content

M0034 readme-badges

Rule: The README carries a badge for the book, CI and every published crate, each linking to its target.

Code M0034 (stable, never reused)
Id readme-badges
Category repo
Source spirit_level
Fix exact: spl check --fix applies it

Level per tier

Tier Level Reason
small warn the top of the README tells a visitor whether the project passes and where its book, crate and API docs are
small-workspace warn the top of the README tells a visitor whether the project passes and where its book, crate and API docs are
medium warn the top of the README tells a visitor whether the project passes and where its book, crate and API docs are
big warn the top of the README tells a visitor whether the project passes and where its book, crate and API docs are
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
file string "README.md" the README, relative to the root
workflow string ".github/workflows/ci.yml" the CI workflow whose status badge the README shows

Why

The top of the README is where a visitor decides whether the project is alive and where to read on. A row of badges answers both at a glance: the CI status of the default branch, the published version, the API docs, the book. A badge that links somewhere else, or a project that has a book nobody can find from its README, wastes that place.

What the README must carry follows from what the repo has, read from its own files:

The repo has Badge links to Image
a book with site_url in zensical.toml or mkdocs.yml the site_url any
the CI workflow (parameter workflow) and a GitHub repository https://github.com/OWNER/REPO/actions/workflows/ci.yml that page's badge.svg
a published crate (publish not false) https://crates.io/crates/NAME any
a published crate with a library https://docs.rs/NAME any

A badge is a linked image: [![alt](image)](link) in Markdown, or <a href="link"><img src="image"></a> in HTML. A link may go deeper than the address in the table (https://docs.rs/NAME/latest/NAME/) or carry a query (?query=branch%3Amain). Badges in code blocks and HTML comments do not count.

[![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/NAME)](https://crates.io/crates/NAME)
[![docs.rs](https://img.shields.io/docsrs/NAME)](https://docs.rs/NAME)
[![Book](https://img.shields.io/badge/book-book.example.org-blue)](https://book.example.org/)

How to fix

Add the badge the finding names. spl check --fix inserts it after the README's existing badges, in their form (Markdown or HTML). Without any badges, each one goes in a block of its own before the first paragraph, after a title, a logo or an HTML header; put them on consecutive lines to show them in one row. A CI badge that shows another image is changed by hand to show the workflow's badge.svg.

Configure

[lints.readme-badges]
level = "deny"
file = "README.md"
workflow = ".github/workflows/ci.yml"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(readme-badges) <reason> (waivers); the code works there too, as in [lints.M0034].