Jazz up your online software documentation, GitHub or Web pages with shields ( badges )
What are shields (aka badges)?
You may search them as badges or shields. They represent status and summaries, credentials on a WebPage and the most popular use on GitHub pages. They certainly look cool; like the earnings of a soldier on a uniform. And that’s what they exactly are, for your GitHub page. Other than the cool factor, shields improve the credibility of the project on first glance and summarize diligence and sincerity towards the repository.
For ease, we assume shield and badge are inter changeable and will use the word “shield” for the rest of this blog.
A shield has three aspects: <Label>:<Value> ; <Link>
The label is a static text or raster. Some shields providing an icon in the label part.
The value can be a static text value, raster, vector or even a combination.
A link can either be a simple status link or link to a site that validates and credits your badge. A status link may open to a page with a cached version of the badge representing the raster or vector SVG, while a service backed one may even open to a report giving the details behind the badge summary. What a link opens to is open to the service.
Types of shield values and shield services
- Static: Just static text
- Dynamic: The value is obtained from a server and related to your repository. Example: Shields can be custom generated also but that is another topic. To help you get going, there are some pre-existing badges from the communities where your code may sit, including GitHub, GitLab, Slack, CI/CD, CII tools and so many more.
Please note that the Shield generator service is just a URL and can be used anywhere, not just on the platform generating the shield.
Create a badge on GitHub
Since you now understand what a Shield Service is, lets see a practical example of a URL using such a service on GitHub. In the following example the dynamic elements are in bold:
https://github.com/<organization-or-user-name>/<repo name>/workflows/<name of my CI/CD action in GitHub>/badge.svg?event=push
Am sure many will still be wondering what the place holders are, so here is a practical animation of usage from one of my repo’s:
Create a badge on Shields.io
References (links)
- Shields.io
- Create your own shield service
- Contributing to shields
- Shield examples: GitHub, GitLab, Slack, CI/CD, CII
- GitHub badges
