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.
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.
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.
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.
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.
When using BadgeSort to update a file (like README.md), you must include special HTML comment markers in your target file. These markers tell BadgeSort where to insert or update the badges.
<!-- start chipwolf/badgesort {id} -->
<!-- end chipwolf/badgesort {id} -->{id}: A unique identifier that matches theidparameter in your GitHub Action or CLI command- BadgeSort will replace everything between these markers with the generated badges
- The markers themselves are preserved and remain in your file
If you don't specify an id, the default value is default:
<!-- start chipwolf/badgesort default -->
[](https://github.com/ChipWolf/BadgeSort)
<!-- end chipwolf/badgesort default -->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 -->Important Without these comment markers in your target file, BadgeSort will only output badges to stdout (or the console) rather than updating the file.
- 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$ python -m badgesort.icons -s osu github americanexpress nodered opensea -o README.md<!-- start chipwolf/badgesort default -->
[](https://github.com/ChipWolf/BadgeSort)
<!-- end chipwolf/badgesort default -->Note: The
idvaluedefaultin the comment markers matches theidparameter in the GitHub Action (or the default when not specified in CLI).
- uses: docker://ghcr.io/chipwolf/badgesort:latest
with:
id: foobar
format: html
output: README.md
random: 5
sort: false
style: flat-square$ python -m badgesort.icons -i foobar -c false -r 5 -f html -b flat-square -o README.md<!-- start chipwolf/badgesort foobar -->
<p>
<a href="#"><img alt="Aeroflot" src="https://img.shields.io/badge/Aeroflot-02458D.svg?style=flat-square&logo=aeroflot&logoColor=white"></a>
<a href="#"><img alt="Dropbox" src="https://img.shields.io/badge/Dropbox-0061FF.svg?style=flat-square&logo=dropbox&logoColor=white"></a>
<a href="#"><img alt="OpenCV" src="https://img.shields.io/badge/OpenCV-5C3EE8.svg?style=flat-square&logo=opencv&logoColor=white"></a>
<a href="#"><img alt="OpenGL" src="https://img.shields.io/badge/OpenGL-5586A4.svg?style=flat-square&logo=opengl&logoColor=white"></a>
<a href="#"><img alt="MSI" src="https://img.shields.io/badge/MSI-FF0000.svg?style=flat-square&logo=msi&logoColor=white"></a>
<a href="https://github.com/ChipWolf/BadgeSort"><img alt="BadgeSort" src="https://img.shields.io/badge/BadgeSort-000000.svg?style=flat-square&logo=githubsponsors"></a>
</p>
<!-- end chipwolf/badgesort foobar -->Note: The custom
idvaluefoobarmust match in both the GitHub Action input (or CLI-iparameter) and the comment markers.
- 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$ 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<!-- start chipwolf/badgesort example -->
<p>
<a href="#"><img alt="D3.js" src="https://img.shields.io/badge/D3.js-F9A03C.svg?style=flat&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyByb2xlPSJpbWciIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTMuMzEyIDEyQzEzLjMxMiA1LjcxOCA4LjIyLjYyNSAxLjkzNy42MjVIMHY1aDEuOTM4YzMuNTIxIDAgNi4zNzUgMi44NTQgNi4zNzUgNi4zNzVzLTIuODU0IDYuMzc1LTYuMzc1IDYuMzc1SDB2NWgxLjkzOGM2LjI4MSAwIDExLjM3NC01LjA5MyAxMS4zNzQtMTEuMzc1ek0yNCA3LjU2M0MyNCAzLjczMSAyMC44OTMuNjI1IDE3LjA2Mi42MjVoLThhMTMuNDE1NCAxMy40MTU0IDAgMCAxIDQuNjg2IDVoMy4zMTRjMS4wNjkgMCAxLjkzOC44NjggMS45MzggMS45MzggMCAxLjA3LS44NjkgMS45MzgtMS45MzggMS45MzhoLTEuOTM4Yy4zMTMgMS42NTIuMzEzIDMuMzQ4IDAgNWgxLjkzOGMxLjA2OCAwIDEuOTM4Ljg2NyAxLjkzOCAxLjkzOHMtLjg2OSAxLjkzOC0xLjkzOCAxLjkzOGgtMy4zMTRhMTMuNDE1NCAxMy40MTU0IDAgMCAxLTQuNjg2IDVoOGMxLjYyMSAwIDMuMTkxLS41NjggNC40MzgtMS42MDUgMi45NDMtMi40NSAzLjM0Ni02LjgyNC44OTUtOS43N0E2Ljk0NTkgNi45NDU5IDAgMCAwIDI0IDcuNTYzeiIgZmlsbD0iI2ZmZiIvPjwvc3ZnPg%3D%3D"></a>
<a href="#"><img alt="Prettier" src="https://img.shields.io/badge/Prettier-F7B93E.svg?style=flat&logo=prettier&logoColor=black"></a>
<a href="#"><img alt="Node.js" src="https://img.shields.io/badge/Node.js-339933.svg?style=flat&logo=nodedotjs&logoColor=white"></a>
<a href="#"><img alt="MongoDB" src="https://img.shields.io/badge/MongoDB-47A248.svg?style=flat&logo=mongodb&logoColor=white"></a>
<a href="#"><img alt="Webpack" src="https://img.shields.io/badge/Webpack-8DD6F9.svg?style=flat&logo=webpack&logoColor=black"></a>
<a href="#"><img alt="React" src="https://img.shields.io/badge/React-61DAFB.svg?style=flat&logo=react&logoColor=black"></a>
<a href="#"><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-3178C6.svg?style=flat&logo=typescript&logoColor=white"></a>
<a href="#"><img alt="GitHub Actions" src="https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style=flat&logo=githubactions&logoColor=white"></a>
<a href="#"><img alt="Google Cloud" src="https://img.shields.io/badge/Google%20Cloud-4285F4.svg?style=flat&logo=googlecloud&logoColor=white"></a>
<a href="#"><img alt="Docker" src="https://img.shields.io/badge/Docker-2496ED.svg?style=flat&logo=docker&logoColor=white"></a>
<a href="#"><img alt="Redux" src="https://img.shields.io/badge/Redux-764ABC.svg?style=flat&logo=redux&logoColor=white"></a>
<a href="#"><img alt="Apollo GraphQL" src="https://img.shields.io/badge/Apollo%20GraphQL-311C87.svg?style=flat&logo=apollographql&logoColor=white"></a>
<a href="#"><img alt="Insomnia" src="https://img.shields.io/badge/Insomnia-4000BF.svg?style=flat&logo=insomnia&logoColor=white"></a>
<a href="#"><img alt="Heroku" src="https://img.shields.io/badge/Heroku-430098.svg?style=flat&logo=heroku&logoColor=white"></a>
<a href="#"><img alt="GraphQL" src="https://img.shields.io/badge/GraphQL-E10098.svg?style=flat&logo=graphql&logoColor=white"></a>
<a href="#"><img alt="ReactiveX" src="https://img.shields.io/badge/ReactiveX-B7178C.svg?style=flat&logo=reactivex&logoColor=white"></a>
<a href="#"><img alt="Sass" src="https://img.shields.io/badge/Sass-CC6699.svg?style=flat&logo=sass&logoColor=white"></a>
<a href="#"><img alt="styled-components" src="https://img.shields.io/badge/styled--components-DB7093.svg?style=flat&logo=styledcomponents&logoColor=white"></a>
<a href="#"><img alt="Brave" src="https://img.shields.io/badge/Brave-FB542B.svg?style=flat&logo=brave&logoColor=white"></a>
<a href="#"><img alt="Git" src="https://img.shields.io/badge/Git-F05032.svg?style=flat&logo=git&logoColor=white"></a>
<a href="#"><img alt="rollup.js" src="https://img.shields.io/badge/rollup.js-EC4A3F.svg?style=flat&logo=rollupdotjs&logoColor=white"></a>
<a href="#"><img alt="HTML5" src="https://img.shields.io/badge/HTML5-E34F26.svg?style=flat&logo=html5&logoColor=white"></a>
<a href="#"><img alt="npm" src="https://img.shields.io/badge/npm-CB3837.svg?style=flat&logo=npm&logoColor=white"></a>
<a href="#"><img alt="NestJS" src="https://img.shields.io/badge/NestJS-E0234E.svg?style=flat&logo=nestjs&logoColor=white"></a>
<a href="#"><img alt="Angular" src="https://img.shields.io/badge/Angular-DD0031.svg?style=flat&logo=angular&logoColor=white"></a>
<a href="https://github.com/ChipWolf/BadgeSort"><img alt="BadgeSort" src="https://img.shields.io/badge/BadgeSort-000000.svg?style=flat&logo=githubsponsors"></a>
</p>
<!-- end chipwolf/badgesort example -->
- 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$ python -m badgesort.icons -p badgen -s github python docker oxygenNote 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.