Badger: Custom GitHub Badges Made Easy

Create and Manage Your Badges from the Command Line

Back in June, inspired by paperswithcode.com my team and I created PapersWithData to emphasize the role that data plays in pushing the boundaries in machine learning and computer vision. To get this project off the ground, we worked together with the authors of a dozen datasets to convert their datasets into a common format and make them publicly browsable. 

Here’s a screenshot of one of the tables from the original GitHub README:

Data wrangling can be a notoriously frustrating process. Yet the most frustrating part of the entire project, by far, was creating the custom FiftyOne GitHub badges — the tiny buttons with the Voxel51 icon and text “FiftyOne”, each of which pointed to a different URL:

Although we bootstrapped the project with our classic orange and gray Voxel51 logo mark, we knew we wanted to quickly move to an ADA compliant color scheme. Just making this minor change – setting the color of the logo — was also frustrating!

To create these badges, we used Shields.io, a flexible framework for creating a variety of standard and custom badges. Shields.io supports a ton of named logos like GitHub, Discord, and Node.js (see a complete list here), as well as custom logos.

However, to use a custom logo like the icon for your company or project, you need to convert the SVG into base64. Every time you want to reuse the same badge, you need to dig through your old projects to find the Markdown code. And every time you want to make a slight modification to an existing badge, you need to remember the Shields.io syntax to do so.

To solve these problems, and more, I built Badger!

Badger is an open source Python library that allows you to create, edit, store, and manage custom badges, all from the command line. 

In this post, I share the basics of how to get up and running with Badger to create the GitHub badge of your dreams. With that, here is just a small subset of what you can do with Badger – and if it sounds interesting to you, I invite you to give it a try!

Badge Management with Badger

🔨 Creating Badges

Badger makes badge creation a breeze, walking you through the entire process.

You can run Badger create to begin the badge creation process — in which case the first detail you will be prompted for is a “name” for the badge — or you can specify the name of the new badge in the command. 

Badges can be created from either local SVGs, or remotely hosted SVG files. The latter can be useful if you want to work with an SVG stored in a GitHub gist, or on some public server. Badger uses Python’s requests library to get the raw data from the SVG at Markdown generation time, so you never need to store it locally.

Let’s see an example of each.

First, let’s create a FiftyOne badge (way more easily than we did initially with PapersWithData!):

In this example, we passed a local (relative in this case) path to the logo file, and in the initial command we told Badger to name the badge “fiftyone”. Also notice that we left some attributes blank. Not every attribute is required to create a badge! This badge is perfectly usable as is.

Now, let’s create a badge from an SVG at a remote URL (hosted by SVG Repo):

This creates the following badge:

🖨️ Printing Badges

Once you have a badge saved in your Badger config, you can print the formatted Markdown to stdout, or directly into a Markdown file of your choice:

📋 Copying Badges to the Clipboard

When you’re working in a Jupyter notebook, you can save the trouble of manually selecting and copying the outputs of a print statement in order to enter into a Markdown cell. Badger’s copy command uses the pyperclip Python library to copy the Markdown for the badge to your clipboard — you can just paste the result directly into a Markdown cell:

💡You can override any of a badge’s default attributes at print/copy time — even the logo file and the URL the badge points to!

📂 Listing Your Badges

Where would we be without a way to keep track of all of the awesome badges we’ve created? Luckily, the Badger list command gives us a formatted list of all of the badges in our config:

If you want detailed information about a single badge, you can use the badger info <badge-name> command:

🪞 Cloning Badges

Badger also makes it incredibly easy to save different variations of the same basic badge via the badger clone command. Pass the name of the original badge, the name of the new badge, and optionally any differences you want to be reflected in the new badge.

For instance, to create the ADA compliant version of the voxel51 badge, we can run:

badger clone voxel51 voxel51_ada --logoColor white

This will save a new voxel51_ada badge to our badger config, with a white logo. It’s that simple!

🖋️ Editing and Deleting Badges

If you want to edit a badge’s configuration — suppose you want to make plastic the new default style for your villa badge — you can do so with Badger’s badger edit command:

badger edit villa --style plastic

You can also delete a badge from your Badger config file with badger delete <badge-name>

To delete this `villa` badge, you would run:

badger delete villa

✨ Going Wild with AI-Generated Badges

Just for fun, I’ve added a badger go-wild command, which will use GPT-4 (with some light prompt engineering and validation) to create a new SVG for you to use in your badges. If you use the command without a prompt, it will generate a completely random SVG, but you can also specify what the subject of the SVG should be with the --prompt argument, followed by the desired subject. For instance, to generate a turtle SVG, run the following command:

badger go-wild --prompt turtle

The SVGs are basic, when they even work, but it’s fun! Creating a high-quality SVG generating model is a project for another day 🐢.

Installation

To install Badger, run the following commands in your terminal:

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

If you want to put your Badger config file in a custom location, you can set this with the BADGER_CONFIG_FILE environment variable:

export BADGER_CONFIG_FILE=<path/to/config>

If you want to use the badger go-wild command to generate some (rudimentary) custom badges with GPT-4, you must have an OpenAI account set up, and the OPENAI_API_KEY environment variable set.

export OPENAI_API_KEY=<your-key>

That’s it!

Conclusion

Badger is the library you didn’t know you needed. It is lightweight, incredibly easy to use, and will save you a lot of trouble. Go forth and make custom badges for all of your GitHub projects, large and small!

https://github.com/voxel51/badger

🚀Not to BADGER you, but if you like Badger, check out some of our other open source projects, which will make your life easier:

• 5️⃣1️⃣FiftyOne: The Leading Library for Data Curation and Visualization
• 🤖⌨️VoxelGPT: Your AI Assistant for Computer Vision
• 📚🔍DocSearch: Turn Your Docs into a Searchable Repo
• 🧩🔌FiftyOne Plugins: Build Custom Machine Learning Applications in Minutes