README.md is the landing page of your code.
If you are building an open-source repository, README is the most important file in the whole repository.
It has to not just look good, but also read well.
It should tell its readers everything.
Usage
Installation
Website
Version
Are tests failing or passing?
Average Activity
User Testimonies
License
Star Gazers on GitHub
And much more...
The good news is, most of the above information can be expressed in just a few dynamic SVG elements!
You have seen them already, everywhere... in every famous repository.
I really like how Mr. Ahmed Awais writes his READMEs. See an example here.
What are README Badges?
See this π
Your badges don't have to be that boring.
You can check out all the badges you can use here.
Here are 5 must-have README badges!
1. π§ͺπ§ͺπ§ͺ Travis Tests Status
This is the current Travis status of my NPM Package π°
You can get the badge in your readme by pasting the following syntax...
Replace :githubUsername
and :repository
with real data.
![Travis Status](https://img.shields.io/travis/:githubUsername/:repository)
2. βοΈβοΈβοΈ Rate on pkgreview.dev
pkgreview.dev is an app where users can review and rate your NPM Package. Users can write testimonies of your package on the app.
To encourage them to write the testimonies/reviews... You can add this in the README π
You can get the badge in your readme by pasting the following syntax...
Replace <package-name>
with the real package name. You can check the package name and URL on pkgreview.dev.
| **Like us a lot?** Help others know why you like us! **Review this package on [pkgreview.dev](https://pkgreview.dev/npm/<package-name>)** | β‘ | [![Review us on pkgreview.dev](https://i.ibb.co/McjVMfb/pkgreview-dev.jpg)](https://pkgreview.dev/npm/<package-name>) |
| ----------------------------------------------------------------------------------------------------------------------------------------- | --- | --------------------------------------------------------------------------------------------------------------------- |
3. π°π°π° NPM Downloads Badge
The below image shows the number of times React was downloaded on NPM last week...
You can get the badge in your readme by pasting the following syntax...
Replace :packageName
with the NPM Package slug/name.
![NPM Downloads](https://img.shields.io/npm/dw/:packageName)
4. πππ License Badge
People should know what license your repository uses. If your repository uses NPM, you can fetch license dynamically and get a badge like this π
You can get the badge in your readme by pasting the following syntax...
Replace :packageName
with the NPM Package slug/name.
![NPM License](https://img.shields.io/npm/l/:packageName)
5. π¦π¦π¦ Twitter Badge
If you have a Twitter account for your repository, or if you have a Twitter Account as a maintainer of the repository, you gotta show a dynamic Twitter badge!
You can get the badge in your readme by pasting the following syntax...
Replace :twitterHandle
with your Twitter username.
[![Twitter](https://img.shields.io/twitter/follow/:twitterHandle.svg?style=social&label=@:twitterHandle)](https://twitter.com/:twitterHandle)
That was just a scratch on the surface!
The possibilities with READMEs are endless if you use SVGs by shields.io.
You can create all kinds of custom and dynamic README SVG badges with it... Take a look!
With it, you can create badges for the following...
NPM Packages
WordPress Plugins
Travis Tests
CircleCI tests
Discord badge with live
online
countTwitter follower count
GitHub Stats
Funding by OpenCollective
Uptime Monitors
GitHub Stargazers
And so much more!
Conclusion
README badges are useful. They provide so many insights and also look cool on GitHub and Package Managers like NPM.
About me
I am Kumar Abhirup, a 16-year-old JavaScript React developer from India who keeps learning a new thing every single day.
Connect with me on Twitter π¦
My personal website and portfolio π₯οΈ
Comment below your better ways, and suggestions to improve this post.Β :)
Top comments (2)
Nice! Thanks for this!
Thanks for Sharing