DEV Community

Cover image for How to create custom badges to improve your Markdown documents
Mustafa ilker Sarac
Mustafa ilker Sarac

Posted on • Updated on

How to create custom badges to improve your Markdown documents

Cover photo by Kevin Luarte on Unsplash

This post is about creating custom badges similar to the ones that you saw over's of coolest projects on Github.

Have you ever wondered about creating a custom badge or why they are used for? People use them to improve the look of their documents and add some professionalism. This is useful, especially for open source projects. No one wants to use code from Github repos that have last commit from 2 years ago (even 6 months) and with a careless README file. These badges are a way to show how much you love your repo.

I first used them for the repo of a react component that I contribute. I added this url as source of an image to the top of the README and tada! a badgetada! appears which shows the latest npm version of the component. And the best part is it increases the version number by itself when we release a new version of the component to the npm registry.

I followed the source of this magic and found out this humble site called The site has many easy to use badges for most common use cases like the one I used for npm version of a package. However, it was not enough for me. I wanted to make a custom badge that is not supported (yet!:) by shields. It was going to be used by versioning the many parts of the project that I am working for almost a year called Thundra. It is a great tool for monitoring AWS Lambda functions and it is in the skyrocketing phase of a startup. So sometimes it is hard to keep track of versions of many pieces (agents, layers, add-ons, apps etc.) that are being developed day and night by the team. For the sake of solving that problem and making our docs a bit better I wanted to build a custom badge for Thundra and it looked like that;

alt text

Now I wanted to explain briefly how you could make one for your own taste.

Create Badge from Endpoint

You can create simple custom badges easily with shields. For example, using this url you get something like; alt text But I could not add a custom icon using url params. So that I discovered making custom badges from json endpoints.

Find an SVG Icon

I needed an SVG icon for the badge, luckily we had an SVG version of our Thundra icon so I used it. The trick here is you need to get rid of the good indentations and need to make the svg a one liner. I created a simple endpoint using Runkit. Then I add the Runkit endpoint to the end of a generic shields url as a parameter like this and the task was done for the badge.

Adding custom badges is a great way to show how much you care for your documentation. It is also awesome to inject some live data to your docs. You do not have to update your docs for just a version change in nowadays, these badges magically do the job for you and keep your docs as fresh as possible.

Top comments (0)