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

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.
ajeetdsouza/zoxide - Badges, project GIF, concise description, quick links, stepwise installation instructions.
alichtman/shallow-backup - Clear description of what the project does. GIF Demo. TOC for easy navigation. Badges. Links for further reading. Simple install instructions.
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.
amplication/amplication - Clear project logo…

GitHub Readme: Responsive? 🤔 Animated? 🤯 Light and dark modes? 😱 You bet! 💪🏼

GrahamTheDev on January 19, 2024

Yes, you heard me right, my GitHub readme has light and dark modes and is even responsive. In this article I will briefly cover the tricks I used t...

Read full post

Vincent A. Cicirello • Jan 19

You should submit your README to:

matiassingers / awesome-readme

View on GitHub

GrahamTheDev • Jan 19

Nice, I was going to submit it to the other repo that showcases readmes but it had like 425 issues. This one looks maintained, so thanks! 🙏🏼💗

You're welcome.

Arthur Neuron • Jan 19

It looks fine 👍🏾, but for some reason one half is generated in a light style and the other half in a dark style.

Hmmmm, that looks like you have the theme set to dark directly in GitHub but the system setting is light mode maybe (and they do some weird trickery for light and dark mode on images)?

Darn, not sure how to fix that unless I use 2 different versions for the buttons and then use the <picture> element to fix.

I will have to have a fiddle, can I ask what browser (and if you have light mode as your system preference as I think?). Thanks for the bug report! 🤣🙏🏼💗

Arthur Neuron • Jan 19 • Edited

Safari Version 17.1.2 (19616.2.9.11.12)

I change the system theme, and the light version works fine.
When I change to the dark version, only the bottom half of the readme changes.

GrahamTheDev • Jan 19 • Edited

Ahhhh, it is the other problem, SVGs using embedded media queries for light mode preference don't work on Safari (actual iOS / MacOS issue) if you have dark mode enabled there!

I will fix that with 2 <picture> elements then, thanks for the heads up, never knew that restriction! 🙏🏼💗

Taufik Hidayatulloh • Jan 20

use image with transparent background

GrahamTheDev • Jan 20

Doesn’t work like that sadly as the colour scheme within the buttons needs to change for colour contrast. 💗

Aleh Zasypkin • Jan 20 • Edited

Very nice job @grahamthedev! Just one small correction:

This is because of something called a Content Security Policy (CSP) and the way it is implemented on GitHub.
Luckily, data URIs are counted as the same context / origin.

The data: URIs aren't considered the same context/origin (and will never be). It works because GitHub explicitly allows loading images using the data: protocol as the image source. I've imported the policy from your profile with Secutils.dev to illustrate (take a look at the Image source (img-src) field): "[Dev.To] GrahamTheDev's Profile" content security policy

The Image source (img-src) also shows that we have a few other options should GitHub remove data: from the allowed sources :)

Now I won't explain CSPs, but in essence they have a rule that says "hey, no images can be loaded from anywhere other than the current context".

And a shameless plug, if anyone likes to learn more about CSP, feel free to check out my other post on exploring web applications through their (CSP): dev.to/azasypkin/explore-web-appli...

Ahhhh, maybe that was raw.github.com that had the more restrictive policy (or maybe I just made it up lol).

I will try and have a dig around on Monday and will correct it!

Thanks! 🙏🏼💗

Nick Taylor • Jan 19

Love this! Cool stuff Graham!

Thanks bud! 🙏🏼💗

Aaron Contreras • Jan 20

To get rid of the vertical space between images, just set line-height to 0 in the wrapping div:

GrahamTheDev • Mar 2

I don't think GitHub will allow you to that and it will get stripped (or is line-height an allowed style attribute they accept?).

Rob OLeary • Jan 19 • Edited

I had the same thought with SVGs on the profile readme! I just was not motivated to carve up images to demonstrate. Nice work!

Haha, don't blame you on that one, this took me hours to get right and working within all the restrictions! Better to just have a simple readme in the end lol! 🤣💗

If you have seen some beautiful GitHub readme's, please share them in the comments section, I would love to see them! 💪🏼💗

Tharaka Sandaruwan • Jan 21

Nice work 🔥

D.aȠ • Jan 21

Awesome!!

Travis • Jan 26

Killer work! This is a great idea, Graham 🔥

ohaddahan • Jan 22

Wonder if this is a big vulnerability to hide JS code in.

No, JS code will not work in an SVG foreignObject on GitHub due to their Content Security Policy settings, so it is pretty safe in that respect. 💗

Tobiloba Adedeji • Jan 21

Amazing stuff!!!

Randell Brian Knight • Jan 24

This is so Cool. Thanks for sharing your insights, and I look forward to more posts about these topics.

hyeonho • Jan 20 • Edited

The most important point is that your README.md should be expressed according to your personality.

100% 💪🏼💗

Nathan G Bornstein • Jan 20

Incredible, thanks for sharing!

No problem, I hope you manage to steal a trick or two! 💪🏼💗

hellowwworld • Jan 20

You're so extra lol 😁

impressive 🔥🔥🔥, I'll try myself

Pieces 🌟 • Jan 19

Love this! Useful stuff 🔥

I hope it helps someone create a cool looking readme! 🤞🏼💗

Ranjan Dailata • Jan 19

Amazing.

GitHub might contact and grab you into their UI/UX team :)

Haha, doubt it, there are far too many hacks here that will make them cry! 🤣💗

Neeraj Sharma • Jan 20

Guys anyone tell me how to implement this and where please

Yashjit Pal • Jan 20

Is there a way to create it easily for myself? I don't have any idea about html

I am afraid that if you do not know html and css this will be very difficult to do. You can always grab the source code from my repo and the images and try and adjust them to your needs but I imagine it will be tough if you don’t understand some of what is going on. 💗