Skip to main content
Shields.io badges are a reliable and consistent way to display dynamic data, such as hit counters, on platforms like GitHub. Below is an example of how to use a Shields.io badge: 
![hits](https://img.shields.io/endpoint?url=https%3A%2F%2Fnums.advay.ca%2Fbadge.json%3Fid%3Dhome%26label%3Dhits%26cacheSeconds%3D30)

​
Key Features

  • Caching: Updates approximately every 30 seconds due to Shields.io’s caching mechanism.
  • Reliability: Works seamlessly across GitHub, npm, and other platforms.
  • Consistency: Ideal for projects requiring stable and predictable badge behavior.

​
How to Use

  1. Copy the Markdown snippet above.
  2. Replace id=home with your unique counter ID.
  3. Paste it into your README.md or any Markdown-supported file.

​
Direct SVG (live from nums)

Direct SVG badges fetch live data directly from your nums server. This method offers more customization options and faster updates. Here’s an example: 
![hits](https://nums.advay.ca/badge?id=home&style=terminal&label=hits&bg=%2308c4fc&labelColor=%23000000&valueColor=%23ffffff&font=ui-monospace)

​
Key Features

  • Instant Updates: Reflects real-time data from your server.
  • Customizable: Modify the badge’s appearance to match your project’s theme.
  • GitHub Caching: Note that GitHub may cache the image for 1–2 minutes.

​
Customization Parameters

Below is a table of parameters you can use to customize your badge:
ParamExampleDescription
idhomeUnique key for your counter (page/project id)
labelhitsText shown on the left side of the badge
styleterminal, monoBadge style. Use terminal (monospace) or omit for classic.
bg#08c4fcBackground color (hex #rgb/#rrggbb or safe name)
labelColor#000000Label color (hex or safe name)
valueColor#ffffffValue color (hex or safe name)
fontui-monospaceFont family for rendering
Below are concrete examples and guidance for each parameter so you can pick values that render well across platforms.

​
Examples and guidance

  • id (string)
    • Example: id=home or id=downloads-page
    • Notes: IDs are arbitrary strings and are created on first /hit call. Use simple, URL-safe names (alphanumerics, dash, underscore).
  • label (string)
    • Example: label=hits, label=downloads, label=page%20views (space must be URL-encoded as %20)
    • Notes: Keep labels short (1–3 words) to avoid badge overflow.
  • style (string)
    • Values: omit for the classic badge, or use terminal / mono for the monospace terminal look.
    • Example (classic): /badge?id=home&label=hits
    • Example (terminal): /badge?id=home&style=terminal&label=hits
  • bg, labelColor, valueColor (colors)
    • Accepts hex (#fff, #ffffff) or a small allowlist of color names (e.g., blue, green, red).
    • IMPORTANT: When embedding in a URL, the # must be URL-encoded as %23.
    • Example: bg=%2308c4fc (renders #08c4fc)
    • Example terminal badge with custom colors (URL-encoded):
      • https://<deployment>/badge?id=home&style=terminal&bg=%23101414&labelColor=%23aaaaaa&valueColor=%233cffb3
    • Fallback: invalid or unsupported colors fall back to safe defaults (server uses allowlist).
  • font (string)
    • Example: font=ui-monospace, font=Verdana,Geneva,DejaVu Sans,sans-serif
    • Notes: Provide a comma-separated font-family. When the chosen font isn’t available on the renderer, the browser/agent will use the next available fallback.

​
Ready-to-copy examples

  • Classic badge (blue):
![hits](https://<deployment>/badge?id=home&label=hits&color=blue)
  • Terminal badge with custom colors (URL-encoded):
![hits](https://<deployment>/badge?id=home&style=terminal&label=views&bg=%23101414&labelColor=%23aaaaaa&valueColor=%233cffb3&font=ui-monospace)
  • Shields + nums (recommended for GitHub):
![hits](https://img.shields.io/endpoint?url=https%3A%2F%2F<deployment>%2Fbadge.json%3Fid%3Dhome%26label%3Dhits%26cacheSeconds%3D30)

​
Rendering and caching notes

  • GitHub and other hosts may cache badge images for 1–2 minutes even for direct SVGs; use the Shields approach for consistent ~30s caching.
  • The terminal-style badge sets strong anti-cache headers to encourage revalidation, but proxies (like GitHub’s image proxy) may still cache.

​
How to Use

  1. Copy the Markdown snippet above.
  2. Replace id=home with your unique counter ID.
  3. Adjust the parameters to customize the badge’s appearance.
  4. Paste it into your README.md or any Markdown-supported file.

​
Plaintext Badge

Plaintext badges are a simple and lightweight option for displaying hit counters in plain text format. These badges are ideal for environments where images are not supported or when you prefer a minimalistic approach.

​
Example

https://<YOUR_DEPLOYMENT_URL>/count.txt?id=home

​
Key Features

  • Lightweight: No images, just plain text.
  • Universal Compatibility: Works in any environment that supports text.
  • Real-Time Updates: Fetches the latest counter value directly from the server.

​
How to Use

  1. Copy the plaintext URL above.
  2. Replace id=home with your unique counter ID.
  3. Paste the URL into your desired location (e.g., README.md, plain text file, etc.).
  4. When accessed, the URL will display the current counter value as plain text.

​
Use Cases

  • CLI Tools: Display hit counters in terminal-based applications.
  • Text-Only Platforms: Ideal for environments that do not support images.
  • Minimalistic Projects: Perfect for projects that prioritize simplicity and speed.

​
Quick Comparison

FeatureShields.io BadgeDirect SVG Badge
Update Speed~30 secondsInstant (GitHub may cache ~1–2 min)
ReliabilityHighDepends on server
CustomizationLimitedExtensive
Use Shields.io for reliability and Direct SVG for real-time updates and customization.
⌘I