Awesome README

A curated list of awesome READMEs

Elements in beautiful READMEs include, but are not limited to: images, screenshots, GIFs, text formatting, etc.

Examples

sebyddd/SDVersion - Project logo. Build badges. Documentation structuring for multiple programming languages. Usage examples.
NSRare/NSGIF - Project logo. GIF Demo. Usage artwork. Usage code samples.
sindresorhus/pageres - Project logo. Clear description of what the project does. Build badges. Demo screenshot. Simple install and usage sections. Includes an examples section with common uses.
petkaantonov/bluebird - Build badges. Clear description of what the project does. TOC for easy navigation. Project logo. Extensive explanations and examples.
jakubroztocil/httpie - Description of what the project does. Demo screenshots. Project logo. TOC for easy navigation. Build badges. Quick and simple installation and usage sections. Includes an examples section.
karan/joe - Project logo. Clear description of what the project does. GIF demo. Easy install and usage sections.
aimeos/aimeos-typo3 - Project logo. Clear description of what the project does. Demo screenshot. TOC for easy navigation. Easy installation and setup sections with screenshots. Links for further reading.
rstacruz/hicat - GIF demo. Easy installation and setup sections with screenshots. Build badges. Great examples of use cases.
skywinder/github-changelog-generator - TOC for easy navigation. Concise project description. Installation and usage sections. Output example. Great feature overview. List of alternatives. FAQ.
shama/gaze - Project logo. Concise description. Feature list. Usage section. FAQ. Great API documentation. Release history.
node-chat - Project screenshot. Informative badges. Clear description. Easy installation/use instructions. Live demo.
anfederico/Clairvoyant - Multiple badges. Clean logo. Simple install instructions. Clear overview of the project accompanied by a schematic. GIF demo. Extensive code examples.
Day8/re-frame - Badges, logo, TOC, etc. Stands out by being a giant, well-written essay about the tech, how to use it, the philosophy behind it, and how it fits into the greater ecosystem.
iharsh234/WebApp - Project landing page. Clear description of what the project does. Demo screenshot. Simple install and usage sections. Includes an examples section with common uses and a mobile demo section.
amitmerchant1990/electron-markdownify - Project logo. Minimalist description of what it is. GIF demo of the project. Key features. How to install guide. Credits.
ryanoasis/nerd-fonts - Clean project logo. Brief description at top. Sankey diagram, quick links, badges, OS specific icons, TOC, detailed release changelog.
yoshuawuyts/choo - Badges, clean, clear. Beautiful little menu above the fold with useful links. An FAQ inside of it for the main questions. Backers. Good language.
Martinsos/edlib - Informative badges (build, version, publication). Concise description. Feature list. TOC. Screenshots. Concise instructions with examples for building and including in your project. Common code examples to get you started quickly.
angular-medellin/meetup - Project banner. Badges for stats. Well placed emoticons. Contributor's photos.

Articles

"How To Write A Readme" - Joshua Holbrook
"How To Write A Great README" - Caleb Thompson (thoughtbot)
"Readme Driven Development" - Tom Preston-Werner
"Top ten reasons why I won’t use your open source project" - Adam Stacoviak
"Art of Readme - Learn the art of writing quality READMEs." - Stephen Whitmore

Tools

Common Readme - A common readme style for Node. Includes a guide and a readme generator.
Feedmereadmes - README editing and project analysis/feedback.
Standard Readme - A standard README style specification. Has a generator to help creat spec-compliant READMEs, too.
Zalando's README Template - Simple template to help you cover all the basics.

Creating GIFs

Embedding an animated gif in your README quickly demonstrates what your project does and catches the reader's eye. Here are a few programs that can help you quickly create gifs for your project:

Gifox - $4 - Cleanest UI, hotkeys, lots of advanced features
LICEcap - FREE - Less intuitive, more features
Recordit - FREE - Simple, clean UI, but auto-uploads to recordit.co

Contribute

Contributions are always welcome! Please read the contribution guidelines first.

License

To the extent possible under law, Matias Singers has waived all copyright and related or neighboring rights to this work.

6.3 KiB Raw Blame History Unescape Escape