Generate and Sort Branded Shields.io and Badgen.net Badges by Color

This is a Python 3 command-line tool and GitHub Action automating the generation and color sorting of badges from Shields.io and Badgen.net that contain brand logos from Simple Icons.

🎨 Interactive Generator

New! Try the interactive web-based generator to visually configure and generate your BadgeSort YAML! No installation required - just select your badges, configure the options, and copy the generated GitHub Actions YAML.

Background:

Many awesome GitHub profiles contain a series of these badges to clearly indicate which tools, services, or other brands the user is affiliated with. These badge collections usually adopt the brand's color, icon, and name.

The problem:

Badge services like Shields.io and Badgen.net provide URLs for these badges that are normally handcrafted or copypasta.

For Shields.io, the format is: https://img.shields.io/badge/<URL_ENCODED_BRAND_NAME>-<BRAND_HEX_COLOR>.svg?style=<BADGE_STYLE>&logoColor=<TEXT_HEX_COLOR>&logo=<SIMPLE_ICONS_SLUG>

For Badgen.net, custom icons require base64-encoded SVG data: https://badgen.net/badge/icon/<BRAND_NAME>?icon=<BASE64_ENCODED_SVG>&label&color=<BRAND_HEX_COLOR>

Normally, the user must repeat the process of manually rendering this URL for each badge they wish to display. This is what the result of this work might look like:

Then, if the user is inclined, they may spend additional time ordering the badges by color to make their profile more visually appealing:

This is a time consuming process if performed manually; it is difficult to maintain, hard to keep consistent, and makes future adjustments offputting.

The solution:

This project automates the process of rendering out the badges into Markdown or HTML from a simple list of slugs.

The badges can be sorted by color [as default] or left in the order specified.

NoteThanks to this article by Alan Zucconi, the visually appealing color sort is achived using a Hilbert walk.

Setup Requirements:

Comment Markers for Badge Interpolation

When using BadgeSort to update a file (like README.md), BadgeSort will automatically manage special HTML comment markers to define where badges should appear.

How It Works:

If markers already exist:

• BadgeSort will replace everything between the markers with the newly generated badges
• The markers themselves are preserved and remain in your file

If markers don't exist:

• BadgeSort will automatically append the badges (with markers) to the end of your target file
• On subsequent runs, BadgeSort will update the badges in place

Marker Syntax:

<!-- start chipwolf/badgesort {id} --><!-- end chipwolf/badgesort {id} -->

• {id}: A unique identifier that matches the id parameter in your GitHub Action or CLI command
• If you don't specify an id, the default value is default

Default ID:

<!-- start chipwolf/badgesort default --><!-- end chipwolf/badgesort default -->

Multiple Badge Sections:

You can have multiple badge sections in the same file by using different IDs:

<!-- start chipwolf/badgesort section1 --><!-- end chipwolf/badgesort section1 -->
Some other content...
<!-- start chipwolf/badgesort section2 --><!-- end chipwolf/badgesort section2 -->

Note When targeting a file with -o or output:, BadgeSort will always update the file. If no markers exist for the specified ID, they will be automatically added to the end of the file. If you want badges printed to stdout instead, don't specify an output file.

Customizing Individual Badges:

BadgeSort allows you to customize individual badges using URL query string syntax. You can override the color, text, and hyperlink URL for any badge.

Syntax:

slug?param=value&param2=value2

Supported Parameters:

• color: Override the badge background color (hex color without #)
• text: Override the badge label text (use empty value text= to remove text)
• url: Add a custom hyperlink URL (for Markdown/HTML output)

Examples:

GitHub Action:

 - uses: docker://ghcr.io/chipwolf/badgesort:latestwith:
format: markdownid: customoutput: README.mdslugs: | osu?color=000000 github?text=ChipWolf&url=https://github.com/ChipWolf nodered?text= openseasort: hilbertstyle: for-the-badge

CLI:

$ python -m badgesort.icons -s \
"osu?color=000000" \
"github?text=ChipWolf&url=https://github.com/ChipWolf" \
"nodered?text=" \
opensea \
-o README.md

Required comment markers in README.md:

<!-- start chipwolf/badgesort custom --><!-- end chipwolf/badgesort custom -->

Note: The id value custom in the comment markers matches the id parameter in the GitHub Action (or the -i parameter in CLI).

Output:

Note Parameters are parsed using Python's standard urllib.parse library, following standard URL query string conventions.

Examples:

Generate five specific badges ordered by color:

GitHub Action:

 - uses: docker://ghcr.io/chipwolf/badgesort:latestwith:
format: markdown # defaultid: default # defaultoutput: README.mdslugs: | osu github americanexpress nodered openseasort: hilbert # defaultstyle: for-the-badge # default

CLI:

$ python -m badgesort.icons -s osu github americanexpress nodered opensea -o README.md

Required comment markers in README.md:

<!-- start chipwolf/badgesort default --><!-- end chipwolf/badgesort default -->

Note: The id value default in the comment markers matches the id parameter in the GitHub Action (or the default when not specified in CLI).

Output:

---

Generate five random badges:

GitHub Action:

 - uses: docker://ghcr.io/chipwolf/badgesort:latestwith:
id: foobarformat: htmloutput: README.mdrandom: 5sort: falsestyle: flat-square

CLI:

$ python -m badgesort.icons -i foobar -c false -r 5 -f html -b flat-square -o README.md

Required comment markers in README.md:

<!-- start chipwolf/badgesort foobar --><!-- end chipwolf/badgesort foobar -->

Note: The custom id value foobar must match in both the GitHub Action input (or CLI -i parameter) and the comment markers.

Output:

---

Generate badges from a list of slugs, sorting using an inverted step algorithm:

GitHub Action:

 - uses: docker://ghcr.io/chipwolf/badgesort:latestwith:
args: | --hue-rotate 240id: exampleformat: htmloutput: README.mdsort: step_invertstyle: flatslugs: | angular,apollographql,brave,d3dotjs,docker git,githubactions,googlecloud,graphql,heroku html5,insomnia,mongodb,nestjs,nodedotjs npm,prettier,react,reactivex,redux rollupdotjs,sass,styledcomponents,typescript,webpack

CLI:

$ python -m badgesort.icons -i example -c step_invert -o README.md -f html -b flat --hue-rotate 240 -s \
angular,apollographql,brave,d3dotjs,docker, \
git,githubactions,googlecloud,graphql,heroku, \
html5,insomnia,mongodb,nestjs,nodedotjs, \
npm,prettier,react,reactivex,redux, \
rollupdotjs,sass,styledcomponents,typescript,webpack

Required comment markers in README.md:

<!-- start chipwolf/badgesort example --><!-- end chipwolf/badgesort example -->

Output:

---

Generate badges with Badgen.net:

GitHub Action:

 - uses: docker://ghcr.io/chipwolf/badgesort:latestwith:
id: badgen-exampleformat: markdownoutput: README.mdprovider: badgenslugs: | github python docker oxygensort: hilbert

CLI:

$ python -m badgesort.icons -p badgen -s github python docker oxygen

Note on Badgen Icon Visibility

Unlike Shields.io, Badgen.net doesn't support black text on badges, only white text on colored backgrounds. To ensure icon visibility on bright brand colors, BadgeSort automatically adjusts very bright icons:

• Bright icons (brightness > 0.7): Scaled down to brightness of 0.7 for optimal visibility

This preserves the icon's hue and saturation while ensuring it remains visible against bright brand color backgrounds.

Output: