GitHub Markdown gives you two ways to show a chart:

  • An image file (SVG or PNG) committed to the repository and linked with a relative path. Works for any chart, looks the same everywhere, and can follow the reader’s light or dark theme.
  • A Mermaid diagram written as text in a code block. Good for simple pie, bar and line charts that you want to edit in a pull request, but limited in styling, and shown as raw code by tools that don’t render Mermaid.

Option 1: commit an image

Put the chart in the repository and link it with a relative path, as GitHub recommends for images stored in the repo:

![Monthly downloads: 18,400 in September 2026, up from 11,200 in April.](docs/downloads.svg)

To control the displayed size, use an HTML <img> tag. GitHub keeps the width attribute and strips style, so set the size with attributes:

<img src="docs/downloads.svg" width="640" alt="Monthly downloads: 18,400 in September 2026, up from 11,200 in April.">

SVG or PNG?

GitHub displays both. SVG stays sharp at any zoom level and is usually smaller, but an SVG shown as an image runs in a locked-down mode:

  • No scripts or animation. GitHub says “SVGs don’t currently support inline scripting or animation” (GitHub Docs), and browsers disable JavaScript in any SVG loaded as an image.
  • No external resources. In an SVG used as an image, “external resources (e.g., images, stylesheets) cannot be loaded, though they can be used if inlined through data: URLs” (MDN). A chart that references a web font through a stylesheet falls back to a system font. Use a common font stack, embed the font, or convert the text to paths.
  • Interactive charts don’t survive. Tooltips and hover effects from a charting library depend on scripts, so only the static drawing remains.

PNG avoids all three, at the cost of blurring when zoomed. Export it at twice the display width (1280 pixels for a 640-pixel image).

Images hosted elsewhere

You can also link an image by absolute URL, for example a chart a service regenerates daily. GitHub serves external images through its Camo proxy, which hides readers’ details from the image host. Camo caches what it fetches; for an image that changes, GitHub advises serving it with Cache-Control: no-cache. Committed images avoid that question and keep the README working if the external service goes away.

Option 2: a Mermaid chart

GitHub has rendered Mermaid diagrams in Markdown since February 14, 2022, in “GitHub Issues, GitHub Discussions, pull requests, wikis, and Markdown files”. Two Mermaid diagram types fit everyday data charts: pie and XY.

A pie chart:

```mermaid
pie title Issues by label, September 2026
    "bug" : 42
    "feature" : 27
    "docs" : 11
```

An XY chart, which draws bars, lines or both:

```mermaid
xychart-beta
    title "Monthly downloads (thousands)"
    x-axis [Apr, May, Jun, Jul, Aug, Sep]
    y-axis "Downloads (thousands)" 0 --> 20
    bar [11.2, 12.0, 13.4, 14.1, 16.3, 18.4]
    line [11.2, 12.0, 13.4, 14.1, 16.3, 18.4]
```

Newer Mermaid versions (11.10 onwards) also accept plain xychart; GitHub rendered both spellings when we tested on October 14, 2026. xychart-beta works on older renderers too, so it’s the safer choice. To see which Mermaid version GitHub runs, put info in a Mermaid block.

Mermaid’s limits:

  • Rendering depends on the viewer. GitHub renders Mermaid in the browser; clients that request the Markdown “in a non-JavaScript environment (such as an API request) will see the original Markdown code” (GitHub blog). Other places that show your README, such as editors and package registry pages, may not render Mermaid either; check before relying on it.
  • Limited styling. Colors and fonts follow Mermaid’s theme, not your brand.
  • Small data only. It’s comfortable for a handful of values, not hundreds of points.

Light and dark versions

A chart drawn for a white background is hard to read in GitHub’s dark theme, and vice versa. The <picture> element with the prefers-color-scheme media feature lets you ship one of each:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/downloads-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="docs/downloads-light.svg">
  <img alt="Monthly downloads: 18,400 in September 2026, up from 11,200 in April." src="docs/downloads-light.svg" width="640">
</picture>

The <img> inside is the fallback and carries the alt text and size. GitHub made this generally available on August 15, 2022.

You may also see the older trick of appending #gh-dark-mode-only or #gh-light-mode-only to an image URL, introduced in November 2021. It still worked when we tested in October 2026, but GitHub’s documentation no longer mentions it, and it only works on GitHub. Prefer <picture>.

A simpler alternative for a single image: draw the chart on its own solid background (white with dark text, for example), with some padding. It won’t match the theme, but it stays readable in both.

Charts in pull requests and issues

To show a chart in a pull request comment, drag the image file into the comment box. GitHub accepts PNG, GIF, JPEG and SVG images up to 10 MB, and for public repositories “uploaded files can be accessed without authentication”.

From automation, such as a CI job that posts a benchmark chart on every pull request:

  • GitHub CLI 2.99.0 and later can upload images, with alt text after a #: gh pr comment 123 --body "Benchmark results" --attach 'chart.png#p95 latency: 212 ms, down 8% from main'. The --attach flag arrived on September 1, 2026, needs push access to the repository, and isn’t supported on GitHub Enterprise Server in that release. The docs list the commands that accept it.
  • The REST API documents no endpoint for uploading attachments. Workflows that use it link to an image hosted elsewhere, or use Mermaid, which needs nothing but text in the comment body.

Making the chart

For a README chart you update occasionally, export it once and commit it: Chart Link turns CSV or JSON into an SVG or PNG in your browser, with a solid background so it reads in both themes. For a chart that changes with every build, render it in CI, for example with Chart.js on Node.js, and commit or attach the result.

Sources

All sources were checked on October 14, 2026. Rendering behavior (the width attribute, xychart spellings, #gh-dark-mode-only) was tested on github.com on the same day.