Adding Shields.io badges to your GitHub profile

Originally published on peateasea.de.

A GitHub user profile page can be a great place to show off what you’re interested in and what experience you might have. Rather than presenting a wall of text, you can add colour and flair to the profile in various ways. One way to do this is to show badges of the programming languages, frameworks, and other technologies that you’re interested in. This post shows how to add badges from the badge generator on Shields.io to your GitHub profile.

GitHub profiles: your own small corner of the internet

Each GitHub user has their own special repository where they can create and personalise their GitHub profile page. This is an opportunity to share who you are, what you do and what you’re interested in. It reminds me a bit of the GeoCities¹ pages that were once popular in the early years of the web. It was a place where anyone could have a small corner of the internet to display what interested them. As with GeoCities pages, the presentation possibilities are endless: you can add images, use emojis, link to other sites, and much more. You can even add a visitor counter for that truly retro feel!

Badges are a common adornment to show off what you like or are involved in. This post focuses on badges and how you can use Shields.io to generate badges for display on your GitHub profile.

Setting up a profile

After cloning the special repository for your GitHub user profile you can add information to a Markdown-formatted README file in much the same way you would do for any normal GitHub repository. The only difference is that the content of this README appears on your user’s profile page.

The repository has the same name as your GitHub username and it takes only a few clicks to create your first README. It seems that this feature was first added in July 2020. More information about managing and customising your profile is available in the GitHub account and profile documentation.

Much more than just badges

It’s taken me a while to get around to creating my GitHub profile. While working out how to set it up, I stumbled upon the amazing things people have on theirs. For instance, you can automatically link to your most recent blog posts (from e.g. dev.to, medium or via RSS feed), display various GitHub statistics, show how long your latest programming streak is, as well as display achievement badges.

For those interested in more than badges, I recommend looking at K M H Mubin’s extensive post about creating a GitHub README. It has a lot of information about the components one could add to a profile README as well as descriptions of how to implement various features.

Another useful resource is the GitHub README generator. Here, one can specify various pieces of metadata to mention. Creating a list of logos is then a simple matter of clicking on some checkboxes. The tool then generates Markdown and HTML to include in your profile README. All you need to do is copy it into your repository, commit the changes and push to GitHub.

If logos or icons are more your thing, and you’re looking for an alternative to badges, then have a look at VectorLogoZone, Devicon, or Iconify. These sites contain SVG versions of logos and icons from many different projects. Iconify in particular includes an enormous number of icons, organised into categories for easy browsing.

Let’s get back on track and focus on creating badges with Shields.io.

Badges

There are three kinds of badges one can create on Shields.io: dynamic badges, endpoint badges and static badges. Dynamic badges fetch information from a given online source and present this information within the badge body. Endpoint badges are created via a JSON endpoint and are beyond the scope of this post. Static badges contain pre-defined text and/or logos.

Dynamic badges

There are hundreds of dynamic badges available on Shields.io for you to create. Most dynamic badges seem to be based upon displaying status metadata for software projects. For instance, you might want to show users the current version number, what the build status is, or how much code coverage a service such as Coveralls shows. These aren’t necessarily the kinds of things you want to mention on your GitHub profile. However, if you’re that way inclined, you could display social-media-related metadata, such as the number of Mastodon or Twitter X followers you have, or the number of views on YouTube channel. For badges of this kind, check out the “Social” section on the Shields.io badges page.

Static badges

As mentioned earlier, you’ll likely want to mention the programming languages and tools you use or are generally interested in on your GitHub profile page. For this purpose the static badges are perfect. For the rest of this post, we’re going to concentrate only on static badges.

Shields.io works together with Simple Icons, a site where you can find SVG icons for popular brands. This is particularly useful if you want to use a pre-existing logo as part of your badge. Often, you’ll need to collect some basic information from the Simple Icons site to create a static badge correctly.

The static badge page contains a badge generator on the right-hand side of the page (shown in the bright orange frame in the image below).

We’ll use this generator to create Markdown which you can put in your GitHub profile README.md file and thus add badges to your GitHub profile.

A two-part badge

Let’s start with the first example from the Shields.io static badges documentation: a two-part badge.

