DEV Community: Accreditly

Screenshot Every Page of a Website from Its Sitemap with One Node.js Script

Accreditly — Sat, 17 Oct 2026 12:23:08 +0000

You're about to relaunch a site and someone asks for a screenshot of every page as it stands today. Or a client wants to sign off 140 pages of copy, or legal wants a dated record of what the pricing page said. Doing it by hand means opening each URL, waiting for the lazy images, closing the cookie banner and saving the file under a name you'll still understand next month. Two minutes a page adds up to most of a working day for a 200-page site.

So I wrote one Node.js script that reads the sitemap, captures every page at desktop and mobile widths in real Chrome, and leaves a folder of named PNGs, a CSV manifest and a contact sheet. Last run: 38 full-page captures in 35 seconds, no failures.

Disclosure: I run HTML to Image, and the script uses its Screenshot API for the captures. This is a cross-post of the full guide on the HTML to Image blog, which is the canonical version and goes further into webhooks, costs and compliance archives.

Prerequisites

Node.js 18 or later, for the built-in fetch.
An HTML to Image API key. The free credits are enough to try this on a handful of pages.
A site with a sitemap, or a text file of URLs from a crawl.

npm install @html2img/client
export HTML2IMG_API_KEY=your_api_key

Step 1: Find the sitemap

Most sites declare their sitemap in robots.txt, so check there first:

curl -s https://example.com/robots.txt | grep -i '^sitemap:'

If nothing comes back, try /sitemap.xml, then /sitemap_index.xml (Yoast and Rank Math on WordPress), then /wp-sitemap.xml (WordPress core since 5.5). Big sites use a sitemap index that points at child sitemaps, some of them gzipped. The script follows all of that, so you only ever pass the top-level URL.

One caveat: a sitemap is the list the CMS chooses to publish. Orphaned landing pages and anything marked noindex won't be in it. For a migration archive, cross-check against a crawl and feed the script a text file instead.

Step 2: The script

Save this as capture-site.mjs. It's long-ish because it handles the boring parts properly: sitemap indexes, .gz files, duplicates, a credit check before spending anything, four captures at a time, retries for errors that can recover, and the reports at the end.

// capture-site.mjs
// node capture-site.mjs https://example.com/sitemap.xml [--dry-run]
// node capture-site.mjs urls.txt
import { mkdir, readFile, writeFile } from 'node:fs/promises';
import { gunzipSync } from 'node:zlib';
import {
  Html2img,
  InsufficientCreditsError,
  TimeoutError,
  ServerError,
  ConnectionError,
} from '@html2img/client';

const SOURCE = process.argv[2];
const DRY_RUN = process.argv.includes('--dry-run');
const OUT = 'shots';
const CONCURRENCY = 4;
const MAX_ATTEMPTS = 3;

// One credit per page per variant.
const VARIANTS = [
  { name: 'desktop', width: 1440 },
  { name: 'mobile', width: 390 },
  // { name: 'pdf', format: 'pdf' }, // A4 document with a real text layer
];

// Sent with every capture.
const CAPTURE = {
  fullpage: true,
  css: `#onetrust-banner-sdk, .onetrust-pc-dark-filter, #CybotCookiebotDialog,
        .qc-cmp2-container, .osano-cm-window, #cookie-law-info-bar,
        .intercom-frame, #crisp-chatbox { display: none !important; }`,
};

const SKIP = /\.(pdf|jpe?g|png|gif|webp|svg|zip|mp4|xml)$/i;
const apiKey = process.env.HTML2IMG_API_KEY;
const client = DRY_RUN ? null : new Html2img(apiKey);

// 1. Every <loc> in a sitemap, following sitemap indexes and .gz files.
async function readSitemap(url, seen = new Set()) {
  if (seen.has(url)) return [];
  seen.add(url);
  const res = await fetch(url);
  if (!res.ok) throw new Error(`${url} returned ${res.status}`);
  let body = Buffer.from(await res.arrayBuffer());
  if (body[0] === 0x1f && body[1] === 0x8b) body = gunzipSync(body);
  const xml = body.toString('utf8');
  const locs = [...xml.matchAll(/<loc>\s*(?:<!\[CDATA\[)?(.*?)(?:\]\]>)?\s*<\/loc>/gs)]
    .map((m) => m[1].replace(/&(amp|apos|quot|lt|gt);/g, (_, e) =>
      ({ amp: '&', apos: "'", quot: '"', lt: '<', gt: '>' })[e]));
  if (!/<sitemapindex[\s>]/.test(xml)) return locs;
  const children = await Promise.all(locs.map((loc) => readSitemap(loc, seen)));
  return children.flat();
}

// 2. Same site only, no files, no duplicates.
const bare = (host) => host.replace(/^www\./, '');
function toPages(urls, onlyHost) {
  const pages = new Set();
  for (const raw of urls) {
    let u;
    try { u = new URL(raw.trim()); } catch { continue; } // header rows, blanks
    if (onlyHost && bare(u.hostname) !== bare(onlyHost)) continue;
    if (SKIP.test(u.pathname)) continue;
    u.hash = '';
    pages.add(u.href);
  }
  return [...pages];
}

// "/blog/launch-notes/" -> "blog__launch-notes"
let multiSite = false;
function fileName(page) {
  const { hostname, pathname, search } = new URL(page);
  const slug = (pathname + search)
    .replace(/^\/+|\/+$/g, '')
    .split('/')
    .map((part) => part.replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, ''))
    .join('__')
    .toLowerCase()
    .slice(0, 150) || 'home';
  return multiSite ? `${bare(hostname)}__${slug}` : slug;
}

async function creditsLeft() {
  const res = await fetch('https://app.html2img.com/api/me', {
    headers: { 'X-API-Key': apiKey },
  });
  if (!res.ok) throw new Error(`Key check failed with ${res.status}`);
  return (await res.json()).credits_remaining;
}

const retryable = (err) =>
  err instanceof TimeoutError ||
  err instanceof ServerError ||
  err instanceof ConnectionError ||
  err.errorCode === 'page_load_timeout';

// 3. One capture, retried on errors that are worth a second attempt.
async function capture({ page, variant }) {
  const { name, ...options } = variant;
  const ext = options.format === 'pdf' ? 'pdf' : 'png';
  const row = { page, variant: name, status: 'failed', file: '', image_url: '', error: '' };
  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
    try {
      const shot = await client.screenshot({ url: page, ...CAPTURE, ...options });
      row.image_url = shot.url;
      const img = await fetch(shot.url);
      if (!img.ok) throw new Error(`download returned ${img.status}`);
      row.file = `${name}/${fileName(page)}.${ext}`;
      await writeFile(`${OUT}/${row.file}`, Buffer.from(await img.arrayBuffer()));
      return { ...row, status: 'ok', error: '' };
    } catch (err) {
      if (err instanceof InsufficientCreditsError) throw err;
      row.error = err.errorCode ?? err.message;
      if (!retryable(err) || attempt === MAX_ATTEMPTS) return row;
      await new Promise((resolve) => setTimeout(resolve, 3000 * attempt));
    }
  }
}

// 4. A fixed number of captures in flight at once.
async function runAll(jobs) {
  const rows = [];
  let next = 0;
  let stopped = false;
  async function lane() {
    while (!stopped && next < jobs.length) {
      const job = jobs[next++];
      try {
        const row = await capture(job);
        rows.push(row);
        console.log(`${rows.length}/${jobs.length} ${row.status} ${row.variant} ${job.page}`);
      } catch (err) {
        if (!stopped) console.error(`Stopping early: ${err.message}`);
        stopped = true;
      }
    }
  }
  await Promise.all(Array.from({ length: CONCURRENCY }, lane));
  return rows;
}

