Skip to content

Latest commit

 

History

History
164 lines (103 loc) · 12.8 KB

README.md

File metadata and controls

164 lines (103 loc) · 12.8 KB
Raw

Awesome Github README Awesome

A curated list of awesome READMEs

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

Contents

Examples

Project Logo

  • alichtman/stronghold - Project logo. Clear description of what the project does. GIF Demo. TOC for easy navigation. Badges. Links for further reading. Simple install instructions.

  • amitmerchant1990/electron-markdownify - Project logo. Minimalist description of what it is. GIF demo of the project. Key features. How to install guide. Credits.

  • 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.

  • nhn/tui.editor - Project logo. Clear overview of project features with a demo GIF. Badges. TOC for easy navigation. Colorful icons in front of titles.

  • React on lambda - Project logo, comics to present the main idea, badges, examples with code snippets, demo projects, api documentations, editor configurations.

  • 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.

  • sulu/sulu - Project logo, useful badges, clear instructions on where to find more information and report bugs, GIF screenshots, nice use of emoticons.

  • 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.

  • thelounge/thelounge - Project logo. Useful badges and links (website, docs, demo). Screenshot. Feature list. Step-by-step instructions for installation, development, and testing. Link to the contributing guide. Good mobile summary.

  • ryanoasis/nerd-fonts - Clean project logo. Brief description at top. Sankey diagram, quick links, badges, OS specific icons, TOC, detailed release changelog.

Clear description

  • gitpoint/git-point - Clear description. Project Logo. App Store logos. TOC. Clean screenshots. List of features. Detailed installation process. Landing Page.
  • ai/size-limit - Project logo, clear description, screenshot, step-by-step installing instructions.
  • 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.
  • 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.
  • karan/joe - Project logo. Clear description of what the project does. GIF demo. Easy install and usage sections.
  • 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.

Badges

  • 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.
  • iterative/dvc - Badges. ReStructuredText format example, PyPi compatible. Logo, custom website-like menu. Smooth how-it-works animation. Nice contribution section with the hall-of-fame.

Multiple badges

  • anfederico/Clairvoyant - Multiple badges. Clean logo. Simple install instructions. Clear overview of the project accompanied by a schematic. GIF demo. Extensive code examples.
  • athityakumar/colorls - Multiple badges. Clean screenshots. Simple install instructions. TOC for easy navigation. Good contributor guidelines.
  • dowjones/react-dropdown-tree-select - Clear readme with GIF screenshot for quick demo. Multiple badges, concise ToC, online playground, storybook, detailed description and more.
  • php-censor/php-censor - Multiple badges, project logo, screenshots, step-by-step installing and upgrading instructions, TOC for easy navigation.

Informative badges

  • 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.

Project banner

GIF Demo

  • NSRare/NSGIF - Project logo. GIF Demo. Usage artwork. Usage code samples.
  • Rebilly/redoc - Multiple badges, project logo, live demo link, GIF-animations of the key features, TL;DR usage.
  • React Parallax Tilt - GIF demo. Multiple badges. Feature list. Great live demo with code examples. Easy to follow instructions for local development set up.
  • rstacruz/hicat - GIF demo. Easy installation and setup sections with screenshots. Build badges. Great examples of use cases.

Other

  • release-it/release-it - Clear overview of project features with a demo GIF. Badges. Expandable TOC. Usage description and examples. Contribution guidelines. Detailed releases.

  • sidneycadot/oeis - Overview. List of required dependencies. Complete list of all files in the repo and what their function is. Visual graph of how it all ties together.

  • sourcerer-io/sourcerer-app - Clean animated screenshot. Customized call to action badge. Usage showcase.

  • sr6033/lterm - Clean logo using characters. Brief updates on development. Detailed contribution guidelines. Contribution suggestions.

Articles

Tools

  • Common Readme - A common readme style for Node. Includes a guide and a readme generator.
  • Feedmereadmes - README editing and project analysis/feedback.
  • Hall-of-fame - Helps show recognition to repo contributors on README. Features new/trending/top contributors. Updates every hour.
  • Make a README - A guide to writing READMEs. Includes an editable template with live Markdown rendering.
  • README best practices - A place to copy-paste your README.md from
  • readme-md-generator - A CLI that generates beautiful README.md files
  • 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.

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.99 - 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
  • Peek - FREE - Simple and easy to use for Linux users.
  • ScreenToGif - FREE - Open source, customizable UI and easily editable GIFs, easy to get started.
  • ttystudio - FREE - For commandline tools, a terminal-to-gif recorder minus the headaches.
  • Gifski - FREE - More vivid colors than the rest, but still keep size low

Get Feedback

  • feedmereadmes - Free README editing+feedback to make your open-source projects grow. See the README maturity model to help you keep going.
  • maintainer.io - Free README standardization and feedback, if you click on 'Book an audit'.
  • This repository. Submit a PR with your README!

Contribute

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

License

CC0

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