🦡 Badger - Custom Badges Made Easy 🌈

🚀 Introduction

Ever felt the need to spice up your GitHub README with cool badges, but found it too tedious? Want to personalize your badges to showcase your style? Badger is here to the rescue! 🎉

Badger is a Python CLI tool that allows you to generate custom badges for your GitHub README or any other markdown files. With a simple command, you can create, manage, and insert badges like a pro. 🌟

🌟 Features

Create badges with custom text, colors, and logos 🎨
Save badge configurations for future use 📂
Generate badges on-the-fly and copy them to clipboard 📋
List, delete, and manage your badges effortlessly 🛠

📦 Installation

Installing Badger is as simple as pie:

git clone https://github.com/voxel51/badger.git
cd badger
pip install -e .

If you want to use Badger with SVGs hosted on the web, you will need to install requests. Change the last line to:

pip install -e ".[web]"

If you want to use the badger go-wild command, you will need to install openai. Change the last line to:

pip install -e ".[wild]"

And make sure to set your OpenAI API key as an environment variable:

export OPENAI_API_KEY=<YOUR_API_KEY>

To install both, change the last line to:

pip install -e ".[web,wild]"

📝 Usage

Here's how you can use Badger:

🏗️ Create a New Badge

badger create badge_name

This will walk you through a series of prompts to customize your badge.

badger create voxel51_ada

Begins the process of creating an ADA compliant badge for Voxel51 named voxel51_ada:


> [REQUIRED] Enter a name for this badge: voxel51_ada

> [OPTIONAL] Enter the badge text: voxel51

Commonly used colors:
1. brightgreen
2. green
3. yellowgreen
4. yellow
5. orange
6. red
7. blue
8. lightgrey
9. success
10. important
11. critical
12. informational
13. inactive

> [OPTIONAL] Enter the color of the badge (or choose a number from the list above): blue

> [REQUIRED] Enter the badge logo: https://gist.githubusercontent.com/jacobmarks/eb18cc90596f7310e4dad1be2526c070/raw/e05e51be697a9501f64fe8d1b7008fc5ebe56369/fiftyone_icon.svg

> [REQUIRED] Enter the badge URL: https://github.com/voxel51/fiftyone

> [OPTIONAL] Enter the badge style: flat

> [OPTIONAL] Enter the badge logoColor: white

> [OPTIONAL] Enter the badge label:

> [OPTIONAL] Enter the badge labelColor:

> [OPTIONAL] Enter the badge logoWidth:

> Successfully added badge 'voxel51_ada'.

💡 As show in this example, you can create a badge from an SVG at a URL! If you do so, the content of the SVG will be retrieved at badge generation time using requests. You can also use local SVGs by specifying the relative or absolute path to the SVG file.

💡 Simple Mode

You can also create a badge in simple mode by passing the --simple flag:

badger create --simple --badge_name simple_badge --logo assets/fiftyone.svg --url https://github.com/voxel51/fiftyone --text FiftyOne

This will bypass the optional prompts and create a badge with the specified parameters. The --simple flag can be used anywhere in the command, before or after the create command.

If you find yourself wanting to use this mode often, you can create an alias for it:

alias badgers="badger create --simple"

📋 Copy a Badge to Clipboard

badger copy badge_name

This copies the badge markdown to your clipboard. Paste it wherever you like!

For instance, we can copy the badge we just created:

badger copy voxel51_ada

🖨️ Print a Badge Markdown

badger print badge_name

Prints the badge markdown to the terminal.

📂 List All Badges

badger list

Lists all the badges you have created.

Available badges:
Badge Name           URL                                                Color                Text
--------------------------------------------------------------------------------------------------------------
badger               https://github.com/voxel51/badger                  blue                 Badger
voxel51              https://github.com/voxel51/fiftyone                blue                 voxel51
voxel51_ada          https://github.com/voxel51/fiftyone                blue                 voxel51
svg-repo-atom        https://www.svgrepo.com/svg/530661/genetic-data    grey                 Atom

🗑️ Delete a Badge

badger delete badge_name

Deletes the badge from your config file.

🪞 Clone a Badge

badger clone badge_name new_badge_name

Clones the badge with the name badge_name and saves it with the name new_badge_name.

🖋️ Edit a Badge

badger edit badge_name --color success

Edits the badge with the name badge_name and sets the color to success.

ℹ️ Get Info About a Badge

