Migrating from wkhtmltopdf
Most option names are the same as in wkhtmltopdf. A few of them behave differently despite the shared name, so it is worth going through this page.
The wkhtmltopdf option mapping covers every option. If you use it from Rails through wicked_pdf, see Migrating from wicked_pdf.
Where the behaviour differs
| wkhtmltopdf | sghtmltopdf | |
|---|---|---|
CLI options versus @page in CSS | The CLI wins | @page wins; the CLI provides initial values |
| Default margins | 10mm left and right | 1in (96px) on all four sides |
| Specifying a cover and a table of contents | Positional arguments, as in cover a.html toc | --cover <PATH> and --toc |
| Merging several HTML files | Supported | Not supported; the input is a single file |
| Page variables in headers and footers | Injected with JavaScript | Placeholder substitution; JavaScript is not executed |
| Fonts | System fonts | The same, and --font can pin them |
| Unsupported options | Sometimes ignored silently | Stops with exit code 1 and explains why |
@page wins
This is the difference people trip over most. If the CSS says @page { margin: 0 }, then --margin-top 20mm is ignored.
@page { size: A4; margin: 20mm; } /* this one wins */
The CLI options act as initial values for whatever the CSS does not set. To drive it from the CLI, remove the corresponding property from @page in the HTML.
Default margins
wkhtmltopdf uses 10mm on the left and right, sghtmltopdf 1 inch (96px, or 25.4mm) on all four sides. Converting without saying anything therefore changes the margins, so state them to keep the existing look.
sghtmltopdf in.html -o out.pdf \
--margin-top 10mm --margin-bottom 10mm --margin-left 10mm --margin-right 10mm
Cover page and table of contents
wkhtmltopdf cover cover.html toc page.html out.pdf # wkhtmltopdf
sghtmltopdf --cover cover.html --toc page.html -o out.pdf # sghtmltopdf
The table of contents is styled to match what wkhtmltopdf’s default TOC XSL produces. XSLT is not supported, so change it with CSS through --user-style-sheet.
Page numbers in headers and footers
wkhtmltopdf appended a query such as ?page=1&topage=5 to the --header-html URL and let JavaScript on that page insert the values. Since JavaScript is not executed here, sghtmltopdf substitutes placeholders as text instead.
sghtmltopdf report.html --footer-center "[page] / [topage]"
When the header is built in HTML, [page] is likewise substituted in the HTML as text.
Unsupported options are never ignored silently
Passing one exits with exit 1, explaining why and what to use instead. This is to keep you from moving over and never noticing that an option has no effect.
The main ones are these.
- JavaScript:
--enable-javascript,--javascript-delay,--run-script,--window-status,--debug-javascript,--stop-slow-scripts. Executing JavaScript is a deliberate non-goal - PDF outlines:
--outline,--outline-depth,--dump-outline - XSLT:
--xsl-style-sheet,--dump-default-toc-xsl. The table of contents uses a built-in template plus CSS instead - Re-encoding images:
--image-quality,--image-dpi - Networking:
--proxy,--cookie,--custom-header,--usernameand--password,--ssl-* - WebKit specific:
--disable-smart-shrinking,--viewport-size,--lowquality,--print-media-type. Print media is always assumed - PDF forms:
--enable-forms
Adjustments you may need in the HTML and CSS
Ranges
!importantis not supported; a declaration carrying it is ignoredinherit,initial, andunsetare not supported- Viewport units such as
vwandvh, andex,ch, andlh, are not supported. Write lengths withpx,em,rem, or the absolute unitsmm,cm,in,pt,pc, andQ
See Selectors, values, and at-rules for details.
Checking that the move worked
Start by converting with --log-level info, the default, and check that no warnings appear. Unsupported options stop the run with exit code 1, so once a conversion succeeds every option has been understood. After that, compare the output by eye, looking at the margins, where the pages break, and the fonts.