Elements in beautiful READMEs include, but are not limited to:
images, screenshots, GIFs, text formatting, etc.
6471β
1818π΄
ai/size-limit) - Project logo, clear description, screenshot, step-by-step installing instructions.228β
742π΄
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.20267β
518π΄
ajeetdsouza/zoxide) - Badges, project GIF, concise description, quick links, stepwise installation instructions.1206β
247π΄
alichtman/shallow-backup) - Clear description of what the project does. GIF Demo. TOC for easy navigation. Badges. Links for further reading. Simple install instructions.1079β
260π΄
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.957β
933π΄
amitmerchant1990/electron-markdownify) - Project logo. Minimalist description of what it is. GIF demo of the project. Key features. How to install guide. Credits.14670β
1442π΄
amplication/amplication) - Clear project logo. Brief explanation. All features explained. Clean documentation. Useful links (website, docs, discord). List of contributors with their pictures and usernames.2401β
770π΄
anfederico/Clairvoyant) - Multiple badges. Clean logo. Simple install instructions. Clear overview of the project accompanied by a schematic. GIF demo. Extensive code examples.43β
35π΄
ankitwasankar/mftool-java) - Project logo with a short display of what can be achieved with it, TOC for easy navigation, important badges, clean installation guide, and multiple code snippets showing how to use the functionality.28β
8π΄
antoinezanardi/werewolves-assistant-api-next) - Project logo. Badges. Concise description. TOC for easy navigation. Simple install instructions and various sections. Clean project with code coverage, CI, and many other features.343β
56π΄
AntonioFalcaoJr/EventualShop) - The project has a logo and well-defined sections such as: information about the project, the architectural solution, along with reference links such as articles, videos, and documentation. It explains how to run the project in different environments (development and production). It has documented load tests, it also describes which technologies are used, and it has diagrams for the archetype.253β
112π΄
aregtech/areg-sdk) - Logo. Multiple info and statistics badges. List of contributors and stargazers with pictures. TOC and "Back to top" links for easy navigation. Headlines with graphics. Topic hide/show menu. Project description and philosophy. Clone and integration instructions. Quick build with multiple tools. Tools configuration instructions. Reference to examples and Demo projects. Reference to use cases. References to guidance and Wiki pages. Links with badges to contact. Links with badges to share project in social network.?β
?π΄
Armync/Arminc-AutoExec) - Rich Markdown functions, modern layout, clear description and compliant with the recommended community standards.4833β
378π΄
athityakumar/colorls) - Multiple badges. Clean screenshots. Simple install instructions. TOC for easy navigation. Good contributor guidelines.4719β
507π΄
ccostan/Home-AssistantConfig) - Project Banner. Badges. Easy navigation.6772β
601π΄
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.70β
108π΄
chroline/well_app) - Features attention-grabbing project thumbnail with clean badges, as well as download information and quick navigation links. Organized into multiple descriptive sections, each of which have a title with a yellow emoji. Includes details about the project itself, as well as the technologies used and how to contribute.2376β
245π΄
create-go-app/cli) - Clean project logo. Useful badges (version, code style, test cover, docs). Clear readme with quickstart, understandable installation and usage manual, video screencast, ToC with well-documented project features (with a demo recording of the work in the terminal), project philosophy notes ("the why another"), most frequently asked questions, and more.5401β
715π΄
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.9269β
1537π΄
dbt-labs/dbt-core) - Project banner, super clear description (friendly to people brand new to the product), screenshot of the docs the tool generates, and concise links to other comprehensive pages explaining Getting Started, Joining the dbt Community, Bug Reports, Code Contribution, and Code of Conduct460β
266π΄
dowjones/react-dropdown-tree-select) - Clear readme with GIF screenshot for quick demo. Multiple badges, concise ToC, online playground, storybook, detailed description and more.74β
42π΄
easybase/easybase-react) - Project banner and logo. Badges. Expandable walkthrough sections. Concise description and purpose. TOC for easy navigation. GIFs for installation demo. Multiple informative visuals.1078β
171π΄
emalderson/thephish) - Project logo, informative badges, useful TOC, clear description, screenshots, step-by-step installation and configuration guide, contributor guidelines, code of conduct, UML diagrams, coherent tags, issue and pull request templates, well-documented and well-commented code, examples.4β
2π΄
eylon-44/Buzz-OS) - Project logo. Colorful emojis. GIFs for project demo, examples, and instructions. Fast and simple copy-paste instructions for installation and usage. Pretty table of contents. A quick overview of project's main features.7340β
845π΄
github-changelog-generator/github-changelog-generator) - TOC for easy navigation. Concise project description. Installation and usage sections. Output example. Great feature overview. List of alternatives. FAQ.4719β
790π΄
gitpoint/git-point) - Clear description. Project Logo. App Store logos. TOC. Clean screenshots. List of features. Detailed installation process. Landing Page.32084β
1593π΄
gofiber/fiber) - Clean project logo. Useful badges and links (languages switcher, code style, test cover, docs, Discord channel). Clear description of what the project does with quickstart, benchmark charts, well-documented code examples (with the ability to hide long content), project philosophy notes ("the why of project"), tables with project addons, list of contributors, star growth statistics, and more.776β
30π΄
gowebly/gowebly) - Clean project banner with logo. Useful badges and links (languages switcher, test cover, docs). Clear description of what the project does with quickstart, understandable feature list, links to the introduction video and article, well-documented CLI command examples, project philosophy notes ("motivation to create"), tables with project components, links to addons and helpers, list of stargazers, and more.745β
136π΄
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.32698β
3674π΄
httpie/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.244β
12π΄
hywax/mafl) - Project logo. Clear description of what the project does. TOC for easy navigation. Usage code samples.755β
742π΄
IgorAntun/node-chat) - Project screenshot. Informative badges. Clear description. Easy installation/use instructions. Live demo.92β
325π΄
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.13377β
1158π΄
iterative/dvc) - ReStructuredText format example, PyPi compatible. Logo, custom website-like menu. Smooth how-it-works animation. Badges. Nice contribution section with the hall-of-fame.428β
50π΄
ivanperez-keera/Yampa) - Clear description. Feature list. TOC for easy navigation. Simple install instructions. Usage code samples. Project samples with GIFs and links to app stores. Documentation and publications. Clear development / contribution rules.2874β
207π΄
karan/joe) - Project logo. Clear description of what the project does. GIF demo. Easy install and usage sections.51β
10π΄
kopach/karma-sabarivka-reporter) - Project logo. Useful badges, clear readme with screenshots for quick demo. Concise ToC.26β
36π΄
L0garithmic/FastColabCopy) - Project logo. Minimalist description. Badges. GIF demo. About The Project. How To Use. Examples. Credits. Additional Examples.34643β
8131π΄
lobehub/lobe-chat) - Modern badge design. Clear feature introductions accompanied by visual design graphics. Ecosystem introduction. Descriptions of project characteristics and development methods. Contributors section.2305β
217π΄
lobehub/sd-webui-lobe-theme) - Feature list and demo. I18n support. Navigation with Header and TOC. Clear instructions.89β
94π΄
ma-shamshiri/Human-Activity-Recognition) - Beautiful table of contents. Project logo. Animated project banner. Complete project folder structure. Clear description of what the project does. Nice contributorsβ section. Easy navigation.73β
99π΄
ma-shamshiri/Pacman-Game) - Beautiful table of contents. Project logo. Animated project banner. Suitable GIFs to display each part of the project. Complete list of project files in the repo along with their function. Complete execution instruction.26β
99π΄
ma-shamshiri/Spam-Detector) - Complete project file description. Project logo. Animated project banner. Concise project description. Clear execution instruction.312β
50π΄
MananTank/radioactive-state) - Badges (version, downloads, coverage, size), Twitter Intent, Project Logo, Feature list, Motivation, Installation, Example with GIFs, Emojis, Collapsible Sections, Live Demos, API detailed usage, FAQs, Chat link.493β
162π΄
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.323β
23π΄
NASA/ogma) - Clear description. Feature list. Demo GIFs. Simple install instructions. Usage code samples. TOC for easy navigation.16904β
1712π΄
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.922β
190π΄
NSRare/NSGIF) - Project logo. GIF Demo. Usage artwork. Usage code samples.177β
3π΄
Owloops/updo) - Well-structured, visually appealing, and provides comprehensive information about the tool, from its purpose and features to installation and usage, in a clear and user-friendly manner.672β
144π΄
php-censor/php-censor) - Multiple badges, project logo, screenshots, step-by-step installing and upgrading instructions, TOC for easy navigation.19368β
1131π΄
PostHog/posthog) - Custom-made section icons, demo GIF, deploy button, profile images for contributors, concise, clear structure, project logo.49β
18π΄
priyavrat-misra/xrays-and-gradcam) - TOC for easy navigation. Clear introduction of what the project does. Complete list of all files in the repo and what their function is. Usage section. Clean and concise tables.263β
58π΄
React on lambda) - Project logo, comics to present the main idea, badges, examples with code snippets, demo projects, api documentations, editor configurations.943β
113π΄
React Parallax Tilt) - GIF demo. Multiple badges. Feature list. Great live demo with code examples. Easy to follow instructions for local development set up.22896β
2266π΄
Rebilly/redoc) - Multiple badges, project logo, live demo link, GIF-animations of the key features, TL;DR usage.25966β
1964π΄
refinedev/refine) - Clean project logo. Brief description at top. Multiple badges. Usage description and examples. Use cases and demo links. Screenshots. Key Features. Contributors. Stargazers. Contribution guidelines.7721β
521π΄
release-it/release-it) - Clear overview of project features with a demo GIF. Badges. Expandable TOC. Usage description and examples. Contribution guidelines. Detailed releases.407β
53π΄
rstacruz/hicat) - GIF demo. Easy installation and setup sections with screenshots. Build badges. Great examples of use cases.52618β
3592π΄
ryanoasis/nerd-fonts) - Clean project logo. Brief description at top. Sankey diagram, quick links, badges, OS specific icons, TOC, detailed release changelog.1313β
214π΄
sebyddd/SDVersion) - Project logo. Build badges. Documentation structuring for multiple programming languages. Usage examples.454β
42π΄
serpro69/kotlin-faker) - Project logo. Badges. Concise description and clear getting-started instructions with a link to the full documentation website. Test, build and contributing guidelines. Licence info.1157β
167π΄
shama/gaze) - Project logo. Concise description. Feature list. Usage section. FAQ. Great API documentation. Release history.46β
35π΄
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.9648β
745π΄
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.298β
58π΄
skydio/revup) - Project logo. Animated GIF demo + GIFs for major stages of the step-by-step tutorial. Concise explanation, installation instructions, and contribution section.4479β
130π΄
Slackadays/Clipboard) - Project logo. Build and test/coverage badges. Transition from plain description to people-oriented description. Animated GIF showing usage. Custom banners for clearly laid out sections. Custom text assets for headers. Immediate call to action with Quick Start section. Consistent and easy to read command names and signatures. Three immediate options for getting help provided. Easter eggs provided for the detail-oriented.6729β
281π΄
sourcerer-io/sourcerer-app) - Clean animated screenshot. Customized call to action badge. Usage showcase.56β
66π΄
sr6033/lterm) - Clean logo using characters. Brief updates on development. Detailed contribution guidelines. Contribution suggestions.6β
9π΄
Stack-in-a-box/triumphmayflowerclub.com) - Stands-out because, while only a simple website, it is presented as a very open project for lesser-experienced developers to cut their teeth on, with a friendly, inclusive tone and accessible set-up instructions. Includes many common elements found in other beautiful READMEs.1β
0π΄
stevenfoncken/multitool-for-spotify-php) - Concise introduction description. Clear overview of features. Why-section with easter egg (heading). Informative badges. Clear disclaimer. Step-by-step setup instructions. Expandable TOC. Headlines with emojis. Detailed usage section. Shortlinks at top. Back-to-top link in footer. Credits to third-party code/libraries.1129β
330π΄
sulu/sulu) - Project logo, useful badges, clear instructions on where to find more information and report bugs, GIF screenshots, nice use of emoticons.172β
94π΄
supunlakmal/thismypc) - Project logo. Useful badges. Web site URL. Screenshot. GIF step-by-step instructions for installation. Project folder structure.38β
81π΄
teles/array-mixer) - Clean project logo, badges. Table of contents. Contributing section. Many illustrated examples.5471β
669π΄
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.5430β
113π΄
themerdev/themer) - Project logo. Visual description (flowchart) of what the project does. Build badges. TOC. Demo screenshot. Concise install and usage sections, including common workflows. Colorful previews.1742β
147π΄
vhesener/Closures) - Project logo, cognitive funnel, animated examples. Color coordinated. Clean documentation.504β
48π΄
xnbox/DeepfakeHTTP) - Original hero section. Clear navigation. Minimalist design. Appendices.3788β
413π΄
zenml-io/zenml) - Clean project logo. Useful TOC. Clear code examples amongst feature list. Quickstart example.
A good ARCHITECTURE.md file helps developers understand how and where to make changes, whether they are new to a project or not.
Diagrams, source code maps, and discussing invariants and design decisions is essential.
This can also be a dedicated section of your README.md files.
37610β
1107π΄
esbuild) - Great use of graphics for visualisations and project structure. Includes a list of important principles for the project.163102β
26834π΄
Flutter Engine) - Good use of high level diagrams to show the stack and its parts. Describes the main processes. Describes platform invariants.- π GitLab - Calls out design decisions.
174089β
52477π΄
Linux cryptography) - Calls out different types of components, provides searchable areas, calls out invariants of different components, and describes structure with diagrams.79806β
5494π΄
Neovim) - Describes the main processes/lifecycle.?β
?π΄
Oh My Zsh) - Describes the initialization process, calls out environment requirements.65549β
23575π΄
Redis) - Good source code map. Overviews of key files. Good use of documentation comments in-code rather than inline comments.94756β
12210π΄
rust-analyser) - Good diagrams, describes entry points and source organisation, discusses architecture considerations.79529β
2357π΄
Tauri) - Well made source code map, discusses architecture considerations, calls out important dependencies.?β
?π΄
VS Code) - Good use of high-level diagrams. Describes source organisation.
7019β
417π΄
"Art of Readme - Learn the art of writing quality READMEs.") - Stephen Whitmore- π "Elegant READMEs" - Yegor Bugayenko
- π "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
- π "What I learned from an old GitHub project that won 3,000 Stars in a Week" - KyuWoo Choi
- Architecture
- π "ARCHITECTURE.md" - Alex Kladov
- π "Two open source projects with great documentation" - John Jago
490β
239π΄
Amazing GitHub Template) - Useful README.md, LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, GitHub Issues, Pull Requests and Actions templates to jumpstart your projects.387β
251π΄
Common Readme) - A common readme style for Node. Includes a guide and a readme generator.1126β
56π΄
Feedmereadmes) - README editing and project analysis/feedback.66442β
21535π΄
GitHub Readme Stats) - Dynamically generated customizable GitHub cards for README. Stats, extra pins, top languages and WakaTime.945β
89π΄
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.
863β
842π΄
README best practices) - A place to copy-paste your README.md from10817β
1365π΄
readme-md-generator) - A CLI that generates beautiful README.md files- π Readme.so - A simple editor that allows you to quickly add and customize all the sections you need for your project's readme.
55β
35π΄
READMINE) - A thorough, clear and self-describing README file template for software projects; copy it and edit it as needed.- π StackEdit - A user-friendly online editor that allows you to quickly customize all the sections you need for your project's readme.
5965β
2586π΄
Standard Readme) - A standard README style specification. Has a generator to help create spec-compliant READMEs, too.81β
34π΄
user-statistician) - A GitHub Action that generates SVG of detailed GitHub user activity for profile readmes.801β
141π΄
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:
7622β
289π΄
Gifski) - FREE - More vivid colors than the rest, but still keep size low.- π Giphy Capture - FREE - Easy to upload to giphy.com, slightly annoying UX.
- π LICEcap - FREE - Less intuitive, more features.
10153β
318π΄
Peek) - FREE - Simple and easy to use for Linux users.- π Recordit - FREE - Simple, clean UI, but auto-uploads to Recordit.
?β
?π΄
ScreenToGif) - FREE - Open source, customizable UI and easily editable GIFs, easy to get started.15108β
491π΄
terminalizer) - FREE - Record your terminal and generate animated gif images or share a web player.3239β
93π΄
ttystudio) - FREE - For commandline tools, a terminal-to-gif recorder minus the headaches.14344β
241π΄
vhs) - FREE - Generate beautiful terminal gifs with a simple scripting language
1126β
56π΄
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'.
Contributions are always welcome! Please read the contribution guidelines first.
To the extent possible under law, π Matias Singers has waived all copyright and related or neighboring rights to this work.
17411β
3806π΄
matiassingers/awesome-readme)