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

1. Choose a JSON, XML, or YAML data URL to extract data from.

2. Create a query using a JSONPath (for JSON or YAML) or XPath (for XML) expression.

3. Set the url and query parameters at the endpoint https://dynamic-badge-formatter-ynrxn78r2oye.runkit.sh/json, using /json for JSON, /xml for XML, and /yaml for YAML.

4. Set additional customizations as query parameters, such as the color, label, labelColor, logo, etc., and specify a formatter to use (see below).

5. 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)
starRating	Formats a number as stars (eg. ★★★★½)
ordinalNumber	Formats a number with an ordinal suffix (eg. 9ᵗʰ)
omitv	Removes a v as a prefix from a version number (eg. v1.2.3 becomes 1.2.3)
addv	Adds a v as a prefix from a version number (eg. 1.2.3 becomes v1.2.3)
formatDate	Formats dates as a month and year, "today" or "yesterday" can appear for recent dates
formatRelativeDate	Formats a UNIX Timestamp in seconds as a relative time (eg. 3 days ago)

⚙️ 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

Deploy to Runkit

1. Sign in to Runkit or create a new account at https://runkit.com
2. Create a new notebook
3. Paste the contents of index.js into the notebook
4. 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!

☕ Buy me a coffee