Dynamic Badge Formatter

October 21, 2022 · View on GitHub

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 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.
Set additional customizations as query parameters, such as the color, label, labelColor, logo, etc., and specify a formatter 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.

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