ep_pdf_export_chromium

⚠️ ADVANCED / SELF-HOSTED ONLY

This plugin needs a system Chromium installed in your Etherpad Docker image. Installing it from the admin panel alone is NOT enough — without Chromium the export route just returns 503. Only use this if you control your own image (custom Dockerfile / docker compose).

If you just want a PDF button that works out of the box, install ep_pdf_export_print instead — it renders in the user's own browser and needs nothing on the server.

Server-side, high-fidelity PDF export for Etherpad.

Etherpad's built-in PDF export uses a hand-rolled pdfkit HTML walker. It overlaps text, drops text colours and ignores images that aren't inline base64. This plugin instead takes the pad's HTML export — which is already correct (images, colours, alignment) — and renders it through a real headless Chromium, returning Chromium's own print-to-PDF output.

Route

GET /p/:padId/export/pdf2
GET /p/:padId/:rev/export/pdf2

The response is a downloadable :padId.pdf. The plugin also adds a “PDF (server)” entry to the export menu (the stock Import/Export popup, or ep_file_menu_toolbar / ep_aa_file_menu_toolbar if present) that points at this route, so users don't have to type the URL.

Install

Install the plugin from the Etherpad admin panel (search ep_pdf_export_chromium), or from the command line:

pnpm run plugins i ep_pdf_export_chromium

Then two more things are required for it to actually work:

1. A system Chromium in your Etherpad image — without it the export route returns 503. See Requirements — a system Chromium below.
2. Companion plugins for images & tables — this plugin does not render images or tables by itself, so without them those parts of your pads come out broken in the PDF:
   • Images → ep_images_extended_v2
   • Tables → ep_data_tables + ep_table_export

Requirements & dependencies

• A system Chromium in the image — the one hard requirement (see the next section). Without it the route returns 503.
• Etherpad (peer dependency ep_etherpad-lite). Nothing else is needed for the export itself to run — but images and tables need the companion plugins below to actually appear in the PDF.
• npm dependency puppeteer-core (installed automatically; it does not download a browser).
• Companion plugins for images & tables — install these, or your output will look broken. The PDF is built from Etherpad's HTML export, and if your pads contain images or tables but these are not installed, those elements will be missing or mangled in the PDF. This is not optional polish:
  • Images → ep_images_extended_v2 — use this fork (the export bugs are fixed). The original ep_images_extended has broken export and will drop images from the PDF.
  • Tables → ep_data_tables plus ep_table_export — without ep_table_export tables will not render in the export at all.

Requirements — a system Chromium

This plugin does not bundle a browser. It drives a Chromium that already exists in the image via puppeteer-core. The official Etherpad Docker image is Alpine-based, where the Chromium that full puppeteer would download (a glibc build) cannot run — so you must install the system package.

Extend the image:

FROM etherpad/etherpad:latest
USER root
RUN apk add --no-cache \
      chromium nss freetype harfbuzz ttf-freefont ca-certificates
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
USER etherpad

On Debian/Ubuntu-based images use apt-get install -y chromium (path /usr/bin/chromium).

If no Chromium is found the route answers 503 with a clear message; the rest of Etherpad keeps working.

Configuration

All optional, under ep_pdf_export_chromium in settings.json:

{
  "ep_pdf_export_chromium": {
    "executablePath": "/usr/bin/chromium-browser",
    "format": "A4",
    "landscape": false,
    "printBackground": true,
    "margin": { "top": "20mm", "bottom": "20mm", "left": "15mm", "right": "15mm" },
    "timeoutMs": 30000
  }
}

If executablePath is omitted the plugin checks PUPPETEER_EXECUTABLE_PATH, CHROMIUM_PATH, then the usual install locations.

How it works

1. ExportHtml.getPadHTMLDocument() builds the full HTML document (the same one /export/html returns, including any plugin export hooks such as ep_images_extended).
2. A <base href> for this Etherpad origin is injected so relative image URLs resolve.
3. A shared, lazily-launched headless Chromium loads the HTML and runs page.pdf().

See also

• ep_pdf_export_print — the zero-setup, admin-panel-installable companion that prints via the user's browser.

License

Apache-2.0 © Ivan Forkaliuk