Embed Charts in Markdown Without Chart.js: SVG, Data URIs, and What Actually Works

Markdown is great until you want a real chart in a README or docs site. Most people reach for a screenshot, a hosted PNG, or a heavy client library. ProvChart takes another path: POST /api/v1/generate-svg returns a self-contained SVG (and optional data URI) from your data—no js on the page, no image CDN required.

This article covers what different Markdown platforms allow, practical embed patterns, and when pure SVG is the better default.

The idea

1. Send series data to ProvChart’s SVG endpoint.
2. Get back:
   • svg — full <svg xmlns="...">...</svg> string
   • dataUri — data:image/svg+xml;base64,...
3. Embed with whatever your platform supports.

Platform reality: not every Markdown engine is equal

Takeaway: Prefer a committed .svg file for GitHub and public docs. Use data URIs for quick demos. Use inline SVG only where the engine allows raw HTML (MDX, some wikis, your own site).

Pattern 1 — Generate SVG (API)

curl -s -X POST "https://provchart-api.devtem.org/api/v1/generate-svg" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "type": "line",
    "series": [
      { "name": "Stars", "color": "#8b7bff", "points": [12, 18, 25, 40, 55] }
    ],
    "axisX": ["Jan", "Feb", "Mar", "Apr", "May"],
    "width": 640,
    "height": 280
  }'

Response shape:

{
  "success": true,
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" ...>...</svg>",
  "dataUri": "data:image/svg+xml;base64,..."
}

Keep the key in CI secrets.

Pattern 2 — Embed options

A. Image from file (recommended for README)

![Stars over time](./docs/charts/stars.svg)

Save the svg field from the API into that path and commit it.

B. Data URI (quick, not always portable)

![Stars over time](data:image/svg+xml;base64,AAAA...)

If the preview is blank, the host likely truncated or blocked the URI—switch to a file.

C. Inline SVG (when HTML is allowed)

<!-- MDX / some static generators -->
<div>
  <!-- paste the svg string from the API -->
</div>

GitHub README will generally not render arbitrary inline SVG.

D. Raster only if you must

If a platform blocks SVG entirely, convert once in your pipeline (e.g. local tool) and commit PNG. That’s a fallback—not the default for your docs site, where SVG is usually better.

Advantages of the SVG path

1. No chart runtime in the doc UI — readers don’t download Chart.js to see a trend.
2. No third-party image host — nothing uploaded to a random CDN for a badge.
3. Sharp at any zoom — useful for docs and retina displays.
4. Same data model as HTML charts — type, series, axisX match ProvChart’s generate API.
5. CI-friendly — regenerate docs/charts/*.svg when metrics change; commit the artifact.
6. Fits the “pipeline” story — compile data → paint geometry; for Markdown the paint target is SVG instead of CSS-in-page.

When pure SVG is the better choice

• Personal knowledge bases, Notion-export-style vaults, and static doc sites you control
• GitHub/GitLab asset charts (versioned next to the repo)
• Design systems / architecture READMEs that should stay dependency-light
• Agent or cron jobs that refresh charts without opening a browser

Use HTML + CSS (/api/v1/generate) when the chart lives inside a web app where theme tokens and layout already use CSS.

Minimal Node helper (write a file)

import fs from "node:fs";

const res = await fetch("https://provchart-api.devtem.org/api/v1/generate-svg", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.PROVCHART_API_KEY,
  },
  body: JSON.stringify({
    type: "area",
    series: [{ name: "Views", color: "#4fd8c4", points: [10, 25, 40, 55, 48] }],
    axisX: ["Mon", "Tue", "Wed", "Thu", "Fri"],
    width: 640,
    height: 240,
  }),
});

const data = await res.json();
if (!data.success) throw new Error(data.error);
fs.writeFileSync("docs/charts/views.svg", data.svg);

Point Markdown at ./docs/charts/views.svg.

Troubleshooting

Links

• SVG API: ProvChart docs – generate-svg
• Guide: Charts in Markdown & docs
• Pricing (quota): chart.devtem.org/pricing

Markdown support for data: URIs is inconsistent. For public README and most docs, generate SVG - save file - ![](./chart.svg). Use data URIs for experiments; use inline SVG only where your engine allows HTML. That’s how you get charts in docs.