Badges

Badges Installation Usage Examples License Version

Lots of GitHub repositories use badges. They are visually nice, but they are also images dynamically built and loaded from third-party servers.

badges generates actually static badges as SVG images hosted on the same server.

It simply scans files, searches for things that look like a badge filename and generates badges as SVG images.

A badge file is a file in a directory named badges (or a subdirectory). The filename describes the badge content, color and size.

Badges with a single text

text-width-color.svg

• text: text displayed in the badge
• width: width in pixels of the badge
• color: background color of the badge (e.g.: green, 123, 123456)

Badges with two texts

text1-text2-width1-width2-color.svg

• text1: first text displayed in the badge
• text2: second text displayed in the badge
• width1: width in pixels of the first text
• width2: width in pixels of the second text
• color: background color of the second text (e.g.: green, 123, 123456)

The default color of the first text is white on grey.

badges makes some substitutions in the text fields:

• _ is replaced width (space)
• @xyz is replaced with the value of the xyz variable (variables table in the configuration file or -D CLI option)

Special characters in text fields can be escaped:

• @@ becomes @
• __ becomes _ (underscore)
• -- becomes - (dash)

To insert characters that are invalid in a filename, you must use variables.

Installation

badges requires LuaX.

# install badges in ~/.local/bin and ~/.local/lib
$ git clone https://codeberg.org/cdsoft/badges
$ cd badges
$ bang && ninja install

or set $PREFIX to install badges to a custom directory ($PREFIX/bin and $PREFIX/lib):

$ export PREFIX=/path # install badges to /path/bin and /path/lib
$ git clone https://codeberg.org/cdsoft/badges
$ cd badges
$ bang && ninja install

This will install 2 files in $PREFIX/bin:

1. $PREFIX/bin/badges: badges command line utility compiled with LuaX. It can be run without any dependency.
2. $PREFIX/bin/badges.lua: badges.lua command line utility bundled with LuaX as a standalone Lua script. It requires a Lua 5.4 or 5.5 interpreter (e.g.: lua).

In case precompiled binaries are needed (GNU/Linux, MacOS, Windows), some can be found at cdelord.fr/pub. These archives contain badges as well as some other softwares more or less related to LuaX.

Usage

Usage: .build/badges [-h] [-v] [-c file.toml] [--init] [-D NAME=VALUE]
 [<input>] ...
Arguments:
 input files or directories to scan
Options:
 -h, --help Show this help message and exit.
 -v, --version Show badges version
 -c file.toml Configuration file (default: badges.toml)
 --init Print the default configuration
 -D NAME=VALUE Define a variable

badges

Scans for files in the current directory and generates badges.

badges file.md dir1 dir2

Generate badges found in file1.md and in all files in dir1 and dir2.

badges -c file.toml ...

Overloads the default configuration with a user configuration file.

badges -D V=42 ...

Defines a variable that can be used in textual fields (e.g.: @V is replaced with 42).

badges --init

Prints the default configuration.

The default configuration is badges.toml.

Examples

License

badges is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
badges is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with badges. If not, see <https://www.gnu.org/licenses/>.
For further information about badges you can visit
https://codeberg.org/cdsoft/badges