// 5. A manifest for spreadsheets and an index.html for people.
async function writeReports(rows) {
  const cols = ['page', 'variant', 'status', 'file', 'image_url', 'error'];
  const cell = (v) => `"${String(v).replaceAll('"', '""')}"`;
  const csv = [cols, ...rows.map((r) => cols.map((c) => r[c]))]
    .map((line) => line.map(cell).join(','))
    .join('\n');
  await writeFile(`${OUT}/manifest.csv`, csv);

  const esc = (s) => s.replace(/[&<>"]/g, (c) => `&#${c.charCodeAt(0)};`);
  const cards = rows
    .filter((r) => r.status === 'ok' && r.file.endsWith('.png'))
    .map((r) => `<a href="${esc(r.file)}"><img src="${esc(r.file)}" loading="lazy"><span>${r.variant} · ${esc(r.page)}</span></a>`)
    .join('\n');
  await writeFile(`${OUT}/index.html`, `<!doctype html><meta charset="utf-8"><title>Site capture</title>
<style>body{font:14px system-ui;margin:24px;display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:20px}
a{color:#334155;text-decoration:none}img{width:100%;height:320px;object-fit:cover;object-position:top;border:1px solid #e2e6ec;border-radius:8px}
span{display:block;margin-top:6px;word-break:break-all}</style>\n${cards}`);
}

const fromSitemap = /^https?:\/\//.test(SOURCE);
const urls = fromSitemap
  ? await readSitemap(SOURCE)
  : (await readFile(SOURCE, 'utf8')).split(/\r?\n/);
const pages = toPages(urls, fromSitemap ? new URL(SOURCE).hostname : null);
multiSite = new Set(pages.map((page) => bare(new URL(page).hostname))).size > 1;

if (DRY_RUN) {
  console.log(pages.join('\n'));
  process.exit(0);
}

const jobs = pages.flatMap((page) => VARIANTS.map((variant) => ({ page, variant })));
const credits = await creditsLeft();
console.log(`${pages.length} pages x ${VARIANTS.length} variants = ${jobs.length} credits. Balance: ${credits}.`);
if (credits < jobs.length) {
  console.error('Not enough credits for the whole run. Trim the list or top up first.');
  process.exit(1);
}

for (const { name } of VARIANTS) await mkdir(`${OUT}/${name}`, { recursive: true });
const rows = await runAll(jobs);
await writeReports(rows);

const failed = rows.filter((r) => r.status !== 'ok').length;
const skipped = jobs.length - rows.length;
console.log(`Saved ${rows.length - failed}, failed ${failed}, skipped ${skipped}. Open ${OUT}/index.html`);

The css string is doing quiet but important work. The renderer arrives as a first-time visitor with no cookies, so every page shows its consent banner. Injecting display: none !important for the common consent providers and chat widgets takes them out before the shot. If a site uses something else, find the banner's ID in dev tools and add it.

Step 3: Dry run first, then capture

--dry-run prints the URLs the script would capture. It doesn't need a key and spends nothing, so use it to filter out tag archives, paginated listings and anything else you don't need a picture of:

node capture-site.mjs https://html2img.com/sitemap.xml --dry-run | grep '/tools/' > urls.txt
node capture-site.mjs urls.txt

That's the real run I mentioned at the top, against the free tools section of my own site:

19 pages x 2 variants = 38 credits. Balance: 100.
1/38 ok desktop https://html2img.com/docs/mcp/tools/
2/38 ok mobile https://html2img.com/docs/mcp/tools/
3/38 ok desktop https://html2img.com/tools/
4/38 ok mobile https://html2img.com/tools/
...
38/38 ok desktop https://html2img.com/tools/youtube-thumbnail/
Saved 38, failed 0, skipped 0. Open shots/index.html

Spot the first line. My lazy grep also matched /docs/mcp/tools/, which I never meant to include. That's exactly why the dry run exists: grep '^https://html2img.com/tools/' would have kept it out.

The desktop captures came back 1,440 pixels wide and between 3,737 and 10,016 pixels tall. Here's the index.html the run produced, each card cropped to the top of its page:

What the script does when things go wrong

Not every page cooperates, so the retry logic only retries what a second attempt can fix:

504 timeouts, 500s, slow-loading sites and dropped connections get two more attempts, 3 then 6 seconds apart.
Dead links, SSL failures and sites that block automated visitors (url_not_found, url_unreachable, connection_refused) are logged in manifest.csv and skipped.
Running out of credits stops every lane, still writes the reports, and tells you how many captures were skipped.

To re-run only the failures, pull them out of the manifest and run them in a fresh folder so the first run's reports stay intact:

awk -F'","' '$3 == "failed" { print substr($1, 2) }' shots/manifest.csv | sort -u > retry.txt
mkdir retry && cd retry && node ../capture-site.mjs ../retry.txt

Keep CONCURRENCY low for sites you don't own. Every capture is a real page load against somebody's production server.

A few limits worth planning around

Public pages only. The renderer has no cookies or headers, so anything behind a login captures as the sign-in page.
Infinite scroll has no bottom. Cap the feed with injected CSS such as main.feed { max-height: 12000px; overflow: hidden; }.
Closed accordions stay closed. Nobody clicks during a capture, so open hidden panels with CSS if they matter.
One credit per page per width. Desktop plus mobile doubles the cost, and the PDF variant adds a third.

Where I'd use this

Before a migration, so you have the old site on disk the day the DNS switches. For client sign-off, where one contact sheet beats 200 links. And for compliance, where the commented-out pdf variant gives you searchable A4 documents in a dated folder.

The full guide on the HTML to Image blog also covers handing long captures to a webhook instead of waiting on them, a bash version for short URL lists, and what a full-site capture costs at different sizes.

How are you archiving sites before a relaunch at the moment? Browser extension, Screaming Frog, something homegrown? Let me know in the comments.

I Tested html2canvas, html-to-image and modern-screenshot on the Same Card

Accreditly — Fri, 09 Oct 2026 20:10:14 +0000

You need a "download as image" button, a shareable stats card, or a PNG of a chart, and the first three npm results are html2canvas, html-to-image and modern-screenshot. Between them they were downloaded about 120 million times last month. They do not work the same way, and the differences only show up once your component uses a web font, a photo from another domain, or any CSS written in the last five years.

So I ran all three against the same card, in Chromium and in WebKit (the engine behind Safari), with each library's defaults, and rendered the same markup on a server for comparison. Every image below is real output.

One disclosure before the results: I run HTML to Image, a rendering API, which has no connection to the html-to-image npm package despite the name. The API only turns up at the end, as the server-side comparison, and the three libraries are judged on their own output.

This is a cross-post of the full write-up on the HTML to Image blog, which is the canonical version if you want to link to it.

The test card

The component is a 760×420 "year in review" card of the kind apps let you download and share. Each part of it exercises something a capture library has to get right:

Fonts: Fraunces for the headline and Manrope for everything else, loaded from Google Fonts with a <link> tag.
A cover photo from another origin, which is how most apps serve user and product images.
A frosted badge over the photo, using backdrop-filter: blur().
A gradient headline, using background-clip: text.
A donut chart drawn with conic-gradient.
An inline SVG sparkline.
A rotated stamp with filter: drop-shadow().

This is the card as Chrome renders it:

The capture code is each library's documented one-liner, run on the same node:

import html2canvas from 'html2canvas';
import { toPng } from 'html-to-image';
import { domToPng } from 'modern-screenshot';

const node = document.getElementById('frame');

const fromHtml2canvas = (await html2canvas(node, { useCORS: true })).toDataURL('image/png');
const fromHtmlToImage = await toPng(node);
const fromModernScreenshot = await domToPng(node);

The versions tested were html2canvas 1.4.1, which is still its latest release and dates from January 2022, html-to-image 1.11.13 from February 2025, and modern-screenshot 4.7.0 from April 2026. The browsers were Playwright's Chromium 153 and WebKit 26.6 builds, at a device pixel ratio of 1.

Two ways to turn the DOM into pixels

The results make sense once you know there are only two techniques here.

html2canvas repaints the page itself. It walks the DOM, reads each element's computed styles, and draws every box, border, gradient and line of text onto a canvas with its own code. Layout comes from the browser, but painting does not, so any CSS feature html2canvas has not implemented is skipped.

html-to-image and modern-screenshot let the browser paint. They clone the node, copy the computed styles onto the clone, embed every font and image as a data URL, and wrap the result in an SVG <foreignObject>. The browser then draws that SVG onto a canvas with its real rendering engine, so modern CSS comes through. The catch is the embedding step: every font file and image has to be readable by JavaScript, which puts CORS in charge of what ends up in your PNG.

The results in Chromium

With the fonts fixed (more on that in a moment), this is what each library produced, next to the same markup rendered by Chrome on a server:

html2canvas lost four of the seven features. The headline came out as a solid gradient bar with no text, because background-clip: text is not implemented, so it painted the background and never cut the letters out of it. The donut vanished with conic-gradient. The stamp lost its glow because filter is ignored, and the badge lost its frosting because backdrop-filter is too. It is also the only library that skips cross-origin images by default: without useCORS: true, the cover photo is simply left blank.

It was fast, though. Without the photo a capture took about 100 ms; with it, 0.7 to 0.9 seconds.

html-to-image and modern-screenshot both matched the on-screen render. html-to-image's first capture took 1.3 seconds while it fetched and inlined the fonts and the photo, and a second capture on the same page took 52 ms because those were cached. modern-screenshot took 0.6 to 0.7 seconds every time.

That is the good news. The next three sections are what it took to get there, and what happened when the conditions were less friendly.

Trap 1: web fonts from a `<link>` tag

On the first run, the two foreignObject libraries produced a card in the wrong fonts. The badge, the "cups this year" label and the stamp all wrapped onto two lines, because the fallback font was wider than Manrope:

To embed a font, these libraries need the @font-face rules, and a script cannot read the rules of a stylesheet from another origin unless the stylesheet was fetched in CORS mode. html-to-image says so in the console:

Error while reading CSS rules from https://fonts.googleapis.com/css2?family=Fraunces...
SecurityError: Failed to read the 'cssRules' property from 'CSSStyleSheet': Cannot access rules

modern-screenshot hit the same wall without logging anything. Google Fonts sends Access-Control-Allow-Origin: *, so the fix is one attribute:

<link
  href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,700&family=Manrope:wght@500;700;800&display=swap"
  rel="stylesheet"
  crossorigin="anonymous">

Self-hosting the font files on your own origin works too. html2canvas is not affected by this one, because it draws text onto the canvas with whatever fonts the page has already loaded.

Trap 2: the first capture in Safari's engine

WebKit is where the libraries separated. html-to-image's first toPng() call returned the card without its cover photo, and a second call on the same page, a moment later, included it:

It happened in both test runs, with and without the font fix, and nothing in the markup changed between the two calls. modern-screenshot was correct on the first call in WebKit every time. html2canvas behaved the same in both browsers, which in this case means the same four missing features.

If you stay on html-to-image, capturing twice and keeping the second result worked in every WebKit run here. It also doubles the work of every capture in Safari.

Trap 3: images from a host without CORS headers

The cover photo in the runs above came from a host that sends Access-Control-Allow-Origin. Plenty do not: an S3 bucket only sends it once someone adds a CORS configuration, and many image hosts never do. So I moved the same photo to a host that sends no CORS headers and ran everything again:

Each library failed differently, and only one of them told you:

html2canvas dropped the photo, with or without useCORS, and resolved normally.
html-to-image rejected the whole capture. The rejection was a DOM Event with the type error, not an Error, so err.message is undefined and a typical logger records nothing useful.
modern-screenshot replaced the photo with its default placeholder, a transparent 1×1 GIF, and resolved normally.

Wherever you capture client-side, wrap the call so a failure says what it was:

async function captureCard(node) {
  try {
    return await toPng(node);
  } catch (err) {
    // A failed image load rejects with a DOM Event, not an Error.
    const reason = err instanceof Event ? `${err.type} event while loading an image` : err.message;
    throw new Error(`Card capture failed: ${reason}`);
  }
}

Both foreignObject libraries can also put a stand-in in place of a broken image: imagePlaceholder in html-to-image, and fetch.placeholderImage in modern-screenshot. That keeps the capture from failing, but the photo is still missing. The real fixes are on the server: add CORS headers to the image host, proxy images through your own origin, or render somewhere CORS does not apply.

The scorecard

Defaults, the same card, both browsers:

	html2canvas 1.4.1	html-to-image 1.11.13	modern-screenshot 4.7.0	Server render
Web fonts from a `<link>`	Yes	Only with `crossorigin`	Only with `crossorigin`	Yes
Cross-origin image, host sends CORS	Only with `useCORS: true`	Yes	Yes	Yes
Cross-origin image, no CORS headers	Dropped silently	Capture rejects	Transparent pixel	Yes
`background-clip: text`	Solid bar	Yes	Yes	Yes
`conic-gradient`	Missing	Yes	Yes	Yes
`filter: drop-shadow()`	Ignored	Yes	Yes	Yes
`backdrop-filter`	Ignored	Yes	Yes	Yes
First call in WebKit	Same as later calls	Photo missing	Correct	Not applicable
Capture time, Chromium, with photo	0.7 to 0.9 s	1.3 s, then 0.05 s	0.6 to 0.7 s	About 2 s including network

If you are choosing a client-side library today, modern-screenshot was the most dependable of the three in this test. html-to-image is close behind once you deal with the font link and the first Safari capture. html2canvas has not had a release since January 2022 and only suits components built from flat colours, borders and plain text.

When the browser is the wrong place to render

Everything above assumes the image should come from the visitor's browser. That is the right call for a download button: the user is looking at the card, the libraries are free, and nothing leaves the device.

It is the wrong call when the output has to be the same for everyone. The PNG a client-side library produces depends on the visitor's browser, their installed fonts, and whether every image host on the page sends CORS headers. Server-side, all three of those stop being variables. Render on a server when the image is a share card or an Open Graph image, goes into an email, is generated without anyone's browser open (a cron job, a webhook, a batch of certificates), or uses images from hosts you do not control.

The server-side version of the card is the same HTML and CSS sent to an API. In Node, with the official client:

import { Html2img } from '@html2img/client';

const client = new Html2img(process.env.HTML2IMG_API_KEY);

const response = await client.html({
  html: cardHtml, // the card's markup with its <style> and font <link>
  width: 808,
  height: 468,
});

console.log(response.url); // hosted PNG, 2x by default

If the card is a React component, renderToStaticMarkup from react-dom/server gives you cardHtml from the same props the page uses, so the shared image and the on-screen card cannot drift apart. And if the thing you want is a component on a live page, the Screenshot API can capture a single element from a URL by its CSS selector, which is the server-side equivalent of passing a DOM node to one of these libraries.

The quickest way to see how one of your own components behaves is to paste its markup into the free HTML to Image Converter and compare the result with what your library of choice gives you. If your cards end up as link previews, Satori's CSS limits are worth knowing too: it is another engine that reimplements CSS instead of using a browser, with a similar list of gaps.

The full write-up lives on the HTML to Image blog, with the comparison images at full size.

Which of the three are you running in production, and has Safari's first capture caught you out yet? Share your experience in the comments below.

Invoice PDFs from one API call: what I sent, what came back, and how I checked it was a real PDF

Accreditly — Wed, 16 Sep 2026 12:46:44 +0000

Every billing system I have worked on has had the same weak spot. The data model is fine, the totals are right, the emails go out. Then someone in accounts opens the attached invoice, tries to copy the invoice number into their ledger, and finds it is a picture.

That happens because generating the file is the part nobody wants to own. You either bolt on a PDF library that fights your CSS, or you run headless Chrome in production and discover what a month-end batch does to memory. I have done both. This time I wanted the invoice PDF to be one HTTP call from a queued job, and I wanted to prove the result was a real PDF before a customer saw it.

I wrote up the full setup, including the receipt variant and the Laravel job, in Invoice PDF API: Generate Invoice and Receipt PDFs from HTML on html2img.com. This post is the shorter, first-person version: what I sent, what came back, and the checks I ran.

Prerequisites

An HTML to Image API key (the free tier is enough to follow along)
curl, and poppler-utils for pdfinfo, pdffonts and pdftotext
Node 18+ if you want to run the receipt example

Step 1: send the invoice as JSON and ask for a PDF

The invoice image template takes the invoice as plain JSON. There is no HTML to write. The trick I did not know until recently is that every template accepts a format key, and setting it to pdf swaps the PNG for an A4 document.

curl -X POST https://app.html2img.com/api/v1/templates/invoice-image \
  -H "X-API-Key: $HTML2IMG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-2026-0912",
    "issue_date": "16 Sep 2026",
    "due_date": "16 Oct 2026",
    "business_name": "Fieldgate Studio Ltd",
    "business_address": "4 Watergate Row\nChester CH1 2LE\nUnited Kingdom",
    "client_name": "Northgate Coffee Ltd",
    "client_address": "18 Bold Street\nLiverpool L1 4DS\nUnited Kingdom",
    "items": [
      {"description": "Online ordering system, phase 2", "quantity": "1", "unit_price": "$6,400.00", "amount": "$6,400.00"},
      {"description": "Menu photography (half day)", "quantity": "2", "unit_price": "$550.00", "amount": "$1,100.00"},
      {"description": "Hosting and monitoring, Q4", "quantity": "3", "unit_price": "$120.00", "amount": "$360.00"},
      {"description": "Support retainer (hours)", "quantity": "8", "unit_price": "$95.00", "amount": "$760.00"}
    ],
    "subtotal": "$8,620.00",
    "tax_label": "VAT (20%)",
    "tax_amount": "$1,724.00",
    "total": "$10,344.00",
    "notes": "Payment due within 30 days by bank transfer.",
    "format": "pdf"
  }'

Notice that every amount is a string. The template renders what you give it and does no arithmetic, which I think is the right call. My app already knows how to format money for the customer; the last thing I want is an API rounding differently to my ledger.

The response is a JSON envelope with a url that ends in .pdf:

{
  "success": true,
  "id": "968de823-85ed-4e79-904d-96168ab85240",
  "template": "invoice-image",
  "credits_remaining": 1234,
  "url": "https://i.html2img.com/image-1789562462319-296970.pdf"
}

Here is the same request rendered as a PNG so you can see the layout. The actual PDF is here if you want to open it and highlight the text.

Step 2: check it is a document, not a screenshot

This is the step I would not skip. Plenty of "HTML to PDF" services hand you a PNG inside a PDF wrapper, and you only find out when a customer cannot search it. Three commands settle it:

curl -sL "https://i.html2img.com/image-1789562462319-296970.pdf" -o invoice.pdf

pdfinfo invoice.pdf | grep -E "Pages|Page size|Producer"
pdffonts invoice.pdf
pdftotext -layout invoice.pdf - | head -30

What I got back:

Producer:  Skia/PDF m131
Pages:     1
Page size: 595.92 x 841.92 pts (A4)

pdffonts listed the template's Open Sans weights as embedded, subsetted TrueType. pdftotext printed the parties, every line item, the VAT row and the total, in reading order. So it is a Chromium-rendered vector PDF with a proper text layer, and the number in accounts can copy is actually copyable.

Step 3: the receipt, twice from one function

Receipts are the same idea with a smaller payload, and in practice I render them twice: a PNG for the confirmation email body and a PDF for the customer to file for expenses. One function, one argument:

const ENDPOINT = 'https://app.html2img.com/api/v1/templates/receipt-image';

async function renderReceipt(order, format = 'png') {
  const res = await fetch(ENDPOINT, {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.HTML2IMG_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      business_name: 'Northgate Coffee',
      order_number: order.number,
      order_date: order.placedAt,
      customer_name: order.customer.name,
      items: order.lines.map((l) => ({
        name: l.name,
        qty: String(l.qty),
        amount: l.amountFormatted,
      })),
      subtotal: order.subtotalFormatted,
      shipping: order.shippingFormatted,
      tax_amount: order.taxFormatted,
      total: order.totalFormatted,
      thank_you_message: 'Thanks for your order. Keep this receipt for your records.',
      format,
    }),
  });

  if (!res.ok) throw new Error(`Receipt render failed: ${res.status}`);
  return (await res.json()).url;
}

