DEV Community: ProvChart

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

FSCSS — Mon, 24 Aug 2026 11:08:20 +0000

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

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

Platform reality: not every Markdown engine is equal

Approach	GitHub README	Many static docs	Personal / controlled MD	Notes
Data URI `![](data:image/svg+xml;...)`	Often fragile	Sometimes OK	Often OK	Long base64 can break or get sanitized
`<img src="data:...">`	Limited	Varies	Often OK	Same length / sanitize issues
File `![](./chart.svg)`	✅ Reliable	✅ Reliable	✅ Best default	Commit the SVG; no key in the repo
Inline `<svg>`	❌ Usually stripped	Sometimes	✅ If HTML allowed	Great for MDX / some SSGs
Raster PNG/WebP	✅	✅	✅	Use only if the host blocks SVG

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

No chart runtime in the doc UI — readers don’t download Chart.js to see a trend.
No third-party image host — nothing uploaded to a random CDN for a badge.
Sharp at any zoom — useful for docs and retina displays.
Same data model as HTML charts — type, series, axisX match ProvChart’s generate API.
CI-friendly — regenerate docs/charts/*.svg when metrics change; commit the artifact.
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

Symptom	Likely cause	Fix
Broken image in README	Data URI too long / blocked	Commit `.svg` + relative path
401	Bad or revoked key	New key in Dashboard → Developer API
429	Monthly limit	Upgrade plan or wait for reset
Empty graphic	Bad payload	Check `series[].points` and `axisX`

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.

Email Charts with the ProvChart API

FSCSS — Sun, 23 Aug 2026 10:41:23 +0000

Most chart libraries assume a browser that runs JavaScript. Email clients don't give you that. If you want a chart in a weekly digest, you need something that renders without a script tag, or a step that turns a chart into an image before it ever reaches an inbox.

That's the problem ProvChart's API is built for. It returns HTML and CSS, generated server-side, and you decide from there whether to rasterize it into a PNG or embed a tightly controlled snippet. This post walks through the flow, the chart types that actually work in a digest, and a handful of practical tips for running this in production.

Why email is different

The inbox never needs to see your API key or your chart library. It only needs a static image and a link back to the live dashboard. Everything else, the data pull, the payload mapping, the API call, happens on your server or in a worker, before the send.

The flow

Pull analytics for the period, from your API, warehouse, or database
Map the rows into a ProvChart payload (type, series, axisX, theme)
POST /api/v1/generate with your API key
Turn the returned html and css into a PNG (or store the snippet)
Embed the result in your email template with a CTA back to the dashboard

Mapping analytics to a payload

Keep a single mapper function so every report type shares the same shape:

function analyticsToPayload(report) {
  return {
    type: "line",
    series: [
      {
        name: "Revenue",
        color: "#8b7bff",
        points: report.revenueByDay.map(d => d.value)
      },
      {
        name: "Orders",
        color: "#4fd8c4",
        points: report.ordersByDay.map(d => d.value)
      }
    ],
    axisX: report.revenueByDay.map(d => d.label),
    theme: {
      bg: "#0c0a16",
      surface: "#1a1628",
      text: "#eae7f5",
      muted: "#837da0",
      grid: "#8b7bff",
      radius: "12px"
    }
  };
}

Swap the data source underneath it, but keep the function stable. Weekly, monthly, and alert emails all stay consistent this way.

Chart types that actually work in a digest

Use case	Type	Why
Trend over 7–30 days	`line` / `area`	Readable as a simple story
Channel or category mix	`bar`	Clear comparison
Goal or conversion	`gauge`	One number, high impact
Share of total	`stackedbar`	Good for mix breakdowns

Skip dense scatter plots or multi-combo charts in email. Save those for the product UI, where someone can actually zoom in and interact.

Ten things worth doing

Generate server-side. The send job or worker owns the API key, the payload, and the output. Never call the API from the client.
Prefer images for email clients. The reliable path is: analytics → API → html/css → headless render (Playwright or Puppeteer) → PNG → CDN → <img> in the template. This works across Gmail, Outlook, and Apple Mail.
Design for one glance. Each chart should answer one question: did revenue rise, which channel led. Cap it at one or two series and 7–14 data points. Put the headline number in the subject line or preheader.
Cache by payload hash. Identical type, series, labels, and theme should produce identical output. Cache the html/css or the PNG so repeat sends don't burn quota.
Check usage before bulk sends. Hit GET /api/v1/usage first. If remaining is low, drop the optional charts or fall back to number-only blocks rather than hitting MONTHLY_LIMIT_REACHED mid-campaign.
Theme for email, not the admin UI. Use higher contrast and a background that matches your template. A dedicated theme object for digests versus in-app charts goes a long way.
Always add a CTA. A simple "Full dashboard →" link under the chart. The email is the snapshot; the app is where people explore.
Keep one layout per digest type. Hero metric, one trend chart, one breakdown, a few bullets, then the CTA. Change the data, not the structure.
Validate before you generate. Empty series, non-numeric points, or oversized arrays waste generations. Enforce max points and required fields in the mapper itself.
Proxy the key. Production frontends shouldn't hold the secret key at all. Route browser requests through your own backend before they reach ProvChart.

A minimal server-side example

const payload = analyticsToPayload(weeklyReport);

const res = await fetch("https://provchart-api.devtem.org/api/v1/generate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.PROVCHART_API_KEY
  },
  body: JSON.stringify(payload)
});

const data = await res.json();
if (!data.success) throw new Error(data.error);

// Option A: rasterize data.html + data.css into a PNG, upload it, then <img src="...">
// Option B: store the snippet for a web version of the same report

Do / Don't

Generate server-side
Map analytics to a fixed payload shape
Cache by hash
Prefer line, bar, or gauge charts
Link back to the live dashboard

Don't

Call the API from the inbox
Build ad-hoc JSON for every send
Regenerate identical charts
Pack five dense series into a digest
Expect full interactivity in email

Next steps

Introduction to ProvChart — Charts Without the JavaScript Tax

FSCSS — Sat, 22 Aug 2026 08:28:32 +0000

Introduction to ProvChart

Most charting libraries ask you to ship 40–150 kb of JavaScript, wait for hydration, and hope crawlers eventually see the chart.

ProvChart takes a different path.

It turns your data into CSS custom properties. The browser paints the chart with native CSS (clip-path, gradients, and a few carefully chosen rules). The result is a chart that:

Loads with the first paint
Ships zero chart library to the page
Is fully visible to search engines on the first crawl
Can still be updated by changing CSS variables

No canvas. No SVG charting runtime. No “wait for JS.”

The idea in one sentence

Data → CSS variables → browser paints the shape.

You (or the API) compile points into variables like --p1, --p2, ….

A pure CSS structure uses those variables to draw lines, areas, bars, or gauges.

After that, the page doesn’t need a charting library at all.

What you get

Feature	Detail
Output	Self-contained HTML + CSS
Runtime on the page	None for the chart itself
Types	Line, area, bar, stacked bar, horizontal bar, scatter, combo, gauge
Themes	Dark, light, midnight, or fully custom
SEO	Chart markup is in the first HTML response
Updates	Change CSS variables (or regenerate) — no virtual DOM chart layer

There is also a Developer API: send JSON, get back { html, css }, inject into any page or pipeline.

Who it’s for

Teams that care about LCP, TTI, and bundle size
Marketing and docs sites that need crawlable charts
Static or mostly-static pages that still need real data viz
Backends that want to generate charts for emails, reports, or static builds without shipping a client-side chart library

If you need heavy interaction, streaming of thousands of points, or complex JS-driven animations, a traditional library may still fit better. ProvChart optimizes for performance, simplicity, and SEO.

Quick taste (API)

const res = await fetch("https://provchart-api.devtem.org/api/v1/generate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    type: "line",
    series: [
      { name: "Revenue", color: "#8b7bff", points: [20, 35, 48, 66] },
      { name: "Users", color: "#4fd8c4", points: [12, 28, 41, 55] }
    ],
    axisX: ["Jan", "Feb", "Mar", "Apr"]
  })
});

const data = await res.json();
// data.html + data.css → inject into the page

Free accounts get a few test generations so you can try the full flow.

Pro and Business unlock higher monthly limits for production use.

Open source core + hosted product

Rendering core: st-core.fscss (MIT) — pure CSS chart primitives for the FSCSS ecosystem
Hosted product: ProvChart — visual builder, dashboard, Developer API, billing (by DevTemple)

You can use the open-source core on its own, or the hosted API when you want keys, limits, and multi-series generation without maintaining the engine yourself.

Try it

Link	What
chart.devtem.org	Product home
Get started	Free visual builder (no signup for single-series)
Docs	Core + Developer API
Pricing	Free / Pro / Business

What’s next from this org

We’ll publish short, practical posts on:

Building a small chart generator with the API
Using ProvChart in email digests (server-side → image/snapshot)
Performance and SEO notes vs typical JS chart stacks
Themes, multi-series patterns, and real dashboard layouts

If you care about charts that stay fast and crawlable, you’re in the right place.

ProvChart — charts without the JavaScript tax.

chart.devtem.org