NativeElixirPdfUtilities.HtmlToPdf (native_elixir_pdf_utilities v0.11.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
  • resolve every text grapheme to an available font
  • lay out the styled tree
  • paginate layout boxes
  • write PDF bytes

The supported surface is a strict, document-oriented HTML/CSS subset. Malformed structure and unsupported features return errors instead of using browser-like guessing. Unsupported text graphemes are visibly replaced by default. See the HTML-to-PDF compatibility guide for the current element, CSS, layout, image, and font support.

Summary

Types

detailed_error_reason()
error_detail()
error_reason()
page_furniture()
page_furniture_template()
page_furniture_variants()
page_margin()
page_size()
pdf_metadata()
render_option()
stylesheet_source()

An explicitly tagged inline stylesheet or local stylesheet file.

unsupported_glyphs()

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() :: {error_reason(), error_detail()}

error_detail()

@type error_detail() :: NativeElixirPdfUtilities.Diagnostics.diagnostic()

error_reason()

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

page_furniture()

@type page_furniture() ::
  [header: page_furniture_variants(), footer: page_furniture_variants()]
  | %{
      optional(:header) => page_furniture_variants(),
      optional(:footer) => page_furniture_variants()
    }

page_furniture_template()

@type page_furniture_template() :: String.t() | false | nil

page_furniture_variants()

@type page_furniture_variants() ::
  String.t()
  | [
      default: page_furniture_template(),
      first: page_furniture_template(),
      odd: page_furniture_template(),
      even: page_furniture_template()
    ]
  | %{
      optional(:default) => page_furniture_template(),
      optional(:first) => page_furniture_template(),
      optional(:odd) => page_furniture_template(),
      optional(:even) => page_furniture_template()
    }

page_margin()

@type page_margin() :: NativeElixirPdfUtilities.HtmlToPdf.PageGeometry.margin_input()

page_size()

@type page_size() :: NativeElixirPdfUtilities.HtmlToPdf.PageGeometry.page_size_input()

pdf_metadata()

@type pdf_metadata() ::
  keyword()
  | %{
      optional(:title) => String.t(),
      optional(:author) => String.t(),
      optional(:subject) => String.t(),
      optional(:keywords) => String.t() | [String.t()],
      optional(:creation_date) =>
        Date.t() | NaiveDateTime.t() | DateTime.t() | String.t(),
      optional(:modification_date) =>
        Date.t() | NaiveDateTime.t() | DateTime.t() | String.t()
    }

render_option()

@type render_option() ::
  {:page_size, page_size()}
  | {:margin, page_margin()}
  | {:base_url, String.t() | nil}
  | {:stylesheets, [stylesheet_source()]}
  | {:default_font, String.t() | [String.t()]}
  | {:fonts, [map() | keyword() | {String.t(), String.t()}]}
  | {:metadata, pdf_metadata()}
  | {:page_furniture, page_furniture() | false | nil}
  | {:unsupported_glyphs, unsupported_glyphs()}

stylesheet_source()

@type stylesheet_source() :: {:css, String.t()} | {:file, String.t()}

An explicitly tagged inline stylesheet or local stylesheet file.

unsupported_glyphs()

@type unsupported_glyphs() :: :replace | :error

Functions

render(html, opts \\ [])

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

Renders an HTML document to a PDF binary.

Returns {:ok, pdf_binary} when rendering succeeds or {:error, {reason, diagnostic}} 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, explicit local :fonts, PDF :metadata, opt-in :page_furniture headers and footers, and :unsupported_glyphs. Metadata supports title, author, subject, keywords, creation date, and modification date. An HTML <title> supplies the PDF title when metadata[:title] is not set.

Unsupported graphemes are replaced visibly with U+FFFD by default. Set unsupported_glyphs: :error to return an :unsupported_glyph diagnostic instead.

Page furniture accepts :header and :footer HTML templates. Each can be a string used on every page or variants named :default, :first, :odd, and :even. A variant set to false or nil is omitted. The :first variant has precedence on page one, followed by the matching odd/even variant and then :default. Templates can contain {{page}} and {{pages}} tokens. Furniture is disabled when :page_furniture is omitted, nil, or false. Enabled furniture must fit inside the page margin.

:page_size accepts the CSS named sizes :a5, :a4, :a3, :b5, :b4, :jis_b5, :jis_b4, :letter, :legal, and :ledger, optionally paired with :portrait or :landscape, 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. CSS two-length strings retain their declared units.

:margin accepts a nonnegative point number, a CSS string containing one to four absolute lengths, or a map with :top, :right, :bottom, and :left values. Explicit renderer :page_size and :margin options override stylesheet @page defaults.

:stylesheets accepts a list of {:css, css} and {:file, path} tuples. The explicit tag determines whether content is parsed directly or read from the local filesystem; bare strings are rejected.

:base_url is also the authorization root for document-selected local image and @font-face paths. Relative paths and absolute paths beneath that root are accepted; traversal outside it and symlink components are rejected. Explicit :fonts and {:file, stylesheet} paths are trusted caller configuration and are not reclassified as document-selected resources.

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

@spec render_file(String.t(), String.t(), [render_option()]) ::
  :ok | {:error, 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, diagnostic}} if reading, rendering, or writing fails. Rendering options are the same as render/2.