const pngUrl = await renderReceipt(order);
const pdfUrl = await renderReceipt(order, 'pdf');

Two renders is two credits. That is still less than the cost of one browser process sitting idle on a server all month, which is what it replaced.

Step 4: when the template is not your brand, send your own HTML

The template covers the common case. When it does not, the /api/html endpoint takes your own markup with the same format key. From Laravel that is a Blade view and one Http call:

$html = view('invoices.pdf', ['invoice' => $invoice])->render();

$url = Http::withHeaders(['X-API-Key' => config('services.html2img.key')])
    ->timeout(60)
    ->post('https://app.html2img.com/api/html', ['html' => $html, 'format' => 'pdf'])
    ->throw()
    ->json('url');

Three things I learned about the stylesheet, because a PDF paginates and an image does not:

The PDF uses your screen CSS. @media print rules are not applied. Everything the document needs goes in the normal styles.
Pages are A4 portrait and content reflows to the page width. Design the invoice to flow, not to a fixed 1240px canvas.
break-inside: avoid on tr and on the totals block works. <thead> does not repeat on page two, so if your invoices run long, repeat the header row yourself.

To check the pagination under load I pushed a 34-line invoice through. It came back as two clean A4 pages with no row split across the break and the totals kept together at the top of page two.

Step 5: put it in a queued job and keep the bytes

The one design rule I would push on anyone doing this: do not return the CDN URL to the customer. Render in a queued job when the invoice is finalised, download the PDF into your own storage keyed by invoice number, and attach from there. Free-tier CDN files expire after seven days, and on any plan the invoice needs to still exist when an auditor asks in five years.

class RenderInvoicePdf implements ShouldQueue
{
    public int $tries = 3;

    public function __construct(public Invoice $invoice) {}

    public function handle(): void
    {
        $response = Http::withHeaders(['X-API-Key' => config('services.html2img.key')])
            ->timeout(60)
            ->post('https://app.html2img.com/api/v1/templates/invoice-image', [
                ...$this->invoice->toTemplatePayload(),
                'format' => 'pdf',
            ])
            ->throw();

        $path = "invoices/{$this->invoice->year}/{$this->invoice->number}.pdf";
        Storage::disk('s3')->put($path, Http::get($response->json('url'))->body());

        $this->invoice->update(['pdf_path' => $path]);
        Mail::to($this->invoice->client_email)->send(new InvoiceIssued($this->invoice));
    }
}

If you are generating thousands at month end, pass a webhook_url in the request instead and let the callback drive the storage step rather than holding a worker on each render.

What I would tell past me

The invoice PDF was never the hard part; owning a renderer was. One extra key on a request I was already making, three commands to prove the output is real, and a job that keeps the bytes. The longer version with the receipt reference, the page-break stylesheet and the full Laravel setup is in the html2img.com article.

How are you generating invoices today? If you are still on wkhtmltopdf or dompdf, I would be interested to hear what is keeping you there. Drop it in the comments.

Turn a JSON File of Testimonials into Quote Card Images with One Node.js Script

Accreditly — Sat, 12 Sep 2026 16:05:10 +0000

You have a folder of customer testimonials, or a spreadsheet of pull quotes, or a transcript with the best lines highlighted. What you do not have is forty quote card images, because someone has to open Figma forty times to make them.

This tutorial turns a JSON file of quotes into a folder of branded PNGs with one Node.js script and an HTML to Image API. If you want the longer version, with a custom-HTML layout and the reasoning behind the design choices, take a look at the full article on generating quote cards from an API. This post is the short, runnable path.

Prerequisites

Node.js 18 or later (we use the built-in fetch).
A free HTML to Image API key. Sign-up takes a minute and the free tier is enough to run everything here.
A testimonials.json file. Any shape works as long as each entry has the quote text and who said it.

Here's the one I'm using:

[
  {
    "quote": "We replaced a designer-in-the-loop process with one API call. The cards went out the same afternoon the quotes came in, and nobody could tell they were not hand made.",
    "name": "Priya Raman",
    "role": "Head of Product, Fieldline"
  },
  {
    "quote": "Onboarding used to take our team a week. It now takes an afternoon.",
    "name": "Tomas Vale",
    "role": "Operations Lead, Harbourline"
  }
]

Step 1: Render one card by hand

Before writing the loop, make one request so you know what comes back. The quote card template takes the quote and the attribution as JSON and returns a hosted PNG:

curl -X POST https://app.html2img.com/api/v1/templates/quote-card \
  -H "X-API-Key: $HTML2IMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote": "We replaced a designer-in-the-loop process with one API call. The cards went out the same afternoon the quotes came in, and nobody could tell they were not hand made.",
    "attribution_name": "Priya Raman",
    "attribution_role": "Head of Product, Fieldline",
    "brand_name": "Fieldline",
    "background_color": "#FAF7F0",
    "accent_color": "#2563EB"
  }'

The response is small:

{
  "success": true,
  "template": "quote-card",
  "credits_remaining": 100,
  "url": "https://i.html2img.com/image-1789228709438-533456.png"
}

And the image at that URL looks like this:

Two things to notice. The type has been sized to the quote automatically, so a ten-word quote comes back bigger rather than sitting in a sea of empty space. And the single accent_color value is the only branding you have to think about; it shows up as the rule and the brand name and nowhere else.

Step 2: Write the loop

Now the script. It reads the JSON, renders one card per entry, and writes the resulting URL back onto each record:

// make-cards.mjs
import { readFile, writeFile } from 'node:fs/promises';

const API_KEY = process.env.HTML2IMG_API_KEY;
const testimonials = JSON.parse(await readFile('testimonials.json', 'utf8'));

for (const t of testimonials) {
  const response = await fetch('https://app.html2img.com/api/v1/templates/quote-card', {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      quote: t.quote,
      attribution_name: t.name,
      attribution_role: t.role,
      brand_name: 'Fieldline',
      background_color: '#FAF7F0',
      accent_color: '#2563EB',
    }),
  });

  const data = await response.json();

  if (!data.success) {
    console.error(`Failed for ${t.name}:`, data.error, data.errors ?? '');
    continue;
  }

  t.card_url = data.url;
  console.log(`${t.name}: ${data.url} (${data.credits_remaining} credits left)`);
}

await writeFile('testimonials.json', JSON.stringify(testimonials, null, 2));

Run it:

HTML2IMG_API_KEY=your_key node make-cards.mjs

The important design choice is writing card_url back into the source file. That makes testimonials.json the single source of truth: the marketing site reads the URL for the testimonial wall, the social scheduler reads it for the post, and re-running the script only renders entries that are missing a URL if you add a one-line if (t.card_url) continue; at the top of the loop.

Step 3: Download the files (optional)

The hosted URL is usually all you need, because it goes straight into a CMS field or a scheduling tool. If you want local files as well, for a pitch deck or a case study PDF, add a download after each render:

import { createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';

async function download(url, path) {
  const res = await fetch(url);
  await pipeline(res.body, createWriteStream(path));
}

// inside the loop, after t.card_url = data.url;
const slug = t.name.toLowerCase().replace(/[^a-z0-9]+/g, '-');
await download(data.url, `cards/${slug}.png`);

The template renders at 2x, so each file is 2400x2400 and around 1 to 1.5 MB. That is what you want for a retina social feed. For something lighter, render your own markup through the HTML endpoint at the default DPI instead; the full article shows a 1200x630 dark testimonial layout that comes back under 200 KB:

Step 4: Keep the batch honest

A few lines that stop a batch from going wrong quietly:

Watch the credit count. Every response carries credits_remaining, so break out of the loop when it hits zero rather than collecting a string of 402s.
Log validation errors, don't throw. A 422 comes with an errors object naming the field. The script above prints it and moves on, so one bad entry does not stop the other thirty-nine.
Use a webhook for large batches. For hundreds of cards, pass a webhook_url with each request and let the API post the finished URL back to you instead of holding the connections open one at a time.

That is the whole pipeline: a JSON file in, a JSON file with image URLs out, and a folder of PNGs if you want them. The full write-up goes further into building your own card layout in HTML, sizing the type to the quote length yourself, and producing the square, link-preview and Story formats from the same data.

How are you making quote and testimonial graphics at the moment? Still by hand, or have you automated it another way? Let me know in the comments.

How HTML to PDF Conversion Actually Works: Rendering Engines, Text Objects and Fonts

Accreditly — Thu, 03 Sep 2026 09:31:49 +0000

Two PDFs can look identical on screen and be completely different files. In one you can select a line, search for an invoice number and print it sharp at 300 dpi. The other is a photograph of a page: nothing to select, nothing to find, and every zoom step makes the text softer. Both came from HTML. Both came from something calling itself an HTML to PDF converter. The difference is what happened in the last few milliseconds of the render.

The full write-up, with the file internals and the font-embedding detail, is on the HTML to Image blog as How HTML to PDF conversion actually works. This is the short version: the pipeline, what "selectable text" really means, where fonts go, and three commands that tell you in seconds which kind of PDF you have been handed.

Same pipeline, different last step

A browser-based converter, whether that is headless Chrome on your own box, a Puppeteer script or a hosted API, runs exactly the pipeline it uses to put a page on your monitor. Parse HTML into a DOM. Resolve CSS into computed styles. Lay out every box in CSS pixels and break text into lines. Paint the result into a display list: fill this rect, stroke this border, draw these glyphs here.

The fork is stage five, when that display list is replayed into a backend. A raster backend replays it into pixels and writes a PNG. Chromium's PDF backend, part of the Skia graphics library, replays the same commands into PDF operators and writes a document. The commands are identical. What differs is what the backend is allowed to keep: text stays text, paths stay paths, fonts get subset and embedded, and only <img> and <canvas> content is stored as pixels.

That is also why a Chrome PDF matches a Chrome PNG so closely, and why the two most common failures, missing fonts and rasterised pages, both happen at stage five.

Pixels in, points out

CSS measures in pixels at 96 per inch. PDF measures in points at 72 per inch. So every CSS pixel becomes 0.75 pt, and an A4 page is 794 by 1123 CSS pixels in layout and roughly 595 by 842 pt in the file. You can see the arithmetic in pdfinfo:

$ pdfinfo invoice.pdf
Creator:         Chromium
Producer:        Skia/PDF m131
Tagged:          yes
Pages:           1
Page size:       595.92 x 841.92 pts (A4)
File size:       69467 bytes

The unit change explains a rule that surprises people: DPI does nothing to a PDF. Raising the device pixel ratio makes a screenshot sharper because it adds pixels. A vector page has no pixels to add, so a 1x render and a 4x render of the same HTML produce identical vector content.

What a text layer actually is

People say a PDF "has a text layer" as if it were a transparent sheet over an image. That is how OCR repairs a scan, and it is where the phrase comes from, but a properly generated PDF has no such thing. The text is not a layer on the page. The text is the page.

Inside a page's content stream you find text objects: select a font, set a position, draw a run of glyph IDs. Those IDs are indices into the embedded font, and on their own they mean nothing to a search box. What makes the text selectable is a second structure, the ToUnicode CMap, which maps each glyph ID back to the character it was drawn from. If it is missing, the text renders and scales perfectly but cannot be copied, and pdftotext returns garbage.

Run it on the invoice and every word comes back in reading order, including a word drawn with an inline <svg> <text> element, because Skia turns SVG text into the same text objects as HTML text:

$ pdftotext -layout invoice.pdf -
Northgate Coffee, invoice #1042
Issued 3 September 2026. Payment due within 30 days.

 ITEM                              QTY   PRICE
 Ethiopian Yirgacheffe, 1 kg       4     $72.00
 Filter papers, box of 100         2     $9.50
 Total                                   $81.50

How fonts get inside the file

A PDF that names a font without carrying it is at the mercy of whichever machine opens it, and the line lengths shift with every substitution. So the backend embeds fonts, and to keep files small it subsets them: only the glyphs actually drawn go in. The six-letter prefix on the name is the subset tag.

$ pdffonts invoice.pdf
name                              type          emb sub uni
--------------------------------- ------------- --- --- ---
AAAAAA+ManropeExtraLight_800wght  Type 3        yes yes yes
BAAAAA+ManropeExtraLight_500wght  Type 3        yes yes yes
FAAAAA+JetBrainsMono-Medium       CID TrueType  yes yes yes

Read the three right-hand columns. emb is whether the font data is in the file, sub whether it was subset, uni whether a ToUnicode map exists. You want yes yes yes on every row.

The type column has a story in it. Both faces came from Google Fonts. JetBrains Mono was served as a static file and went in as CID TrueType, the original outlines, the format every PDF tool likes. Manrope was served as a variable font, and Chrome embedded each instance as Type 3, where every glyph is its own little drawing procedure. Still vector, still selectable, and every mainstream viewer handles it, but PDF/A validators and some accessibility checkers are unhappy about Type 3. If your documents have to pass those, serve static font files instead of variable ones. Nothing else changes.

Vector where it can, raster where it must

Text, borders, gradients, shadows and inline SVG all go in as geometry. <img> and <canvas> go in as pixels at whatever resolution they arrived, which pdfimages -list shows you:

$ pdfimages -list invoice.pdf
page num type  width height  size ratio
   1   0 image    64    64    98B  0.8%

One small logo, 98 bytes. That is what a healthy document's image list looks like. If you are printing, supply bitmaps at two or three times their CSS size, or supply them as SVG and let them go in as paths.

The screenshot in a wrapper

Now the file from the first paragraph. It comes from tools with no PDF backend at all: they screenshot the page and write the bitmap into a PDF container, one image per page. The three commands expose it instantly.

$ pdffonts wrapped.pdf
name   type   encoding   emb sub uni
------ ------ ---------- --- --- ---

$ pdfimages -list wrapped.pdf
page num type  width height  size ratio
   1   0 image  1654  2339   1.9M   38%

$ pdftotext wrapped.pdf -
$

No fonts, because there is no text. One page-sized image per page. Nothing from pdftotext. The file is often ten to thirty times larger, and it gets worse exactly where PDFs matter, which is printing: 1654 by 2339 is 200 ppi on A4, and body text goes soft on a laser printer.

So "can I select the text" is the single best acceptance test for a converter. Not "does it look right", which every tool passes.

The three-command check

All three ship with Poppler (apt install poppler-utils, brew install poppler):

pdffonts  output.pdf          # every row: emb yes, sub yes, uni yes
pdfimages -list output.pdf    # one entry per real picture, no page-sized bitmaps
pdftotext output.pdf - | head # your content, in reading order

Empty pdffonts means a screenshot in a wrapper. emb: no means the document looks different on every machine. uni: no means text that renders but cannot be searched. A page-sized image in pdfimages means the page was rasterised.

If you want to try it on a real file, the HTML to PDF converter returns an A4 PDF from the same Skia backend described above, and from code it is one field on an image request to the HTML to PDF API: add "format": "pdf" and the response url points at a .pdf. The longer version on the blog covers screen versus print CSS, webfont timing, pagination and what actually drives file size: How HTML to PDF conversion actually works.

What is the worst PDF you have been handed by a converter, and did pdffonts come back empty? Share it in the comments.

Convert HTML to PDF in Node.js With One API Call

Accreditly — Wed, 26 Aug 2026 08:12:03 +0000

You have an invoice, a receipt or a report that already exists as HTML and CSS, and you need a Node.js process to turn it into a PDF. Not a person pressing print, a process: a payment webhook, a queue worker, a cron job, an API route. The usual advice is Puppeteer, which means shipping a copy of Chrome with your application, pinning its version, feeding it fonts and watching its memory. That is a lot of infrastructure to own for a document.

The alternative is one HTTP request. You send the markup with format: "pdf" and get back a URL to an A4 vector PDF: selectable text, embedded webfonts, automatic pagination. This guide does that in Node.js with the official @html2img/client package, then covers what a real integration needs on top: a template, downloading and attaching the file, fixed-width layouts, error handling and long documents.

This is the dev.to edition of a guide that lives on the HTML to Image blog as Convert HTML to PDF in Node.js With One API Call. The code is the same in both places; the original is where the linked parameter docs are kept current.

What one request gives you

The HTML to PDF API is the same endpoint as image rendering with one extra parameter. Your HTML is rendered in current Chrome and returned as a real PDF rather than a screenshot wrapped in a PDF shell:

Text is selectable and searchable, so the document works with copy and paste, search and screen readers.
Webfonts are embedded. Google Fonts, Adobe Fonts and self-hosted @font-face all load server-side and travel with the file.
Text, borders, shapes and gradients are vector, so they stay sharp at any zoom. Only <img> elements and canvases are embedded as pixels.
Long content paginates automatically across as many A4 pages as it needs.
Background colours, gradients and images are included by default.
The response url points at a .pdf on the CDN, served as application/pdf. A PDF costs the same single credit as an image.

Two things to know before you write any markup. Pages are A4 portrait, with no US Letter, landscape or custom sizes, and there are no header and footer slots. And the document is rendered with your normal screen CSS: @media print rules are not applied, so everything the PDF needs belongs in your standard styles. The format parameter docs cover the full behaviour, including which sizing parameters are ignored in PDF mode (width, height, dpi, fullpage and selector).

Prerequisites

Node.js 18 or newer, for the built-in global fetch. Bun and Deno work too.
An HTML to Image API key from the dashboard. Every account starts with free credits and no card is needed.
Some HTML you want as a PDF. The guide builds an invoice, but a receipt, report or certificate follows the same path.

Step 1: install the client and store your key

The official package has no runtime dependencies and is built on the standard fetch API, so it runs unchanged in Node.js 18 or newer, Bun, Deno and serverless runtimes.

npm install @html2img/client

Get an API key from the dashboard and put it in the environment, without a public prefix. This is a server-side client: the key spends credits, so it never goes anywhere near browser code.

# .env
HTML2IMG_API_KEY=your-api-key

The authentication docs cover rotating keys and checking a key with GET /api/me, which does not consume a credit.

Step 2: render your first PDF

The whole conversion is one call. Set format to 'pdf' and the response carries the URL of the finished document.

// render-pdf.mjs
import { Html2img } from '@html2img/client';

const client = new Html2img(process.env.HTML2IMG_API_KEY);

const response = await client.html({
  html: `<!doctype html>
<html>
  <body style="font-family: sans-serif; padding: 48px">
    <h1>Invoice #1042</h1>
    <p>Due within 30 days.</p>
  </body>
</html>`,
  format: 'pdf',
});

console.log(response.url);              // https://i.html2img.com/....pdf
console.log(response.creditsRemaining); // credits left on the account

Run it with node --env-file=.env render-pdf.mjs on Node 20.6 or newer, or load the .env file with dotenv on older versions. The response is a typed RenderResponse with url, id, creditsRemaining, expiresAt and raw, which holds the full decoded JSON if you want the envelope as the API sent it.

That is a working PDF. Everything from here is about making it a document you would put in front of a customer.

Step 3: build the document from a template

Keep the HTML in a function that takes your data and returns a complete document. Three rules make the output behave:

Write a flowing layout, not a fixed one. The A4 page is roughly 794 CSS pixels wide and content reflows to that width, so use percentages and flex rather than a hard width: 1200px.
Load fonts with a <link> tag or @import in the head. They are fetched at render time and embedded in the PDF.
Escape every value you interpolate. A customer called <script> should not become a script.

// invoice.mjs
const escape = (value) =>
  String(value).replace(/[&<>"']/g, (char) => ({
    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
  })[char]);

