wkhtmltopdfからの移行

オプション名の多くはwkhtmltopdfと同じです。ただし同じ名前でも結果が違うものがいくつかあるので、確認してください。

全オプションの対応状況はwkhtmltopdfオプション対応表にあります。 Railsでwicked_pdf経由で使っている場合はwicked_pdfからの移行を参照してください。

挙動が違うところ

もっとも引っかかりやすい違いです。 CSSに@page { margin: 0 }と書いてあると、--margin-top 20mmは無視されます。

@page { size: A4; margin: 20mm; }   /* こちらが勝つ */

CLIオプションは「CSSに書かれていなかったときの初期値」として働きます。 CLIで制御したい場合は、HTMLから@pageの該当プロパティを外してください。

wkhtmltopdfは左右10mm、sghtmltopdfは四辺1インチ(96px = 25.4mm)です。指定なしで変換すると余白が変わるので、既存の見た目を保つには明示します。

sghtmltopdf in.html -o out.pdf \
  --margin-top 10mm --margin-bottom 10mm --margin-left 10mm --margin-right 10mm

wkhtmltopdf cover cover.html toc page.html out.pdf          # wkhtmltopdf
sghtmltopdf --cover cover.html --toc page.html -o out.pdf   # sghtmltopdf

目次の見た目はwkhtmltopdfの既定TOC XSLの出力に合わせてあります。 XSLTは非対応なので、変更は--user-style-sheetのCSSで行います。

wkhtmltopdfは--header-htmlのURLにクエリ(?page=1&topage=5)を付け、ページ側のJavaScriptで差し込む方式でした。 JSを実行しないので、sghtmltopdfはプレースホルダの文字列置換に置き換えています。

sghtmltopdf report.html --footer-center "[page] / [topage]"

HTMLでヘッダーを作る場合も、HTMLのテキストとして[page]が置換されます。

指定すると理由と代替手段を示してexit 1で終了します。移行時に「オプションが効いていないことに気づかない」事故を避けるためです。

主なものは以下です。

JavaScript関連: --enable-javascript・--javascript-delay・--run-script・--window-status・--debug-javascript・--stop-slow-scripts(JS実行は設計上の非目標)
PDFアウトライン: --outline・--outline-depth・--dump-outline
XSLT: --xsl-style-sheet・--dump-default-toc-xsl(目次は内蔵テンプレート + CSSで代替)
画像の再エンコード: --image-quality・--image-dpi
ネットワーク: --proxy・--cookie・--custom-header・--username/--password・--ssl-*
WebKit固有: --disable-smart-shrinking・--viewport-size・--lowquality・--print-media-type(常に印刷メディア扱い)
PDFフォーム: --enable-forms

エンジンが別物なので、CSSの対応範囲も違います。移行時によく当たるのは次の3つです。

!importantが使えません。付いた宣言は無視されます
inherit/initial/unsetが使えません
ビューポート単位(vw/vh等)とex/ch/lhが使えません。長さはpx/em/remと絶対単位(mm/cm/in/pt/pc/Q)で書いてください

詳しくはセレクタ・値・at-ruleを参照してください。

まずは--log-level info(既定)のまま変換し、警告が出ないことを確認します。非対応オプションはexit 1で止まるので、変換が通った時点でオプションはすべて解釈されています。あとは出力を目視で比べて、余白・改ページ位置・フォントを確認してください。