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.

Note Thanks 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:latest
        with:
          format: markdown
          id: custom
          output: README.md
          slugs: |
            osu?color=000000
            github?text=ChipWolf&url=https://github.com/ChipWolf
            nodered?text=
            opensea
          sort: hilbert
          style: 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:latest
        with:
          format: markdown # default
          id: default # default
          output: README.md
          slugs: |
            osu
            github
            americanexpress
            nodered
            opensea
          sort: hilbert # default
          style: 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:latest
        with:
          id: foobar
          format: html
          output: README.md
          random: 5
          sort: false
          style: 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:latest
        with:
          args: |
            --hue-rotate 240
          id: example
          format: html
          output: README.md
          sort: step_invert
          style: flat
          slugs: |
            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:latest
        with:
          id: badgen-example
          format: markdown
          output: README.md
          provider: badgen
          slugs: |
            github
            python
            docker
            oxygen
          sort: 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: