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 GeoCities1 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.2
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 name3 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,4 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!
I found out that if you search for GeoCities in Google, the results are displayed in Comic Sans! đ â©
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. â©
The logo name as used in the
logo
field on Shields.io is also referred to as a slug in the Shields.io documentation. â©The static badge docs mention using the HTML
<object>
tag, but I couldnât get that to work either. â©
Top comments (0)