wkhtmltopdf option mapping
This covers every option listed by --extended-help in wkhtmltopdf 0.12.6, that is the official manual at https://wkhtmltopdf.org/usage/wkhtmltopdf.txt. The sections and their order follow that manual.
| Symbol | Meaning |
|---|---|
| ✅ Supported | Available under the same name with the same meaning as in wkhtmltopdf |
| ❌ Not supported | Deliberately not implemented. Passing one prints what to use instead and exits with code 1; it is never ignored silently |
The behavioural differences people trip over when moving across are collected in Migrating from wkhtmltopdf.
Differences in the command line itself
wkhtmltopdf specifies the cover and the table of contents as positional arguments.
wkhtmltopdf cover cover.html toc page.html out.pdf # wkhtmltopdf
sghtmltopdf --cover cover.html --toc page.html -o out.pdf # sghtmltopdf
sghtmltopdf takes a single HTML file as input and uses the --cover <path> and --toc options instead. Merging several HTML files, which wkhtmltopdf does by listing them as positional arguments, is not supported.
For the same reason --exclude-from-outline and --include-in-outline, which exclude individual input pages from the outline, are out of scope.
Global Options
| Option | Rationale | Notes |
|---|---|---|
--collate, --no-collate | ❌ Not supported | Collation when printing; it means nothing when producing a PDF |
--cookie-jar <path> | ❌ Not supported | Authenticated fetching is out of scope |
--copies <number> | ❌ Not supported | As above; it is a printing concern |
-d, --dpi <dpi> | ✅ Supported | 96 by default |
-H, --extended-help | ❌ Not supported | Folded into --help |
-g, --grayscale | ✅ Supported | |
-h, --help | ✅ Supported | Generated by clap |
--htmldoc, --manpage, --readme, --license | ❌ Not supported | The documentation lives in docs/ and the README |
--image-dpi <integer> | ❌ Not supported | Images are never resampled |
--image-quality <integer> | ❌ Not supported | There is no JPEG decoder or encoder; the data is embedded as it is |
--log-level <level> | ✅ Supported | none, error, warn, info |
-l, --lowquality | ❌ Not supported | There is no counterpart to WebKit’s rasterisation quality setting |
-B, --margin-bottom <unitreal> | ✅ Supported | |
-L, --margin-left <unitreal> | ✅ Supported | The default differs; see below |
-R, --margin-right <unitreal> | ✅ Supported | The default differs; see below |
-T, --margin-top <unitreal> | ✅ Supported | |
-O, --orientation <orientation> | ✅ Supported | Portrait, Landscape |
--page-height <unitreal> | ✅ Supported | |
-s, --page-size <Size> | ✅ Supported | A4, A3, A5, Letter, Legal |
--page-width <unitreal> | ✅ Supported | |
--no-pdf-compression | ✅ Supported | Flate compression is currently always on |
-q, --quiet | ✅ Supported | The same as --log-level none |
--read-args-from-stdin | ❌ Not supported | Standard input is used for the HTML, so the two would clash |
--title <text> | ✅ Supported | The PDF Info dictionary; without it the <title> is used |
--use-xserver | ❌ Not supported | There is no dependency on an X server |
-V, --version | ✅ Supported |
Default margins: wkhtmltopdf uses 10mm left and right and leaves top and bottom unset, while sghtmltopdf currently defaults to 96px, that is 1in or 25.4mm, on all four sides. The default is not being changed, so that existing output stays as it is. State --margin-* explicitly when you move across.
Outline Options
PDF outlines, that is bookmarks, are not supported at all, so nothing in this section is. A table of contents inside the document can be built with --toc.
| Option | Rationale | Notes |
|---|---|---|
--outline, --no-outline | ❌ Not supported | PDF bookmarks are not implemented |
--outline-depth <level> | ❌ Not supported | As above |
--dump-outline <file> | ❌ Not supported | As above |
--dump-default-toc-xsl | ❌ Not supported | XSLT is not used |
Page Options
| Option | Rationale | Notes |
|---|---|---|
--allow <path> | ✅ Supported | The directories local reads are confined to; it matters most in server mode |
--background, --no-background | ✅ Supported | |
--bypass-proxy-for <value> | ❌ Not supported | Proxies are not supported |
--cache-dir <path> | ❌ Not supported | There is no fetch cache; one can be added if it turns out to be needed |
--checkbox-checked-svg, --checkbox-svg, --radiobutton-checked-svg, --radiobutton-svg | ❌ Not supported | SVG cannot be drawn. Form controls are drawn with built-in shapes instead |
--cookie <name> <value> | ❌ Not supported | Authenticated fetching is out of scope |
--custom-header <name> <value>, --custom-header-propagation | ❌ Not supported | As above |
--debug-javascript, --no-debug-javascript | ❌ Not supported | JavaScript is not supported |
--default-header | ✅ Supported | A default header with the document name and page number; a shortcut for the simple header options |
--encoding <encoding> | ✅ Supported | The order is BOM, --encoding, <meta charset>, then UTF-8 |
--disable-external-links, --enable-external-links | ✅ Supported | Link annotations |
--disable-forms, --enable-forms | ❌ Not supported | Fillable PDF forms (AcroForm) are never produced |
--images, --no-images | ✅ Supported | |
--disable-internal-links, --enable-internal-links | ✅ Supported | |
-n, --disable-javascript, --enable-javascript | ❌ Not supported | Executing JavaScript is a deliberate non-goal |
--javascript-delay <msec> | ❌ Not supported | As above |
--keep-relative-links, --resolve-relative-links | ✅ Supported | How link annotation URLs are resolved, implemented together with <base href> |
--load-error-handling <handler> | ✅ Supported | abort and ignore. There is no skip, since there is only one input |
--load-media-error-handling <handler> | ✅ Supported | Failures to fetch images, fonts, and stylesheets |
--disable-local-file-access, --enable-local-file-access | ✅ Supported | Arranged alongside the existing --allow-remote-assets |
--minimum-font-size <int> | ✅ Supported | |
--exclude-from-outline, --include-in-outline | ❌ Not supported | Meaningless when there is only one input |
--page-offset <offset> | ✅ Supported | Where page numbering starts |
--password, --username | ❌ Not supported | HTTP authentication is out of scope |
--disable-plugins, --enable-plugins | ❌ Not supported | There is no plugin mechanism |
--post <name> <value>, --post-file <name> <path> | ❌ Not supported | POSTing when the input is a URL is out of scope |
--print-media-type, --no-print-media-type | ❌ Not supported | Print media is always assumed |
-p, --proxy <proxy>, --proxy-hostname-lookup | ❌ Not supported | Proxies are not supported |
--run-script <js> | ❌ Not supported | JavaScript is not supported |
--disable-smart-shrinking, --enable-smart-shrinking | ❌ Not supported | A shrinking strategy specific to WebKit |
--ssl-crt-path, --ssl-key-password, --ssl-key-path | ❌ Not supported | Client certificates are out of scope |
--stop-slow-scripts, --no-stop-slow-scripts | ❌ Not supported | JavaScript is not supported |
--disable-toc-back-links, --enable-toc-back-links | ✅ Supported | Links back from a heading to the table of contents |
--user-style-sheet <path> | ✅ Supported | CSS in the user origin |
--viewport-size <size> | ❌ Not supported | There is no notion of a viewport |
--window-status <status> | ❌ Not supported | JavaScript is not supported |
--zoom <float> | ✅ Supported |
Headers And Footer Options
Everything in this section is supported. Since JavaScript is not executed, the page variables that wkhtmltopdf passed as a query such as ?page=1&topage=5 on the --header-html URL, to be inserted by JavaScript, are handled by substituting placeholders as text.
| Option | Rationale | Notes |
|---|---|---|
--header-left, --header-center, --header-right | ✅ Supported | Mapped onto the @page margin boxes |
--footer-left, --footer-center, --footer-right | ✅ Supported | As above |
--header-html <url>, --footer-html <url> | ✅ Supported | A separate HTML file is rendered into the margin area |
--header-line, --no-header-line | ✅ Supported | |
--footer-line, --no-footer-line | ✅ Supported | |
--header-spacing <real>, --footer-spacing <real> | ✅ Supported | mm |
--header-font-name, --header-font-size | ✅ Supported | |
--footer-font-name, --footer-font-size | ✅ Supported | |
--replace <name> <value> | ✅ Supported | Replaces [name] in the header or footer, mapping directly onto the placeholder scheme here |
Of wkhtmltopdf’s built-in placeholders, the ones that work are [page], [frompage], [topage], [date], [time], and [title] with [doctitle]. [section] and [subsection], which name the nearest heading, and [webpage], [sitepage], and [sitepages], which are for multiple inputs, are not supported. Any other name can be defined with --replace.
TOC Options
The HTML structure and default styling of the generated table of contents follow what wkhtmltopdf’s default TOC XSL produces: nested <ul> for the levels, and <li><div><a>heading</a><span>page number</span></div></li> for each entry.
| Option | Rationale | Notes |
|---|---|---|
--toc-header-text <text> | ✅ Supported | “Table of Contents” by default; the text of the <h1> |
--toc-level-indentation <width> | ✅ Supported | 1em by default; ul { padding-left } |
--toc-text-size-shrink <real> | ✅ Supported | 0.8 by default; ul ul { font-size: 80% } |
--disable-dotted-lines | ✅ Supported | Omits the border-bottom: dashed on the div |
--disable-toc-links | ✅ Supported | Omits the <a href> links from the entries to the headings |
--xsl-style-sheet <file> | ❌ Not supported | XSLT is not supported; change the appearance with --user-style-sheet |
Options unique to sghtmltopdf
| Option | What it does |
|---|---|
--font <path>, --font-index <N> | Names the fonts explicitly; optional and repeatable. Without it the system fonts are used |
--gothic-font, --mono-font, --serif-font, each with an -index | Names the actual font behind the generic families sans-serif, monospace, and serif |
--allow-remote-assets | Allows fetching absolute http(s) URLs |
--streaming | Processes the input in streaming mode |
--base-url <url|dir> | The base for resolving relative references, for example when reading from standard input |
--author, --subject, --keywords | The PDF Info dictionary; wkhtmltopdf only had --title |
--cover <path>, --toc | The cover and the table of contents; wkhtmltopdf used positional arguments |
The server subcommand | HTTP server mode |