NativeElixirPdfUtilities.HtmlToPdf (native_elixir_pdf_utilities v0.3.0)

View Source

Public facade for native HTML/CSS to PDF rendering.

The renderer is intentionally structured as a small pipeline:

  • parse HTML into a document tree
  • compute styles
  • lay out the styled tree
  • paginate layout boxes
  • write PDF bytes

The supported surface is a strict, document-oriented HTML/CSS subset. Invalid or unsupported input returns an error instead of falling back to browser-like guessing. See the README support matrix for the current element, CSS, layout, image, and font support.

Summary

Types

detailed_error_reason()
error_detail()
error_reason()
page_size()
render_option()

Functions

render(html, opts \\ [])

Renders an HTML document to a PDF binary.

render_file(input_path, output_path, opts \\ [])

Reads an HTML file, renders it to PDF, and writes the PDF to output_path.

Types

detailed_error_reason()

@type detailed_error_reason() ::
  {:invalid_css
   | :invalid_document
   | :invalid_html
   | :invalid_layout
   | :invalid_margin
   | :invalid_page_size
   | :invalid_pdf_input
   | :unsupported_html, error_detail()}

error_detail()

@type error_detail() :: %{
  :stage => atom(),
  :reason => atom(),
  :message => String.t(),
  optional(:line) => pos_integer(),
  optional(:column) => pos_integer(),
  optional(:source) => String.t()
}

error_reason()

@type error_reason() ::
  :invalid_document
  | :invalid_css
  | :invalid_html
  | :invalid_layout
  | :invalid_margin
  | :invalid_page_size
  | :invalid_path
  | :invalid_pdf_input
  | :not_implemented
  | :unsupported_html
  | File.posix()

page_size()

@type page_size() :: :a4 | :letter | {number(), number()}

render_option()

@type render_option() ::
  {:page_size, page_size() | {number(), number()}}
  | {:margin, String.t() | number()}
  | {:base_url, String.t() | nil}
  | {:stylesheets, [String.t()]}
  | {:default_font, String.t()}
  | {:fonts, [map() | keyword() | {String.t(), String.t()}]}

Functions

render(html, opts \\ [])

@spec render(String.t(), [render_option()]) ::
  {:ok, binary()} | {:error, error_reason() | detailed_error_reason()}

Renders an HTML document to a PDF binary.

Returns {:ok, pdf_binary} when rendering succeeds or {:error, reason} when parsing, styling, layout, pagination, or PDF writing cannot be completed. Rendering failures include a broad reason and diagnostic detail, for example {:error, {:invalid_css, %{message: "...", line: 18, source: "..."}}}.

Supported options include :page_size, :margin, :base_url, :stylesheets, :default_font, and explicit TTF :fonts.

:page_size accepts :a4, :letter, or a positive {width, height} tuple. Tuple values up to 20 x 20 are interpreted as inches for compatibility with ChromicPDF-style custom label sizes; larger tuples are interpreted as PDF points.

render_file(input_path, output_path, opts \\ [])

@spec render_file(String.t(), String.t(), [render_option()]) ::
  :ok | {:error, error_reason() | detailed_error_reason()}

Reads an HTML file, renders it to PDF, and writes the PDF to output_path.

Returns :ok after writing the output file or {:error, reason} if reading, rendering, or writing fails. Rendering options are the same as render/2.