{"id":19764089,"url":"https://github.com/rikonardo/catbadge","last_synced_at":"2025-08-14T18:44:54.574Z","repository":{"id":122886290,"uuid":"504799544","full_name":"Rikonardo/CatBadge","owner":"Rikonardo","description":"Selfhosted lightweight custom badges generator. Good engine for your own badges. SVG, PNG and WEBP formats supported!","archived":false,"fork":false,"pushed_at":"2022-06-18T09:52:32.000Z","size":228,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-05T15:39:19.137Z","etag":null,"topics":["badge-generator","kotlin","rendering","shields"],"latest_commit_sha":null,"homepage":"https://cat.rikonardo.com","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rikonardo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-18T09:29:51.000Z","updated_at":"2022-09-13T19:23:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"3b6458b3-c5d0-4817-bae0-ee8d86f12968","html_url":"https://github.com/Rikonardo/CatBadge","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Rikonardo/CatBadge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rikonardo%2FCatBadge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rikonardo%2FCatBadge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rikonardo%2FCatBadge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rikonardo%2FCatBadge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rikonardo","download_url":"https://codeload.github.com/Rikonardo/CatBadge/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rikonardo%2FCatBadge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270466805,"owners_count":24588793,"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","status":"online","status_checked_at":"2025-08-14T02:00:10.309Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","kotlin","rendering","shields"],"created_at":"2024-11-12T04:12:20.130Z","updated_at":"2025-08-14T18:44:54.483Z","avatar_url":"https://github.com/Rikonardo.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CatBadge ✨\nA selfhosted lightweight custom badges generator, powered by catboys cuteness 😻\n\n[![Live Example](https://cat.rikonardo.com/builtin/static/CLICK_TO_VISIT-EXAMPLE_SITE_?style=large-square)](https://cat.rikonardo.com)\n\n**Note, that CatBadge is just an engine and doesn't include any badges except static one by default. In order to add custom dynamic badges, you need to write an extension. For example, [this is my extension](https://github.com/Rikonardo/MyCatBadges).**\n\n[How to make an extension?](#developing-extension)\n\n## Formats\nCatBadge supports **svg**, **webp** and **png** formats out of the box:\n\n| Format | URL param      | Example                                                                               |\n|--------|----------------|---------------------------------------------------------------------------------------|\n| SVG    | `?format=svg`  | ![SVG example](https://cat.rikonardo.com/builtin/static/mutiple-formats?format=svg)   |\n| WEBP   | `?format=webp` | ![WebP example](https://cat.rikonardo.com/builtin/static/mutiple-formats?format=webp) |\n| PNG    | `?format=png`  | ![PNG example](https://cat.rikonardo.com/builtin/static/mutiple-formats?format=png)   |\n\nThis can be useful when SVG format not supported by website. By default, CatBadge uses SVG format.\n\n## Styles\nCatBadge supports three styles inspired by [shields.io](https://shields.io/):\n\n| Theme        | URL param             | Example                                                                                     |\n|--------------|-----------------------|---------------------------------------------------------------------------------------------|\n| Flat         | `?style=flat`         | ![Flat](https://cat.rikonardo.com/builtin/static/mutiple-styles?style=flat)                 |\n| Flat Square  | `?style=flat-square`  | ![Flat Square](https://cat.rikonardo.com/builtin/static/mutiple-styles?style=flat-square)   |\n| Large Square | `?style=large-square` | ![Large Square](https://cat.rikonardo.com/builtin/static/mutiple-styles?style=large-square) |\n\n## Icon\nCatBadge allows to set icon from base64 encoded image via ``?icon=data:image/png;base64,iVBORw0KGg...`` parameter.\n\nIf badge serves icon by default, you can remove it by adding empty icon param (`?icon=`).\n\nIf badge has no label, icon will be placed in the message section.\n\n![Icon Example](https://cat.rikonardo.com/builtin/static/cat-icon?icon=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAAbgAAAG4BI+U+pwAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAAGvSURBVDiNnZA9axRRFIafc2fGRdyPmWww2Q/SqqmE4G7QQH6ArYVgJQQ7BX+GlaBYueAIpogk/gdBkCRsYSFikRQirolNdtysJvNxLCbuR0YWzOnOc+773HOvqM8O8AXlLQ4t7uhXJtWq1AlZQVgG5kR9esCFk3EItAh4yH09Ggs+lRxFHgMrgHNCD0V9OsDs2GGRLQr5NxiZR0mI4o/86t8i0eapfb7bQG/Q2jbMXIRioUE3aPCtk/JaFebqcNCF/R8Qx38TvaHALcHsDBjDoI+itC8VU+a5UCxAZw+CYCD4ST4P1Ur2w6bLWWZZUKuk8n6/Z8jlYmr/CE8qEahXwXFCQ9krY1mD2bNXUzxf8zKZJy/L+BvuENg2THklg1sK/u/6kXK9fdGty7+B3BkVewY4PvMG6LENrAN3R3H/UR49MGNHTSXm/IPDU3lZN0ALiEe5s5RdyrmRYSEWL0RVYfvKMrAK1ABIIHx3juiDAxbYV0Oc62OCXUhuc+3zdioAaF+aRo2PcnPyu+U15ugeCztdgKEgHQrt+QZJvIhKE2ERiEA2Ed0k5j3NT+1R3R/Kw4h8lIQ4mgAAAABJRU5ErkJggg==) ![Icon Example](https://cat.rikonardo.com/builtin/static/-cat_icon?icon=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAAbgAAAG4BI+U+pwAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAAGvSURBVDiNnZA9axRRFIafc2fGRdyPmWww2Q/SqqmE4G7QQH6ArYVgJQQ7BX+GlaBYueAIpogk/gdBkCRsYSFikRQirolNdtysJvNxLCbuR0YWzOnOc+773HOvqM8O8AXlLQ4t7uhXJtWq1AlZQVgG5kR9esCFk3EItAh4yH09Ggs+lRxFHgMrgHNCD0V9OsDs2GGRLQr5NxiZR0mI4o/86t8i0eapfb7bQG/Q2jbMXIRioUE3aPCtk/JaFebqcNCF/R8Qx38TvaHALcHsDBjDoI+itC8VU+a5UCxAZw+CYCD4ST4P1Ur2w6bLWWZZUKuk8n6/Z8jlYmr/CE8qEahXwXFCQ9krY1mD2bNXUzxf8zKZJy/L+BvuENg2THklg1sK/u/6kXK9fdGty7+B3BkVewY4PvMG6LENrAN3R3H/UR49MGNHTSXm/IPDU3lZN0ALiEe5s5RdyrmRYSEWL0RVYfvKMrAK1ABIIHx3juiDAxbYV0Oc62OCXUhuc+3zdioAaF+aRo2PcnPyu+U15ugeCztdgKEgHQrt+QZJvIhKE2ERiEA2Ed0k5j3NT+1R3R/Kw4h8lIQ4mgAAAABJRU5ErkJggg==)\n\n## Color overriding\nYou can override colors for any badge.\n\n| URL params                                      | Example                                                                                                           |\n|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|\n| `?labelColor=FFFFFF`                            | ![Example](https://cat.rikonardo.com/builtin/static/color-overriding?labelColor=FFFFFF)                           |\n| `?labelColor=FFFFFF\u0026labelTextColor=2288EE`      | ![Example](https://cat.rikonardo.com/builtin/static/color-overriding?labelColor=FFFFFF\u0026labelTextColor=2288EE)     |\n| `?messageColor=111111`                          | ![Example](https://cat.rikonardo.com/builtin/static/color-overriding?messageColor=111111)                         |\n| `?\u0026messageColor=111111\u0026messageTextColor=22BBEE` | ![Example](https://cat.rikonardo.com/builtin/static/color-overriding?messageColor=111111\u0026messageTextColor=22BBEE) |\n\nCatBadge also has same pre-defined colors as [shields.io](https://shields.io/#colors) (brightgreen, green, yellowgreen, yellow, orange, red, blue, lightgrey, success, important, critical, informational, inactive).\n\n## Developing Extension\nAs I said, CatBadge doesn't include any dynamic badges by default, so you need to make extension yourself.\n\nTo make an extension, create empty Kotlin/JVM project.\n\nTo start, we gonna add CatBadge api as compile-time dependency.\n\n```kotlin\nrepositories {\n    maven {\n        url = uri(\"https://maven.rikonardo.com/releases\")\n    }\n}\n\ndependencies {\n    compileOnly(\"com.rikonardo.catbadge:badge-api:1.0.0\")\n}\n```\n\nIf you are new to Kotlin, I highly recommend using [Yok](https://github.com/Virefire/Yok) HTTP request library to make API requests. So we gonna add it and KSON json parsing library as runtime dependencies.\n\n```kotlin\ndependencies {\n    implementation(\"dev.virefire.yok:Yok:1.0.4\")\n    implementation(\"dev.virefire.kson:KSON:1.3.1\")\n}\n```\n\nBecause we are using some libraries, let's install Gradle Shadow plugin to include them in our extension jar.\n\n```kotlin\nplugins {\n    id(\"com.github.johnrengelman.shadow\") version \"7.1.2\"\n}\n\ntasks.build {\n    dependsOn(tasks.getByName(\"shadowJar\")) // Autorun shadowJar on build\n}\n\ntasks.withType\u003ccom.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar\u003e {\n    archiveClassifier.set(\"\") // Replace our common jar with a bundled one\n}\n```\n\nNow, let's create a Kotlin class, representing our badge. It must implement `BadgeProvider` interface and have the `@RegisterBadge` annotation.\n\n```kotlin\n@RegisterBadge(\n    category = \"My Badges\",\n    name = \"My Badge\",\n    description = \"It's my awesome badge\",\n)\nclass MyBadge : BadgeProvider {\n    override fun make(): Badge {\n        return Badge(\n            label = \"hello\",\n            message = \"world\",\n        )\n    }\n}\n```\n\nWe can also accept parameters by adding variable class field with `@BadgeProperty` annotation. You can add as many properties as you want.\n\n```kotlin\nclass MyBadge : BadgeProvider {\n    @BadgeProperty(\"name\") lateinit var name: String\n    \n    override fun make(): Badge {\n        return Badge(\n            label = \"hello\",\n            message = name,\n        )\n    }\n}\n```\n\nAnd here is an example of badge that displays current time in Amsterdam:\n\n```kotlin\n@RegisterBadge(\n    category = \"My Badges\",\n    name = \"Time In Amsterdam\",\n    description = \"Display current time in Amsterdam\",\n)\nclass TimeInAmsterdam : BadgeProvider {\n    override fun make(): Badge {\n        val res = Yok.get(\"https://timeapi.io/api/Time/current/zone?timeZone=Europe/Amsterdam\")\n        return Badge(\n            label = \"time\",\n            message = res.body.json[\"time\"].string!!,\n        )\n    }\n}\n```\n\nTo install your extension, simply place it in the \"extensions\" directory located in the folder where your CatBadge instance is running. Extension does not require any configuration or manifest to work.\n\n---\n\n\u003e P.S. Cat icon form [Icon](#icon) example created by [Pixel perfect](https://www.flaticon.com/free-icon/cat_725058).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frikonardo%2Fcatbadge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frikonardo%2Fcatbadge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frikonardo%2Fcatbadge/lists"}