How to Preserve Colors When Exporting R Markdown to PDF With Puppeteer

Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.

Render the R Markdown document to HTML, add print-color CSS, and then create the PDF with Puppeteer. Chromium uses the print media type for page.pdf() and may alter colors unless you request exact color adjustment. Set printBackground: true for filled panels, and use page.emulateMediaType('screen') only when the PDF should follow your on-screen stylesheet rather than your print stylesheet.

The reliable rendering path

There are two separate operations:

1. R Markdown to HTML: rmarkdown::render() creates the document, executes chunks, and attaches your CSS.
2. HTML to PDF: Puppeteer opens that HTML in Chromium and calls page.pdf().

Color problems usually happen in the second operation. A browser can apply print-specific rules, suppress background graphics, or adjust colors for paper. The following setup makes those decisions explicit.

#	Preview	Product	Price
1		R Markdown: The Definitive Guide (Chapman & Hall/CRC The R Series)	$20.00	Buy on Amazon
2		R Markdown Cookbook (Chapman & Hall/CRC The R Series)	$25.31	Buy on Amazon
3		bookdown (Chapman & Hall/CRC The R Series)	$22.90	Buy on Amazon
4		Analyzing Social Networks Using R	$41.91	Buy on Amazon

Install the components

In R, install the renderer if necessary:

install.packages(c("rmarkdown", "knitr"))

In a JavaScript project, install Puppeteer:

npm install puppeteer

Puppeteer downloads a compatible Chromium build during installation unless your project is configured to use an existing browser.

Add print-aware color CSS

Create a file named print-colors.css beside your .Rmd file:

#1 Best Overall

Sale

R Markdown: The Definitive Guide (Chapman & Hall/CRC The R Series)

$20.00

Buy on Amazon

@media print {
  *, *::before, *::after {
    -webkit-print-color-adjust: exact;
    print-color-adjust: exact;
  }
}

/* Example callout colors */
.callout-warning {
  background: #fff3cd;
  border-left: 0.35rem solid #d39e00;
  color: #664d03;
}

.callout-info {
  background: #cff4fc;
  border-left: 0.35rem solid #087990;
  color: #055160;
}

The vendor-prefixed declaration supports Chromium’s implementation; the unprefixed declaration is the standards spelling. Applying the rule to pseudo-elements matters when a theme draws borders, badges, or icons with ::before and ::after.

If you want exact color adjustment only for selected components, replace the universal selector with a class such as .callout, .callout::before, .callout::after. A universal rule is the simplest way to preserve an entire report, but it can produce darker or more saturated output on some printers.

Attach the stylesheet in YAML

---
title: "Color test report"
output:
  html_document:
    css: print-colors.css
    self_contained: true
---

css accepts a CSS or Sass file. self_contained: true embeds linked stylesheets, images, and scripts as data URIs so a local Chromium run does not lose dependencies. MathJax remains external even in a self-contained HTML file, so provide network access or configure a local MathJax copy when mathematical formulas are required.

Put the rule in an R Markdown CSS chunk

For a one-file report, the same rule can live in a CSS chunk:

```{css, echo = FALSE}
@media print {
  *, *::before, *::after {
    -webkit-print-color-adjust: exact;
    print-color-adjust: exact;
  }
}
```

Use the file-based stylesheet when several reports share a theme; use the chunk when the print behavior belongs only to one report.

Render the Rmd to HTML

Run this command from the directory containing the source file:

Rank #2

Sale

R Markdown Cookbook (Chapman & Hall/CRC The R Series)

$25.31

Buy on Amazon

Rscript -e 'rmarkdown::render("report.Rmd", output_format = "html_document", output_file = "report.html")'

For an R script or an interactive session:

rmarkdown::render(
  "report.Rmd",
  output_format = "html_document",
  output_file = "report.html"
)

Specifying html_document is intentional. The pdf_document format follows the LaTeX route and is not controlled by browser print CSS or Puppeteer settings.

Check the HTML before involving Puppeteer

1. Open report.html directly in Chromium.
2. Confirm that callouts, syntax-highlighted code, table headers, and other colored elements look correct on screen.
3. Open developer tools and inspect the element’s computed background-color and color.
4. Use the print preview to see whether the print media query changes the result.

If the color is already missing in the HTML, fix the R Markdown theme, generated markup, or CSS path first. Puppeteer cannot restore a color that was never present in the document.

Export the HTML with Puppeteer

Save this as export-pdf.js:

const puppeteer = require('puppeteer');
const path = require('node:path');
const { pathToFileURL } = require('node:url');

(async () => {
  const browser = await puppeteer.launch({ headless: 'new' });
  try {
    const page = await browser.newPage();
    const htmlPath = path.resolve('report.html');

    // Print media is the default for page.pdf(); this makes it explicit.
    await page.emulateMediaType('print');
    await page.goto(pathToFileURL(htmlPath).href, {
      waitUntil: 'load',
      timeout: 60_000
    });

    // Wait for web fonts when the page uses them.
    await page.evaluate(() => document.fonts && document.fonts.ready);

    await page.pdf({
      path: 'report.pdf',
      printBackground: true,
      preferCSSPageSize: true
    });
  } finally {
    await browser.close();
  }
})();

Run it with:

node export-pdf.js

