CLIリファレンス

sghtmltopdfコマンドの全オプション。

sghtmltopdf [OPTIONS] <INPUT.HTML>
sghtmltopdf server [OPTIONS]

上が変換、下がHTTPサーバです。

wkhtmltopdfのオプションとの対応(非対応にしたものを含む全一覧)はwkhtmltopdfオプション対応表を参照してください。

基本

# もっとも単純な使い方(フォントはシステムのものが使われる)
sghtmltopdf invoice.html -o invoice.pdf

# 出力先を省略すると入力の拡張子を .pdf にしたもの
sghtmltopdf invoice.html

# 標準入力から読み、標準出力へ書く
cat invoice.html | sghtmltopdf - -o - > invoice.pdf

入出力

出力ファイルは一時ファイルへ書いてからrenameされるため、失敗したときに壊れたPDFが残ることはありません。

ページ設定

長さの単位はmm/cm/in/pt/px。 単位を省略するとmmです(wkhtmltopdf互換)。

CSSの@pageとの関係

これらのオプションは初期値であり、HTMLのCSSに@page { size: … }や@page { margin: … }が書かれていればそちらが勝ちます(プロパティ単位)。 wkhtmltopdfとは逆なので注意してください。

フォント

フォントの解決順は「--font → @font-face → font-family名でのシステム探索」。 それでも1つも見つからない場合だけ、システムのsans-serif候補が既定フォントになります。

--fontを指定しないと出力が実行環境のフォントに依存します。 サーバ運用やCIで出力を安定させたい場合は--font(または@font-face)を明示してください。 詳しくはフォントを参照。

PDFの出力形式・メタデータ

/Producerと/CreationDateは常に書かれます。

グレースケールの限界

JPEG(/DCTDecodeのパススルー)とCMYK画像はデコーダを持たないため、変換されずカラーのまま残ります。

コンテンツの挙動

ヘッダー/フッター

2つの方法があります。 同じ側に両方を指定した場合は--header-htmlが優先されます。

1. テキストで指定する

@pageのmargin boxへマップされます。

sghtmltopdf report.html \
  --header-center "四半期レポート" \
  --footer-right "[page] / [topage]" \
  --header-line

プレースホルダは[page](現在ページ)・[topage](総ページ数)・[frompage]・[title]/[doctitle]・[date]・[time]、および--replaceで定義した名前です。

[section]/[subsection]と[webpage]/[sitepage]/[sitepages]は非対応です。

2. HTMLで指定する

sghtmltopdf report.html --header-html header.html --footer-html footer.html

各ページの余白領域へ、別のHTMLをレンダリングして合成します。 プレースホルダはHTMLのテキストとして置換されます(JavaScriptは実行しません)。

• 余白に入りきらない分はクリップされます(マージンは自動で広がりません)
• 外部リソースを取得しません。使えるのはインラインの<style>・テキスト・枠線・背景色までで、<img>と外部CSSは非対応です
• ヘッダー/フッターHTML内の@font-faceは読み込みません。そこでしか使わないフォントは--fontで明示してください

表紙と目次

sghtmltopdf report.html --cover cover.html --toc --footer-center "[page]"

書き出される順は 表紙 → 目次 → 本文 です。

目次のHTML構造と既定スタイルはwkhtmltopdfの既定TOC XSLの出力に合わせてあります(階層は入れ子の<ul>、各項目は<div><a>見出し</a><span>ページ番号</span></div>)。 見た目を変えたい場合は--user-style-sheetでCSSを当ててください(XSLTは非対応)。

見出しはh1〜h6から集めます。 idが無い見出しには自動で宛先名が振られます。

アクセス制御

--allowを1つ以上指定すると、ローカル参照はそのディレクトリ配下だけに限定されます。 <img src>・外部CSS・@font-faceのすべてに効きます。

判定は実パス(シンボリックリンクを辿った後のパス)で行います。 指定したディレクトリが存在しない場合は起動時にエラーになります。 黙って無視すると、許可した範囲と実際に効く範囲がずれるためです。

基準ディレクトリの外への参照

ローカル参照は既定で基準ディレクトリ(--base-url、既定は入力HTMLのあるディレクトリ)の中に閉じます。 ../で外へ出ようとする参照はエラーになります。 信頼できないHTMLを変換したときに<img src="../../../../etc/passwd">のような参照で任意のファイルを読み出されるのを防ぐためです。

assets/../images/logo.pngのように基準ディレクトリの中で完結する../は従来どおり使えます。

外のファイルを意図的に参照する場合は--allowで範囲を明示してください。 --allowを指定した場合は、基準ディレクトリではなく許可したディレクトリが境界になります。

$ sghtmltopdf pages/index.html -o out.pdf
エラー: ../images/logo.png: 基準ディレクトリ(pages)の外を参照しています。
  外部のファイルを読む場合は --allow でディレクトリを明示してください

$ sghtmltopdf pages/index.html --allow . -o out.pdf

判定はパス文字列に対して行うため、基準ディレクトリ配下のシンボリックリンクは辿ります。 シンボリックリンクの先まで含めて閉じたい場合は--allowを使ってください(こちらは実パスで判定します)。

入力の大きさの制限

要素数がおよそ50万ノードを超えるHTMLはエラーになります。 算出スタイル・ボックスツリー・レイアウト結果がノード数に比例して積み上がるためで、実測では1ノードあたり472B〜1210Bでした。

数千ページ規模の文書でも数十万ノードなので、実在の文書がここに当たることはまずありません。 当たった場合は文書を分割するか、ストリーミングモードを使ってください。 ストリーミングモードでは処理済みの部分が随時解放されるため、総量が上限を超えていても変換できます。

テキストの量に比例するメモリはこの上限では抑えられません(要素3個でも10MiBのテキストなら約1.7GiB使います)。 HTTPサーバモードでは--max-body-sizeがその役割を担います。

ログとexit code

--log-level <none|error|warn|info>(既定info)、-q/--quiet(=--log-level none)。