sghtmltopdf

https://waka.github.io/sghtmltopdf/en/
Admin
sghtmltopdf is a Rust-based HTML-to-PDF converter and renderer that generates PDFs directly without...
Tokens:42,294
Snippets:303
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run server with custom options

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

Starts the server with custom options: --listen, --workers, and --max-body-size. The command must start with 'server' to override the default CMD.

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

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

### sghtmltopdf with HTML header and footer files

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

Command-line example showing how to use separate HTML files for the header and footer. Placeholders are substituted as text; JavaScript is not executed, external resources are not fetched, and @font-face is not loaded.

```bash
sghtmltopdf report.html --header-html header.html --footer-html footer.html
```

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

### GET /version

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

Returns the version of the software.

```APIDOC
## GET /version

### Description
Returns the version of the software, in the format `sghtmltopdf <version>`.

### Method
GET

### Endpoint
/version

### Response
Success response example: `sghtmltopdf 1.0.0`
```

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

### Start sghtmltopdf server with --listen and font

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

Runs the sghtmltopdf server in resident mode, listening on the given address (default 127.0.0.1:8080) with a specified font (required for Japanese text). The binary prints 'listening on 127.0.0.1:8080' to standard output when ready.

```bash
sghtmltopdf server --listen 127.0.0.1:8080 --font NotoSansJP-Regular.ttf
```

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

### Run sghtmltopdf as an HTTP server

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

Starts the server mode with default settings, listening on 0.0.0.0:8080 inside the container. The image's CMD sets --listen 0.0.0.0:8080 because the default is 127.0.0.1, which is unreachable from outside the container.

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

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

### sghtmltopdf with header and footer text options

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

Command-line example showing how to generate a PDF with a centered header, right-aligned footer with page numbers, and a header line. Uses --header-center, --footer-right, and --header-line.

```bash
sghtmltopdf report.html \
  --header-center "Quarterly report" \
  --footer-right "[page] / [topage]" \
  --header-line
```

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

### Server-only startup options list

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

Options that can only be set when the server starts. Passing any of these to the client raises UsageError. In a Rails app, the Railtie's base_url and allow_path defaults are dropped automatically when server_url is set.

```plaintext
font, font-index, gothic-font, gothic-font-index, serif-font,
serif-font-index, mono-font, mono-font-index,
output, cover, header-html, footer-html, user-style-sheet, base-url,
allow, enable-local-file-access, disable-local-file-access,
allow-remote-assets, log-level, quiet
```

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

### Basic sghtmltopdf usage examples

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

Shows the simplest form using system fonts, writing to a specified output file. Without an output path, the input name is used with the extension changed to .pdf. Reading from standard input and writing to standard output is also demonstrated.

```bash
# The simplest form; the system fonts are used
sghtmltopdf invoice.html -o invoice.pdf

# Without an output path, the input name with the extension changed to .pdf
sghtmltopdf invoice.html

# Read from standard input and write to standard output
cat invoice.html | sghtmltopdf - -o - > invoice.pdf
```

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

### sghtmltopdf CLI usage

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

Shows the two command-line forms of sghtmltopdf: one for converting a file and one for running the HTTP server. The first form takes an input HTML file, while the second starts the server.

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

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

### Install the sghtmltopdf gem

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

Adds the sghtmltopdf gem to a Gemfile. Precompiled gems are available for x86_64-linux, aarch64-linux, and arm64-darwin (glibc) on Ruby 3.2 or later, so no Rust toolchain is required. Conversion runs in-process as a native extension; the GVL is released during heavy work.

```ruby
# Gemfile
gem "sghtmltopdf"
```

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

### GET /healthz

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

Returns the health status of the service.

```APIDOC
## GET /healthz

### Description
Returns the health status of the service.

### Method
GET

### Endpoint
/healthz

### Response
Success response: `ok`
```

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

### Start new page for each chapter

Source: https://waka.github.io/sghtmltopdf/en/supports/pagination.html

Starts a new page for each chapter by forcing a page break before every section.chapter that follows another section.chapter. Note: in streaming mode, selectors that look backwards (like :last-child) never match, but the adjacent sibling combinator (+) used here does work.

```css
section.chapter + section.chapter { break-before: page; }
```

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

### Configure gothic_font in Sghtmltopdf

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

Sets a custom gothic font for Japanese output, avoiding reliance on system fonts. Use this in an initializer or setup block.

```ruby
Sghtmltopdf.configure do |c|
  c.gothic_font = Rails.root.join("vendor/fonts/NotoSansJP-Regular.ttf")
end
```

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

### Run sghtmltopdf as a CLI

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

Runs the binary as a CLI, converting invoice.html to invoice.pdf. The container runs as UID 10001, so use --user to match the host owner when writing to a mounted directory.

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

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

### Page break with break-before

Source: https://waka.github.io/sghtmltopdf/en/getting-started/first-pdf.html

HTML with a CSS class using break-before: page to start a new page before the element. Also mentions break-after and break-inside: avoid.

```html
<style>
  .page-break { break-before: page; }
</style>

<h1>Invoice</h1>
<p>This is page 1.</p>

<div class="page-break">
  <h1>Line items</h1>
  <p>This is page 2.</p>
</div>
```

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

### hello.html - Basic invoice HTML

Source: https://waka.github.io/sghtmltopdf/en/getting-started/first-pdf.html

