...because your users shouldn't need to connect to someone else's server, just to display a few (static) badges in your README
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Lucas Hinderberger d80f348cd3 Added hint for badgerenderer package 1 day ago
docs Adding link to API Reference to README 1 day ago
pkg Moving to Codeberg 3 weeks ago
.gitignore Added binaries to .gitignore 3 weeks ago
LICENSE.txt Initial experiments with font rendering 4 weeks ago
NOTICE.txt Added default parameters for badge generation 3 weeks ago
README.md Added hint for badgerenderer package 1 day ago
go.mod Moving to Codeberg 3 weeks ago
go.sum Added builtin theme loading 4 weeks ago
main.go Moving to Codeberg 3 weeks ago

README.md

./badges

...because your users shouldn't need to connect to someone else's server, just to display a few (static) badges in your README

Status: Active Issue Tracker License: Apache v2.0 API Reference

Why?

Repository badges are a great visual cue you can use in your repository's README file to point your users to the most relevant information about your project.

Many badges that are out there are ready to use by just including an image tag into your README that dynamically loads the badge from the respective service's servers. Unless you use a proxy to access the badges (as GitHub does by default, unlike your average local markdown viewer), this implies that you have to point your users to the badge service's servers when they want to read your README. While that is very convenient for you as a developer, it is not optimal from a privacy and reliability point-of-view. That is because you now have to trust the badge service(s) to deal with your user's data responsibly and to run their servers reliably and safely. Also, if your users have cloned your repository, they now need Internet access to see your README the way you intended it to be.

To provide a decentralized and customizable alternative for those who don't want to go without repository badges, I have created ./badges. It is a collection of and generator for badges that you can copy to your repository and refer to locally.

How?

Use pre-built badges

This project's Releases page contains .zip files with a number of generic badges, like the ones you can see below.

You can download them and copy the badges you need into a subdirectory of your repository (for example ./badges 🤓) and then refer to them in Markdown like this:

![API Reference](./badges/docs-apireference.svg) ![Apache License v2.0](./badges/license-apache20.svg) ...

Example Badges

Generate your own badges

You can also generate your own, custom badges using the ./badges generator, which you can download from this project's Releases page.

It is a single dependency-free executable that comes with templates, themes and fonts built-in.

To generate a single badge using the built-in standard template, run the following command:

./dot-slash-badges -theme builtin-dark-blue -template builtin-standard-badge -param left:string:Foo -param right:string:Bar

You can also generate a batch of templates using the -params parameter:

./dot-slash-badges -theme builtin-dark-blue -template builtin-standard-badge -params batch-parameters.json

For an example of a batch parameters file, have a look at docs/default-parameters.json.

The ./badges generator is fairly customizable. You can for example specify your own templates and themes that can be loaded from a file. For an overview of all available options, run

./dot-slash-badges -help

Use ./badges as a library

The built-in templates and themes are literally built into ./badges, which you can in turn use as a batteries-included library in your own code.

This can be useful to create dynamic badges from your own server-side services.

To learn more, please have a look at the Reference Documentation and especially the documentation for the badgerenderer package

Limitations

While ./badges is a good solution for decentralizing badges that don't change (such as licensing information or a link to the docs), it cannot provide you with badges that change dynamically, for example a build status indicator.

You can, however, absolutely use ./badges to generate badges for your own, self-hosted (and most likely self-written 😉) dynamic batch services, that visually integrate nicely with the rest of the badges produced by ./badges. In fact, ./badges can be included as a Go library - and it comes with batteries included: The fonts, templates and themes of the ./badges generator are compiled into the library!

Contributing

Feel free to contribute by posting issues on this project's Issue Tracker.

Please note that pull requests are only accepted if they are in line with the licensing of the rest of the project (see below).

The ./badges generator is (C) 2021 Lucas Hinderberger

It is licensed under the Apache Licence Version 2.0.

The output of the ./badges generator using the built-in fonts, themes and templates is unencumbered by copyright restrictions (to the extent possible under law), due to the built-in fonts, themes and templates being released under CC0 1.0 Universal.

To the extent possible under law, the author has waived all copyright and related or neighboring rights to the pre-built badges originally distributed alongside ./badges, as described in CC0 1.0 Universal.

For details, please refer to the LICENCE file and the NOTICE file.

Author and Contact

./badges is authored by Lucas Hinderberger. For contact data, see https://lhinderberger.com/impressum

The repository of ./badges can be found at https://codeberg.org/lhinderberger/dot-slash-badges

You're welcome to file bug reports, other issues and pull requests there.

You can also contact the author via email at mail@lhinderberger.com