Pagecraft

html-to-pdf

HTML to PDF

Set a page of HTML on paper, with the page size, margins and breaks it asks for.

Reads
an HTML file — text/html, application/xhtml+xml
Writes
one file — PDFs
Tool page
/html-to-pdf

Example

Print an invoice template your own system produced.

Given

  • invoice.html — an HTML file

From code

            import { loadDocument, runOperation } from '@pagecraft/core';

const invoice = await loadDocument({ bytes, name: 'invoice.html' });

const [output] = await runOperation('html-to-pdf', [invoice], {
  size: 'a4',
  margin: 20,
});

From a shell

            pagecraft html-to-pdf invoice.html --size a4 --margin 20

What comes back

One PDF, containing “Quarterly report”.

This example is run by the test suite. If it stopped being true, the build would fail.

Options

filename--filename

string

Filename

What the PDF will be called.

Default: ''

size--size

string, one of

Page size

Default: 'source'

  • source — The size and margins in the file, or A4 with 20mm where it names none.
  • a3 — A3
  • a4 — A4
  • a5 — A5
  • a6 — A6
  • b5 — B5
  • letter — Letter
  • legal — Legal
  • tabloid — Tabloid
  • executive — Executive
  • custom — Custom size

width--width

number

Width

Only when size is 'custom'.

Default: 210

height--height

number

Height

Only when size is 'custom'.

Default: 297

orientation--orientation

string, one of

Orientation

Default: 'portrait'

  • portrait — Portrait
  • landscape — Landscape

margin--margin

number

Margin

Default: 20

unit--unit

string, one of

Measured in

Default: 'mm'

  • mm — Millimetres
  • cm — Centimetres
  • in — Inches
  • pt — Points

fontSize--font-size

number (pt)

Text size

Default: 11

lineHeight--line-height

number

Line spacing

A multiple of the text size. 1.4 is what a book uses.

Default: 1.4

align--align

string, one of

Alignment

Default: 'left'

  • left — Even word spacing; an uneven right edge.
  • justify — Both edges flush; the word spacing stretches to do it.

font--font

string, one of

Typeface

Default: 'sans'

  • sans — Helvetica.
  • serif — Times.
  • mono — Courier.

fontFile--font-file

Uint8Array

Font file

A TrueType or OpenType font to set the text in. Needed for scripts the built-in fonts do not cover, unless the host supplies one.

header--header

string

Running head

Drawn at the top of every page, in place of the file's own. Understood: {n}, {total}, {filename}, {date}.

Default: ''

footer--footer

string

Running foot

Drawn at the foot of every page, in place of the file's own. Understood: {n}, {total}, {filename}, {date}.

Default: ''

What it cannot do

  • This is not a browser. Nothing is fetched, nothing is run, and there is no viewport: an external stylesheet, an image at a URL, a web font and anything a script would have written are all absent from the file that is read, so they are absent from the PDF.
  • The stylesheet is read for `@page` size and margins, for page breaks, and for `font-size`, `font-weight`, `font-style`, `font-family`, `color` and `text-align`. Selectors are matched by element, class and id only. Everything else — floats, flexbox, grid, positioning, backgrounds, borders — is ignored, so a page laid out in columns is set as one column.
  • A `<header>` or `<footer>` at the top level of the body becomes the running head or foot on every page rather than content at the start of it. It understands {n}, {total}, {filename} and {date}.
  • A picture is drawn only where the file carries its bytes, as a `data:` URI. One named by a path or an address has its alt text set in its place.
  • Text is set in the standard fonts every reader already carries, so the file renders identically on a machine that has none of your fonts installed. Anything they cannot draw needs a font file, which is embedded and subsetted into the PDF with it.
  • A font file you supply is used for everything: bold, italic and monospaced text are all drawn in that one face rather than in a bold, italic or fixed-width cut of it. Code blocks and columns of figures lose their alignment as a result, so supply one only when the built-in fonts cannot draw your text.
  • Shaping and joining come from the font itself, and nothing reorders a line: text is drawn in the order it is given, so a line mixing right-to-left and left-to-right writing comes out in that order rather than in reading order.