How to create a good GitHub Readme

Recently a few clients asked me to tear down their GitHub Readme's which was the final straw to prepare a doc I could share with good examples and principles. As always this is a work in progress but should already be helpful. Any feedback, suggestions, insights, examples are very much welcome.

TLDR my default structure suggestion is:

Banner (Logo + Tagline + Visual)
Badges
Links (Website, Docs, Examples, Blog, Discord)
About (What it is)
Visual Demo (GIF, Video, Screenshot, Code Snippet etc)
Installation
Getting Started / Quickstart / Basic usage examples
Features list
How to Contribute
License

You can optionally add, Features, Architecture, Links & Resources, Limitations and FAQ. If it gets very long add a Table of Contents. But Readme is a single doc, navigating through it will never be fun when it is very long so keep it short and send to docs or examples where it makes sense.

Make it visual with GIF, tables, code snippets, bullets. Keep it as short as possible but NOT shorter. It has to be clear and guide people to a first accomplishment. For everything else, send people to the docs.

More context, examples, and resources below.

Every example is a screenshot with a link to repo before it so do go and check it out for yourself as some of those are gifs and stuff.

Header: Banner + Badges + Links

Logo
Tagline
(optional) Visual
(optional) companies using it

https://github.com/prisma/prisma/#readme

https://github.com/algolia/algoliasearch-client-javascript#readme

https://github.com/amitmerchant1990/electron-markdownify#readme

https://github.com/brenocq/implot3d#readme

https://github.com/gowebly/gowebly#readme

https://github.com/refinedev/refine#readme

About

Could be a “ {Project} - tagline” or just “About {project}” depending on the visual
Short description - explain what you do in plain language stay on the side of clear vs overly jargony
- Bad: “XYZ is a flexible polyglot widget orchestration framework”
- Good: “XYZ is a tool to easily integrate and manage widgets in multiple programming languages, allowing you to orchestrate complex workflows.”
Possible with links to docs if bigger project

https://github.com/prisma/prisma/#readme

https://github.com/laravel/laravel#readme

https://github.com/PostHog/posthog#readme

https://github.com/ArmynC/ArminC-AutoExec/#readme

Visual demo

Screenshot / gif
UI / app in action
Code snippet
Terminal recording
Examples:

‍https://github.com/alichtman/shallow-backup#readme

https://github.com/algolia/docsearch#readme

https://github.com/httpie/cli?tab=readme-ov-file#readme

https://github.com/PostHog/posthog#readme

https://github.com/meilisearch/meilisearch#readme

https://github.com/athityakumar/colorls#readme

Installation

Can use tables

https://github.com/sindresorhus/pageres#readme

https://github.com/eylon-44/Buzz-OS#readme

https://github.com/iterative/dvc#readme

https://github.com/owloops/updo#readme

https://github.com/owloops/updo#readme

https://github.com/stevenfoncken/multitool-for-spotify-php#readme

Getting started / Quickstart / Usage examples

Shows code
Shows simple 1-2-3 steps

https://github.com/create-go-app/cli#readme

https://github.com/eylon-44/Buzz-OS#readme

https://github.com/sr6033/lterm#readme

https://github.com/iterative/dvc#readme

https://github.com/L0garithmic/FastColabCopy#readme

https://github.com/refinedev/refine#readme

Features

Short explanations, overview of capabilities
Links to docs, examples, tutorials
Can be a table
Can also be used to compare vs alternatives

https://github.com/httpie/cli#readme

https://github.com/meilisearch/meilisearch#readme

https://github.com/ArmynC/ArminC-AutoExec/#readme

(Optional) Architecture or How it works

Diagrams
Explaining internals (framework, server etc)
Examples:

https://github.com/dbt-labs/dbt-core#readme

https://github.com/AntonioFalcaoJr/EventualShop#readme

https://github.com/iterative/dvc#readme

(Optional) Links & resources

You can add learning materials/resources, links to docs, examples, etc grouped by themes

(Optional) FAQ

Some companies explain limitations, common problems, alternative options

Contributing

Info on how to contribute
Top Contributors embed
Link to discord

https://github.com/amplication/amplication#readme

https://github.com/iterative/dvc#readme

Notes on Formatting

Make sure it renders on the package manager site (PyPI for python, crates for Rust, npm for Javascript)
Use bold, backtics (grey text), italic to highlight points, filenames and concepts.
Markdown
HTML
GIFs
Banner

Tables

https://github.com/algolia/instantsearch#readme

https://github.com/dracula/dracula-theme#readme

Grey boxes

https://github.com/alichtman/shallow-backup#readme

https://github.com/alichtman/shallow-backup#readme