Black Friday50% OFFGet the deal
← Back to Blog

README Examples 2026: 10 READMEs Worth Copying + Template

By Morgan•Published November 12, 2026•12 min read

A good README tells a newcomer what the project does in one sentence, shows it working in a screenshot or short GIF, and gets them running in three commands. The README examples below, from bat, lazygit, FastAPI and more, add per-OS install steps, a minimal usage example, and links to contributing, license and full docs.

These ten add to the Starship teardown in these technical documentation examples. Examples 1 to 8 are live GitHub READMEs; 9 and 10 use fictional data. GitHub profile READMEs are a different job.

#ProjectTypeStandout elementCopy this
1batCLIScreenshot per featureProof for every claim
2lazygitTerminal UIClip per featureKeys beside each clip
3gumCLIScripted GIFsDemos you can re-record
4FastAPIWeb frameworkCreate, run, checkShow the output
5RuffDev toolLight and dark chartTheme-aware visuals
6PowerToysDesktop appCollapsible installsA short install section
7SupabasePlatformArchitecture diagramHow it works, drawn
8ReactUI librarySignpost READMELink the docs site
9invoice-sync (worked example)Internal serviceOwner and on-callVisible ownership
10Tree survey (worked example)DatasetVariables with unitsPlain text

What a good README file includes (section checklist)

GitHub Docs says a README should cover what the project does, why it's useful, how to start, where to get help and who maintains it.

README.md and README.rst render on GitHub and GitLab; README.txt stays plain, which suits datasets. GitHub looks in .github, the root, then docs, truncates past 500 KiB, and builds a table of contents from your headings, so a manual one is optional.

README file structure: section checklist by project type

SectionLibraryCLIAppInternal serviceDataset
Name + one-line descriptionRequiredRequiredRequiredRequiredRequired
Hero screenshot or GIFOptionalRecommendedRequiredOptionaln/a
BadgesRecommendedRecommendedOptionalOptionaln/a
FeaturesRecommendedRecommendedRequiredOptionaln/a
RequirementsRequiredRecommendedRequiredRequiredOptional
Install or quick startRequiredRequiredRequiredRequiredn/a
Usage example + outputRequiredRequiredRecommendedRecommendedn/a
ConfigurationRecommendedRecommendedOptionalRequiredn/a
Project structureOptionalOptionalOptionalRecommendedRequired
How it works or methodsOptionalOptionalOptionalRequiredRequired
TestsRecommendedRecommendedOptionalRequiredn/a
Files, variables and unitsn/an/an/an/aRequired
ContributingRecommendedRecommendedRecommendedOptionaln/a
Maintainers or owner teamOptionalOptionalOptionalRequiredRequired
LicenseRequiredRequiredRequiredOptionalRequired
SupportRecommendedRecommendedRequiredRequiredRecommended
Status or roadmapOptionalOptionalOptionalOptionalOptional

Other docs get their own files: CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, ARCHITECTURE.md, LICENSE, and the .github issue templates and pull request template.

10 README examples worth copying

1. bat: a screenshot for every feature

bat, a cat clone with syntax highlighting, proves every claim with a picture.

README example: bat with logo, badges, menu and a feature screenshot
README example: bat with logo, badges, menu and a feature screenshot
  1. A committed logo with alt text.
  2. Three badges.
  3. One line, then a menu.
  4. A screenshot per feature.

Skip this: the screenshots are hotlinked from Imgur. GitHub's image proxy still shows them on github.com, but Imgur has blocked UK access since 30 September 2025, so local previews and docs mirrors show UK readers a broken image. Commit images to the repo.

2. lazygit: one short clip per feature

lazygit, a terminal UI for git, pitches itself with a funny rant about git pain, then shows each feature in motion.

lazygit README: contents, feature heading, key hints and video
lazygit README: contents, feature heading, key hints and video
  1. A table of contents.
  2. A heading per feature.
  3. The keys to press, in words.
  4. A short video, uploaded to GitHub.

Copy this: a short clip per feature beats one long GIF.

3. gum: GIFs recorded from scripts

gum adds prompts and spinners to shell scripts. Its 12 VHS GIFs mostly come from .tape scripts in the repo.

gum README: demo GIF, script link and per-command GIF
gum README: demo GIF, script link and per-command GIF
  1. A demo GIF under the tagline.
  2. A link to its script.
  3. A section per command.
  4. A GIF per command, with alt text like "Shell running gum input typing Not much, you?"

Copy this: scripted demos. Without a host like Charm's, commit the GIF.

4. FastAPI: show the output, not only the code

FastAPI, a Python web framework, goes from code to result in three headings.

