Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/DenverCoder1/dynamic-badge-formatter
Format dynamic shields.io badges to look consistent using formatters for metrics, versions, and more
https://github.com/DenverCoder1/dynamic-badge-formatter
badge-generator badges dynamic hacktoberfest serverless shieldsio-endpoint
Last synced: about 2 months ago
JSON representation
Format dynamic shields.io badges to look consistent using formatters for metrics, versions, and more
- Host: GitHub
- URL: https://github.com/DenverCoder1/dynamic-badge-formatter
- Owner: DenverCoder1
- License: mit
- Created: 2022-06-15T03:45:44.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-10-21T00:23:53.000Z (almost 2 years ago)
- Last Synced: 2024-06-23T07:42:40.811Z (3 months ago)
- Topics: badge-generator, badges, dynamic, hacktoberfest, serverless, shieldsio-endpoint
- Language: JavaScript
- Homepage: https://dynamic-badge-formatter.demolab.com
- Size: 71.3 KB
- Stars: 18
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- badges-awesome-badges - Dynamic Badge Formatter
- awesome-badges - Dynamic Badge Formatter
README
# Dynamic Badge Formatter
[](https://github.com/DenverCoder1/dynamic-badge-formatter/stargazers "stars") [](https://github.com/DenverCoder1/dynamic-badge-formatter/issues "issues") [](https://github.com/DenverCoder1/dynamic-badge-formatter/blob/main/LICENSE?rgh-link-date=2021-08-09T18%3A10%3A26Z "license MIT") [](https://discord.gg/fPrdqh3Zfu "Dev Pro Tips Discussion & Support Server")
Format [Shields Dynamic Badges](https://shields.io/#dynamic-badge) to look consistent using formatters for metrics, versions, stars and more.
Dynamic Badge Formatter works alongside [shields.io](https://shields.io/) using [Endpoint Badges](https://shields.io/endpoint) with a [Runkit Endpoint](https://runkit.com/denvercoder1/dynamic-badge-formatter).
## ⚡ How to use
The easiest way to get started is to [try out the demo site](https://dynamic-badge-formatter.demolab.com/)!
[](https://dynamic-badge-formatter.demolab.com/)
### Advanced steps
1. Choose a JSON, XML, or YAML data URL to extract data from.
2. Create a query using a [JSONPath](https://jsonpath.com/) (for JSON or YAML) or [XPath](http://xpather.com/) (for XML) expression.
3. Set the `url` and `query` parameters at the endpoint , 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](https://user-images.githubusercontent.com/20955511/173730516-1470689e-0e05-4761-89f4-4aa7d8fcb023.png) at [shields.io/endpoint](https://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`.
```jsonc
// 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 , 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](CONTRIBUTING.md) for details.
## 📤 Deploying it on your own
Deploy to Runkit
1. Sign in to **Runkit** or create a new account at
2. Create a new notebook
3. Paste the contents of [`index.js`](./runkit/index.js) into the notebook
4. Click `endpoint` to get your endpoint to run requests against
## 💬 Questions?
Feel free to [open an issue](http://github.com/DenverCoder1/dynamic-badge-formatter/issues/new).
## ❤️ Thanks
- [Shields.io](https://github.com/badges/shields) 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](LICENSE.md).
Some formatters make use of code written for [shields.io](https://shields.io/) in the [public domain](https://github.com/badges/shields/blob/master/LICENSE).
## 🤩 Support
💙 If you like this project, give it a ⭐ and share it with friends!
[☕ Buy me a coffee](https://ko-fi.com/jlawrence)