https://github.com/rikonardo/catbadge
Selfhosted lightweight custom badges generator. Good engine for your own badges. SVG, PNG and WEBP formats supported!
https://github.com/rikonardo/catbadge
badge-generator kotlin rendering shields
Last synced: 2 months ago
JSON representation
Selfhosted lightweight custom badges generator. Good engine for your own badges. SVG, PNG and WEBP formats supported!
- Host: GitHub
- URL: https://github.com/rikonardo/catbadge
- Owner: Rikonardo
- Created: 2022-06-18T09:29:51.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2022-06-18T09:52:32.000Z (over 3 years ago)
- Last Synced: 2025-08-05T15:39:19.137Z (2 months ago)
- Topics: badge-generator, kotlin, rendering, shields
- Language: Kotlin
- Homepage: https://cat.rikonardo.com
- Size: 223 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# CatBadge ✨
A selfhosted lightweight custom badges generator, powered by catboys cuteness 😻
[](https://cat.rikonardo.com)
**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).**
[How to make an extension?](#developing-extension)
## Formats
CatBadge supports **svg**, **webp** and **png** formats out of the box:
| Format | URL param | Example |
|--------|----------------|---------------------------------------------------------------------------------------|
| SVG | `?format=svg` |  |
| WEBP | `?format=webp` |  |
| PNG | `?format=png` |  |
This can be useful when SVG format not supported by website. By default, CatBadge uses SVG format.
## Styles
CatBadge supports three styles inspired by [shields.io](https://shields.io/):
| Theme | URL param | Example |
|--------------|-----------------------|---------------------------------------------------------------------------------------------|
| Flat | `?style=flat` |  |
| Flat Square | `?style=flat-square` |  |
| Large Square | `?style=large-square` |  |
## Icon
CatBadge allows to set icon from base64 encoded image via ``?icon=data:image/png;base64,iVBORw0KGg...`` parameter.
If badge serves icon by default, you can remove it by adding empty icon param (`?icon=`).
If badge has no label, icon will be placed in the message section.
 
## Color overriding
You can override colors for any badge.
| URL params | Example |
|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
| `?labelColor=FFFFFF` |  |
| `?labelColor=FFFFFF&labelTextColor=2288EE` |  |
| `?messageColor=111111` |  |
| `?&messageColor=111111&messageTextColor=22BBEE` |  |
CatBadge 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).
## Developing Extension
As I said, CatBadge doesn't include any dynamic badges by default, so you need to make extension yourself.
To make an extension, create empty Kotlin/JVM project.
To start, we gonna add CatBadge api as compile-time dependency.
```kotlin
repositories {
maven {
url = uri("https://maven.rikonardo.com/releases")
}
}
dependencies {
compileOnly("com.rikonardo.catbadge:badge-api:1.0.0")
}
```
If 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.
```kotlin
dependencies {
implementation("dev.virefire.yok:Yok:1.0.4")
implementation("dev.virefire.kson:KSON:1.3.1")
}
```
Because we are using some libraries, let's install Gradle Shadow plugin to include them in our extension jar.
```kotlin
plugins {
id("com.github.johnrengelman.shadow") version "7.1.2"
}
tasks.build {
dependsOn(tasks.getByName("shadowJar")) // Autorun shadowJar on build
}
tasks.withType {
archiveClassifier.set("") // Replace our common jar with a bundled one
}
```
Now, let's create a Kotlin class, representing our badge. It must implement `BadgeProvider` interface and have the `@RegisterBadge` annotation.
```kotlin
@RegisterBadge(
category = "My Badges",
name = "My Badge",
description = "It's my awesome badge",
)
class MyBadge : BadgeProvider {
override fun make(): Badge {
return Badge(
label = "hello",
message = "world",
)
}
}
```
We can also accept parameters by adding variable class field with `@BadgeProperty` annotation. You can add as many properties as you want.
```kotlin
class MyBadge : BadgeProvider {
@BadgeProperty("name") lateinit var name: String
override fun make(): Badge {
return Badge(
label = "hello",
message = name,
)
}
}
```
And here is an example of badge that displays current time in Amsterdam:
```kotlin
@RegisterBadge(
category = "My Badges",
name = "Time In Amsterdam",
description = "Display current time in Amsterdam",
)
class TimeInAmsterdam : BadgeProvider {
override fun make(): Badge {
val res = Yok.get("https://timeapi.io/api/Time/current/zone?timeZone=Europe/Amsterdam")
return Badge(
label = "time",
message = res.body.json["time"].string!!,
)
}
}
```
To 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.
---
> P.S. Cat icon form [Icon](#icon) example created by [Pixel perfect](https://www.flaticon.com/free-icon/cat_725058).