FastAPI README: Create it, Run it, Check it and API docs
FastAPI README: Create it, Run it, Check it and API docs
  1. Create it: a complete main.py.
  2. Run it: one command and its output.
  3. Check it: the JSON you'll see.
  4. The API docs it generates, as a screenshot.

Skip this on small projects: the long sponsor block above the example.

5. Ruff: a chart that follows the theme

Ruff, a Python linter, leads with speed.

Ruff README: badges, links and a light and dark chart
Ruff README: badges, links and a light and dark chart
  1. Badges for version, license and CI.
  2. Docs and Playground links.
  3. A benchmark chart with alt text: "Shows a bar chart with benchmark results."
  4. A dark variant via a picture element, on GitHub's upload domain.

Copy this: theme-aware charts and diagrams.

6. PowerToys: a big app, kept scannable

PowerToys fits over 30 Windows utilities into one scannable README.

PowerToys README: hero, links, utilities table and install blocks
PowerToys README: hero, links, utilities table and install blocks
  1. Light and dark hero images by relative path.
  2. Docs, blog and release notes up top.
  3. A utilities table with alt-texted icons.
  4. Four collapsible install blocks.

Copy this: collapse long install paths. Skip this: the hero image has no alt attribute.

7. Supabase: how it works, in one diagram

The Supabase monorepo README adds a dashboard screenshot plus docs and support links.

Supabase README: logo, checklist, How it works and diagram
Supabase README: logo, checklist, How it works and diagram
  1. A logo per theme.
  2. A feature checklist with docs links.
  3. "How it works" in plain words.
  4. An architecture diagram by relative path.

Note: the logo uses older #gh-light-mode-only and #gh-dark-mode-only fragments; GitHub Docs only list picture.

8. React: the README as a signpost

React keeps its README short and lets a docs-as-code site carry the detail.

React README: description, principles, install links and example
React README: description, principles, install links and example
  1. One sentence on what React is.
  2. Three principles.
  3. Install and docs links.
  4. A tiny example and its output.

9. Internal service README (worked example)

This README lives in private repos, so you rarely see one. Here it is with fake data.

README file example: a fictional internal service with owner, diagram and runbooks
README file example: a fictional internal service with owner, diagram and runbooks
  1. Owner team, chat and on-call up top.
  2. One-line purpose and a diagram.
  3. Run locally with env var names only; secrets come from the vault.
  4. Deploy, dashboards and a Runbooks line pointing to the runbook.

Copy this: keep it a signpost; alert steps belong in the runbook.

10. Dataset README.txt example (worked example)

For research data, the Cornell guide lists these sections, and Harvard Medical School's guide asks for one plain-text README per dataset, not a Word file.

TITLE    Urban Tree Canopy Survey
CONTACT  A. Rivera, data-team@example.org
DATES    Collected 2026-04-02 to 2026-06-30 (ISO 8601)
LICENSE  CC BY 4.0
FILES    trees_2026.csv (one row per tree), photos/PLOTID_YYYY-MM-DD.jpg
CODES    NA = not measured; SPP = species code
VARIABLES
  dbh_cm     trunk diameter at 1.3 m, centimeters
  height_m   tree height, meters
METHODS  Heights measured with a laser rangefinder.
CITE AS  Rivera A. (2026). Urban Tree Canopy Survey [Data set].

How to add screenshots and GIFs to a README

What to show

Put one hero visual under the description. Crop tight, use fake data, show one idea per visual and add padding for both themes. Number GUI setup steps with matching callouts.

Before and after: a text-only README and one with a demo GIF and quick start
Before and after: a text-only README and one with a demo GIF and quick start

GIF or video demo

Keep a demo to one task in 5 to 10 seconds, about 800 px wide at 10 to 15 fps, recorded on a Mac or Windows. GitHub allows 10 MB per image or GIF, and 10 MB of video (100 MB on paid plans).

An MP4 plays inline only if you upload it in GitHub's editor (a github.com/user-attachments URL); a video tag pointing at a committed .mp4 gets stripped. Check the result logged out.

Terminal tools: asciinema plus agg (how to record a terminal session) or VHS. Built-ins: macOS saves screen recordings as .mov files you can turn into a GIF, and Snipping Tool saves MP4 and can export up to 30 seconds as a GIF.

Scripted demo GIF of a fictional driftcheck CLI flagging drifted config files in 7.5 seconds
Scripted demo GIF of a fictional driftcheck CLI flagging drifted config files in 7.5 seconds

Store images in the repo with relative paths

Commit images to docs/images/ or .github/assets/ and link them by relative path: they resolve on the current branch and survive forks, and a leading slash starts at the repo root. Paths are case-sensitive on GitHub, even when your Mac or PC is not. To set a size, use an img tag:

