sghtmltopdf

https://waka.github.io/sghtmltopdf/
Admin
sghtmltopdf is a Rust-based HTML-to-PDF converter and renderer designed to generate PDF documents...
Tokens:62,197
Snippets:257
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start sghtmltopdf server with --listen and --font

Source: https://waka.github.io/sghtmltopdf/usage/server.html

Starts the resident server that accepts HTTP conversion requests. The --listen flag sets the address and --font specifies a Japanese font. On success, the standard output shows `listening on 127.0.0.1:8080`.

```bash
sghtmltopdf server --listen 127.0.0.1:8080 --font NotoSansJP-Regular.ttf
# → 標準出力に `listening on 127.0.0.1:8080` が出る
```

--------------------------------

### Basic sghtmltopdf usage examples

Source: https://waka.github.io/sghtmltopdf/usage/cli/reference.html

Basic usage examples: specifying an output file, omitting the output to use the input filename with a .pdf extension, and reading from standard input while writing to standard output.

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

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

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

--------------------------------

### Run sghtmltopdf as an HTTP server

Source: https://waka.github.io/sghtmltopdf/getting-started/docker.html

Starts the HTTP server with default settings. The container listens on 0.0.0.0:8080, but the default server mode binds to 127.0.0.1 to prevent external exposure.

```bash
docker run --rm -p 8080:8080 ghcr.io/waka/sghtmltopdf
```

--------------------------------

### sghtmltopdf command usage

Source: https://waka.github.io/sghtmltopdf/usage/cli/reference.html

Shows the two command forms: converting an HTML file and starting the HTTP server. The first line is for conversion, the second for the server.

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

--------------------------------

### Run sghtmltopdf HTTP server with Docker

Source: https://waka.github.io/sghtmltopdf/getting-started/install.html

Pulls the Docker image and runs the HTTP server on port 8080. The image includes Japanese fonts (BIZ UDPGothic / BIZ UDPMincho), so no font setup is needed for Japanese PDFs.

```bash
docker pull ghcr.io/waka/sghtmltopdf:latest
docker run --rm -p 8080:8080 ghcr.io/waka/sghtmltopdf
```

--------------------------------

### File access: default error and --allow-path example

Source: https://waka.github.io/sghtmltopdf/usage/cli/reference.html

The first command fails with an error because a local reference outside the base directory is blocked; use --allow-path to grant access. The error message shows both the reference and the required fix. Note that path checking is done on the real path after symlink resolution.

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

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

```

--------------------------------

### sghtmltopdf HTTP API

Source: https://waka.github.io/sghtmltopdf/usage/server.html

HTTP API for converting HTML to PDF via a resident server. Endpoints include POST /pdf, POST /pdf?stream=1, GET /healthz, and GET /version.

```APIDOC
## [POST] /pdf

### Description
Converts the HTML in the request body to a PDF and returns it as `application/pdf`. This is the primary endpoint for converting HTML to PDF via the server.

### Method
POST

### Endpoint
`/pdf`

### Parameters
#### Query Parameters
- **page-size** (string) - Optional - Sets the page size (e.g., `A4`). Corresponds to the CLI option `--page-size`.
- **margin-top** (string) - Optional - Sets the top margin (e.g., `20mm`). Corresponds to the CLI option `--margin-top`.
- **toc** (boolean) - Optional - Enables table of contents. Corresponds to the CLI option `--toc`.
- **grayscale** (boolean) - Optional - Enables grayscale rendering. Accepts `1`, `true`, `0`, `false`. Corresponds to the CLI option `--grayscale`.
- **stream** (boolean) - Optional - If set to `1`, uses chunked transfer encoding to stream the PDF as pages are ready.

#### Request Body
- **HTML content** (string) - Required - The HTML to convert to PDF. Sent as the raw request body.

### Request Example
```
curl --data-binary @invoice.html \
     'http://127.0.0.1:8080/pdf?page-size=A4&margin-top=20mm&toc' \
     -o invoice.pdf
```

### Response
#### Success Response (200)
- **Content-Type** (string) - `application/pdf`
- **Body** (binary) - The generated PDF file.

#### Response Example
```
HTTP/1.1 200 OK
Content-Type: application/pdf

[PDF binary data]
```

### Error Handling
- **400** - Unknown or forbidden query key, invalid value format, or empty body.
- **413** - Body exceeds `--max-body-size`.
- **500** - Rendering failure.
- **503** - Queue overflow (exceeds `--max-queue`).
- **504** - Timeout exceeded (queue wait or conversion too long).

## [POST] /pdf?stream=1