A two-part badge consists of a left-hand side (referred to in the documentation as the “label”) containing text and an optional logo, as well as a right-hand side (referred to as the “message”) which usually contains only text. Each part can be configured to have different text and background colours. You’re likely to have seen the two-part badge style in such things as a CI pipeline’s build status badge.

The Shields.io API allows you to create badges in this style very easily: specify within the badgeContent field the label text, message text, and colour each separated by a hyphen. For instance, let’s consider the example from the documentation: build-passing-brightgreen. This will put the word “build” in the badge’s label part, the word “passing” in the message part, and will use the CSS named colour “brightgreen” as the background colour in the badge’s message part. It seems that the default background colour for the label part is black.

Let’s see this in action. Enter build-passing-brightgreen into the badgeContent field in the static badge generator and then click on the “Execute” button. You’ll get the following:

Congratulations! You’ve created your first badge!

As you can see from the output, not only did the generator produce an image, but also a URL pointing to the Shields.io API which generates the image. This URL can then be embedded in a website so that the image is generated on the fly when a user visits your page. One can also choose from other options to link to the generated badge image:Markdown, rSt, AsciiDoc and HTML. In this article, we’re going to focus on the Markdown output because this is what is commonly used on GitHub for project and profile page README files.

A single-part badge

The other kind of static badge that you can generate on Shields.io is the single-part badge. This kind of badge only contains a message, i.e. there’s no “label” component. You can also configure it to have different text and background colours as we did with the two-part badge above. For instance, using the text “lorem ipsum” and specifying the colour purple by entering lorem ipsum-purple into the badgeContent field of the badge generator, we get:

Note that we only use one hyphen in this case because the badge only contains a message along with its background colour definition.

When using multiple words to specify the message text, one can separate them by plain spaces in the badgeContent field. These spaces will be converted via percent encoding into the text %20 within the URL created by the badge generator. If you want to avoid percent encoding strings appearing in your URLs, separate words by underscores in the badgeContent field. The text in the badge will be separated by spaces, but the URL will be easier to read because it will use underscores.

For example, using lorem_ipsum-purple produces the same badge, but a more readable URL:

Flexible colour specification

Not only can you specify the badge’s background colour by using a CSS named colour, but you can also have fine-grained control over the colour by using a hex, rgb, rgba, hsl, or hsla string. For instance, using the example on the static badges page, we use the hex string 8A2BE2 to define the colour:

Shady colour intelligence

Playing around a bit with the colours, one can see that there’s some built-in intelligence in the Shields.io system controlling the contrast between the background colour and the foreground text. E.g. the text will be white if the background is dark

and the text will be black if the background is light.²

Badge not found

Note that if you don’t have at least two text “fields” separated by a hyphen (or there is some other error in your input), you will get a “badge not found” error. Rather appropriately, this will appear as a badge:

Lots of options to choose from

As you can see, there’s already lots of range and flexibility in what one can create using only the default settings. Let’s now create badges for more specific use cases and thus demonstrate more of the options available on Shields.io.

A badge for Git

Let’s now be a bit more concrete and create a badge for Git.

A very basic example

A fundamental skill a programmer has to have is the ability to work with version control systems(VCS). Git is the most common VCS these days, so you’ll likely want to add a badge for it to your GitHub profile. Fortunately, it’s also a good example of a basic badge setup.

One of the simplest things to begin with is to create a badge with the word git on a black background. To do this, type git-black into the badgeContent field in the badge generator and then click on the “Execute” button. A small badge with the word git in white text on a black background will appear below the “Execute” button.

Admittedly, this isn’t very exciting, but it’s a start.

Including the project’s logo

A nice touch is to add a logo to the badge because often a brand logo is immediately recognisable. This is where the badge generator’s “+ Show optional parameters” section comes in. Clicking on this text shows the many other parameters one can set (there are parameter docs on the page with the badge generator if you need more help).

Now enter git into the logo field:

Scrolling down to the “Execute” button and clicking on it (and selecting “Markdown” from the list of text output options) we get

As you can see, the logo appears with the right design and colours that we’re familiar with from the Git project.

Generating Markdown for the GitHub profile’s README.md

We can now take the Markdown text (not all of it is visible in the badge generator output from the screenshot above)