badger info badge_name

Prints information about the badge with the name badge_name.

Badge: badger
--------------------------------------------------------------------------------------------------------------
URL: https://github.com/voxel51/badger
Color: blue
Text: Badger
Logo: /Users/jacobmarks/Desktop/work/badger/assets/badger.svg
Style: flat
Label: N/A
Label Color: grey
Logo Width: N/A
Logo Color: white

✨ Go Wild!

badger go-wild

Generates a random badge using AI and copies it to your clipboard. 🤪 This takes a --prompt argument that allows you to specify the prompt to use for generating the badge.

For example:

badger go-wild --prompt turtle

Creates a trial badge for the turtle prompt.

You can then save the badge to your config file by entering y when prompted and follow the instructions to save the badge.

And:

badger go-wild --prompt flamingo

💡 This uses your OpenAI API Key to call GPT 4

❓ Get Help

badger help

Prints the help message.

🎨 Customization

Custom Colors
Custom Logos
Custom Text
Custom Styles
... and much more! 🌈

Once you have created a badge (added it to your config), you can work with modified versions of that badge incredibly easily using the following command line arguments, which can be passed along with the copy and print commands:

--logo: The logo color of the badge
--url: The URL the badge points to
--style: The style of the badge
--color: The color of the badge
--text: The text of the badge
--label: The label of the badge
--labelColor: The label color of the badge
--logoColor: The logo color of the badge
--logoWidth: The logo width of the badge

Editing the Config File

You can also edit the config file directly to customize your badges. The config file is located at ~/.badger/config.yaml and has the following format:

badges:
  badger:
    color: blue
    labelColor: grey
    logo: /Users/jacobmarks/Desktop/work/badger/assets/badger.svg
    logoColor: white
    style: flat
    text: Badger
    url: https://github.com/voxel51/badger
  voxel51:
    color: blue
    logo: https://gist.githubusercontent.com/jacobmarks/eb18cc90596f7310e4dad1be2526c070/raw/e05e51be697a9501f64fe8d1b7008fc5ebe56369/fiftyone_icon.svg
    text: voxel51
    url: https://github.com/voxel51/fiftyone
  voxel51_ada:
    color: blue
    logo: /Users/jacobmarks/Desktop/work/badger/assets/fiftyone.svg
    logoColor: white
    text: voxel51
    url: https://github.com/voxel51/fiftyone
  svg-repo-atom:
    color: grey
    labelColor: blue
    logo: https://www.svgrepo.com/download/530661/genetic-data.svg
    logoColor: white
    text: Atom
    url: https://www.svgrepo.com/svg/530661/genetic-data
    style: plastic

You can add, remove, and edit badges as you see fit. Badger will automatically detect changes to the config file and update your badges accordingly.

💡 You can also set the location of the config file in your environment variables using the BADGER_CONFIG_DIR variable.

Where to Get Badges

If you're looking for some cool badges to use, check out these resources:

Free-to-Use SVGs

Because Badger supports copying and printing badges with SVGs at URLs, you can use any of the above resources to generate badges on-the-fly! 🎉

Just click into the SVG you want to use, copy the URL, and use it as the logo argument when creating a badge.

Here's an example from SVG Repo with this SVG:

badges:
  ...
  svg-repo-atom:
    color: grey
    logo: https://www.svgrepo.com/download/530661/genetic-data.svg
    logoColor: white
    text: Atom
    url: https://www.svgrepo.com/svg/530661/genetic-data
    style: for-the-badge
  ...

With this in your Badger config file, running badger copy svg-repo-atom will copy the following badge to your clipboard:

Simplifying SVGs

Occassionally, you may find that the SVG you want to use is too complex for shields.io or Github's rendering handle. In this case, you can simplify the SVG using the SVG optimizer SVGO.

You can install SVGO using:

npm install -g svgo

And then simplify your SVG using:

svgo -i input.svg -o output.svg

💡 Why You Absolutely Need This

Saves Time: No need to manually write markdown or HTML for badges. 🕒
Be Unique: Stand out from the crowd with personalized badges. 🦄
Stay Organized: Keep all your badges in one place, ready to be used anytime. 🗂
It's Cool: Because let's face it, who doesn't like badges? 😎

Acknowledgements

Huge shout out to Rustem Galiullin and Kishan Savant for beta-testing the tool and providing valuable feedback!

Shields.io for the awesome badges