### Description
Same as `POST /pdf`, but uses chunked transfer encoding to stream the PDF as pages are ready. This allows the client to receive the PDF incrementally.

### Method
POST

### Endpoint
`/pdf?stream=1`

### Parameters
#### Query Parameters
- **stream** (boolean) - Required - Must be set to `1` to enable streaming.
- Other query parameters as listed for `POST /pdf`.

#### Request Body
- **HTML content** (string) - Required - The HTML to convert to PDF. Sent as the raw request body.

### Request Example
```
curl --data-binary @big.html 'http://127.0.0.1:8080/pdf?stream=1' -o out.pdf
```

### Response
#### Success Response (200)
- **Content-Type** (string) - `application/pdf`
- **Body** (binary) - The PDF file, streamed in chunks.

#### Response Example
```
HTTP/1.1 200 OK
Content-Type: application/pdf
Transfer-Encoding: chunked

[PDF binary data in chunks]
```

### Error Handling
- **400** - Unknown or forbidden query key, invalid value format, or empty body.
- **413** - Body exceeds `--max-body-size`.
- **500** - Rendering failure.
- **503** - Queue overflow (exceeds `--max-queue`).
- **504** - Timeout exceeded (queue wait or conversion too long).

## [GET] /healthz

### Description
Returns a simple health check response indicating the server is alive.

### Method
GET

### Endpoint
`/healthz`

### Parameters
None

### Request Example
```
curl http://127.0.0.1:8080/healthz
```

### Response
#### Success Response (200)
- **Body** (string) - `ok`

#### Response Example
```
HTTP/1.1 200 OK
Content-Type: text/plain

ok
```

### Error Handling
- **404** - Unknown path.
- **405** - Method not allowed.

## [GET] /version

### Description
Returns the version of the sghtmltopdf server.

### Method
GET

### Endpoint
`/version`

### Parameters
None

### Request Example
```
curl http://127.0.0.1:8080/version
```

### Response
#### Success Response (200)
- **Body** (string) - `sghtmltopdf <version>`

#### Response Example
```
HTTP/1.1 200 OK
Content-Type: text/plain

sghtmltopdf 1.0.0
```

### Error Handling
- **404** - Unknown path.
- **405** - Method not allowed.

```

--------------------------------

### `--allow-remote-assets` でリモートアセットを有効化

Source: https://waka.github.io/sghtmltopdf/supports/images.html

リモートアセットは既定では無効です。`--allow-remote-assets` で明示的に有効化します。有効にした場合も、グローバルに到達可能でない宛先へのリクエストは常にブロックされます。判定は「グローバルなユニキャストだけを通す」方針で、ループバック、プライベート、リンクローカル、CGNAT、その他の非グローバル、IPv6 の特殊用途、IPv4 を埋め込む IPv6 表記を拒否します。判定は名前解決の結果に対して行うため、DNS リバインディングやリダイレクト経由の迂回も同じ仕組みで防いでいます。ポート番号は制限しません。

```bash
sghtmltopdf report.html --allow-remote-assets
```

--------------------------------

### Build sghtmltopdf CLI from source

Source: https://waka.github.io/sghtmltopdf/getting-started/install.html

Builds the CLI from source. Requires only the Rust stable toolchain; no C libraries or system packages are needed. The executable is created at target/release/sghtmltopdf.

```bash
git clone https://github.com/waka/sghtmltopdf.git
cd sghtmltopdf
cargo build --release
```

--------------------------------

### `--allow-path` でローカル参照の範囲を絞る

Source: https://waka.github.io/sghtmltopdf/supports/images.html

信頼できない HTML を変換する場合は、`--allow-path` でローカル参照の範囲も併せて絞ってください。

```bash
sghtmltopdf untrusted.html --allow-path /var/app/assets
```

--------------------------------

### Stream PDF output with curl and ?stream=1

Source: https://waka.github.io/sghtmltopdf/usage/server.html

Requests streaming output with ?stream=1, which uses chunked transfer encoding and sends pages as they are ready. The input is read fully before the response starts.

```bash
curl --data-binary @big.html 'http://127.0.0.1:8080/pdf?stream=1' -o out.pdf
```

--------------------------------

### Initializer: Configure sghtmltopdf

Source: https://waka.github.io/sghtmltopdf/migration/wicked-pdf.html

Global configuration for sghtmltopdf, equivalent to WickedPdf.config. Merge order is global config then render arguments, with render arguments taking precedence.

```ruby
# config/initializers/sghtmltopdf.rb
Sghtmltopdf.configure do |c|
  c.page_size   = "A4"
  c.margin_top  = "20mm"
  c.gothic_font = Rails.root.join("vendor/fonts/NotoSansJP-Regular.ttf")