![Static Badge](https://img.shields.io/badge/git-black?logo=git)

and paste it into our GitHub profile’s README.md file to add the badge. Unfortunately, the badge image’s alt-text Static Badge isn’t very informative, so let’s change that:

![Git badge](https://img.shields.io/badge/git-black?logo=git)

In essence, that’s it! If you’ve already added this Markdown code to your GitHub profile README and pushed upstream, you’ve published your first badge. Well done!

Plain and simple, if that’s to your taste

Now we start to enter the realm of personal taste. One variation on the theme outlined above could be to use the project logo’s main colour as the badge’s background colour and then use plain white for the logo and text colour. Let’s implement this variation now.

To find out the project logo’s colour as a hex value, visit Simple Icons (which is what Shields.io uses to generate the logos in the badges) to find what colour to use. Because we’re focussing on Git here, we visit the Simple Icons site and type git into the search field. The search results will show many different Git-related projects including GitLab, GitHub and GitKraken. We’re only interested in the first search result, Git. You should see an informational panel like this:

The informational panel displayed on the Simple Icons site shows relevant metadata about the logo: a black-and-white SVG version of the logo, licensing information, the name of the project, and the logo’s colour (both the actual colour and a hex string representing the colour). Clicking on the colour information automatically copies the hex string into the clipboard so that we can use this information straight away in the Shields.io badge generator.

In the case here, the hex string for the colour of the Git project is #F05032. Returning to Shields.io and replacing the string git-black in the badgeContent field with git-#F05032

and then scrolling down to the “Execute” button and clicking on it, gives

which isn’t very useful, because now the logo and the background are the same colour. Oops.

Let’s fix this by changing the logoColor parameter to white and running “Execute” again. This gives

which is much more useful and is a simpler version of the badge with the black background we created above. The Markdown for this badge is

![Static Badge](https://img.shields.io/badge/git-%23F05032?logo=git&logoColor=white)

Fixing the alt-text we get

![Git badge](https://img.shields.io/badge/git-%23F05032?logo=git&logoColor=white)

Note how the parameters are embedded into the URL for the badge. This means that it’s possible to play with the options within the text of a README.md file as opposed to testing things first in the Shields.io badge generator and then copy-and-pasting the Markdown into the README.md. Try playing around with the parameters to see what you can come up with!

Building a basic Bash badge

Not all logo designs play nicely with default background colours and text or have the logo name one might first expect. One I found to have an unexpected logo name and that was difficult to get a nice contrast while still including the official project colour was the Bash logo.

I’ll show you what I mean by building a badge for bash.

Visiting the Simple Icons site and typing bash into the search box returns–as one of the search results–the logo entry for our familiar shell.

Clicking on the name in the info panel copies the logo name³ into the clipboard so that you can paste the value into the logo field of the badge generator on Shields.io. For Bash this value is gnubash. This surprised me. My gut feeling was that it would have been called bash. But I was wrong and only worked out the correct name by clicking on the name in the logo’s info panel on Simple Icons. At least now it’s clear to me why using bash in the badge generator’s logo field didn’t generate a badge.

Let’s use some basic settings to see what happens. Let’s put bash-black in the badgeContent field and gnubash in the logo query field. Doing so we get:

which I don’t find to be very clear.

Using a white background (i.e. badgeContent: bash-white) we get a visually clearer variant:

However, if we want to use Bash’s official colour (#4EAA25) for the background (i.e. badgeContent: bash-#4EAA25) and white for the logo foreground (logoColor: white)–thus matching the second badge style described in the Git section above–we get

This variant is also not very clear. How could we improve this?

One idea I came up with was to use the two-box form for the badge and put the logo on the left-hand side with black in the foreground and white in the background. Then the right-hand side would contain the text in white and use the official logo’s colour as the background.

The settings are now: badgeContent: bash-#4EAA25, logo: gnubash, logoColor: black, labelColor: white.

Putting these parameters into the badge generator and clicking on “Execute” creates this badge:

which I considered to be a good compromise between using the official project colour, its logo, and the contrast between background and foreground colours.

The Markdown generated for this badge setup is:

![Bash badge](https://img.shields.io/badge/bash-%234EAA25?logo=gnubash&logoColor=black&labelColor=white)

after having improved the alt-text.

Now it’s just a matter of adding this Markdown to your GitLab profile’s README.md and you’ve got another badge to present. Yay! 🎉

Much more variation possible

Now that you’ve seen how to create a more complex badge, I hope you’ve gained some insight into what’s possible with Shields.io’s badge generator.

The Shields.io docs are a bit sparse, so be aware that it might not always be clear exactly how to use a parameter. Be prepared to do a bit of experimentation to create a badge with the desired properties.

There are many more options you can play with, so don’t restrict yourself to only those designs I’ve discussed here: have a play and see what you come up with!

Linking to other sites from for-the-badge style badges

The default flat style (as used above) is fairly typical for displaying programming languages or technologies that you have experience with. For buttons or badges linking to a social media presence, a blog, or a website, you might like to use a different style of badge. After all, different things should look different. One style I find that lends itself to linking to external sites is the for-the-badge style.

At first, it wasn’t clear to me what for-the-badge referred to. It turns out that it’s a badge style popularised by the site https://forthebadge.com/ which Shields.io implemented after receiving a feature request for for-the-badge-style badges.

To illustrate this idea, let’s create a Mastodon badge and link it to a Mastodon user’s profile page.

Creating a Mastodon badge

Setting up a Mastodon badge in the for-the-badge style with a black background and the official Mastodon logo, we use these parameters

Clicking on the “Execute” button gives this output

This badge looks quite nice and we could copy the Markdown into our GitHub profile’s README.md file

![Static Badge](https://img.shields.io/badge/mastodon-black?style=for-the-badge&logo=mastodon)

however something’s not quite right here.

Linking badges to URLs

The problem is that this Markdown code doesn’t link anywhere. It’d be nice if it linked to (say) your Mastodon profile. This way a visitor to your GitHub profile could click on the Mastodon badge and then see who you are on the fediverse.

Interestingly enough, GitHub will automatically create a link to camo.githubusercontent.com from the badge on your profile. Clicking on the badge (and thus the link) will open a page containing only the badge, which isn’t very helpful.

It’s possible to add a link to our badge in the badge generator settings. Had we done that, the badge now sitting alone on its own page would then link to where we wanted the user to go in the first place (to visit the link, you click on the badge again). In my opinion, having to click twice on the same badge to get to where the badge is purporting to link to isn’t very clear UX. Surely there’s another way.

Because I couldn’t get the link parameter to work properly,⁴ I came up with a solution which embeds the image within the link text of a normal Markdown link. The URL of where you want the badge to link to is thus in the parentheses of the Markdown link as per normal.

You can embed the image with an HTML <img> tag like so:

[<img src="https://img.shields.io/badge/mastodon-black?style=for-the-badge&logo=mastodon">](https://mastodon.social/@<mastodon-username>)

or by embedding a Markdown image

[![Link to Mastodon profile](https://img.shields.io/badge/mastodon-black?style=for-the-badge&logo=mastodon)](https://mastodon.social/@<mastodon-username>)

which looks a bit more complicated, but allows you to add an alt-text for the image in the familiar Markdown manner.

An alternative solution involves saving the badge’s SVG generated after the “Execute” step (for example, right-click on the badge and select “Save Image As…”). Then your Markdown code would look like this:

[![Link to Mastodon profile](/path/to/mastodon-badge.svg)](https://mastodon.social/@<mastodon-username>)

This solution has the advantage that you don’t have to rely on an online service to generate badge images each time someone visits your GitHub profile.

Now you’re able to create badges which link to any other presence you have online. Brilliant!

Wrapping up

Personalising your GitHub profile gives visitors insights into what kind of developer you are, what you’re interested in and what you can do. It’s a little corner of the internet that you can set up to be “just yours” and where you can show off a bit of your personality. Adding badges to your page gives a good overview of your skills and interests, as well as providing a dash of colour to what might otherwise be a very plain wall of text.

There’s heaps of variety here and lots of flexibility available to create the badges you want to display on your GitHub profile. Have fun!

1. I found out that if you search for GeoCities in Google, the results are displayed in Comic Sans! 😆 ↩

2. You may be wondering why I chose blue and beige here for the dark and light colours (respectively). I didn’t want to use black and white because these colours have too much contrast. I wanted something dark (light) but not the darkest (lightest) one could have to demonstrate the automatic choice of good contrast text. ↩

3. The logo name as used in the logo field on Shields.io is also referred to as a slug in the Shields.io documentation. ↩

4. The static badge docs mention using the HTML <object> tag, but I couldn’t get that to work either. ↩