Markdown Badge & Shield URL Generator

What does the Markdown Badge Generator do?

The Markdown Badge & Shield URL Generator creates custom status badges and shields for GitHub README files, open-source repositories, and developer documentation. It provides real-time SVG previews, customizable brand colors, SimpleIcons integration, and ready-to-copy Markdown, HTML, and reStructuredText (RST) embed snippets.

Developers and DevOps engineers use this utility to showcase build status, package version numbers, license types, test coverage metrics, and live Discord/community links across project documentation.

Core Concepts & Badge Geometry

Shields.io style badges follow standard visual conventions:

• Badge Format: https://img.shields.io/badge/<LABEL>-<MESSAGE>-<COLOR>
• Character Sanitization: Dashes (-) are escaped as --, underscores (_) as __, and spaces as _.
• Visual Styles: Supports 4 distinct geometric styles:
  • flat: Standard rounded corner modern badge.
  • flat-square: Crisp, rectangular square edges.
  • for-the-badge: Bold uppercase typography.
  • plastic: Subtle 3D gradient look.
• Brand Icons: Integrates SimpleIcons slugs (e.g. docker, npm, react, jest, githubactions).

How to use the tool?

1. Pick a Preset or Enter Custom Text: Click a preset button (e.g., Build Passing, npm Version, MIT License) or enter your own left Label, right Message, and color.
2. Select Style & Logo: Choose your preferred badge style (Flat, Flat Square, For-the-Badge) and optionally specify a brand logo.
3. Add Target Link (Optional): Provide a destination URL (e.g. your GitHub repository or documentation site) to wrap the badge in a clickable link.
4. Copy Embed Snippet: Select your preferred output format tab (Markdown, HTML, RST, or raw SVG URL) and click Copy.

REST API Integration

Blueutils provides a free REST API endpoint (POST https://blueutils.com/api/markdown/badge-generator) for programmatic integration.

API Request Parameters

API Request Payload Examples

cURL

curl -X POST https://blueutils.com/api/markdown/badge-generator \
  -H "Content-Type: application/json" \
  -d '{
    "label": "npm",
    "message": "v2.4.0",
    "color": "cb3837",
    "style": "flat",
    "logo": "npm",
    "linkUrl": "https://www.npmjs.com/package/blueutils"
  }'

Python

import requests

url = "https://blueutils.com/api/markdown/badge-generator"
payload = {
    "label": "npm",
    "message": "v2.4.0",
    "color": "cb3837",
    "style": "flat",
    "logo": "npm"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String jsonPayload = "{\"label\":\"license\",\"message\":\"MIT\",\"color\":\"blue\"}";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://blueutils.com/api/markdown/badge-generator"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

API Response Parameters

API Response Payload Examples

Success Response (HTTP 200 OK)

{
  "isValid": true,
  "label": "npm",
  "message": "v2.4.0",
  "color": "cb3837",
  "style": "flat",
  "badgeUrl": "https://img.shields.io/badge/npm-v2.4.0-cb3837?logo=npm",
  "markdownSnippet": "![npm: v2.4.0](https://img.shields.io/badge/npm-v2.4.0-cb3837?logo=npm)",
  "htmlSnippet": "<img src=\"https://img.shields.io/badge/npm-v2.4.0-cb3837?logo=npm\" alt=\"npm: v2.4.0\" />",
  "rstSnippet": ".. image:: https://img.shields.io/badge/npm-v2.4.0-cb3837?logo=npm\n   :alt: npm: v2.4.0"
}

Validation Failure Response (HTTP 400 Bad Request)

{
  "isValid": false,
  "error": "Please enter at least a badge Label or Message."
}

Rate Limit Exceeded Response (HTTP 429 Too Many Requests)

{
  "error": "API rate limit exceeded. Please wait or contact support@blueutils.com."
}

Why use an API to generate Markdown Badges?

Integrating the Markdown Badge Generator API into CI/CD pipelines, DevOps deployment bots, or repository scaffolding tools provides several practical advantages:

• Automated Release Notes & PR Bot Comments: GitHub Actions and GitLab CI jobs can programmatically generate dynamic test coverage and version badges to embed directly in pull request comments.
• Scaffolding CLI Utilities: Automated package generators can build uniform README templates with pre-configured license and build shields without manual string formatting.
• Deterministic URL Sanitization: Handles underscore/dash escape rules deterministically without broken SVG links.

Native Usage

How to construct Shields.io badge URLs and Markdown links locally using native command-line utilities and scripts:

Windows (PowerShell Badge URL Builder)

# Generate Shields.io Markdown badge link in PowerShell
$label = "build"
$message = "passing"
$color = "4c1"
$safeLabel = $label -replace '_', '__' -replace '-', '--' -replace '\s+', '_'
$safeMessage = $message -replace '_', '__' -replace '-', '--' -replace '\s+', '_'
$badgeUrl = "https://img.shields.io/badge/$safeLabel-$safeMessage-$color"
"![${label}: ${message}]($badgeUrl)"

Linux / Unix (Bash Shell Script)

# Generate Shields.io Markdown badge using bash
label="build"
message="passing"
color="4c1"
badge_url="https://img.shields.io/badge/${label//-/_}-${message//-/_}-${color}"
echo "![${label}: ${message}](${badge_url})"

Python (Standard Library urllib Badge Generator)

import urllib.parse

def make_badge(label, message, color="4c1", style="flat", logo=None):
    safe_label = label.replace("_", "__").replace("-", "--").replace(" ", "_")
    safe_msg = message.replace("_", "__").replace("-", "--").replace(" ", "_")
    url = f"https://img.shields.io/badge/{safe_label}-{safe_msg}-{color}"
    params = {}
    if style != "flat": params["style"] = style
    if logo: params["logo"] = logo
    if params: url += "?" + urllib.parse.urlencode(params)
    return f"![{label}: {message}]({url})"

print(make_badge("npm", "v2.4.0", color="cb3837", logo="npm"))

Java (Native Standard Library Badge Builder)

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class BadgeGenerator {
    public static void main(String[] args) {
        String label = "license";
        String message = "MIT";
        String color = "blue";
        String safeLabel = label.replace("_", "__").replace("-", "--").replace(" ", "_");
        String safeMessage = message.replace("_", "__").replace("-", "--").replace(" ", "_");
        String url = "https://img.shields.io/badge/" + safeLabel + "-" + safeMessage + "-" + color;
        System.out.println("![" + label + ": " + message + "](" + url + ")");
    }
}