A curated list of awesome READMEs
Elements in beautiful READMEs include, but are not limited to: images, screenshots, GIFs, text formatting, etc.
- 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.
- amitmerchant1990/electron-markdownify - Project logo. Minimalist description of what it is. GIF demo of the project. Key features. How to install guide. Credits.
- anfederico/Clairvoyant - Multiple badges. Clean logo. Simple install instructions. Clear overview of the project accompanied by a schematic. GIF demo. Extensive code examples.
- angular-medellin/meetup - Project banner. Badges for stats. Well placed emoticons. Contributor's photos.
- athityakumar/colorls - Multiple badges. Clean screenshots. Simple install instructions. TOC for easy navigation. Good contributor guidelines.
- choojs/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.
- 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.
- gitpoint/git-point - Clear description. Project Logo. App Store logos. TOC. Clean screenshots. List of features. Detailed installation process. Landing Page.
- Hexworks/Zircon - Dogfood in readme. Clear description of what the project does. Demo screenshot. TOC for easy navigation. Easy installation and setup sections with screenshots. Links for further reading.
- 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.
- 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.
- 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.
- node-chat - Project screenshot. Informative badges. Clear description. Easy installation/use instructions. Live demo.
- NSRare/NSGIF - Project logo. GIF Demo. Usage artwork. Usage code samples.
- petkaantonov/bluebird - Build badges. Clear description of what the project does. TOC for easy navigation. Project logo. Extensive explanations and examples.
- rstacruz/hicat - GIF demo. Easy installation and setup sections with screenshots. Build badges. Great examples of use cases.
- ryanoasis/nerd-fonts - Clean project logo. Brief description at top. Sankey diagram, quick links, badges, OS specific icons, TOC, detailed release changelog.
- sebyddd/SDVersion - Project logo. Build badges. Documentation structuring for multiple programming languages. Usage examples.
- shama/gaze - Project logo. Concise description. Feature list. Usage section. FAQ. Great API documentation. Release history.
- 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.
- skywinder/github-changelog-generator - TOC for easy navigation. Concise project description. Installation and usage sections. Output example. Great feature overview. List of alternatives. FAQ.
- teles/array-mixer - Clean project logo, badges. Table of contents. Contributing section. Many illustrated examples.
- vhesener/Closures - Project logo, cognitive funnel, animated examples. Color coordinated. Clean documentation.
- webpro/release-it - Clear overview of project features with a demo GIF. Badges. Expandable TOC. Usage description and examples. Contribution guidelines. Detailed releases.
- "Art of Readme - Learn the art of writing quality READMEs." - Stephen Whitmore
- "How To Write A Great README" - Caleb Thompson (thoughtbot)
- "How To Write A Readme" - Joshua Holbrook
- "Readme Driven Development" - Tom Preston-Werner
- "Top ten reasons why I won’t use your open source project" - Adam Stacoviak
- 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 create spec-compliant READMEs, too.
- Zalando's README Template - Simple template to help you cover all the basics.
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
- Giphy Capture - FREE - Easy to upload to giphy.com, slightly annoying UX.
- LICEcap - FREE - Less intuitive, more features
- Recordit - FREE - Simple, clean UI, but auto-uploads to recordit.co
- ttystudio - FREE - For commandline tools, a terminal-to-gif recorder minus the headaches.
To the extent possible under law, Matias Singers has waived all copyright and related or neighboring rights to this work.