...because your users shouldn't need to connect to someone else's server, just to display a few (static) badges in your README
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.
Use pre-built badges
This project's Releases page
.zip files with a number of generic badges, like the ones you can see
at the top of this README.
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
![API Reference](./badges/docs-apireference.svg) ![Apache License v2.0](./badges/license-apache20.svg) ...
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 -template default -theme blue -p left=Foo -p right=Bar -o badge.svg
You can override nested parameters, such as theme parameters. For example:
./dot-slash-badges -template default -theme blue -p left=Foo -p right=Bar -p "theme.leftBgColor=#ff0000" -o custombadge.svg
You can load your own fonts. For example:
./dot-slash-badges -template default -theme blue -p left=Foo -p right=Bar -p "theme.leftFont=comic" -p "theme.rightFont=comicbd" -lf comic=comic.ttf -lf comicbd=comicbd.ttf -o custombadge.svg
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
Parameters of the default template
The following parameters are supported in the default badge template:
|left||Hello||The text on the left of the badge|
|right||Hello||The text on the right of the badge|
|theme.fontSize||16||The size of the text on the badge|
|theme.height||25||The height of the badge|
|theme.leftBgColor||#2976B7||The background color of the left side of the badge|
|theme.leftFont||builtin-regular||The font family to be used for the left side of the badge. The font must be loaded explicitly first using the -lf parameter.|
|theme.leftBgColor||#FFFFFF||The text color of the left side of the badge|
|theme.rightBgColor||#A74168||The background color of the right side of the badge|
|theme.rightFont||builtin-black||The font family to be used for the right side of the badge. The font must be loaded explicitly first using the -lf parameter.|
|theme.rightBgColor||#FFFFFF||The text color of the right side of the badge|
Use ./badges web
The sister project
./badges web provides a webservice and corresponding
frontend for generating badges from the web.
Check it out at https://codeberg.org/lhinderberger/dot-slash-badges-web
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.
You can create your own templates for using with
./badges or use the template
To get started creating or adapting templates, you can have a look at the
built-in standard badge template, located at
the source tree of
Each template has its own directory, which contains:
template.tmplfile, which is a template in Go's text/template format
parameters.jsonfile that declares the template's parameters
themessubdirectory, containing one JSON file for each theme that you want to include with your template. Themes simply contain a set of template parameters that can be applied by specifying
./badgesto use the theme.
COPYING.txtfile describing Copyright restrictions on your template and its themes
- An optional
template.gofile, useful in case you want to compile your template into your application when using
./badgesas a library
template.tmpl file is written in Go's text/template
The template parameters are available via the dot notation, as described in the
text/template. For an example, have a look at the
template.tmpl file provided with the built-in standard badge template.
There are a number of functions available to
|Add||Adds two numbers|
|Div||Divides two numbers|
|FontMetrics||Calculates the metrics of the font with the given name. Results in a FontMetrics struct.|
|Mult||Multiplies two numbers|
|RenderText||Renders text to an SVG fragment. Parameters: Font name, text, font size, text color (in #rrggbb notation). Results in a RenderResult struct.|
|Sub||Subtracts two numbers|
Each template declares its parameters in its
parameters.json file is structured as a tree of Objects, with each node
either having a member called
parameter (to declare a parameter) or a member
subtree to recursively define a nested parameter specification.
Each parameter declaration consists of a
type, which is one of the types in
the table below, an optional
example value, the indicator
itself is optional) and - only for
string-type parameters - the optional hint
Supported parameter types:
- boolean (allows for the values "true" and "false")
- color (allows for color strings in #rrggbb notation)
- float (allows for single-precision floating point numbers)
- integer (allows for 24-bit signed integer values)
- string (allows for arbitrary strings)
Have a look at the
parameters.json file of the builtin standard badge template
./badges, located at
pkg/templates/standard-badge/parameters.json for an
./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!
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).
Copyright and Licensing
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.
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 email@example.com
There is no documentation for this package.
Package badgetemplate contains an abstraction of how to represent non-compiled badge templates in an application For built-in badge templates, refer to the templates package instead.
|Package badgetemplate contains an abstraction of how to represent non-compiled badge templates in an application For built-in badge templates, refer to the templates package instead.|
Package fonts contains the fonts "Aileron Black" and "Aileron Regular" by Sora Sagano (http://www.dotcolon.net/font/aileron/).
|Package fonts contains the fonts "Aileron Black" and "Aileron Regular" by Sora Sagano (http://www.dotcolon.net/font/aileron/).|