const money = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });

export function invoiceHtml(invoice) {
  const rows = invoice.items.map((item) => `
    <tr>
      <td>${escape(item.description)}</td>
      <td class="num">${item.quantity}</td>
      <td class="num">${money.format(item.unitPrice)}</td>
      <td class="num">${money.format(item.quantity * item.unitPrice)}</td>
    </tr>`).join('');

  const total = invoice.items.reduce((sum, item) => sum + item.quantity * item.unitPrice, 0);

  return `<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap" rel="stylesheet">
  <style>
    body { margin: 0; padding: 56px; font-family: 'Inter', sans-serif; font-size: 14px; color: #0f172a; }
    header { display: flex; justify-content: space-between; align-items: flex-start; margin-bottom: 40px; }
    h1 { margin: 0 0 4px; font-size: 28px; }
    .muted { color: #64748b; }
    table { width: 100%; border-collapse: collapse; margin-top: 24px; }
    th { padding: 0 0 8px; border-bottom: 2px solid #e2e8f0; text-align: left; font-size: 12px; text-transform: uppercase; letter-spacing: 0.06em; color: #64748b; }
    td { padding: 12px 0; border-bottom: 1px solid #e2e8f0; }
    .num { text-align: right; }
    tr { break-inside: avoid; }
    .total { display: flex; justify-content: flex-end; gap: 32px; margin-top: 24px; font-size: 18px; font-weight: 700; }
  </style>
</head>
<body>
  <header>
    <div>
      <h1>Invoice ${escape(invoice.number)}</h1>
      <div class="muted">Issued ${escape(invoice.issued)} &middot; Due ${escape(invoice.due)}</div>
    </div>
    <div>
      <strong>${escape(invoice.from.name)}</strong><br>
      <span class="muted">${escape(invoice.from.email)}</span>
    </div>
  </header>

  <div><span class="muted">Billed to</span><br><strong>${escape(invoice.to.name)}</strong></div>

  <table>
    <thead>
      <tr><th>Description</th><th class="num">Qty</th><th class="num">Unit</th><th class="num">Amount</th></tr>
    </thead>
    <tbody>${rows}</tbody>
  </table>

  <div class="total"><span>Total due</span><span>${money.format(total)}</span></div>
</body>
</html>`;
}

The tr { break-inside: avoid; } line is the one people forget. Without it, a line item that lands on a page boundary is cut in half, with its description at the foot of one page and its amount at the top of the next. Automatic pagination fills pages; it has no opinion about what belongs together, and you supply that opinion in CSS. How to control page breaks in HTML to PDF output covers the full set of fragmentation properties.

Because the renderer is real Chrome, the layout CSS you already use works: grid, flexbox, custom properties, gap, modern selectors. Can I use it in a PDF? compares that support against the other PDF engines if you are moving a template across from one of them.

Now render it:

// send-invoice.mjs
import { Html2img } from '@html2img/client';
import { invoiceHtml } from './invoice.mjs';

const client = new Html2img(process.env.HTML2IMG_API_KEY);

const invoice = {
  number: 'INV-1042',
  issued: '26 August 2026',
  due: '25 September 2026',
  from: { name: 'Northgate Coffee', email: 'billing@northgate.example' },
  to: { name: 'Riverside Bakery' },
  items: [
    { description: 'Wholesale beans, 5kg', quantity: 12, unitPrice: 48 },
    { description: 'Delivery', quantity: 1, unitPrice: 15 },
  ],
};

const { url } = await client.html({ html: invoiceHtml(invoice), format: 'pdf' });

console.log(url);

If you want to see what the markup will look like before spending a credit, paste it into the free HTML to PDF converter. It runs the same renderer.

Step 4: download the file, attach it, or keep the URL

The response carries a hosted URL rather than the bytes, which is usually what you want: store it against the order and link to it from the account page. When you need the file itself, for an email attachment or your own storage, fetch it:

import { writeFile } from 'node:fs/promises';

const render = await client.html({ html: invoiceHtml(invoice), format: 'pdf' });

const file = await fetch(render.url);
const pdf = Buffer.from(await file.arrayBuffer());

await writeFile(`invoices/${invoice.number}.pdf`, pdf);

The same buffer goes straight into a mail attachment. With Nodemailer:

await transporter.sendMail({
  to: 'accounts@riverside.example',
  subject: `Invoice ${invoice.number}`,
  text: 'Your invoice is attached.',
  attachments: [
    { filename: `${invoice.number}.pdf`, content: pdf, contentType: 'application/pdf' },
  ],
});

One detail to build in: on the free tier, renders expire and response.expiresAt tells you when. On paid plans it is null and the file is hosted permanently. If a free-tier document needs to outlive that window, download a copy as above.

Step 5: serve it from an API route

In a long-running Node server, build the client once at module scope and reuse it. Return the URL rather than proxying the bytes: the CDN serves the file better than your process will.

import express from 'express';
import { Html2img, Html2imgError } from '@html2img/client';
import { invoiceHtml } from './invoice.mjs';

const app = express();
const client = new Html2img(process.env.HTML2IMG_API_KEY);

app.post('/api/invoices/:id/pdf', async (request, response) => {
  const invoice = await loadInvoice(request.params.id);

  try {
    const render = await client.html({ html: invoiceHtml(invoice), format: 'pdf' });
    response.json({ url: render.url });
  } catch (error) {
    if (error instanceof Html2imgError) {
      response.status(error.statusCode ?? 502).json({ error: error.message });
      return;
    }
    throw error;
  }
});

app.listen(3000);

The same shape works in a Next.js route handler, a Nuxt server route or a Lambda handler. The JavaScript integration guide has each of those written out.

Fixed-width layouts: scale the design to the page

Some documents are not flowing text. A certificate, a wide comparison table or a dashboard export is a fixed-width design, and if it is wider than the A4 page a plain PDF render crops it at the right edge. The scale_to_fit parameter fixes that: the renderer lays the content out at its natural width, then scales the whole layout down to fit the page. The scaling is vector, so text stays selectable and sharp, and any trailing blank page is trimmed.

As of version 2.0.0, scale_to_fit is not on the SDK's option types, so send that one request with plain fetch. This is also the whole API without a dependency: one POST, one header.

const response = await fetch('https://app.html2img.com/api/html', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Accept: 'application/json',
    'X-API-Key': process.env.HTML2IMG_API_KEY,
  },
  body: JSON.stringify({
    html: certificateHtml(attendee),
    format: 'pdf',
    scale_to_fit: true,
  }),
  signal: AbortSignal.timeout(35_000),
});

const data = await response.json();

if (!response.ok || !data.success) {
  throw new Error(`Render failed with ${response.status}: ${JSON.stringify(data)}`);
}

console.log(data.url);

Leave scale_to_fit off for the invoice above. A document written to flow reads better reflowed to the page width at full size than scaled down. The scale_to_fit docs explain the measuring step and when it applies.

Handle the errors that will actually happen

Every failed request rejects with an Html2imgError, and the useful cases have their own subclass. The distinction that matters is between failures that are worth retrying and failures that are not.

import {
  Html2img,
  Html2imgError,
  InsufficientCreditsError,
  TimeoutError,
  ValidationError,
} from '@html2img/client';

try {
  const render = await client.html({ html: invoiceHtml(invoice), format: 'pdf' });
  await saveInvoiceUrl(invoice.number, render.url);
} catch (error) {
  if (error instanceof ValidationError) {
    // 400 or 422: the request is wrong, retrying will not help
    console.error('Rejected fields:', error.details);
  } else if (error instanceof InsufficientCreditsError) {
    // 402: nothing will render until the account is topped up
    console.error(`Out of credits (${error.creditsRemaining} left)`);
  } else if (error instanceof TimeoutError) {
    // 504: the render exceeded the 30 second budget, resend with a webhook
  } else if (error instanceof Html2imgError) {
    // 5xx or a connection failure: retry with backoff
    console.error(error.statusCode, error.errorCode, error.payload);
  } else {
    throw error;
  }
}

