Awesome
Dynamic Badge Formatter
Format Shields Dynamic Badges to look consistent using formatters for metrics, versions, stars and more.
Dynamic Badge Formatter works alongside shields.io using Endpoint Badges with a Runkit Endpoint.
⚡ How to use
The easiest way to get started is to try out the demo site!
Advanced steps
-
Choose a JSON, XML, or YAML data URL to extract data from.
-
Create a query using a JSONPath (for JSON or YAML) or XPath (for XML) expression.
-
Set the
url
andquery
parameters at the endpoint https://dynamic-badge-formatter-ynrxn78r2oye.runkit.sh/json, using/json
for JSON,/xml
for XML, and/yaml
for YAML. -
Set additional customizations as query parameters, such as the
color
,label
,labelColor
,logo
, etc., and specify aformatter
to use (see below). -
URL Encode the new endpoint URL and append it after
https://img.shields.io/endpoint?url=
. You can also do this by pasting the URL at shields.io/endpoint.
Example
The following is a JSON API I want to use for displaying data. I want to display the stars but formatted as a metric (eg. "3.2k"
instead of "3227"
). To extract the star count from the JSON, I will use the query $.stars
.
// https://api.github-star-counter.workers.dev/user/DenverCoder1
{
"stars": 3227,
"forks": 1207
}
To create the Runkit URL, pass the query
, url
, and additional parameters to the endpoint. In this example, I set formatter
to metric
, label
to stars
, color
to green
, and logo
to github
.
https://dynamic-badge-formatter-ynrxn78r2oye.runkit.sh/json?query=$.stars&url=https://api.github-star-counter.workers.dev/user/DenverCoder1&formatter=metric&label=stars&color=green&logo=github
Using the customizer at https://shields.io/endpoint, I can turn this endpoint into a badge.
https://img.shields.io/endpoint?url=https%3A%2F%2Fdynamic-badge-formatter-ynrxn78r2oye.runkit.sh%2Fjson%3Fquery%3D%24.stars%26url%3Dhttps%3A%2F%2Fapi.github-star-counter.workers.dev%2Fuser%2FDenverCoder1%26formatter%3Dmetric%26label%3Dstars%26color%3Dgreen%26logo%3Dgithub
Result:
⚡ Formatters
The following values are supported for the formatter
parameter:
Formatter | Description | Example |
---|---|---|
metric | Formats a number as a short metric (eg. 3.4k , 12.3M ) | <br/> |
starRating | Formats a number as stars (eg. ★★★★½ ) | <br/> |
ordinalNumber | Formats a number with an ordinal suffix (eg. 9ᵗʰ ) | <br/> |
omitv | Removes a v as a prefix from a version number (eg. v1.2.3 becomes 1.2.3 ) | <br/> |
addv | Adds a v as a prefix from a version number (eg. 1.2.3 becomes v1.2.3 ) | <br/> |
formatDate | Formats dates as a month and year, "today" or "yesterday" can appear for recent dates | <br/> |
formatRelativeDate | Formats a UNIX Timestamp in seconds as a relative time (eg. 3 days ago ) | <br/> |
⚙️ Other Parameters
Parameter | Type | Description |
---|---|---|
url | string | required The JSON, XML, or YAML data URL to fetch a message value from |
query | string | required The JSONPath or XPath query for extracting a field for the value |
label | string | optional The label to use for the badge, default: "custom badge" |
color | string | optional The color to use for the badge, default: "blue" |
labelColor | string | optional The color to use for the label, default: "grey" |
isError | boolean | optional If true, the badge color is overriden to be red, default: false |
logo | string | optional A named logo to use from Simple Icons or base64 encoded SVG, default: none |
namedLogo | string | optional The name of a logo to use from Simple Icons, overrides logo , default: none |
logoSvg | string | optional The base64 encoded SVG content of a logo to use, overrides logo , default: none |
logoColor | string | optional The color to use for the logo, default: none |
logoWidth | number | optional The width of the logo, default: none |
logoPosition | number | optional The position offset of the logo, default: none |
style | string | optional The badge style (plastic, flat, flat-square, for-the-badge, or social), default: "flat" |
cacheSeconds | number | optional The number of seconds to cache the response, default: 300 |
prefix | string | optional A prefix to use before the message, default: none |
suffix | string | optional A suffix to use after the message, default: none |
formatter | string | optional The name of a formatter to use on the message (see options above), default: none |
🤗 Contributing
We welcome contributions!
Please see CONTRIBUTING.md for details.
📤 Deploying it on your own
<details> <summary>Deploy to Runkit</summary>- Sign in to Runkit or create a new account at https://runkit.com
- Create a new notebook
- Paste the contents of
index.js
into the notebook - Click
endpoint
to get your endpoint to run requests against
💬 Questions?
Feel free to open an issue.
❤️ Thanks
- Shields.io for all the great work they have done with creating tools for creating Dynamic and Endpoint Badges
📚 License
This project is licensed under the MIT license.
Some formatters make use of code written for shields.io in the public domain.
🤩 Support
💙 If you like this project, give it a ⭐ and share it with friends!
<p align="left"> <a href="https://www.youtube.com/channel/UCipSxT7a3rn81vGLw9lqRkg?sub_confirmation=1"><img alt="Youtube" title="Youtube" src="https://custom-icon-badges.herokuapp.com/badge/-Subscribe-red?style=for-the-badge&logo=video&logoColor=white"/></a> <a href="https://github.com/sponsors/DenverCoder1"><img alt="Sponsor with Github" title="Sponsor with Github" src="https://custom-icon-badges.herokuapp.com/badge/-Sponsor-ea4aaa?style=for-the-badge&logo=heart&logoColor=white"/></a> </p>