{"id":13407973,"url":"https://github.com/DenverCoder1/dynamic-badge-formatter","last_synced_at":"2025-03-14T12:31:55.531Z","repository":{"id":37080657,"uuid":"503605173","full_name":"DenverCoder1/dynamic-badge-formatter","owner":"DenverCoder1","description":"Format dynamic shields.io badges to look consistent using formatters for metrics, versions, and more","archived":false,"fork":false,"pushed_at":"2022-10-21T00:23:53.000Z","size":73,"stargazers_count":18,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-07-31T20:28:40.755Z","etag":null,"topics":["badge-generator","badges","dynamic","hacktoberfest","serverless","shieldsio-endpoint"],"latest_commit_sha":null,"homepage":"https://dynamic-badge-formatter.demolab.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DenverCoder1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["DenverCoder1"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2022-06-15T03:45:44.000Z","updated_at":"2024-06-16T10:45:59.000Z","dependencies_parsed_at":"2023-01-19T10:21:39.774Z","dependency_job_id":null,"html_url":"https://github.com/DenverCoder1/dynamic-badge-formatter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DenverCoder1%2Fdynamic-badge-formatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DenverCoder1%2Fdynamic-badge-formatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DenverCoder1%2Fdynamic-badge-formatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DenverCoder1%2Fdynamic-badge-formatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DenverCoder1","download_url":"https://codeload.github.com/DenverCoder1/dynamic-badge-formatter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243578359,"owners_count":20313813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["badge-generator","badges","dynamic","hacktoberfest","serverless","shieldsio-endpoint"],"created_at":"2024-07-30T20:00:49.896Z","updated_at":"2025-03-14T12:31:55.182Z","avatar_url":"https://github.com/DenverCoder1.png","language":"JavaScript","funding_links":["https://github.com/sponsors/DenverCoder1","https://ko-fi.com/jlawrence"],"categories":["JavaScript","Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# Dynamic Badge Formatter\n\n[![stars](https://custom-icon-badges.herokuapp.com/github/stars/DenverCoder1/dynamic-badge-formatter?logo=star)](https://github.com/DenverCoder1/dynamic-badge-formatter/stargazers \"stars\") [![issues](https://custom-icon-badges.herokuapp.com/github/issues-raw/DenverCoder1/dynamic-badge-formatter?logo=issue)](https://github.com/DenverCoder1/dynamic-badge-formatter/issues \"issues\") [![license](https://custom-icon-badges.herokuapp.com/github/license/DenverCoder1/dynamic-badge-formatter?logo=law\u0026logoColor=white)](https://github.com/DenverCoder1/dynamic-badge-formatter/blob/main/LICENSE?rgh-link-date=2021-08-09T18%3A10%3A26Z \"license MIT\") [![discord](https://custom-icon-badges.herokuapp.com/discord/819650821314052106?color=7289DA\u0026logo=comments\u0026label=discord\u0026logoColor=white)](https://discord.gg/fPrdqh3Zfu \"Dev Pro Tips Discussion \u0026 Support Server\")\n\nFormat [Shields Dynamic Badges](https://shields.io/#dynamic-badge) to look consistent using formatters for metrics, versions, stars and more.\n\nDynamic 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).\n\n## ⚡ How to use\n\nThe easiest way to get started is to [try out the demo site](https://dynamic-badge-formatter.demolab.com/)!\n\n[![demo site](https://user-images.githubusercontent.com/20955511/174156046-a84dd1c7-d08a-4d5f-bc73-c79cca980180.png)](https://dynamic-badge-formatter.demolab.com/)\n\n### Advanced steps\n\n1. Choose a JSON, XML, or YAML data URL to extract data from.\n\n2. Create a query using a [JSONPath](https://jsonpath.com/) (for JSON or YAML) or [XPath](http://xpather.com/) (for XML) expression.\n\n3. Set the `url` and `query` parameters at the endpoint \u003chttps://dynamic-badge-formatter-ynrxn78r2oye.runkit.sh/json\u003e, using `/json` for JSON, `/xml` for XML, and `/yaml` for YAML.\n\n4. Set additional customizations as query parameters, such as the `color`, `label`, `labelColor`, `logo`, etc., and specify a `formatter` to use (see below).\n\n5. 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).\n\n### Example\n\nThe 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`.\n\n```jsonc\n// https://api.github-star-counter.workers.dev/user/DenverCoder1\n{\n  \"stars\": 3227,\n  \"forks\": 1207\n}\n```\n\nTo 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`.\n\n```\nhttps://dynamic-badge-formatter-ynrxn78r2oye.runkit.sh/json?query=$.stars\u0026url=https://api.github-star-counter.workers.dev/user/DenverCoder1\u0026formatter=metric\u0026label=stars\u0026color=green\u0026logo=github\n```\n\nUsing the customizer at \u003chttps://shields.io/endpoint\u003e, I can turn this endpoint into a badge.\n\n```\nhttps://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\n```\n\nResult:\n\n![preview](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)\n\n## ⚡ Formatters\n\nThe following values are supported for the `formatter` parameter:\n\n| Formatter            | Description                                                                           | Example                                                                                                                                   |\n| -------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `metric`             | Formats a number as a short metric (eg. `3.4k`, `12.3M`)                              | ![before](https://img.shields.io/badge/before-3400-cc6060)\u003cbr/\u003e![after](https://img.shields.io/badge/after-3.4k-2ea44f)                   |\n| `starRating`         | Formats a number as stars (eg. `★★★★½`)                                               | ![before](https://img.shields.io/badge/before-4.5-cc6060)\u003cbr/\u003e![after](https://img.shields.io/badge/after-★★★★½-2ea44f)                   |\n| `ordinalNumber`      | Formats a number with an ordinal suffix (eg. `9ᵗʰ`)                                   | ![before](https://img.shields.io/badge/before-9-cc6060)\u003cbr/\u003e![after](https://img.shields.io/badge/after-9ᵗʰ-2ea44f)                       |\n| `omitv`              | Removes a `v` as a prefix from a version number (eg. `v1.2.3` becomes `1.2.3`)        | ![before](https://img.shields.io/badge/before-v1.2.3-cc6060)\u003cbr/\u003e![after](https://img.shields.io/badge/after-1.2.3-2ea44f)                |\n| `addv`               | Adds a `v` as a prefix from a version number (eg. `1.2.3` becomes `v1.2.3`)           | ![before](https://img.shields.io/badge/before-1.2.3-cc6060)\u003cbr/\u003e![after](https://img.shields.io/badge/after-v1.2.3-2ea44f)                |\n| `formatDate`         | Formats dates as a month and year, \"today\" or \"yesterday\" can appear for recent dates | ![before](https://img.shields.io/badge/before-2019--01--01-cc6060)\u003cbr/\u003e![after](https://img.shields.io/badge/after-january%202019-2ea44f) |\n| `formatRelativeDate` | Formats a UNIX Timestamp in seconds as a relative time (eg. `3 days ago`)             | ![before](https://img.shields.io/badge/before-1655162563-cc6060)\u003cbr/\u003e![after](https://img.shields.io/badge/after-3%20days%20ago-2ea44f)   |\n\n## ⚙️ Other Parameters\n\n| Parameter      | Type      | Description                                                                                        |\n| -------------- | --------- | -------------------------------------------------------------------------------------------------- |\n| `url`          | `string`  | `required` The JSON, XML, or YAML data URL to fetch a message value from                           |\n| `query`        | `string`  | `required` The JSONPath or XPath query for extracting a field for the value                        |\n| `label`        | `string`  | `optional` The label to use for the badge, default: \"custom badge\"                                 |\n| `color`        | `string`  | `optional` The color to use for the badge, default: \"blue\"                                         |\n| `labelColor`   | `string`  | `optional` The color to use for the label, default: \"grey\"                                         |\n| `isError`      | `boolean` | `optional` If true, the badge color is overriden to be red, default: false                         |\n| `logo`         | `string`  | `optional` A named logo to use from Simple Icons or base64 encoded SVG, default: none              |\n| `namedLogo`    | `string`  | `optional` The name of a logo to use from Simple Icons, overrides `logo`, default: none            |\n| `logoSvg`      | `string`  | `optional` The base64 encoded SVG content of a logo to use, overrides `logo`, default: none        |\n| `logoColor`    | `string`  | `optional` The color to use for the logo, default: none                                            |\n| `logoWidth`    | `number`  | `optional` The width of the logo, default: none                                                    |\n| `logoPosition` | `number`  | `optional` The position offset of the logo, default: none                                          |\n| `style`        | `string`  | `optional` The badge style (plastic, flat, flat-square, for-the-badge, or social), default: \"flat\" |\n| `cacheSeconds` | `number`  | `optional` The number of seconds to cache the response, default: 300                               |\n| `prefix`       | `string`  | `optional` A prefix to use before the message, default: none                                       |\n| `suffix`       | `string`  | `optional` A suffix to use after the message, default: none                                        |\n| `formatter`    | `string`  | `optional` The name of a formatter to use on the message (see options above), default: none        |\n\n## 🤗 Contributing\n\nWe welcome contributions!\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## 📤 Deploying it on your own\n\n\u003cdetails\u003e\n  \u003csummary\u003eDeploy to Runkit\u003c/summary\u003e\n\n1. Sign in to **Runkit** or create a new account at \u003chttps://runkit.com\u003e\n2. Create a new notebook\n3. Paste the contents of [`index.js`](./runkit/index.js) into the notebook\n4. Click `endpoint` to get your endpoint to run requests against\n\n\u003c/details\u003e\n\n## 💬 Questions?\n\nFeel free to [open an issue](http://github.com/DenverCoder1/dynamic-badge-formatter/issues/new).\n\n## ❤️ Thanks\n\n- [Shields.io](https://github.com/badges/shields) for all the great work they have done with creating tools for creating Dynamic and Endpoint Badges\n\n## 📚 License\n\nThis project is licensed under the [MIT license](LICENSE.md).\n\nSome formatters make use of code written for [shields.io](https://shields.io/) in the [public domain](https://github.com/badges/shields/blob/master/LICENSE).\n\n## 🤩 Support\n\n💙 If you like this project, give it a ⭐ and share it with friends!\n\n\u003cp align=\"left\"\u003e\n  \u003ca href=\"https://www.youtube.com/channel/UCipSxT7a3rn81vGLw9lqRkg?sub_confirmation=1\"\u003e\u003cimg alt=\"Youtube\" title=\"Youtube\" src=\"https://custom-icon-badges.herokuapp.com/badge/-Subscribe-red?style=for-the-badge\u0026logo=video\u0026logoColor=white\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/sponsors/DenverCoder1\"\u003e\u003cimg alt=\"Sponsor with Github\" title=\"Sponsor with Github\" src=\"https://custom-icon-badges.herokuapp.com/badge/-Sponsor-ea4aaa?style=for-the-badge\u0026logo=heart\u0026logoColor=white\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n[☕ Buy me a coffee](https://ko-fi.com/jlawrence)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDenverCoder1%2Fdynamic-badge-formatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDenverCoder1%2Fdynamic-badge-formatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDenverCoder1%2Fdynamic-badge-formatter/lists"}