Crate shields 

shields

A Rust library for generating SVG badges, inspired by shields.io.

This crate provides flexible APIs for creating customizable status badges for CI, version, downloads, and more, supporting multiple styles (flat, plastic, social, for-the-badge, etc.).

Features

• Generate SVG badge strings with custom label, message, color, logo, and links.
• Multiple badge styles: flat, flat-square, plastic, social, for-the-badge.
• Accurate text width calculation using font width tables embedded at compile time.
• Builder pattern and parameter struct APIs.
• Color normalization and aliasing (e.g., “critical” → red).
• No runtime file I/O required for badge generation.

Example

use shields::{BadgeStyle, BadgeParams, render_badge_svg};

let params = BadgeParams {
    style: BadgeStyle::Flat,
    label: Some("build"),
    message: Some("passing"),
    label_color: Some("green"),
    message_color: Some("brightgreen"),
    link: Some("https://ci.example.com"),
    extra_link: None,
    logo: None,
    logo_color: None,
};
let svg = render_badge_svg(&params);
assert!(svg.contains("passing"));

Or use the builder API:

use shields::{BadgeStyle};
use shields::builder::Badge;

let svg = Badge::style(BadgeStyle::Plastic)
    .label("version")
    .message("1.0.0")
    .logo("github")
    .build();
assert!(svg.contains("version"));

See BadgeParams, BadgeStyle, and BadgeBuilder for details.

Modules

builder

Badge builder module for shields crate.

measurer

Font character width measurer for SVG badge rendering.

Structs

BadgeParams

Parameters for generating a badge SVG.

BadgeParamsOwned

Owned variant of BadgeParams, for callers that cannot borrow — typically deserializing from an HTTP query string or JSON body.

ParseBadgeStyleError

Error returned when parsing an unknown BadgeStyle name.

RenderError

Error type of try_render_badge_svg. Rendering can no longer fail, so no value of it is ever produced.

RenderOptions

Additional rendering options that extend BadgeParams without breaking its literal-construction API.

Enums

BadgeStyle

Badge style variants supported by the shields crate.

Font

Font enumeration for supported fonts

Traits

FontMetrics

Font width calculation trait, to be implemented and injected by the main project

Functions

colors_for_background

Dynamically calculates foreground and shadow colors based on background color (equivalent to JS colorsForBackground)

default_label_color

Returns the default label color hex string (#555).

default_message_color

Returns the default message color hex string (#007ec6).

get_text_width

Calculates the width of text in the given font (in pixels)

render_badge_svg

Generate an SVG badge string from BadgeParams.

render_badge_svg_into

Appends the badge SVG to out instead of returning a new String.

render_badge_svg_with

Generate an SVG badge string from BadgeParams plus RenderOptions.

try_render_badge_svg

Fallible variant of render_badge_svg.

try_render_badge_svg_with

try_render_badge_svg with additional RenderOptions.

warm_up

Performs the one-time initialization the first logo badge would otherwise pay for, so it does not land on the first request.