The client deliberately does not retry on its own. A 5xx or a dropped connection is worth a second attempt; a 4xx is not, and a retry loop around a validation error just spends credits on the same bad request. If you want a retry policy, pass your own fetch in the constructor options and put the backoff there.

Long reports: take the render off the request

A synchronous render has a 30 second budget and the client waits 35 by default. An invoice is nowhere near that. A 40-page report with large tables can be, and several serverless platforms cut a function off well before either limit. For those, pass a webhookUrl. The API answers immediately with a processing status and the render id, then POSTs the finished URL to your endpoint when the document is ready.

const response = await client.html({
  html: monthlyReportHtml(report),
  format: 'pdf',
  webhookUrl: 'https://your-app.example.com/hooks/html2img?token=shared-secret',
});

if (response.isProcessing()) {
  await db.renders.insert({ id: response.id, report: report.id, status: 'pending' });
}

Your endpoint receives a JSON body with status, the url on success or an error message on failure, and a log_id that matches the id from the initial response, which is how you tie the callback back to the report. Return a 200 within a few seconds and do the rest asynchronously. Delivery is attempted once and the API sends no custom headers, so put a secret in the URL as above. The webhook_url docs have the exact payloads.

What you are no longer maintaining

The list of things this integration does not contain is the point of it. There is no Chrome binary in the deploy and no puppeteer-core and @sparticuz/chromium pair to keep in step every time Chrome ships a major version. There is no font manifest to curate so that a customer's name does not render as hollow rectangles. There is no memory tuning, no crash recovery and no cold-start budget spent booting a browser. Why HTML to PDF with Puppeteer keeps breaking on serverless goes through each of those failures in detail if you are currently living with them.

The trade is stated plainly on the product page: the PDF is built for parity with the image renderer, so it looks exactly like the PNG of the same input would. If your project needs US Letter, landscape pages, running headers and footers or print stylesheets, a dedicated PDF service is the better fit, and The complete guide to generating PDFs from HTML compares every route, including the ones that count against us. For the invoice, receipt, certificate or report that already exists as HTML in your application, the whole job is the one call at the top of this article.

Recap

You installed @html2img/client, sent an HTML string with format: 'pdf' and got back a URL to an A4 vector PDF with selectable text and embedded fonts. From there you built the document from a template with break-inside: avoid on the rows, downloaded the file for an email attachment, put the render behind an Express route, scaled a fixed-width design onto the page with scale_to_fit, handled the errors that are worth retrying separately from the ones that are not, and moved long reports onto a webhook. Nothing in that list installs a browser.

The full guide, with the parameter docs it links to, is at Convert HTML to PDF in Node.js With One API Call on the HTML to Image blog.

How are you generating PDFs from Node at the moment? If you are still running Puppeteer for it, what does it cost you to keep it working? Share your setup in the comments.

I Tested 7 HTML to PDF APIs Against the Same Awkward Invoice

Accreditly — Sun, 23 Aug 2026 10:55:41 +0000

Every "best HTML to PDF API" list you will find is written by a vendor. So is this one: I run HTML to Image, and it is one of the seven services below. The difference is that I am telling you in the second sentence, and every service gets judged against the same fixed document instead of a feature grid copied from marketing pages.

This is a cross-post of the full comparison on the HTML to Image blog, which is the canonical version if you want to link to it.

"Best" is the wrong question anyway. The right question is: best for which document, at which volume? A one-page receipt and a 40-page annual report with running headers are different jobs, and the service that wins one loses the other. So I built one deliberately awkward invoice, worked out exactly what it demands from a rendering engine, and put seven services in front of it: HTML to Image, DocRaptor, PDFShift, Api2Pdf, PDFCrowd, PDFMonkey, and self-hosted Gotenberg as the benchmark for doing it yourself.

The invoice that does the judging

The test document is a two-page supplier invoice: 38 line items, a totals block, small print. Ordinary on the surface, and booby-trapped underneath. Every feature in it was chosen because at least one engine in this market handles it badly.

Here is what it quietly demands:

A webfont. The whole document is set in Inter, loaded from Google Fonts. The engine has to fetch it, render with it, and embed it in the PDF, or the text layer falls back to something ugly.
Flexbox. The header is a flex row. Trivial in a browser, fatal in anything built on 2015-era WebKit.
CSS Grid. The billing block is a three-column grid. This one matters because one major commercial engine still does not support Grid at all. More on that below.
Custom properties. Brand colours live in :root variables. Legacy engines resolve none of it.
A table that crosses the page boundary. 38 rows will not fit on one A4 page, so pagination behaviour is on show, including whether <thead> repeats on page two.
break-inside: avoid. Rows and the totals block must not split across pages.
Page numbers via @page margin boxes. The stylesheet asks for "Page " counter(page) " of " counter(pages) in the bottom-right margin of every page. Historically this separated the CSS Paged Media engines from the browser engines. In 2026 the answer is more interesting than that.
JavaScript. The subtotal, tax and total are computed by a script at render time. An engine that does not execute JavaScript prints an invoice with dashes where the money should be.

The trap CSS, in full:

@page {
  size: A4;
  margin: 18mm 16mm 22mm 16mm;
  @bottom-right { content: "Page " counter(page) " of " counter(pages); }
  @bottom-left  { content: "Fieldgate Studio Ltd · INV-2026-0847"; }
}

tbody tr { break-inside: avoid; }

.totals  { break-inside: avoid; }

If a service renders this invoice correctly, it will handle the overwhelming majority of transactional documents: receipts, statements, packing slips, certificates, simple reports. If it fails, you now know exactly where.

How the judging works

Full disclosure of method, because this is where vendor lists usually go quiet.

I ran the invoice through my own API and inspected the output with pdfinfo, pdffonts and pdftotext. Those results are reported below as tested facts. For the other six services, I did not create six accounts and pretend to run a neutral lab. Instead, each service is judged on the engine it runs, that engine's documented CSS support, and its published pricing, all checked in August 2026. Engines are honest in a way marketing pages are not: if a service renders with Prince, Prince's documented behaviour is its behaviour. If it renders with Chromium, the invoice behaves the way it behaves in Chrome.

One tested finding is worth pulling out before the scorecard, because most advice online has not caught up with it. The classic rule was that Chromium-based PDF generation cannot do CSS page numbers, and that you needed Prince, WeasyPrint, or a vendor's header and footer templates to get them. That rule died in November 2024: Chromium 131 shipped support for @page margin boxes, including counter(page) and counter(pages), and the Chrome 131 release notes document it. My test render came back stamped Skia/PDF m131, and both pages carried a correct "Page 1 of 2" and "Page 2 of 2" in the bottom margin, from plain CSS, with no vendor-specific footer syntax. Whether your provider gives you this depends entirely on which Chromium build it has pinned. It is now a question worth asking every vendor on this list.

The scorecard

Service	Engine	Flexbox + Grid	CSS page numbers	Runs JS	Starting price
HTML to Image	Current Chrome	Yes	Yes, tested	Yes	$9/mo, 1,000 renders
DocRaptor	Prince	Flexbox yes, Grid no	Yes, full Paged Media	Limited	$15/mo, 125 docs
PDFShift	Chromium	Yes	Via header/footer templates	Yes	$24/mo, 2,500 credits
Api2Pdf	Chrome, wkhtmltopdf or LibreOffice	Yes on the Chrome route	Via header/footer options	Yes on the Chrome route	$1/mo + usage
PDFCrowd	Chromium-based converters	Yes	Via header/footer parameters	Yes	$23/mo, 1,000 credits
PDFMonkey	Chromium	Yes	Template-driven workflow	Yes, on paid plans	€5/mo, 300 docs
Gotenberg (self-hosted)	Chromium + LibreOffice	Yes	Via header/footer files	Yes	Free, plus your server

The rest of this post is each service against the invoice, strengths and failures both.

HTML to Image

Mine, so read this section with the scepticism it deserves. Here is what the API did with the test document, verified rather than claimed.

The invoice came back as a two-page A4 vector PDF, 230KB, with Inter embedded as subsetted fonts and a real text layer throughout: every line item, and the JavaScript-computed totals, are selectable and searchable in the output. The break-inside rules held, so no row split across the boundary and the totals block arrived intact on page two. The @page margin boxes rendered, which honestly surprised me too, because my own comparison pages have been telling people the service does not do page numbers. The renderer is current Chrome, Chrome is now past 131, so counter(page) simply works.

Two failures, stated plainly. First, the <thead> did not repeat on page two; the 38-row table just continues. That is a known Chromium PDF behaviour and the fix is repeating the header yourself, not a parameter. Second, the scope is deliberately narrow: A4 portrait only, no US Letter, no landscape, no watermarking, no encryption, no merging, and your @media print styles are ignored because rendering uses screen CSS. The whole PDF surface is one format parameter on the same endpoint that renders PNGs.

What you get in exchange for that narrowness: one credit per render regardless of document size, output hosted on a CDN URL that stays live on paid plans, the same API key rendering both images and PDFs, and pricing that starts at $9 for 1,000 renders and reaches 100,000 for $300. If your documents are transactional and A4, this is the cheap, boring option. If they are not, one of the next five services is your answer.

DocRaptor

DocRaptor is the only service here that does not render with a browser engine, and that single fact decides everything about it. It runs Prince, the commercial CSS Paged Media engine, and Prince remains the best print typographer in the business: real headers and footers, page counters, footnotes, cross-references, PDF bookmarks, mixed page sizes within one document, and tagged, accessible output meeting WCAG 2.0, Section 508 and ISO-14289. DocRaptor holds SOC2 and HIPAA compliance on top. For a regulated 60-page financial statement, nothing else on this list is a serious rival.

Against this invoice, though, Prince trips on trap number three. Prince's own documentation is upfront that it does not support CSS Grid, so the three-column billing block would need rewriting as flexbox or floats before this invoice renders correctly. JavaScript support exists but is Prince's own engine rather than a browser, so scripts that lean on browser APIs need testing rather than trusting. If your templates were written for Chrome, budget for a porting pass.

Two more honest observations. DocRaptor's trial policy is the best in the market: test documents are watermarked but unlimited and free forever, so you can develop against it indefinitely without paying. And its pricing is the steepest here by a distance: $15 a month covers 125 documents, $149 covers 5,000, and 40,000 costs $1,000. You are paying for Prince, and for many document types Prince is worth it.

PDFShift

PDFShift is the straightforward one: a French-run, Chromium-based converter that has been doing exactly this job for years without trying to become a platform. The invoice renders correctly because current Chromium renders it correctly, and PDFShift layers on page-level controls: page sizes including Letter and custom dimensions, landscape, encryption, watermarks, custom headers and footers with page numbers, and delivery straight to your own S3 bucket. Asynchronous mode and parallel processing are there for batch work.

The pricing model needs one careful read: credits are metered by output size, one credit per 5MB, so a 14MB catalogue costs three credits while this 230KB invoice costs one. The free tier is a genuine 50 conversions a month, the published Boost plan is $24 for 2,500 credits with overage at $0.03, and the ladder above that is not published, so high-volume teams are quoting rather than reading a price list. For a team that wants Chromium fidelity plus real PDF options at a sane price, PDFShift is the safe default in the middle of this market.

Api2Pdf

Api2Pdf does something rare: it tells you precisely what it runs. Headless Chrome, wkhtmltopdf and LibreOffice are all surfaced as explicit choices, alongside merging, barcodes and thumbnails. That candour cuts both ways. The Chrome route renders the invoice as well as any Chromium service here. The wkhtmltopdf route fails it comprehensively, because wkhtmltopdf is an archived project rendering with a WebKit build that predates flexbox-era CSS; it is still offered for legacy compatibility, not for new work. Pick the Chrome engine and never look back.

The LibreOffice engine is the genuinely differentiating piece: Api2Pdf converts Word, Excel and PowerPoint files to PDF, which nothing else on this list attempts. And the pricing is pay-as-you-go taken seriously: $1 a month base, $0.001 per MB of bandwidth, $0.00019551 per second of compute. At this invoice's real weight of 230KB and roughly two seconds of render time, 2,500 invoices a month costs about $2.60. That is not a typo, and it makes Api2Pdf the cheapest metered option in the market by an order of magnitude. The trade is forecastability and the absence of a hosting layer: you get bytes back, and storage is your problem.

PDFCrowd

PDFCrowd has been converting HTML since 2009 and its API reads like it: over one hundred configuration parameters covering page size, margins, headers and footers with page numbers, page break control, watermarking and password protection, with official SDKs for Python, PHP, Node.js, Java, .NET, Ruby and Go. The current converter versions are Chromium-based, so the invoice's layout, fonts, custom properties and JavaScript all render correctly, and the header and footer parameters supply the page numbers.

The things to check before committing are operational rather than rendering. Credits are metered at one per 0.5MB of output, the tightest size metering here, so a 2MB report costs four credits and plan capacity is smaller than the document counts suggest. Plans carry per-minute rate limits and concurrency allowances that step up with price, which matters for bursty invoice runs on billing day. Published pricing starts at $23 for 1,000 credits and $61 covers 10,000. If you want maximum knobs from a vendor that has outlived most of its competitors, this is that vendor.

PDFMonkey

PDFMonkey is shaped differently from everything above, and comparing it fairly means saying so. You do not POST HTML per render. Templates live in PDFMonkey's dashboard, written in HTML and CSS with Liquid placeholders, and each API call sends the JSON data to merge into one. For an invoice pipeline where the accounts team occasionally edits the template and developers only ever send {"invoice_number": "INV-2026-0847", ...}, that split is genuinely the right architecture, and it is why PDFMonkey keeps winning small SaaS teams.