end
```

--------------------------------

### Controller: Render PDF with custom header HTML file

Source: https://waka.github.io/sghtmltopdf/migration/wicked-pdf.html

When using header_html, you must provide a file path. This example renders a Rails template to a temporary file and passes its path. The ensure block cleans up the temp file.

```ruby
def show
  header = Tempfile.new(["header", ".html"])
  header.write(render_to_string(template: "invoices/header", layout: false))
  header.flush

  render pdf: "invoice", template: "invoices/show", header_html: header.path
ensure
  header&.close!
end
```

--------------------------------

### Run sghtmltopdf as a CLI

Source: https://waka.github.io/sghtmltopdf/getting-started/docker.html

Runs the container as a CLI, mounting the current directory and setting the user to match the host user to avoid permission issues. The container runs as UID 10001 by default.

```bash
docker run --rm -v "$PWD:/work" -w /work --user "$(id -u):$(id -g)" \
    ghcr.io/waka/sghtmltopdf invoice.html -o invoice.pdf
```

--------------------------------

### 表紙と目次を指定するwkhtmltopdf→sghtmltopdfのコマンド対応

Source: https://waka.github.io/sghtmltopdf/migration/wkhtmltopdf.html

表紙と目次を指定するコマンドの対応例です。wkhtmltopdfは位置引数(`cover a.html toc`)ですが、sghtmltopdfは`--cover <PATH>`と`--toc`を使います。目次の見た目はwkhtmltopdfの既定TOC XSLの出力に合わせてあり、XSLTは非対応なので変更は`--user-style-sheet`のCSSで行います。

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

--------------------------------

### Use sghtmltopdf helpers in ERB template

Source: https://waka.github.io/sghtmltopdf/migration/wicked-pdf.html

Replace wicked_pdf helpers with sghtmltopdf equivalents. The stylesheet helper expands CSS into a <style> tag, and the image helper references images by path, embedding as data: URI if not readable. This example shows both helpers in an ERB template.

```erb
<%= sghtmltopdf_stylesheet_link_tag "pdf" %>
<%= sghtmltopdf_image_tag "logo.png" %>
```

--------------------------------

### Render HTML with streaming mode

Source: https://waka.github.io/sghtmltopdf/usage/ruby_rails.html

Enables streaming mode for large HTML documents to reduce memory usage. For example, 60,000 elements can drop from 228MB to 28MB. Note that features requiring the whole document, such as toc, counter(pages), or <style> after <body>, are not available in this mode.

```ruby
Sghtmltopdf.render(html, streaming: true)
```

--------------------------------

### Run server with custom options

Source: https://waka.github.io/sghtmltopdf/getting-started/docker.html

Overrides the server command to set listen address, workers, and max body size. Useful for adjusting server behavior.

```bash
docker run --rm -p 8080:8080 ghcr.io/waka/sghtmltopdf \
    server --listen 0.0.0.0:8080 --workers 4 --max-body-size 52428800
```

--------------------------------

### Stream PDF with ActionController::Live

Source: https://waka.github.io/sghtmltopdf/usage/ruby_rails.html

Stream a PDF from a Rails controller using `ActionController::Live`. The `render pdf:` renderer returns the whole PDF via `send_data`; this example streams chunks as they are finalized. If an error occurs after headers are sent, the client receives a corrupted PDF and the status cannot be changed.

```ruby
class InvoicesController < ApplicationController
  include ActionController::Live

  def show
    response.headers["Content-Type"] = "application/pdf"
    html = render_to_string(template: "invoices/show", layout: "pdf")
    Sghtmltopdf.render(html) { |bytes| response.stream.write(bytes) }
  ensure
    response.stream.close
  end
end
```

--------------------------------

### カラー絵文字フォントを指定する CLI 例

Source: https://waka.github.io/sghtmltopdf/supports/fonts.html

Noto Color Emoji を --font で指定する例。カラー絵文字はそのままカラーで描画されます。

```bash
__
sghtmltopdf report.html --font NotoColorEmoji.ttf

```

--------------------------------

### sghtmltopdfのフッターでページ番号プレースホルダを使う

Source: https://waka.github.io/sghtmltopdf/migration/wkhtmltopdf.html

ヘッダー/フッターのページ番号を指定する例です。wkhtmltopdfはURLにクエリを付けてJavaScriptで差し込む方式でしたが、sghtmltopdfはJSを実行しないためプレースホルダの文字列置換に置き換えています。HTMLでヘッダーを作る場合もHTMLのテキストとして`[page]`が置換されます。

```bash
sghtmltopdf report.html --footer-center "[page] / [topage]"
```
Tokens:
Raw