printBackground: true enables CSS background graphics. Without it, a colored callout may retain its text and border while losing its fill. preferCSSPageSize: true tells Chromium to honor an @page declaration instead of overriding it with Puppeteer’s format, width, or height settings.

Control paper size and margins in CSS

@page {
  size: A4;
  margin: 16mm 14mm 18mm;
}

@media print {
  .page-break {
    break-after: page;
  }
}

Use letter instead of A4 when that is the required paper size. If you omit @page, you can set format: 'A4' or another Puppeteer format in the JavaScript options, but do not expect that option to preserve CSS page-size rules unless preferCSSPageSize is enabled.

When to emulate screen media instead

page.pdf() uses print media by default. That is normally desirable because it lets you hide navigation, adjust spacing, and apply print-only page breaks. If the report’s intended appearance is exactly the screen version, switch before exporting:

await page.emulateMediaType('screen');
await page.pdf({
  path: 'report-screen-colors.pdf',
  printBackground: true,
  preferCSSPageSize: true
});

This does not disable the need for printBackground; background graphics still depend on that PDF option. It also does not make printer color management identical to a monitor. It simply selects the screen media query while Chromium generates the PDF.

Rank #3

Sale

bookdown (Chapman & Hall/CRC The R Series)

• bookdown: Authoring Books and Technical Documents with R Markdown
• ABIS BOOK
• CRC Press

$22.90

Buy on Amazon

Choosing an R Markdown PDF route

pagedown::chrome_print() is a practical alternative when you want an R-side command to print HTML with Chrome. It remains a browser workflow, so the CSS and Chromium-version considerations still apply. Do not mix instructions for pdf_document() with Puppeteer: they are different rendering pipelines.

Pagination, assets, and loading reliability

Make dependencies resolvable

Relative CSS, fonts, and images are resolved from the HTML location. Keep the generated file and its asset directories together, or use self_contained: true to embed most dependencies. A stylesheet path that works in RStudio can fail when a different working directory is used by a CI job.

Wait for content that changes after load

If JavaScript inserts a table or chart after the initial load, wait for a stable selector before calling page.pdf():

await page.goto(pathToFileURL(htmlPath).href, { waitUntil: 'load' });
await page.waitForSelector('#final-report', { timeout: 30_000 });
await page.evaluate(() => document.fonts && document.fonts.ready);

Use a selector that your document actually creates. Waiting for network idle can be useful for remote assets, but analytics, live widgets, or long polling can prevent the network from becoming idle. For a static self-contained report, load plus an explicit selector or font wait is usually more predictable.

Use print-only page breaks

Keep a break marker visible on screen only when it helps editing, then activate the break for print:

.page-break {
  display: none;
}

@media print {
  .page-break {
    display: block;
    break-after: page;
  }
}

This avoids blank space in the interactive HTML while preserving deliberate section boundaries in the PDF.

Rank #4

Sale

Analyzing Social Networks Using R

$41.91

Buy on Amazon

Troubleshooting color and PDF failures

Reproducibility, performance, and cost

Pin the Puppeteer version and record the Chromium version used in CI. Print behavior, default flags, and font rasterization can change when either dependency changes. Keep a representative color fixture containing backgrounds, borders, syntax-highlighted code, and at least one page break; compare generated PDFs after upgrades.

Self-contained HTML reduces missing-file failures but can make the HTML larger. Waiting for a precise selector is generally faster and more deterministic than an unlimited network-idle wait. For large reports, render once to HTML and reuse that file for repeated PDF attempts instead of rerunning every R chunk.

Puppeteer does not define a per-document service price in this setup. Your operational cost is the machine or CI runtime and any browser-hosting service you add. A hosted URL-to-screenshot service can be useful when you do not want to install Chromium.

Or skip the browser setup

If the rendered report is available at a public URL, ScreenshotNeo can capture that page through one GET request and return PNG, JPEG, WebP, or PDF output. Its clean-shot workflow accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.

For the complete parameter list and PDF options, see the ScreenshotNeo documentation. A basic request looks like this:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://your-domain.example/report.html -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://your-domain.example/report.html"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://your-domain.example/report.html'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`ScreenshotNeo returned ${res.status}`);

ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. Every feature is available on every plan: the Free plan includes 1,000 shots per month with no card, and paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to try it without adding a card.

Frequently Asked Questions

Will exact color adjustment make a printed sheet look identical to my monitor?

No. It asks Chromium to preserve the CSS colors in the PDF; paper, printer profiles, and display calibration can still make the physical print look different.

Can I keep different colors for screen and PDF versions?

Yes. Put the PDF palette in @media print and the interactive palette in normal or @media screen rules, then choose the matching Puppeteer media type.

How should I diagnose a difference that appears only after a Puppeteer upgrade?

Save the generated HTML, PDF, Puppeteer version, and Chromium version, then compare the same fixture with the previous pinned environment. This separates CSS changes from browser implementation changes.

Quick Recap

SaleBestseller No. 1

R Markdown: The Definitive Guide (Chapman & Hall/CRC The R Series)

$20.00

SaleBestseller No. 2

R Markdown Cookbook (Chapman & Hall/CRC The R Series)

$25.31

SaleBestseller No. 3

bookdown (Chapman & Hall/CRC The R Series)

bookdown: Authoring Books and Technical Documents with R Markdown; ABIS BOOK; CRC Press

$22.90

SaleBestseller No. 4

Analyzing Social Networks Using R

$41.91

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.