A minimal HTML document used as the input for the sghtmltopdf examples. It includes inline CSS for font family, heading border, and a right-aligned total.

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <style>
      body { font-family: sans-serif; }
      h1 { border-bottom: 2px solid #333; padding-bottom: 8px; }
      .total { text-align: right; font-size: 1.2em; font-weight: bold; }
    </style>
  </head>
  <body>
    <h1>Invoice</h1>
    <p>Thank you for your continued business. Please find the charges below.</p>
    <p class="total">Total 12,000 JPY</p>
  </body>
</html>
```

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

### Build the CLI binary from source

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

Clones the repository and builds the CLI binary in release mode. Requires the stable Rust toolchain; no C libraries or system packages are needed. The binary is written to target/release/sghtmltopdf.

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

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

### Check the built binary version

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

Verifies the built binary by printing its version. Run from the repository root after building.

```bash
./target/release/sghtmltopdf --version
```

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

### Run the HTTP server with Docker

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

Pulls the Docker image and runs the HTTP server on port 8080. The image bundles Japanese fonts (BIZ UDPGothic and BIZ UDPMincho), so Japanese PDFs render without supplying a font.

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

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

### Convert via standard input/output

Source: https://waka.github.io/sghtmltopdf/en/getting-started/first-pdf.html

Pipes hello.html into sghtmltopdf and writes the PDF to standard output. Use - for both input and output to read from stdin and write to stdout.

```bash
cat hello.html | sghtmltopdf - -o - > hello.pdf
```

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

### Streaming conversion via server mode query

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

Use the `?stream=1&streaming` query parameters in server mode to make the response body chunked and enable streaming input, rendering, and output.

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

```

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

### Render HTML to PDF using Sghtmltopdf.render and render_to_file

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

Convert HTML strings to PDF bytes with `Sghtmltopdf.render` and write to a file with `render_to_file`. The returned string is ASCII-8BIT. Input HTML is passed as bytes; encoding is detected from BOM, `encoding:`, `<meta charset>`, or UTF-8. `render_to_file` writes atomically, and the GVL is released during heavy work.

```ruby
pdf = Sghtmltopdf.render("<h1>Invoice</h1>")             # → the PDF as a byte String
Sghtmltopdf.render_to_file(html, "invoice.pdf")         # → writes to a file and returns nil

```

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

### Initializer: configure sghtmltopdf globally

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

Global configuration for sghtmltopdf, the counterpart of wicked_pdf's WickedPdf.config. The global config is merged first, and arguments to render take 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
```

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

### Set orphans and widows to control paragraph breaks

Source: https://waka.github.io/sghtmltopdf/en/supports/pagination.html

CSS example using orphans and widows to control how many lines of a paragraph must remain at the bottom/top of a page. Both accept an integer of 1 or more and default to 2; if the requirement can't be met, the whole paragraph moves to the next page.

```css
__
p {
  orphans: 3;   /* leave at least three lines at the bottom of the page */
  widows: 3;    /* carry at least three lines to the top of the next page */
}

```

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

### Set page size and margins via CLI

Source: https://waka.github.io/sghtmltopdf/en/getting-started/first-pdf.html

sghtmltopdf command with --page-size A4 and --margin-top/--margin-bottom set to 20mm. Accepted units are mm, cm, in, pt, and px; a bare number means mm.

```bash
sghtmltopdf hello.html -o hello.pdf \
  --page-size A4 --margin-top 20mm --margin-bottom 20mm
```

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

### Stream PDF with ActionController::Live

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

Combine the render pdf: renderer with ActionController::Live to send pages as they are finalized. The renderer assembles the whole PDF and returns it with send_data, but this example streams chunks to the response. If it fails after part of the file has been written, the client receives a broken PDF because the headers have already gone out and the status can no longer 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
```

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

### Convert large HTML file using --streaming

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

Run sghtmltopdf with the `--streaming` flag to read the HTML in chunks and release memory page by page. Best for HTML with tens of thousands of elements.

```shell
sghtmltopdf big.html -o big.pdf --streaming

```

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

### Render PDF with a block for chunked output

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

Pass a block to Sghtmltopdf.render to receive each chunk of the PDF as it is finalized, instead of the whole PDF being assembled and returned. The return value is nil. This is the hook for writing into Rack's response.stream or feeding an S3 multipart upload. Writing can start before the whole PDF has been assembled; locally the chunks arrive page by page as each is finalized.

```ruby
Sghtmltopdf.render(html) { |bytes| response.stream.write(bytes) }
```

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

### Define @page size, margins, and margin box content

Source: https://waka.github.io/sghtmltopdf/en/supports/pagination.html

CSS @page rule that sets paper size, page margins, and margin box text such as a header, page numbers, and a first-page footer. @page overrides CLI page setup options; size accepts keywords like A4 or Letter, lengths, and orientation; counter(page) and counter(pages) provide page numbers. Note size and margin cannot vary between pages, and counter(pages) is unavailable in streaming mode.

```css
@page {
  size: A4;
  margin: 20mm;

  @top-center    { content: "Invoice"; }
  @bottom-center { content: counter(page) " / " counter(pages); }
}

@page :first {
  @bottom-center { content: "Cover"; }
}

```

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

### Convert hello.html to hello.pdf

Source: https://waka.github.io/sghtmltopdf/en/getting-started/first-pdf.html

Basic sghtmltopdf command that converts hello.html to hello.pdf. Without -o, the output file is the input name with the extension changed to .pdf.

```bash
sghtmltopdf hello.html -o hello.pdf
```

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

### Configure Sghtmltopdf with page size and gothic font in Rails initializer

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

Sets global configuration for Sghtmltopdf, specifying A4 page size and a gothic font path. Global configuration is merged first, and call-site arguments take precedence. Use Sghtmltopdf.reset_config! to clear configuration, mainly for tests.

```ruby
# for example config/initializers/sghtmltopdf.rb
Sghtmltopdf.configure do |c|
  c.page_size   = "A4"
  c.gothic_font = Rails.root.join("vendor/fonts/NotoSansJP-Regular.ttf")
end
```
Tokens:
Raw