The engine is Chromium, so the invoice's CSS and JavaScript are safe, with one asterisk: the free plan cannot load external images, fonts or scripts at all, so trap number one, the Google-hosted webfont, fails until you pay. Pricing is the friendliest entry point on this list, €5 a month for 300 documents and €15 for 3,000, but read the retention column before storing invoice URLs anywhere: documents are deleted after one day on Starter and seven days on Pro, with unlimited retention only from the €60 Pro+ plan. If your app links to the PDF later, that detail is a production incident waiting in the pricing table.

Gotenberg, if you would rather run it yourself

Every managed service above competes with one alternative: a Docker container on your own infrastructure. Gotenberg is the best version of that idea, an MIT-licensed API wrapping Chromium and LibreOffice, so the invoice renders exactly as it does on any current-Chromium service, header and footer files included, for a licence cost of nothing.

The cost is not nothing, it has just moved. You now own a browser in production: memory limits, zombie processes, concurrency under a billing-day burst, and the Chromium upgrade treadmill, which, as the margin-box story above shows, is also how you receive new CSS features. A small VM at $20 to $40 a month is the visible line item; the engineer who answers when rendering falls over at 2am is the real one. Gotenberg is the right choice when data genuinely cannot leave your infrastructure, and a self-imposed operations tax the rest of the time.

What the same invoice costs at three volumes

Monthly prices for rendering the 230KB invoice, at published August 2026 rates. Api2Pdf figures are estimates from its published per-MB and per-second rates at the invoice's measured weight and a two-second render; size-metered services assume the document stays under their credit threshold, which at 230KB it comfortably does.

Volume per month	250 invoices	2,500 invoices	25,000 invoices
HTML to Image	$9	$25	$120
DocRaptor	$29	$149	$1,000
PDFShift	$24	$24	Not published
Api2Pdf	~$1.20	~$2.60	~$17
PDFCrowd	$23	$61	Not published
PDFMonkey	€5	€15	€180–300
Gotenberg	Your server	Your server	Your server, plus real ops work

Three things jump out of that table. Api2Pdf's metered model is untouchable on raw price if you can live with usage billing and bring your own storage. DocRaptor costs ten to forty times the Chromium services at every volume, which is the price of Prince and worth paying only when you need what only Prince does. And two of seven vendors stop publishing prices exactly where volume gets interesting, which tells you something about how those negotiations go.

Which one should you pick

Match the service to the document, not to the adjectives.

Transactional A4 documents at volume, images from the same key: HTML to Image. One credit each, hosted URLs, $9 to start.

Print-grade typography, accessibility tagging, or compliance requirements: DocRaptor, and rewrite your Grid layouts first. Nothing else here produces tagged PDFs.

Chromium fidelity plus page-level control, Letter and landscape, watermarks, encryption: PDFShift for the cleaner API, PDFCrowd for the deepest parameter surface and official SDKs.

Office documents in the pipeline, or the lowest possible bill: Api2Pdf on its Chrome engine, with your own storage behind it.

Templates edited by non-developers, data merged by API: PDFMonkey, on a paid plan, with the retention column read twice.

Data that cannot leave your infrastructure: Gotenberg, priced honestly to include the engineer.

Whatever this or any other vendor's list says: every service here has a free tier, free test documents or a trial. The only test that outranks mine is your own document through two or three of them. The full comparison, with the deeper engine notes, lives on the HTML to Image blog.

Which HTML to PDF service are you running in production, and has it bitten you? Share your experience in the comments below.

Can I use it in a PDF? CSS support across HTML to PDF engines

Accreditly — Thu, 20 Aug 2026 20:02:13 +0000

Your template renders perfectly in the browser, then falls apart in the PDF: the grid collapses, the footer vanishes and counter(page) prints nothing. Your CSS is fine. The problem is that "HTML to PDF" is not one renderer. It is four different engines with four different ideas about which parts of CSS exist.

Browsers have caniuse.com. PDF engines have changelogs, forum threads and folklore. So we built the missing table. The full write-up lives on the HTML to Image blog as Can I use it in a PDF? CSS support across HTML to PDF engines; this is the condensed version with the rows that bite most often.

The four engines

Nearly every converter you will meet is one of these under the hood:

Chrome headless: Puppeteer, Playwright, Gotenberg and most hosted APIs. Browser-grade CSS, and since Chrome 131 (November 2024) proper @page margin boxes.
wkhtmltopdf: Qt WebKit frozen around 2012. Archived in January 2023, last release June 2020, and carrying an unpatched 9.8 SSRF vulnerability (CVE-2022-35583).
WeasyPrint: a Python layout engine built for pagination. No JavaScript, excellent paged media.
Prince: the commercial reference implementation for print CSS, with its own engine and its own JavaScript.

The support table

Checked against Chrome 131 or later, wkhtmltopdf 0.12.6, WeasyPrint 69 and Prince 16, in August 2026.

Feature	Chrome headless	wkhtmltopdf	WeasyPrint	Prince
Flexbox	Yes	Broken (2009 draft syntax)	Yes	Yes
Grid	Yes	No	Yes, gaps remain	Partial, no fragmentation
Custom properties `var()`	Yes	No	Yes	Yes
`calc()`	Yes	Unreliable	Yes, added 2025	Yes
`@page` size and margins	Yes	CLI flags instead	Yes	Yes
`@page` margin boxes	Yes, since 131	No, CLI headers	Yes	Yes
`counter(page)` / `counter(pages)`	Margin boxes only	No, `[page]` tokens	Yes	Yes
Named pages (`page: cover`)	Yes	No	Yes	Yes
`break-before` / `after` / `inside`	Yes	Legacy `page-break-*` only	Yes	Yes
Named strings (`string-set`)	No	No	Yes	Yes
`target-counter()`	No	No	Yes	Yes
`leader()`	No	No	Yes	Yes
Footnotes (`float: footnote`)	No	No	Yes	Yes
Runs JavaScript	Yes, full V8	2012-era engine	No	Own engine

The shape of it: Chromium wins everything a browser cares about and loses everything print specific beyond margin boxes. wkhtmltopdf loses everything. The two dedicated print engines are the only ones with the generated content features long documents need.

The row that changed recently: headers and footers

Until late 2024 Chromium ignored @page margin boxes entirely, which is why every Puppeteer tutorial reaches for headerTemplate and footerTemplate, a clunky parallel HTML system with its own font quirks. From Chrome 131 it is just CSS, in all 16 margin regions:

@page {
  @top-center {
    content: "Northgate Coffee · Statement";
    font-size: 9pt;
  }
  @bottom-right {
    content: "Page " counter(page) " of " counter(pages);
    font-size: 9pt;
  }
}

One catch: in Chromium, counter(page) only resolves inside margin boxes. Drop it into body content and you get nothing. WeasyPrint and Prince render it anywhere.

What Chromium still cannot do is pull document content into the header. The classic "current chapter title in the running head" pattern needs named strings, which only the print engines implement:

h2 {
  string-set: chapter content();
}

@page {
  @top-right {
    content: string(chapter);
  }
}

The rows Chromium does not have at all

A print table of contents needs the page number of a target element, plus the dotted line leading to it:

.toc a::after {
  content: leader(".") target-counter(attr(href), page);
}

target-counter() and leader() work in WeasyPrint and Prince and nowhere else. The same goes for footnotes via float: footnote. If you are locked into Chromium and need these, Paged.js polyfills them in JavaScript before printing, at the cost of a heavier render and another dependency.

The gotchas hiding inside "Yes"

WeasyPrint only gained grid in v62 (April 2024) and calc() in the 2025 releases. An older install following a newer tutorial fails in confusing ways, so pin and check your version.
Prince 16's grid cannot fragment across pages yet. Use grid for components, not page-spanning layout.
wkhtmltopdf's flexbox is the abandoned 2009 -webkit-box draft. Modern display: flex markup silently renders as stacked blocks.
Fragmentation is where most real bugs live. Chrome, WeasyPrint and Prince honour break-inside: avoid and repeat thead across pages; wkhtmltopdf only understands the legacy page-break-* spellings, and its table splitting is fragile even then.

Picking an engine

For invoices, statements and reports: Chromium, now that it has real headers and page numbers. For books, contracts and anything with a table of contents or cross references: WeasyPrint for free, Prince when there is budget. And if you are still on wkhtmltopdf, the table above is the migration argument in one screen: an archived engine, a critical CVE and a decade of missing CSS.

The full version, covering @page setup, named pages, fragmentation control and the JavaScript story, is on the blog: CSS support across HTML to PDF engines.

Which engine are you running, and what is the worst CSS surprise it has given you? Share it in the comments below.

How to Generate Images in n8n (Social Cards, Certificates and PDF Reports)

Accreditly — Tue, 18 Aug 2026 19:42:07 +0000

Your n8n workflow pulls the data, formats the message and posts it to Slack, then stops dead at the visual. The share card still gets made by hand, the certificate waits for someone to export it, and the Monday report goes out as a wall of numbers.

You can fix all three with n8n's stock HTTP Request node and an HTML to Image API. No community node, no headless browser to maintain, and it works the same on n8n Cloud and self-hosted. This tutorial builds three workflows: social cards from an RSS feed, certificates from a form submission, and a weekly PDF report on a schedule.

This is a cross-post: the original lives on the HTML to Image blog as How to Generate Images in n8n: Automate Social Cards, Certificates and Reports, where you'll also find the template gallery and API docs referenced throughout.

Prerequisites

An n8n instance, either Cloud or self-hosted
A free HTML to Image API key (the free tier gives you 25 renders a month, which covers everything here)
Somewhere to deliver the output: a Slack workspace and a Gmail account in these examples

How the API fits into n8n

Two endpoints do all the work.

POST https://app.html2img.com/api/v1/templates/{slug} renders one of 25 named templates. You send a small JSON payload (a title, a name, some line items) and get back a finished image at known dimensions. No HTML anywhere in your workflow.

POST https://app.html2img.com/api/html renders raw HTML you supply, in real Chrome. Grid, flexbox, custom fonts and inline JavaScript all behave the way they do in your browser.

Both respond with the same shape:

{
  "success": true,
  "id": "abc123",
  "url": "https://i.html2img.com/abc123.png",
  "credits_remaining": 973
}

The url is a permanent CDN link, which is what makes this pleasant in n8n: no binary data moves between nodes. You pass a short string to Slack or into an email and you're done.

Step 1: Create the credential

Copy your API key from the dashboard, then in any HTTP Request node:

Set Authentication to Generic Credential Type
Set Generic Auth Type to Header Auth
Create a credential with Name X-API-Key and Value set to your key

Save it once, reuse it in every workflow below. The key never appears in node parameters or workflow exports.

Step 2: Social cards from an RSS feed

The workflow is three nodes: RSS Feed Trigger → HTTP Request → Slack.

Point the RSS Feed Trigger at your blog's feed. Each new post arrives with title, link and creator fields.

Configure the HTTP Request node:

Method: POST
URL: https://app.html2img.com/api/v1/templates/open-graph-image
Authentication: the Header Auth credential from Step 1
Body Content Type: JSON, with Specify Body set to Using JSON

And the body:

{
  "title": {{ JSON.stringify($json.title) }},
  "subtitle": "Fresh on the blog"
}

Notice there are no quotes around the expression. JSON.stringify() adds them itself and escapes whatever is inside. If you write "title": "{{ $json.title }}" instead, the workflow runs fine for weeks and then breaks the first time a post title contains a double quote. Let stringify build the value and that failure mode disappears. It's a habit worth applying to every hand-built JSON body in n8n.

Finally, the Slack node posts the article link plus {{ $json.url }} from the HTTP Request output. Slack unfurls the CDN URL into the card. Swap Slack for LinkedIn, X or Buffer and nothing upstream changes.

Step 3: Certificates from a form submission

Templates need no markup, but certificates usually want your own design. That's the raw HTML endpoint's job, and the clean pattern in n8n is: build the whole API payload in a Code node, then hand it to the HTTP Request untouched.

The workflow: n8n Form Trigger → Code → HTTP Request → Gmail.

Here's the Code node:

const name = $json['Full name'];
const course = $json['Course'];
const date = new Date().toLocaleDateString('en-GB', {
  day: 'numeric', month: 'long', year: 'numeric'
});
const certId = 'NC-' + Date.now().toString(36).toUpperCase();

const html = `<!doctype html>
<html><head><meta charset="utf-8">
<style>
  @import url('https://fonts.googleapis.com/css2?family=Manrope:wght@500;700;800&family=JetBrains+Mono:wght@500&display=swap');
  body { width: 1200px; height: 850px; margin: 0; box-sizing: border-box;
         padding: 56px; background: #ffffff; font-family: 'Manrope', sans-serif;
         color: #0e1521; }
  .frame { height: 100%; border: 2px solid #2563eb; border-radius: 12px;
           box-sizing: border-box; padding: 64px; text-align: center;
           display: flex; flex-direction: column; justify-content: space-between; }
  .eyebrow { font-family: 'JetBrains Mono', monospace; font-size: 15px;
             letter-spacing: 0.2em; color: #2563eb; }
  h1 { font-size: 44px; font-weight: 800; margin: 12px 0 0; }
  .name { font-size: 56px; font-weight: 800; color: #2563eb; margin: 8px 0; }
  .body { font-size: 20px; color: #6b7585; line-height: 1.6; }
  .meta { display: flex; justify-content: space-between; align-items: flex-end;
          font-family: 'JetBrains Mono', monospace; font-size: 14px; color: #6b7585; }
  .sig { border-top: 1px solid #0e1521; padding-top: 8px; width: 220px; }
</style></head>
<body><div class="frame">
  <div>
    <div class="eyebrow">CERTIFICATE OF COMPLETION</div>
    <h1>Northgate Coffee Academy</h1>
  </div>
  <div>
    <p class="body">This certifies that</p>
    <div class="name">${name}</div>
    <p class="body">has successfully completed<br><strong>${course}</strong><br>on ${date}</p>
  </div>
  <div class="meta">
    <div class="sig">Course Director</div>
    <div>Verify: ${certId}</div>
  </div>
</div></body></html>`;

