How to create custom badges to improve your Markdown documents
Tags: github, markdown, documents, svg
Published: 2019-07-18 07:37:09

*<span>Cover photo by <a href="https://unsplash.com/@luartevisual?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Kevin Luarte</a> on <a href="https://unsplash.com/s/photos/badge?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></span>*

This post is about creating custom badges similar to the ones that you saw over README.md'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](https://github.com/thundra-io/thundra-trace-chart) of a react component that I contribute. I added this url `https://img.shields.io/npm/v/thundra-trace-chart.png` as source of an image to the top of the README and tada! a badge![tada!](https://img.shields.io/npm/v/thundra-trace-chart.png) 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 [shields.io](https://shields.io/). 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](https://thundra.io). 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](https://img.shields.io/endpoint.svg?url=https://thundra-version-0qw7bzmwj7wy.runkit.sh&link=https://thundra.io "Custom Thundra badge")

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 `https://img.shields.io/static/v1.svg?label=left&message=right&color=red` you get something like; ![alt text](https://img.shields.io/static/v1.svg?label=left&message=right&color=red "Custom badge") But I could not add a custom icon using url params. So that I discovered making custom badges from [json endpoints](https://shields.io/endpoint). 

### 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](https://dev.to/benjaminblack/using-a-string-of-svg-as-an-image-source-8mo). I created a simple [endpoint](https://runkit.com/milkers/thundra-version) using Runkit. Then I add the Runkit endpoint to the end of a generic shields url as a parameter like this `https://img.shields.io/endpoint.svg?url=https://thundra-version-0qw7bzmwj7wy.runkit.sh` 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.