![driftcheck flagging two drifted config files](docs/images/demo.gif)
<img src="docs/images/hero.png" alt="driftcheck scan results in a terminal" width="800">

Dragging a file into GitHub's web editor also works; private repo images show only to people with access.

Light and dark images with the picture element

Logos, diagrams and charts on transparent backgrounds need a dark-mode version. GitHub supports the picture element (changelog):

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.svg">
  <img src="docs/images/logo-light.svg" alt="driftcheck logo" width="320">
</picture>
A plain img logo vanishes in dark mode; a picture element swaps in a light logo
A plain img logo vanishes in dark mode; a picture element swaps in a light logo

Screenshots on solid backgrounds rarely need one. Test both themes in a public demo repo.

Alt text and file size

Say what the visual shows in under about 125 characters, like "lazygit staging one line from a diff" (image alt text). Use empty alt only for decorative images (W3C decision tree). Keep screenshots under about 1 MB and shrink heavy GIFs.

Redact before you commit

Git history keeps every version, and public repo uploads open without signing in. Cover tokens, emails and customer data with a solid box; blur and pixelate can be reversed (how to redact text). Rotate any committed secret.

To record the demo yourself, ScreenSnap Pro (Mac and Windows) records straight to GIF, or to MP4 you can trim, speed up and auto-zoom in its built-in editor before exporting MP4 or GIF. For screenshots, its image editor adds padding with 500+ backgrounds, numbers steps with the counter tool and covers secrets with a filled rectangle.

Those tools work on screenshots, not recordings, so record demos against fake data. Its cloud share links suit a quick Slack ping, not README images.

ScreenSnap Pro
From the makers of this site

Tired of plain screenshots? Try ScreenSnap Pro.

Beautiful backgrounds, pro annotations, GIF recording, and instant cloud sharing, all in one app. Pay $39 once, own it forever.

See pricing and features

README template you can copy

Copy this sample README file for a fictional CLI, driftcheck. HTML comments explain each part.

<!-- Optional: one logo per GitHub theme -->
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.svg">
  <img src="docs/images/logo-light.svg" alt="driftcheck logo" width="320">
</picture>

# driftcheck

Flags config files that drifted from the version in Git.

<!-- Up to 3 badges -->
[![CI build status](https://img.shields.io/github/actions/workflow/status/your-org/driftcheck/ci.yml?label=CI)](../../actions)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

![driftcheck flagging two drifted config files](docs/images/demo.gif)

## Features

- Checks YAML, JSON and TOML files
- Fails CI on drift (exit code 1)

## Quick start

Requires Git 2.30 or later.

    brew install your-org/tap/driftcheck   # macOS
    winget install YourOrg.Driftcheck      # Windows

Other platforms: see Releases.

## Usage

<!-- The smallest command and its real output -->

    $ driftcheck scan ./config
    ✗ 2 files drifted: app.yaml, db.yaml

## Configuration

|Option| Default| What it does|
|---|---|---|
|--base| origin/main| Branch to compare against|

## How it works

Design notes: [docs/design.md](docs/design.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Support

Open an issue with your OS and version.

## License

MIT. See [LICENSE](LICENSE).
  • Delete sections that don't apply. For a GUI app, swap Usage for 3 to 5 numbered screenshots.
  • Fit the name, description, visual and quick start on the first screen; export a PDF for clients.
  • Link your design doc from How it works; this software design document template covers it.

GitHub's syntax guide lists what else a README can use: fenced code with a language, tables, collapsed sections, Mermaid diagrams, badges and alerts such as > [!NOTE].

Common README mistakes and fixes

MistakeFix
Images don't showMatch path case, avoid raw links to renamed branches, stop hotlinking, and check private repo access
A committed MP4 shows nothingUpload it through GitHub's editor
GIF too heavyRe-record smaller, compress the GIF, or upload an MP4
README cut offMove long sections to docs; GitHub truncates past 500 KiB
Terminal output as a screenshotUse a code block; extract the text from old screenshots
Code as a styled imageUse a code block; code images suit slides and social posts
Stale screenshotsName files by feature and re-capture each release
Secrets in screenshots or .env examplesUse solid boxes and placeholder values; rotate leaked keys

Frequently Asked Questions

How to write a README that gets read

Start from the template, add one hero visual and check it logged out. ScreenSnap Pro is a one-time $39 purchase for Mac and Windows: 1 license, 2 seats (2 computers, Mac or Windows). See pricing.

Author
Morgan

Morgan

Indie Developer

Indie developer, founder of ScreenSnap Pro. A decade of shipping consumer Mac apps and developer tools. Read full bio

@m_0_r_g_a_n_