Recipes

Charts in a GitHub README

Put a chart in a README that stays sharp on retina screens.

The result

Copy a snippet

Markdown

![Builds per week](https://chartpng.dev/chart?w=600&h=360&dpr=2&c=%7B%22type%22%3A%22line%22%2C%22data%22%3A%7B%22labels%22%3A%5B%22W1%22%2C%22W2%22%2C%22W3%22%2C%22W4%22%2C%22W5%22%2C%22W6%22%5D%2C%22datasets%22%3A%5B%7B%22label%22%3A%22Builds%20per%20week%22%2C%22data%22%3A%5B42%2C51%2C47%2C63%2C70%2C82%5D%7D%5D%7D%7D)

HTML, with a display width

<img src="https://chartpng.dev/chart?w=600&h=360&dpr=2&c=%7B%22type%22%3A%22line%22%2C%22data%22%3A%7B%22labels%22%3A%5B%22W1%22%2C%22W2%22%2C%22W3%22%2C%22W4%22%2C%22W5%22%2C%22W6%22%5D%2C%22datasets%22%3A%5B%7B%22label%22%3A%22Builds%20per%20week%22%2C%22data%22%3A%5B42%2C51%2C47%2C63%2C70%2C82%5D%7D%5D%7D%7D" width="600" alt="Builds per week">

Why the HTML version

dpr=2 doubles the pixels but not the layout. The file is 1200 pixels wide and the text stays the size it would have in a 600 pixel chart. The Markdown image syntax has no size, so the picture can show at the full file width. An img tag with width="600" shows it at the size you meant, with twice the pixels behind it.

The Markdown spec GitHub builds on leaves img tags untouched. Its help page on images does not coverwidth, so check the size in the preview tab before you commit.

Caching

• GitHub caches the image. It serves README images through its own proxy, and the proxy keeps a copy.
• One URL is one image. The config is part of the URL. Change the numbers and the URL changes, so GitHub fetches the new image.
• ChartPNG says the image never changes. It answers with Cache-Control: public, max-age=86400, s-maxage=31536000, immutable.
• No scheduled refresh. The chart is the data in the URL. To update a README chart, edit the URL, or generate it in a script when you release.

Limits that matter

• A README is public. Never put an API key in the URL. The free plan draws a small chartpng.dev watermark.
• Parentheses in labels. A raw ( or ) can end a Markdown link early. The examples here encode them as %28 and %29.
• Size. The config can be up to 16 KB, and a free image up to 4 megapixels (width times height times dpr squared).
• Long URLs. The source of your README gets hard to read. Build the URL in a script and paste the result.