Markdown Tidy
◈ Go Premium
← Blog

README.md: a writing guide with examples (2026)

A README is your project's storefront. The structure that works, the sections that matter, and the patterns that make a README convert a curious visitor into a user.

A README.md is the file every visitor to your GitHub repo sees first. It's your project's storefront, its sales page, and its quickstart documentation — usually in 300-1000 lines. A good README is the difference between a star and a closed tab.

This guide covers the structure that works in 2026, the sections that matter (and the ones to skip), and the writing patterns that make a README actually useful.

The structure that works

# Project name

> One-line description — what it is, who it's for.

[Badges]
[Hero image / screenshot]

## Why

What problem this solves, in two paragraphs.

## Install

The fewest commands needed to get started.

## Quick example

The smallest piece of code that does something useful.

## How it works

The mental model. Not the API reference — that lives elsewhere.

## Documentation

Link to the real docs site.

## Contributing

Link to CONTRIBUTING.md. One-line for "how to run tests locally."

## License

SPDX identifier.

That's the structure 95% of high-star READMEs converge on. Variations exist (a Table of Contents at the top for very long READMEs; a "Sponsors" section for OSS projects; a "Comparison" table for tools entering a crowded space). The core shape doesn't change.

The one-line description test

Look at the top of your README. Can a stranger read the first line and know:

  • What it is (a CLI? a library? an app? a docs theme?)
  • Who it's for (engineers? data scientists? designers?)
  • What it does (the verb)

If the first line is "A modular framework for…" or "The next generation of…", it fails the test. The visitor doesn't know what category of thing your project is.

Compare:

  • ❌ "A modular, extensible toolkit for modern web development."
  • ✅ "A static-site generator for Markdown docs sites, written in Python."

The second one tells you: tool type (static-site generator), domain (Markdown docs), language (Python). The visitor decides in 5 seconds whether to keep reading.

The 30-second test

After the one-liner, the visitor scrolls. In the next 30 seconds, they need:

  1. An install command (or a "Try it now" link)
  2. A code example small enough to read at a glance
  3. Enough context to know "this fits my problem"

If your README requires reading three paragraphs before you see code, most visitors leave. Cut to the example fast.

Sections that win

Hero image or screenshot

If your project has a UI, screenshot it. If it's a CLI, show the output (a terminal recording withvhs orasciinema works beautifully). If it's a library, a syntax-highlighted code snippet of the API is the equivalent.

![Screenshot of the editor](docs/screenshot.png)

Visuals compress 1000 words. Use them.

Why this exists

Two-paragraph version of the elevator pitch. The first paragraph: the problem. The second: how this project solves it differently. No comparison tables (those come later). No feature lists (those come later).

Quick start

The smallest possible "do useful thing in 30 seconds" sequence:

## Install

```bash
npm install my-package
```

## Use

```js
import { thing } from 'my-package';
console.log(thing('hello'));
// → "Hello, world!"
```

If your install has 5 prerequisites, you've already lost most visitors. Find a way to ship a Docker image, a one-click install, or a hosted demo.

"How does this compare to X?"

If you're entering a crowded space (Markdown editors, static-site generators, web frameworks), a comparison table is the kindest thing you can do for visitors. Three columns: yours, the obvious incumbent, the obvious alternative. Three rows of features that actually differ.

Don't compare on dimensions where you lose — visitors notice. Compare on the dimensions where your differentiation lives.

Sections to skip (or move out)

  • Long API reference — belongs in the docs site, not the README. Link from the README.
  • Detailed changelog — belongs in CHANGELOG.md.
  • Detailed contributing guide — belongs in CONTRIBUTING.md.
  • Long history / motivation essay — belongs in a blog post you link to.
  • List of all contributors — GitHub generates this automatically. Don't curate it manually.

Badges — fewer is more

Badges (the colored shields at the top of READMEs) are useful in moderation:

  • ✅ Build status, latest version, license — these communicate trust at a glance
  • ⚠️ Code coverage, weekly downloads — only if the numbers are good
  • ❌ Twenty badges across three rows — visual noise

Shields.io is the de-facto badge service.

Image hosting in READMEs

Two patterns:

  1. In-repo images — store images indocs/images/ orassets/ inside the repo. Reference with relative paths:![](docs/images/screenshot.png). Versioned with the code. Doesn't break if you change repo names.
  2. External hosting — for files too big for the repo (videos, hi-res screenshots). GitHub Issue uploads, S3, Imgur all work.

Most modern projects use option 1 for everything. The "issue upload" trick (upload an image to a GitHub issue, copy the URL) is a graceful fallback for images you don't want to commit.

GitHub Flavored Markdown features worth using

GFM extends CommonMark with features GitHub's README renderer supports:

  • Task lists —- [x] Done /- [ ] Todo — useful for visible roadmaps
  • Tables — for compatibility matrices, feature comparisons
  • Strikethrough — for marking deprecated APIs
  • Code blocks with language hints — always specify the language for syntax highlighting
  • Autolinked URLs and issue references —#123 autolinks to the issue
  • Mermaid diagrams — fenced code blocks taggedmermaid render as diagrams on GitHub

Seethe complete Markdown syntax cheat sheet for the full surface.

Common README mistakes

  1. No install instructions. Or instructions that assume you're on the exact same OS + language version as the author. Test with a fresh checkout.
  2. No example. "Here's how to use it: see the docs." Visitors leave.
  3. Marketing speak. "Blazingly fast", "battle-tested", "production-ready" — these phrases trigger skepticism. Show, don't claim.
  4. Wall of text. No headings, no code blocks, no images. Scroll-resistant.
  5. Outdated. The README still references v0.4 syntax but v2.1 is out. Audit your README when you release.

Tools

Try Markdown Tidy free

Paste markdown, get a polished document — no signup required.

Open the editor

Related articles