The Shields service (at shields.io) provides a way to create custom badges for your projects. These are badges are very common and are frequently used to show status information about the project, or demonstrate tools that were used for the development of your project.
Each badge has three main configuration options:
- Subject - Text on the left side of the badge; the background color for this is normally gray (specifically, #555555)
- Status - Text on the right side of the badge; usually the name of a service or a status code; the background color can be chosen by modifying the next option
- Color - The background color for the text on the right side of the badge; colors can be chosen by name, or by a given hex code (i.e. #B7F5B2)
A badge can be created interactively by visiting the shields.io website and scrolling to the bottom, where 3 fields (corresponding to the options above) allow you to make a badge. (Note, if you wish to use a hex color code with this generator, the '#' symbol should be omitted.)
Another way to create a badge is by modifying the URL that points to the badge. The badge in the example above has the following URL: https://img.shields.io/badge/Powered%20by-PostgreSQL-blue.svg. The magic is in the last part of the URL (after /badge/). In that part of the URL, you can see the three configuration options shown above. Each option is separated by a dash '-'. You will also notice that a space is represented by %20 (why). See below for escaping other characters.
Finally, you will notice that the image has a .svg extension. SVG is a vector image format that can be displayed by most modern browsers. Using a SVG file will greatly reduce the amount of information that needs to be transmitted (the above image is < 1 KB in size), and renders the image in full resolution (the text and shapes are actually drawn by the browser). However, older browsers (IE 8, for example) may not support this format. If necessary, the image's extension can be (manually) changed to .png, however, this increases the amount of data needed to be sent, along with causing an increased load on shield.io's servers. If you need to do this, it might be a good idea to host the image on your own server.
Dashes, spaces, and underscores need to be escaped when manually creating a badge:
| In URL | On Badge | |
|---|---|---|
| Dash | -- |
- |
| Space | %20 or _ or * |
|
| Underscore | __ |
_ |
* using a space alone will usually work, as browsers should convert it to %20 automatically
Beyond the three main configuration options, several other parameters exist. These are used by appending a question mark at the end of the URL, followed by the parameter, an equals sign, and the value to assign:
- style - How the badge looks, "flat" is the default, but "plastic", "flat-square", and "social" are also available.
- label - Replaces the text on the left side of the badge (the subject option given above)
- logo - Add a logo to the badge
- logoWidth - Gives a specific amount of space for the logo
- link_&link_ - Add a link to the left and right side of a badge
- colorA - Background of the left side of the badge
- colorB - Background of the right side of the badge
- maxAge - Maximum amount of time the badge should be stored in the HTTP cache of a browser
The Shields service provides this service for free, but accepts donations. Visit the shields.io for more information. This creator of this document has no association whatsoever with the Shields service, apart from using and benefitting from the service that Shields provides. No warranty of any kind is provided with respect to any part of this document.
Your gist explains it much better than the Shields' official site. Thank you.
By the way, I don't know if I miss it, but the process for generating a dynamic badge that I'm seeing is different for what you wrote. The section is at the middle of the page length, below the heading Your Badge. The configuration field names have also changed: