...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.

10 KiB

./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 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 this:

![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.

Invocation Examples

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

./dot-slash-badges -help

Parameters of the default template

The following parameters are supported in the default badge template:

parameter example description
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.

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

Templates

You can create your own templates for using with ./badges or use the template provided with ./badges.

To get started creating or adapting templates, you can have a look at the built-in standard badge template, located at pkg/templates/standard-badge in the source tree of ./badges.

Template Structure

Each template has its own directory, which contains:

  • A template.tmpl file, which is a template in Go's text/template format
  • A parameters.json file that declares the template's parameters
  • A themes subdirectory, 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 ./badges to use the theme.
  • A COPYING.txt file describing Copyright restrictions on your template and its themes
  • An optional template.go file, useful in case you want to compile your template into your application when using ./badges as a library

Template Authoring

The template.tmpl file is written in Go's text/template syntax.

The template parameters are available via the dot notation, as described in the documentation of 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 ./badges templates:

Function Description
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

Parameter Specification

Each template declares its parameters in its parameters.json file. A 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 called 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 optional (which itself is optional) and - only for string-type parameters - the optional hint isFontName.

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 of ./badges, located at pkg/templates/standard-badge/parameters.json for an example.

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