Badges and Charts

Badges and charts

The published JSON and SVG files are static branch content. README badges query the JSON, while chart embeds reference generated SVG files directly.

Generate snippets visually

The Generator Lab builds badge URLs, Markdown snippets, chart embeds, and chart action settings. It is the simplest option when you want to change labels, colors, providers, chart types, or themes without manually encoding URLs.

JSON source URL

With the default branch and path:

https://raw.githubusercontent.com/OWNER/REPOSITORY/gh-pages/gh-dl/downloads.json

GitHub Raw is direct and simple. A jsDelivr equivalent is:

https://cdn.jsdelivr.net/gh/OWNER/REPOSITORY@gh-pages/gh-dl/downloads.json

Content delivery networks and Shields cache responses, so a successful workflow update may not appear immediately in an already rendered badge.

Shields badge fields

Badge	JSON query
Total	$.stats.total
Day	$.stats.day
Week	$.stats.week
Month	$.stats.month
Workflow profile	$.profile.defaultMode

Example total badge:

![Downloads total](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FOWNER%2FREPOSITORY%2Fgh-pages%2Fgh-dl%2Fdownloads.json&query=%24.stats.total&label=downloads%2Ftotal&color=0A7EA4)

Replace OWNER and REPOSITORY. For a range badge, consider displaying or otherwise checking its matching partial flag before treating the value as exact.

Enable charts

Add chart settings to the action step:

with:
  token: ${{ secrets.GITHUB_TOKEN }}
  publish_chart: "true"
  chart_types: "total-trend,daily,weekly,monthly"
  chart_themes: "black,slate,orange"
  chart_output_path: "gh-dl/downloads-trend.svg"
  charts_output_dir: "gh-dl/charts"

chart_output_path receives the first requested chart type with the first requested theme. charts_output_dir receives the full type and theme matrix using names such as weekly--orange.svg.

Chart types

Type	Series shown
total-trend	Cumulative release asset total at every stored date
daily	One-day change calculated for each chart date
weekly	Seven-day change calculated for each chart date
monthly	Thirty-day change calculated for each chart date

Available themes are black, slate, and orange.

Range charts are calculated from the available snapshot series but do not annotate partial coverage at each point. Early or interrupted sections should therefore be interpreted alongside the dates present in downloads.json.

Embed the primary chart:

![Downloads trend](https://raw.githubusercontent.com/OWNER/REPOSITORY/gh-pages/gh-dl/downloads-trend.svg)

Embed one matrix chart:

![Weekly downloads](https://raw.githubusercontent.com/OWNER/REPOSITORY/gh-pages/gh-dl/charts/weekly--orange.svg)

Presentation controls

Charts can be sized from 640 to 4096 pixels wide and 240 to 2160 pixels high. Other controls configure:

• zero or data-relative vertical baselines;
• two through twelve vertical intervals;
• automatic or fixed date-label spacing;
• optional values above individual points;
• date labels in yyyy-mm-dd, yy/mm/dd, dd/mm, mm/dd, or no date format;
• generated-date footer visibility;
• default repository title, custom title, or no title.

Showing every value and every date can make a long series difficult to read. For a general README chart, the defaults provide clearer spacing. Dense labels are most useful for short daily series.

Public visibility

Public badges and README chart embeds require publicly readable output URLs. A private repository's raw branch content normally cannot be fetched anonymously by Shields or README visitors. If the measured repository must remain private, publish only the intended aggregate data to an appropriate public repository with a separately scoped token.