return [{ json: { html, width: 1200, height: 850, dpi: 2 } }];

Template literals drop the attendee's name straight into the markup, and the node returns the complete API payload as its output item. That makes the HTTP Request trivial: POST to https://app.html2img.com/api/html, Specify Body set to Using JSON, and the entire body is:

{{ JSON.stringify($json) }}

No escaping the quotes, newlines and backticks buried in 40 lines of HTML. The Code node built a clean object; stringify serialises it correctly by definition.

The dpi: 2 renders at double pixel density so the certificate stays sharp on retina screens and survives printing, at the cost of roughly double the render time.

The Gmail node then sends an HTML email with the certificate inline:

<p>Congratulations! Your certificate is below.</p>
<img src="{{ $json.url }}" width="600" alt="Certificate of completion" style="max-width:100%">

Because the certificate is a PNG on a CDN rather than styled HTML in the email body, it renders identically in Outlook, Gmail and Apple Mail.

Step 4: A weekly report PDF on a schedule

Same pattern as the certificate, two changes: a Schedule Trigger at the front and format: "pdf" in the payload.

The workflow: Schedule Trigger → Google Sheets → Code → HTTP Request → Slack.

Set the trigger to Monday at 08:00 and have the Google Sheets node return your metrics rows. The Code node turns them into a report, with a bar chart made of plain divs. CSS is a perfectly good charting library when real Chrome is your renderer:

const rows = $input.all().map(i => i.json);
const latest = rows[rows.length - 1];
const max = Math.max(...rows.map(r => Number(r.signups)));

const bars = rows.map(r => `
  <div class="bar-row">
    <span class="label">${r.week}</span>
    <div class="track"><div class="bar" style="width:${(Number(r.signups) / max) * 100}%"></div></div>
    <span class="val">${r.signups}</span>
  </div>`).join('');

const html = `<!doctype html>
<html><head><meta charset="utf-8">
<style>
  @import url('https://fonts.googleapis.com/css2?family=Manrope:wght@500;700;800&display=swap');
  body { font-family: 'Manrope', sans-serif; color: #0e1521; padding: 48px; }
  h1 { font-size: 28px; margin: 0 0 4px; }
  .sub { color: #6b7585; margin: 0 0 32px; }
  .kpis { display: flex; gap: 16px; margin-bottom: 40px; }
  .kpi { flex: 1; border: 1px solid #e2e6ec; border-radius: 10px; padding: 20px; }
  .kpi b { display: block; font-size: 30px; }
  .kpi span { color: #6b7585; font-size: 14px; }
  .bar-row { display: flex; align-items: center; gap: 12px; margin-bottom: 10px; }
  .label { width: 90px; font-size: 13px; color: #6b7585; }
  .track { flex: 1; background: #eff4ff; border-radius: 4px; }
  .bar { height: 18px; background: #2563eb; border-radius: 4px; }
  .val { width: 50px; font-size: 13px; text-align: right; }
</style></head>
<body>
  <h1>Weekly growth report</h1>
  <p class="sub">Generated ${new Date().toLocaleDateString('en-GB')}</p>
  <div class="kpis">
    <div class="kpi"><b>${latest.signups}</b><span>Signups this week</span></div>
    <div class="kpi"><b>${latest.revenue}</b><span>Revenue this week</span></div>
    <div class="kpi"><b>${rows.length}</b><span>Weeks tracked</span></div>
  </div>
  ${bars}
</body></html>`;

return [{ json: { html, format: 'pdf' } }];

The HTTP Request is identical to Step 3, body {{ JSON.stringify($json) }}. The difference is format: "pdf": the API returns an A4 portrait PDF with selectable text and embedded fonts, and long content paginates automatically. Width and height are ignored in PDF mode, so leave them out.

The Slack node posts the returned url. It ends in .pdf and opens straight in the browser.

Production tips

Renders are synchronous within a 30 second budget. For heavy renders, pass a webhook_url in the payload and the API responds immediately, then POSTs the finished file's URL to a second n8n workflow that starts with a Webhook node.

Don't re-render what hasn't changed. Every render costs a credit and every URL is permanent, so store the URL back in your sheet or database on first render and reuse it. An IF node checking whether the URL column is populated is usually enough.

Turn on Retry On Fail in each HTTP Request node's settings. Validation errors come back as a 422 with a details object naming the bad field, and n8n shows the response body in the execution log.

Watch credits_remaining in every response. An IF node that pings you when it drops below a threshold means a busy month never silently stops your certificates going out.

Wrapping up

You've built three workflows, and they're really one pattern: a trigger, an optional Code node that assembles a payload, and an HTTP Request that returns a CDN URL. Templates cover the no-code cases, raw HTML covers your own designs, and {{ JSON.stringify($json) }} keeps the whole thing escape-proof. The full version of this guide, with a rendered example of the certificate and the workflow diagrams, is on the HTML to Image blog: How to Generate Images in n8n.

Are you generating images or PDFs from your n8n workflows already? Share your setup in the comments below.

How to Convert Markdown to an Image (Without Screenshotting Your Editor)

Accreditly — Sat, 15 Aug 2026 07:51:21 +0000

You write release notes, changelogs and comparison tables in Markdown, and then you need to post them somewhere that refuses to render it. Slack collapses your table into a line of pipes. X and LinkedIn strip every heading and bullet to flat text. Email clients show your readers literal asterisks.

So you open the preview pane and take a screenshot. It works, in the way that holding a door shut works instead of fixing the lock. We've just published a fuller guide on converting Markdown to an image over on HTML to Image, and this post covers the working version for JavaScript developers.

What's wrong with a screenshot

A screenshot carries everything you didn't want along with the content. Your editor theme comes with it, so a dark-mode preview lands in a light-mode inbox looking like a ransom note. The resolution is whatever your display happens to be, so text that was crisp on your laptop turns soft on a retina screen. The crop is hand-drawn, so there's a sliver of scrollbar down one edge.

And it's manual. If the notes change, you screenshot again. Fine once; wrong as a workflow.

The better approach: convert the Markdown to HTML, wrap it in a clean stylesheet, and render it in a real browser at a fixed width. The formatting survives because it's no longer formatting. It's pixels.

Prerequisites

Node 18 or newer (for built-in fetch)
The marked package: npm install marked
An API key for a rendering service (HTML to Image has a free tier; any HTML-to-PNG renderer with a full-page option works the same way)

Step 1: Parse the Markdown

marked handles GitHub-flavoured Markdown out of the box, so tables, strikethrough and fenced code blocks all convert properly:

import { readFile } from "node:fs/promises";
import { marked } from "marked";

const markdown = await readFile("release-notes.md", "utf8");
const fragment = marked.parse(markdown, { gfm: true });

What you get back is a bare HTML fragment with no opinion about its own appearance. That's the next step's job.

Step 2: Wrap it in a document stylesheet

The parser gives you semantics; this gives you the look. It's deliberately close to how GitHub renders Markdown, because that's what people expect a rendered document to look like:

const stylesheet = `
  body { margin: 0; padding: 48px 56px;
    font-family: -apple-system, "Segoe UI", Helvetica, Arial, sans-serif;
    font-size: 17px; line-height: 1.6; color: #1f2328; }
  h2 { font-size: 30px; margin: 0 0 16px; padding-bottom: 10px;
    border-bottom: 1px solid #d1d9e0; }
  table { border-collapse: collapse; width: 100%; margin: 0 0 18px; }
  th, td { border: 1px solid #d1d9e0; padding: 9px 14px; text-align: left; }
  th { background: #f6f8fa; }
  blockquote { margin: 0 0 18px; padding: 4px 18px;
    border-left: 4px solid #d1d9e0; color: #59636e; }
  code { font-family: ui-monospace, Menlo, Consolas, monospace;
    font-size: 0.9em; background: #f0f1f3; padding: 2px 6px; border-radius: 5px; }
  pre { background: #f6f8fa; border: 1px solid #d1d9e0;
    border-radius: 8px; padding: 16px 18px; }
  pre code { background: none; padding: 0; font-size: 15px; }
`;

const html = `<!doctype html>
<html><head><meta charset="utf-8"><style>${stylesheet}</style></head>
<body>${fragment}</body></html>`;

Swap the font stack for your brand face and tint the borders if you want it on-brand. The structure doesn't change.

Step 3: Render it

One POST. The two parameters that matter are width, which sets the line length (1,000px reads well for a document), and fullpage: true, which makes the capture height follow the content:

const response = await fetch("https://app.html2img.com/api/html", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.HTML2IMG_KEY,
  },
  body: JSON.stringify({ html, width: 1000, fullpage: true }),
});

const { url } = await response.json();
console.log(url);

The full-page part is what separates this from screenshotting. A three-line note produces a small image and a forty-line changelog produces a tall one, from the same code, with nothing cropped at the bottom.

Here's a release note that started life as thirty lines of Markdown and came out of exactly this script:

The bold lead-ins, the inline code, the table columns, the blockquote and the fenced block all survived. Post that image anywhere and it looks the same everywhere.

Where this pays off

Release notes as social posts are the obvious one: the structure survives on platforms that would flatten it to a paragraph. Tables in Slack are the daily one. Email is the sneaky one, because clients disagree about nearly every layout feature, and a PNG looks identical in Gmail, Outlook and Apple Mail since there's nothing left to interpret.

And because it's one HTTP call, it automates: run it in CI when a release tags, or in a cron that turns the week's merged PRs into a Friday summary card. The Markdown was already being written. Now it travels.

For the browser-based version of this (paste Markdown, get a PNG, no code), plus Python and PHP implementations and the full stylesheet, the complete guide is here.

Do you post rendered Markdown anywhere regularly, or are you still screenshotting the preview pane? Share your setup in the comments.

Why your Open Graph image doesn't show up when you share a link

Accreditly — Wed, 12 Aug 2026 17:26:06 +0000

You paste a link into Slack and the preview comes back as a bare grey rectangle. Or the title shows and the image does not. Or LinkedIn serves artwork from three deploys ago. You open devtools, the tags are right there, and the card is still wrong.

The reason is nearly always the same one. The thing reading your page is not a browser. A social crawler makes one anonymous request, parses the HTML that came back over the wire, fetches the image, and leaves. No session, no JavaScript engine, no patience. We have published the full version of this with the platform specifics on the HTML to Image blog, in Why your Open Graph image doesn't show up when you share a link, and this post walks through the eight causes and how to tell them apart.

What happens when someone shares your URL

Four steps, and each fails independently:

The platform requests your URL with a crawler user agent, following redirects.
It parses the served HTML for og: and twitter: tags.
It resolves og:image to an absolute URL and fetches it, often reading only enough of the file to get its dimensions.
It builds a card using its own rules about which tag wins, how to crop, and how much of the title to keep.

Working out which step broke is most of the job.

1. The tags are in devtools but not in the response

The most common cause by a distance. If your head is set client-side, a Vue app assigning meta on mount, a React app using a client-only helmet component, a CMS script patching the head after load, the crawler sees none of it. Devtools shows the DOM after your JavaScript has run. The crawler reads the document as served.

One command tells you:

curl -sL https://example.com/pricing | grep -i 'og:\|twitter:'

Empty output means the tags have to move into server-rendered HTML. In Next.js that is the metadata export or generateMetadata in a server component, not anything set in useEffect. In Nuxt it is useSeoMeta on a server-rendered route. In a static site generator it is the head partial at build time.

2. `og:image` is a relative path

<meta property="og:image" content="/images/og/pricing.png">

Valid HTML, useless to a crawler. The protocol asks for an absolute URL including the scheme, and several platforms drop the image rather than guess your host.

<meta property="og:image" content="https://example.com/images/og/pricing.png">

Same problem with protocol-relative // URLs, and with anything still pointing at localhost because the base URL comes from an environment variable nobody set in production.

3. The image is not reachable by an anonymous bot

The image fetch is as anonymous as the page fetch. Hotlink protection that wants a same-origin referer, Cloudflare Bot Fight Mode on the asset path, a robots.txt rule over the image directory, an expired signed CDN URL, or a private bucket object will all kill it.

curl -sI https://example.com/images/og/pricing.png | head -n 3

You want a 200 and an image content type. A 403 for curl is a 403 for Facebook.

4. No `og:image:width` and `og:image:height`

Seeing your URL for the first time, a platform has no idea how big the image is, so it downloads and measures it before laying out the card. Several will render the card without the image rather than wait, then get it right on the second or third share. Your launch post has already been seen by then.

<meta property="og:image" content="https://example.com/images/og/pricing.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:type" content="image/png">
<meta property="og:image:alt" content="Pricing plans for Northgate">

5. The image is the wrong size, ratio or format

1200 by 630 renders cleanly everywhere. Below 600 by 315, Facebook and LinkedIn downgrade to a small square thumbnail beside the text. Over 8MB, the image is dropped. SVG is not read as an og:image anywhere that matters, and WebP support is patchy enough that PNG or JPEG remains the safe answer.

Then the crop. Everything centre-crops toward roughly 1.91:1 and square unfurls keep only the middle band, so a logo or headline near an edge is a logo or headline you sometimes lose.

6. `twitter:card` is missing so X renders the small card

X falls back to og: tags for the title, description and image, which is why people skip the twitter: namespace. The one tag you cannot skip is the card type. Without it you get summary, a small square thumbnail beside the text, instead of the full-width image card.

<meta name="twitter:card" content="summary_large_image">

7. The URL you tested is not the URL people share

Tags are read from the final URL after redirects, and what ends up in the wild is rarely the clean URL you tested. Campaign parameters, a trailing slash difference, a locale prefix, an AMP variant or an http to https hop can each resolve to a document with different tags. Test the canonical URL, then test the exact string your campaign is about to use.

8. Facebook is still showing a card you fixed last week

Meta caches the first scrape hard and can hold it for days. Deploying a fix does not invalidate it, so run the URL through Meta's Sharing Debugger once and use Scrape Again. This one matters mostly because it makes the other seven harder to diagnose. If a live fetch shows correct tags and Facebook shows the old card, the cache is stale rather than your fix being wrong.

Checking the lot in one pass

The official debuggers have thinned out. Meta's needs a Facebook login and only covers Facebook. X removed the rendered preview from its Card Validator, so it now tells you a card is valid without showing you the card. Neither says anything about Slack, Discord or WhatsApp.

We built the Open Graph Checker to run the whole sequence in one request: fetch as a crawler without executing JavaScript, follow redirects and read tags from the final URL, resolve relative image URLs, then read the image's real dimensions, type and file size from the file rather than from what the tags claim. It renders the card as Facebook, X, LinkedIn, Slack, Discord and WhatsApp would each build it, scores the page, and prints a corrected tag block. No login, and it reads live rather than from a cache.

The failures it separates fastest are the ones that look identical from outside: tags missing because they are client-side, an image URL that resolves but returns a 403, an image that is present but 400 pixels wide, and a page that redirects somewhere with different tags.

The block you are aiming for

<meta property="og:type" content="article">
<meta property="og:url" content="https://example.com/pricing">
<meta property="og:site_name" content="Northgate">
<meta property="og:title" content="Pricing that scales with your traffic">
<meta property="og:description" content="Per-render pricing with no seat fees, and a free tier that covers a small site.">
<meta property="og:image" content="https://example.com/images/og/pricing.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:type" content="image/png">
<meta property="og:image:alt" content="Pricing plans for Northgate">

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Pricing that scales with your traffic">
<meta name="twitter:description" content="Per-render pricing with no seat fees, and a free tier that covers a small site.">
<meta name="twitter:image" content="https://example.com/images/og/pricing.png">

Titles under about 60 characters and descriptions under about 155, or they truncate in most placements.

Stopping it happening again

Share metadata rots quietly. It breaks during framework migrations, CMS moves and route refactors, and nothing in your test suite notices because the page still returns a 200. A crude assertion over your important URLs catches most of it:

for url in \
  https://example.com/ \
  https://example.com/pricing \
  https://example.com/docs
do
  html=$(curl -sL "$url")
  echo "$html" | grep -q 'property="og:image"' \
    && echo "ok   $url" \
    || echo "FAIL $url"
done

Run it in CI after deploy, and put your top twenty URLs through a checker after any migration, while the traffic that would have hit those broken cards is still recoverable.

The longer version, including how to generate the card image itself when the answer turns out to be that you never had one, is on the HTML to Image blog.

Which of the eight has bitten you? Mine is client-side tags, twice on the same project.

Generate Open Graph images in GitHub Actions (no headless browser required)

Accreditly — Thu, 06 Aug 2026 13:21:26 +0000

You can render Open Graph images, pull request screenshots and release cards from a GitHub workflow without installing a single browser on the runner. No Puppeteer, no apt-get install block for Chrome's dependencies, no cache step for a 300 MB browser download. One workflow step does the rendering remotely and hands you back a file.

The step is html2img/action, the official GitHub Action for the HTML to Image API. We have published a full write-up of the workflow patterns in Generate Open Graph Images in GitHub Actions, and this tutorial walks you through getting from nothing to committed OG images and PR screenshots, step by step.

Why bother moving the render out of the runner at all? Because a GitHub-hosted runner is a fresh machine every run. Anything a headless browser needs gets installed every time or cached with actions/cache, and both routes add minutes and new ways to fail. An API call takes a couple of seconds whatever the page contains, and fonts, emoji and CSS support stop being your problem.

Prerequisites

A GitHub repository with Actions enabled.
A free HTML to Image account. The free tier comes with 50 credits and does not ask for a card. One credit is one render.
Your API key from the dashboard.

Step 1: Add your API key as a secret

In your repository, go to Settings, then Secrets and variables, then Actions, and create a repository secret named HTML2IMG_API_KEY with your key as the value. The action masks the key in logs, but it still belongs in a secret rather than in the workflow file.

Step 2: Render your first image

Create .github/workflows/render.yml:

name: Render

on: workflow_dispatch

jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: html2img/action@v1
        id: render
        with:
          api-key: ${{ secrets.HTML2IMG_API_KEY }}
          html: '<div style="font: 700 72px system-ui; padding: 80px">Hello</div>'
          width: 1200
          height: 630
          output-path: hello.png

      - run: echo "Rendered ${{ steps.render.outputs.url }}"

Run it from the Actions tab. The step writes hello.png into the workspace and sets three outputs you can use in later steps: url (the hosted render), path (where the file landed) and skipped (more on that in a moment).

You give the action exactly one source per step: html for inline markup, html-file for a file in your repository, url to screenshot a live page, or template plus variables to render a named template.

Step 3: Generate OG images for your blog posts

Here is the real workflow: every time posts change on main, find the ones with no social card yet, render them, and commit the PNGs. The example paths are Astro's, but only the paths are. Point it at content/posts and it is a Hugo workflow.

name: OG images

on:
  push:
    branches: [main]
    paths: ['src/content/blog/**']

permissions:
  contents: write

jobs:
  find-posts:
    runs-on: ubuntu-latest
    outputs:
      slugs: ${{ steps.find.outputs.slugs }}
    steps:
      - uses: actions/checkout@v4

      - id: find
        run: |
          slugs=$(for file in src/content/blog/*.md; do
            slug=$(basename "$file" .md)
            if [ ! -f "public/og/$slug.png" ]; then printf '%s\n' "$slug"; fi
          done | jq -R . | jq -sc .)
          echo "slugs=$slugs" >> "$GITHUB_OUTPUT"

  render:
    needs: find-posts
    if: needs.find-posts.outputs.slugs != '[]'
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        slug: ${{ fromJSON(needs.find-posts.outputs.slugs) }}
    steps:
      - uses: actions/checkout@v4

      - name: Build the card markup
        run: |
          title=$(sed -n 's/^title: *//p' "src/content/blog/${{ matrix.slug }}.md" | head -1 | tr -d '"')
          mkdir -p build
          cat > build/card.html <<HTML
          <!doctype html>
          <meta charset="utf-8">
          <div style="display:flex;align-items:center;width:1200px;height:630px;
                      box-sizing:border-box;padding:80px;background:#0f172a;
                      color:#fff;font:700 68px/1.15 system-ui,sans-serif">
            $title
          </div>
          HTML

      - uses: html2img/action@v1
        with:
          api-key: ${{ secrets.HTML2IMG_API_KEY }}
          html-file: build/card.html
          width: 1200
          height: 630
          output-path: public/og/${{ matrix.slug }}.png

      - uses: actions/upload-artifact@v4
        with:
          name: og-${{ matrix.slug }}
          path: public/og/

  commit:
    needs: render
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/download-artifact@v4
        with:
          pattern: og-*
          merge-multiple: true
          path: public/og

      - run: |
          git config user.name 'github-actions[bot]'
          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
          git add public/og
          if git diff --cached --quiet; then
            echo 'No new cards.'
          else
            git commit -m 'Add Open Graph images'
            git push
          fi

Committing the images matters, and it is not just tidiness. On the free plan a hosted render is kept for 7 days. An OG image referenced from a meta tag has to exist for as long as the post does, so the PNG belongs in your repository or your deploy output, not hotlinked from a CDN you do not control.

The card markup above is deliberately minimal so the workflow stays readable. In a real project you would design something better, or skip HTML altogether and use a named template.

Step 4: Screenshot the pull request preview

If your host deploys a preview per pull request, you can screenshot it and post the image as a comment that updates on every push. Reviewers see the change without leaving the PR.

name: Preview screenshot

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  screenshot:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    steps:
      - name: Wait for the preview to answer
        id: preview
        run: |
          url="https://deploy-preview-${{ github.event.pull_request.number }}--example.netlify.app"
          for _ in $(seq 1 30); do
            if curl -fsS -o /dev/null "$url"; then
              echo "url=$url" >> "$GITHUB_OUTPUT"
              exit 0
            fi
            sleep 10
          done
          exit 1

      - uses: html2img/action@v1
        id: shot
        with:
          api-key: ${{ secrets.HTML2IMG_API_KEY }}
          url: ${{ steps.preview.outputs.url }}
          width: 1280
          height: 800
          wait-for-selector: 'main'
          css: '.cookie-banner, .chat-widget { display: none !important }'

      - uses: peter-evans/create-or-update-comment@v4
        with:
          issue-number: ${{ github.event.pull_request.number }}
          body: |
            Preview of ${{ github.event.pull_request.head.sha }}:

            ![Preview screenshot](${{ steps.shot.outputs.url }})

Two inputs are doing the heavy lifting. wait-for-selector holds the capture until your content actually exists in the DOM, and returns the moment it does, which beats guessing a fixed delay. css injects styles over the page's own, and since the page's styles usually win on specificity, that !important is not optional. It is the cleanest way to hide a cookie banner before the shot.

Note the if: guard. GitHub does not expose secrets to workflows triggered by pull requests from forks, so this recipe is for branches on your own repository. That is a platform security decision, and a sensible one, but it is better to know before you wonder why fork PRs get no screenshot.

Two things that save your credits

First, caching. When output-path is set, the action hashes the resolved inputs and writes the digest next to the file as <output-path>.html2img-hash. If the file and a matching digest already exist, the API is never called and the skipped output is true. Commit both files, as the OG workflow does, and re-runs cost nothing. CI re-runs identical work all day long, so this default is what keeps 50 free credits meaning 50 images rather than 50 workflow runs.

Second, DPI. For HTML sources the API's dpi default is 2, so a 1200 by 630 card comes back as a 2400 by 1260 file. That is the right call for retina screens, but if anything downstream asserts exact pixel dimensions, set dpi: 1.

Going further

The same step renders named templates (template: open-graph-image with a variables JSON object), which is how you attach a social card to every release without maintaining any markup, and it takes format: pdf if the artefact you need is a document rather than an image. The full article covers the release workflow, the PDF options and the parameter combinations the action refuses to send, and the action's README has the complete inputs table.

In this tutorial you have set up an API key as a secret, rendered a first image from a workflow, wired up committed OG images for a blog and posted preview screenshots on pull requests, all without a browser anywhere near your CI.

Are you generating OG images at build time, in CI, or on demand at request time? Share your setup in the comments below.

DEV Community: Accreditly

Screenshot Every Page of a Website from Its Sitemap with One Node.js Script

Prerequisites

Step 1: Find the sitemap

Step 2: The script

Step 3: Dry run first, then capture

What the script does when things go wrong

A few limits worth planning around

Where I'd use this

I Tested html2canvas, html-to-image and modern-screenshot on the Same Card

The test card

Two ways to turn the DOM into pixels

The results in Chromium

Trap 1: web fonts from a <link> tag

Trap 2: the first capture in Safari's engine

Trap 3: images from a host without CORS headers

The scorecard

When the browser is the wrong place to render

Invoice PDFs from one API call: what I sent, what came back, and how I checked it was a real PDF

Prerequisites

Step 1: send the invoice as JSON and ask for a PDF

Step 2: check it is a document, not a screenshot

Step 3: the receipt, twice from one function

Step 4: when the template is not your brand, send your own HTML

Step 5: put it in a queued job and keep the bytes

What I would tell past me

Turn a JSON File of Testimonials into Quote Card Images with One Node.js Script

Prerequisites

Step 1: Render one card by hand

Step 2: Write the loop

Step 3: Download the files (optional)

Step 4: Keep the batch honest

How HTML to PDF Conversion Actually Works: Rendering Engines, Text Objects and Fonts

Same pipeline, different last step

Pixels in, points out

What a text layer actually is

How fonts get inside the file

Vector where it can, raster where it must

The screenshot in a wrapper

The three-command check

Convert HTML to PDF in Node.js With One API Call

What one request gives you

Prerequisites

Step 1: install the client and store your key

Step 2: render your first PDF

Step 3: build the document from a template

Step 4: download the file, attach it, or keep the URL

Step 5: serve it from an API route

Fixed-width layouts: scale the design to the page

Handle the errors that will actually happen

Long reports: take the render off the request

What you are no longer maintaining

Recap

I Tested 7 HTML to PDF APIs Against the Same Awkward Invoice

The invoice that does the judging

How the judging works

The scorecard

HTML to Image

DocRaptor

PDFShift

Api2Pdf

PDFCrowd

PDFMonkey

Gotenberg, if you would rather run it yourself

What the same invoice costs at three volumes

Which one should you pick

Can I use it in a PDF? CSS support across HTML to PDF engines

The four engines

The support table

The row that changed recently: headers and footers

The rows Chromium does not have at all

The gotchas hiding inside "Yes"

Picking an engine

How to Generate Images in n8n (Social Cards, Certificates and PDF Reports)

Prerequisites

How the API fits into n8n

Step 1: Create the credential

Step 2: Social cards from an RSS feed

Step 3: Certificates from a form submission

Step 4: A weekly report PDF on a schedule

Trap 1: web fonts from a `<link>` tag

2. `og:image` is a relative path

4. No `og:image:width` and `og:image:height`

6. `twitter:card` is missing so X renders the small card