Rendro

https://hexdocs.pm/rendro/
Admin
Rendro is an open-source, Elixir-native PDF layout library for Phoenix teams that need reliable PDFs...
Tokens:74,192
Snippets:892
Trust Score:9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Setup Rendro Dependencies

Source: https://hexdocs.pm/rendro/first_invoice.html

Install Rendro and other necessary dependencies for the project. It includes conditional logic for local development using environment variables.

```elixir
rendro_dep = 
  if System.get_env("RENDRO_LIVEBOOK_LOCAL") == "1" do
    {:rendro, path: System.get_env("RENDRO_LIVEBOOK_PATH") || File.cwd!()}
  else
    {:rendro, "~> 1.0"}
  end

Mix.install([
  rendro_dep,
  {:jason, "~> 1.4"},
  {:jsv, "~> 0.19"},
  {:yaml_elixir, ">= 2.11.0 and < 3.0.0"},
  {:kino, "~> 0.16"}
])
```

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

### Example Usage of Rendro.Recipes.Invoice.document/2

Source: https://hexdocs.pm/rendro/Rendro.Recipes.Invoice.html

Demonstrates how to call the `document/2` function with sample data and inspect the resulting document's page template.

```elixir
iex> data = %{id: "INV-001", date: ~D[2026-01-15], items: []}
iex> doc = Rendro.Recipes.Invoice.document(data)
iex> doc.page_template
:invoice
```

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

### Example: Document Function Usage

Source: https://hexdocs.pm/rendro/Rendro.Recipes.Receipt.html

Demonstrates calling the `document/2` function with sample data and inspecting the resulting page template.

```elixir
iex> data = %{
...>   title: "Payment Receipt",
...>   date: ~D[2026-05-29],
...>   customer: %{name: "Acme Corp"},
...>   lines: []
...> }
iex> doc = Rendro.Recipes.Receipt.document(data)
iex> doc.page_template
:receipt
```

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

### Example: Page Template Structure

Source: https://hexdocs.pm/rendro/Rendro.Recipes.Receipt.html

Shows how to obtain a default page template using `page_template/1` and verify its properties, such as footer height.

```elixir
iex> t = Rendro.Recipes.Receipt.page_template()
iex> t.name
:receipt
iex> footer = Enum.find(t.regions, & &1.role == :footer)
iex> footer.height > 0
true
```

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

### Example: Sections Function Usage

Source: https://hexdocs.pm/rendro/Rendro.Recipes.Receipt.html

Illustrates how to generate content sections for a receipt using `sections/2` and verify their assigned regions.

```elixir
iex> data = %{
...>   title: "Payment Receipt",
...>   date: ~D[2026-05-29],
...>   customer: %{name: "Acme Corp"},
...>   lines: []
...> }
iex> [header, body, footer] = Rendro.Recipes.Receipt.sections(data)
iex> header.region
:header
iex> footer.region
:footer
```

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

### Example: Register Built-in Font

Source: https://hexdocs.pm/rendro/Rendro.Document.html

Demonstrates registering a built-in font like Helvetica for the 'body' logical name.

```Elixir
iex> Rendro.Document.new()
...> |> Rendro.Document.register_font(:body, built_in: :helvetica)
%Rendro.Document{
  font_registry: %Rendro.FontRegistry{
    fonts: %{default: %{source: :built_in, family: :helvetica}, body: %{source: :built_in, family: :helvetica}}
  }
}
```

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

### Verify Threadline Integration (Failure Path)

Source: https://hexdocs.pm/rendro/integrations.html

Example demonstrating how a failed render is recorded as :render_failed in Threadline.

```elixir
doc = Rendro.flow(
  [Rendro.block(Rendro.text("x", size: 12))],
  options: %{policies: [max_pages: 0]}
)
{:error, %Rendro.Error{reason: :max_pages_exceeded}} = Rendro.render(doc)

[action | _] = Threadline.list_actions()
assert action.action == :render_failed
```

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

### Surface Equivalence for Apple Preview

Source: https://hexdocs.pm/rendro/viewer_evidence.html

Use this template when two surfaces share identical viewer behavior. This example shows Apple Preview's supported status with proof details and evidence file reference.

```json
{
  "apple_preview": {
    "status": "supported",
    "proof": ["prepared_artifact_opens_cleanly", "widget_renders_as_unsigned_placeholder", "viewer_does_not_silently_re_sign_or_corrupt", "byte_range_layout_intact_after_save_as"],
    "evidence": "priv/viewer_evidence/signature_widget/apple_preview.md",
    "recorded_at": "2026-05-29",
    "viewer_kind": "pdfium-cli"
  }
}
```

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

### Supported Automated Recordings for Rendro Viewer Evidence

Source: https://hexdocs.pm/rendro/Mix.Tasks.Rendro.ViewerEvidence.html

Shows examples of specific viewer and surface combinations that can be automatically recorded.

```bash
mix rendro.viewer_evidence record forms chrome_pdfium
mix rendro.viewer_evidence record forms apple_preview
mix rendro.viewer_evidence record forms adobe_acrobat_reader
mix rendro.viewer_evidence record embedded_files adobe_acrobat_reader
mix rendro.viewer_evidence record links adobe_acrobat_reader
mix rendro.viewer_evidence record links apple_preview
mix rendro.viewer_evidence record protection apple_preview
mix rendro.viewer_evidence record protection adobe_acrobat_reader
mix rendro.viewer_evidence record signature_widget chrome_pdfium
mix rendro.viewer_evidence record signature_widget adobe_acrobat_reader
mix rendro.viewer_evidence record signature_widget apple_preview
mix rendro.viewer_evidence record signed_artifact chrome_pdfium
mix rendro.viewer_evidence record signed_artifact adobe_acrobat_reader
mix rendro.viewer_evidence record signing_preparation adobe_acrobat_reader
mix rendro.viewer_evidence record long_lived_signed_artifact adobe_acrobat_reader
```

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

### Hypothetical Deferral for Apple Preview Signed Artifact

Source: https://hexdocs.pm/rendro/viewer_evidence.html

A hypothetical teaching example illustrating deferral for Apple Preview's signed artifact handling. It specifies the status and the reason for deferral.

```json
{
  "apple_preview": {
    "status": "explicit_deferral",
    "evidence_deferred": "Apple Preview renders signature appearance but does not implement /Sig cryptographic validation as of Preview 11.0 on macOS 15 — integrity UI absent."
  }
}
```

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

### Get Pdfium-cli Version

Source: https://hexdocs.pm/rendro/Rendro.Adapters.Pdfium.html

Retrieves the version string of the installed `pdfium-cli` executable. Accepts optional keyword arguments.

```Elixir
Rendro.Adapters.Pdfium.version(opts \\ [])
```

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

### Create New Empty Document

Source: https://hexdocs.pm/rendro/Rendro.Document.html

Creates a new empty Rendro Document struct. This is the starting point for building a document.

```Elixir
Rendro.Document.new()
```

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

### Serve PDFs from Phoenix Controllers

Source: https://hexdocs.pm/rendro/index.html

Integrate Rendro with Phoenix to serve generated PDFs directly from your controllers using the `Rendro.Adapters.Phoenix` adapter. This example shows how to render an invoice PDF.

```elixir
defmodule MyAppWeb.PDFController do
  use MyAppWeb, :controller
  alias Rendro.Adapters.Phoenix, as: RendroPhoenix

  def show(conn, _params) do
    data = %{
      id: "INV-001",
      date: Date.utc_today(),
      items: [%{name: "Consulting", qty: 1, price: 1_500}]
    }

    doc = Rendro.Recipes.Invoice.document(data)

    RendroPhoenix.render_pdf(conn, doc, "invoice.pdf")
  end
end

```

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

### Generate Rendro Document from Accrue Invoice

Source: https://hexdocs.pm/rendro/integrations.html

Use the Accrue adapter to convert an Accrue.Invoice struct into a Rendro.Document. This is a schematic example; fetching the invoice is application-specific.

```elixir
invoice = MyApp.Billing.fetch_invoice!(invoice_id)

{:ok, doc} = Rendro.Adapters.Accrue.recipe(invoice)
{:ok, pdf}  = Rendro.render(doc)
```

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

### Phoenix Controller for PDF Handoff

Source: https://hexdocs.pm/rendro/first_invoice.html

An example Phoenix controller action to fetch invoice data, render a PDF using Rendro, and send it as an inline response with appropriate headers.

```elixir
defmodule MyAppWeb.InvoiceController do
  use MyAppWeb, :controller

  def show(conn, %{"id" => id}) do
    invoice = Billing.get_invoice!(id)
    doc = Rendro.Recipes.Invoice.document(invoice)
    {:ok, pdf} = Rendro.render(doc, deterministic: true)

    conn
    |> put_resp_content_type("application/pdf")
    |> put_resp_header("content-disposition", "inline; filename=invoice-#{id}.pdf")
    |> send_resp(200, pdf)
  end
end
```

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

### Extracting Invoice Sections

Source: https://hexdocs.pm/rendro/Rendro.Recipes.Invoice.html

This example shows how to extract the header, body, and footer sections of an invoice using the `sections/2` function and verify the region of the first section.

```elixir
iex> data = %{id: "INV-001", date: ~D[2026-01-15], items: []}
iex> [header, body, footer] = Rendro.Recipes.Invoice.sections(data)
iex> header.region
:header
```

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

### Inspect Rendro Document Structure

Source: https://hexdocs.pm/rendro/readme.html

Use `render_with_diagnostics/2` to get the final document struct and `Rendro.Inspector.inspect/1` to print a human-readable layout tree. Diagnostics are available in `final_doc.diagnostics`.

```elixir
# docs-contract: readme-inspector-compile
doc = Rendro.flow([Rendro.block(Rendro.text("Hello World"))])

{:ok, _pdf, final_doc} = Rendro.render_with_diagnostics(doc)

# Print a human-readable tree of pages, blocks, and dimensions
IO.puts(Rendro.Inspector.inspect(final_doc))

# Access structured diagnostics emitted during the pipeline.
# final_doc.diagnostics is a list of structured maps with stable common keys
# such as :level and :type plus event-specific optional fields.
_diagnostics = final_doc.diagnostics
```

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

### Inspect Rendro Document Structure and Diagnostics

Source: https://hexdocs.pm/rendro/index.html

Use `render_with_diagnostics/2` to get the final document struct and PDF binary, then `Rendro.Inspector.inspect/1` to view the layout tree. Access structured diagnostics via `final_doc.diagnostics`.

```elixir
# docs-contract: readme-inspector-compile
doc = Rendro.flow([Rendro.block(Rendro.text("Hello World"))])

{:ok, _pdf, final_doc} = Rendro.render_with_diagnostics(doc)

# Print a human-readable tree of pages, blocks, and dimensions
IO.puts(Rendro.Inspector.inspect(final_doc))

# Access structured diagnostics emitted during the pipeline.
# final_doc.diagnostics is a list of structured maps with stable common keys
# such as :level and :type plus event-specific optional fields.
_diagnostics = final_doc.diagnostics

```

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

### Create Viewer Evidence File

Source: https://hexdocs.pm/rendro/viewer_evidence.html

Copies a template to create a new viewer evidence file. The file path must match the pattern priv/viewer_evidence/<surface>/<viewer>.md, and the frontmatter surface/viewer must match the matrix mapping.

```shell
cp priv/viewer_evidence/_template.md priv/viewer_evidence/<surface>/<viewer>.md

```

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

### Rendro Telemetry Event Metadata Structure

Source: https://hexdocs.pm/rendro/Rendro.Telemetry.html

Defines the metadata included in start, stop, and exception events for Rendro telemetry. Start events include render ID, stage, document type, and determinism. Stop events add duration, status, page count, and byte size. Exception events include kind, reason, and stacktrace.

```elixir
%{render_id: String.t(), stage: atom(), document_type: atom(), deterministic: boolean()}
```

```elixir
%{duration: integer(), status: :ok | :error, page_count: non_neg_integer(), byte_size: non_neg_integer()}
```

```elixir
%{kind: atom(), reason: term(), stacktrace: list()}
```

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

### Attach Threadline Handler

Source: https://hexdocs.pm/rendro/integrations.html

Attach the Rendro Threadline adapter once at application start. The attach/0 function is idempotent.

```elixir
defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    Rendro.Adapters.Threadline.attach()
    # ... supervise children
  end
end
```

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

### Build Receipt (Basic)

Source: https://hexdocs.pm/rendro/Rendro.Recipes.html

Builds a receipt document. Delegates to the two-arity version with an empty options list.

```elixir
receipt(data)
```

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

### Get Built-in Helvetica Descriptor

Source: https://hexdocs.pm/rendro/Rendro.FontRegistry.html

Returns the built-in Helvetica descriptor. This is used for the public compatibility path.

```elixir
@spec helvetica() :: descriptor()
```

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

### get(t, keyword)

Source: https://hexdocs.pm/rendro/Rendro.Storage.html

Retrieves a stored artifact by its identifier. Returns `{:ok, Artifact.t()}` if found, or `{:error, :not_found}` / `{:error, reason}`.

```APIDOC
## get(t, keyword)

### Description
Retrieves a stored artifact by its identifier.

### Parameters
#### Path Parameters
- **t** (String.t()) - Description not available
- **keyword** (keyword()) - Description not available

### Response
- **return value** ({:ok, Rendro.Artifact.t()} | {:error, term()}) - `{:ok, Artifact.t()}` if found, or `{:error, :not_found}` / `{:error, reason}`.
```

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

### new(opts)

Source: https://hexdocs.pm/rendro/Rendro.Document.html

Creates a new `%Rendro.Document{}` struct with the given keyword options.

```APIDOC
## new(opts)

### Description
Creates a new `%Rendro.Document{}` struct with the given keyword options.

### Method
N/A (SDK Function)

### Parameters
- **opts** (keyword()) - Keyword options to initialize the document with.

### Response
- **t()** - A new Rendro document initialized with the provided options.
```

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

### Build Receipt (with Options)

Source: https://hexdocs.pm/rendro/Rendro.Recipes.html

Builds a receipt document with options. Forwards options verbatim to the underlying document function.

```elixir
receipt(data, opts)
```

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

### Get Rendro Render Prefix

Source: https://hexdocs.pm/rendro/Rendro.Telemetry.html

Retrieves the top-level render prefix used in Rendro telemetry. This is typically `[:rendro, :render]`.

```elixir
@spec render_prefix() :: [atom()]
```

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

### prepare(artifact, opts)

Source: https://hexdocs.pm/rendro/Rendro.Sign.html

Prepares an artifact for signing by patching deterministic signature placeholders. It accepts an artifact and preparation options.

```APIDOC
## prepare(artifact, opts)

### Description
Prepares an artifact for signing by patching deterministic signature placeholders.

### Parameters
#### Path Parameters
- **artifact** (Rendro.Artifact.t()) - The artifact to prepare.
- **opts** (prepare_options()) - A list of preparation options.

### Response
#### Success Response
- **{:ok, Rendro.Artifact.t()}** - The prepared artifact.

#### Error Response
- **{:error, Rendro.Error.t()}** - An error occurred during preparation.
```

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

### Create New Document with Options

Source: https://hexdocs.pm/rendro/Rendro.Document.html

Creates a new Rendro Document struct with specified keyword options. Use this to initialize a document with specific metadata.

```Elixir
Rendro.Document.new(metadata: %Rendro.Metadata{title: "Invoice"})
```

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

### Build Certificate (Basic)

Source: https://hexdocs.pm/rendro/Rendro.Recipes.html

Builds a certificate document. Delegates to the two-arity version with an empty options list.

```elixir
certificate(data)
```

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

### new

Source: https://hexdocs.pm/rendro/Rendro.AssetRegistry.html

Creates a new, empty asset registry.

```APIDOC
## new()

### Description
Creates a new, empty asset registry.

### Response
#### Success Response (200)
- **new_registry** (t()) - Returns a new asset registry.
```

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

### Get Branded Invoice Page Template

Source: https://hexdocs.pm/rendro/Rendro.Recipes.BrandedInvoice.html

Retrieves the default page template for the branded invoice. Verifies the template name and its regions.

```elixir
iex> template = Rendro.Recipes.BrandedInvoice.page_template()
iex> template.name
:branded_invoice
iex> Enum.map(template.regions, & &1.name) |> Enum.sort()
[:body, :footer, :header, :logo]
```

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

### Run Normalized Benchmark

Source: https://hexdocs.pm/rendro/comparison.html

Execute the normalized benchmark from the repository root. This command builds Docker images, uses the host Typst CLI, and records raw artifacts.

```bash
elixir bench/comparison/run.exs --track normalized --all
mix rendro.comparison.check
```

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

### Rendro.Storage get Callback

Source: https://hexdocs.pm/rendro/Rendro.Storage.html

Defines the callback signature for retrieving a stored artifact by its identifier. Returns {:ok, Rendro.Artifact.t()} if found, or an error tuple.

```Elixir
@callback get(
  String.t(),
  keyword()
) :: {:ok, Rendro.Artifact.t()} | {:error, term()}
```

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

### Verify Accrue Invoice Document Generation

Source: https://hexdocs.pm/rendro/integrations.html

Create a sample Accrue.Invoice, generate a Rendro document, and verify the PDF output and document content. Ensure the input is an Accrue.Invoice struct, not a plain map.

```elixir
# docs-contract: integrations-accrue-verification
invoice = %Accrue.Invoice{
  id: "INV-001",
  issued_at: ~D[2026-04-26],
  customer: %{name: "Acme Corp"},
  line_items: [
    %Accrue.LineItem{description: "Widget", quantity: 2, unit_amount: 50, subtotal: 100}
  ],
  total: 100
}

{:ok, doc} = Rendro.Adapters.Accrue.recipe(invoice)
{:ok, pdf}  = Rendro.render(doc)

# PDF magic bytes confirm a valid PDF was produced
assert binary_part(pdf, 0, 4) == "%PDF"

# Inspect the document to confirm the invoice id is present
assert inspect(doc) =~ "INV-001"
```

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

### Build Standard Invoice (with Options)

Source: https://hexdocs.pm/rendro/Rendro.Recipes.html

Builds a standard invoice document with options. Forwards options verbatim to the underlying document function.

```elixir
invoice(data, opts)
```

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

### Get Rendro Stage Names

Source: https://hexdocs.pm/rendro/Rendro.Telemetry.html

Retrieves a list of all possible stage names within the Rendro pipeline. These are used in telemetry event metadata.

```elixir
@spec stage_names() :: [atom()]
```

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

### Get Portrait Certificate Page Template

Source: https://hexdocs.pm/rendro/Rendro.Recipes.Certificate.html

Retrieve a certificate page template configured for portrait orientation. This is achieved by passing the `:orientation` option.

```elixir
iex> t = Rendro.Recipes.Certificate.page_template(orientation: :portrait)
iex> t.height > t.width
true
```

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

### Generate a Basic Payment Receipt

Source: https://hexdocs.pm/rendro/recipes.html

This snippet demonstrates how to create a simple payment receipt document using the `Rendro.Recipes.Receipt.document/1` function and render it to PDF. Ensure the `Rendro` library is configured.

```elixir
# docs-contract: recipes-receipt-document
data = %{
  title: "Payment Receipt",
  date: ~D[2026-05-29],
  customer: %{name: "Acme Corp"},
  lines: [
    %{description: "Widget A", amount: Decimal.new("29.99")},
    %{description: "Widget B", amount: Decimal.new("49.99")}
  ],
  totals: %{subtotal: Decimal.new("79.98"), total: Decimal.new("79.98")}
}

doc = Rendro.Recipes.Receipt.document(data)
assert doc.page_template == :receipt
assert %Rendro.Document{} = doc

{:ok, pdf} = Rendro.render(doc, deterministic: true)
assert binary_part(pdf, 0, 5) == "%PDF-"
```

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

### document/2

Source: https://hexdocs.pm/rendro/Rendro.Recipes.Certificate.html

Assembles and returns a fully composed %Rendro.Document{} ready for Rendro.render/2. It accepts data for the certificate and optional configuration settings.

```APIDOC
## document(data, opts \\ [])

### Description
Assembles and returns a fully composed `%Rendro.Document{}` ready for `Rendro.render/2`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **data** (map) - Required - Certificate data including title, recipient, and date. Optional keys include body, seal_line, and brand.
* **opts** (keyword) - Optional - Options for page template and border configuration. Includes `:page_number_opts` and `:border`.

### Request Example
```elixir
data = %{title: "Certificate of Completion", recipient: "Jane Smith", date: ~D[2026-05-29]}
doc = Rendro.Recipes.Certificate.document(data)
```

### Response
#### Success Response (200)
* **Rendro.Document.t()** - A composed document struct ready for rendering.
```

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

### Get PDF Metadata

Source: https://hexdocs.pm/rendro/Rendro.Adapters.Pdfium.html

Retrieves metadata from a PDF file using the `pdfium info` command. Returns a map with string keys on success.

```Elixir
Rendro.Adapters.Pdfium.info(file_path, opts \\ [])
```

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

### Build Standard Invoice (Basic)

Source: https://hexdocs.pm/rendro/Rendro.Recipes.html

Builds a standard invoice document. Delegates to the two-arity version with an empty options list.

```elixir
invoice(data)
```

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

### Get Default Font Name

Source: https://hexdocs.pm/rendro/Rendro.FontRegistry.html

Returns the default logical font name used by new documents. This is the font that will be used if no other font is explicitly specified.

```elixir
@spec default_font() :: logical_name()
```

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

### Build Certificate (with Options)

Source: https://hexdocs.pm/rendro/Rendro.Recipes.html

Builds a certificate document with options. Forwards options verbatim to the underlying document function.

```elixir
certificate(data, opts)
```

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

### Soft Deprecation Example

Source: https://hexdocs.pm/rendro/api_stability.html

Illustrates how to soft-deprecate a function using the `@doc deprecated:` annotation. This approach keeps the function functional while signaling its upcoming removal.

```elixir
@doc deprecated: "Use `Rendro.new_function/2` instead. This function will be removed in 2.0."
def old_function(doc, opts), do: new_function(doc, opts)
```

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

### Mix Rendro Viewer Evidence Subcommands

Source: https://hexdocs.pm/rendro/Mix.Tasks.Rendro.ViewerEvidence.html

Lists the available subcommands for the `mix rendro.viewer_evidence` task.

```bash
mix rendro.viewer_evidence list [--json]
mix rendro.viewer_evidence missing [--json]
mix rendro.viewer_evidence validate [--strict]
mix rendro.viewer_evidence record <surface> <viewer> [--fixture PATH] [--recorded-by ID]
```

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

### Record Hex Download Snapshot

Source: https://hexdocs.pm/rendro/adoption.html

Use this command to record a snapshot of Hex download statistics for a package. This is useful for tracking package adoption over time.

```bash
curl -fsSL https://hex.pm/api/packages/rendro | jq '.downloads'
```

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

### Get Rendro Telemetry Event Prefixes

Source: https://hexdocs.pm/rendro/Rendro.Telemetry.html

Retrieves the defined event prefixes for Rendro telemetry. This function returns a list of lists, where each inner list is a prefix.

```elixir
@spec event_prefixes() :: [[atom()]]
```

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

### Build Statement (Basic)

Source: https://hexdocs.pm/rendro/Rendro.Recipes.html

Builds a statement document. Delegates to the two-arity version with an empty options list.

```elixir
statement(data)
```

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

### Get Variant Logical Name

Source: https://hexdocs.pm/rendro/Rendro.FontRegistry.html

Retrieves the logical name for a given font family and variant. This function is used to map specific font variants to their canonical logical names.

```elixir
spec variant_logical_name(logical_name(), embedded_variant()) :: logical_name()
```

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

### Rendro Artifact Prepare Callback

Source: https://hexdocs.pm/rendro/Rendro.Sign.Adapter.html

The prepare callback is used by adapters to process artifact data before signing. It accepts an artifact and a map, and should return an updated binary and map upon success, or an error.

```Elixir
@callback prepare(Rendro.Artifact.t(), map()) :: {:ok, binary(), map()} | {:error, term()}
```

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

### Prepare Fixture for Forms

Source: https://hexdocs.pm/rendro/viewer_evidence.html

Generates a PDF fixture file for forms. The fixture path must exist on disk and be committed or staged before manual observation.

```elixir
mix run -e 'Rendro.Test.FormSupportFixture.write_fixture("test/fixtures/forms_support_fixture.pdf")'

```

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

### Get Default Certificate Page Template

Source: https://hexdocs.pm/rendro/Rendro.Recipes.Certificate.html

Retrieve the default page template for a certificate, which is A4 landscape. This function supports options for page size, orientation, margins, and borders.

```elixir
iex> t = Rendro.Recipes.Certificate.page_template()
iex> t.width > t.height
true
```

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

### new()

Source: https://hexdocs.pm/rendro/Rendro.Document.html

Creates a new empty `%Rendro.Document{}` struct.

```APIDOC
## new()

### Description
Creates a new empty `%Rendro.Document{}` struct.

### Method
N/A (SDK Function)

### Parameters
None

### Response
- **t()** - A new, empty Rendro document.
```

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

### Get All Rendro Telemetry Event Names

Source: https://hexdocs.pm/rendro/Rendro.Telemetry.html

Retrieves a list of all defined telemetry event names for Rendro. This function returns a list of lists, where each inner list represents an event name.

```elixir
@spec all_event_names() :: [[atom()]]
```

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

### Generate Invoice Document and Render to PDF

Source: https://hexdocs.pm/rendro/Rendro.Recipes.Invoice.html

This snippet demonstrates the simplest way to generate a fully composed invoice document and render it to PDF using the default settings.

```elixir
data = %{id: "INV-001", date: ~D[2026-01-15], items: [...]}
doc  = Rendro.Recipes.Invoice.document(data)
{:ok, pdf} = Rendro.render(doc)
```

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

### Deferral for Chrome PDFium LTV Indicators

Source: https://hexdocs.pm/rendro/viewer_evidence.html

Use this template when long-term-validation (LTV) indicators are absent. This example notes that pdfium-cli does not expose LTV indicators, limiting LTV posture to Acrobat-only.

```json
{
  "chrome_pdfium": {
    "status": "explicit_deferral",
    "evidence_deferred": "pdfium-cli structural open and form extraction do not expose long-term-validation timestamp, revocation, or expiry indicators; LTV posture remains Acrobat-only for viewer promotion."
  }
}
```

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

### render/2

Source: https://hexdocs.pm/rendro/Rendro.Adapters.Pdfium.html

Rasterizes a PDF binary to a list of PNG binaries using `pdfium-cli render`.

```APIDOC
## render/2

### Description
Rasterizes a PDF binary to a list of PNG binaries using `pdfium-cli render`.

### Function Signature
```elixir
render(pdf_binary :: binary(), opts :: keyword()) :: {:ok, [binary()]} | {:error, term()}
```

### Parameters
#### Request Body
- `pdf_binary` (binary()) - The binary content of the PDF file.
- `opts` (keyword()) - Optional keyword list for configuration:
  - `dpi:` (positive integer, default 150) - Dots per inch for rendering.
  - `pages:` (non-empty string, default nil) - Page range string for `pdfium-cli --pages`.

### Returns
- `{:ok, [binary()]}` - A list of PNG binaries (one per page) on success.
- `{:error, term()}` - An error term on failure.
```

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

### Run Visual UAT Task

Source: https://hexdocs.pm/rendro/Mix.Tasks.Rendro.VisualUat.html

Execute the `mix rendro.visual_uat` task to perform visual acceptance testing on the branded invoice fixture. You can specify a phase number or use the default.

```bash
mix rendro.visual_uat            # phase 29 (default)
mix rendro.visual_uat 29
```

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

### Deferral for Apple Preview Signature Validation

Source: https://hexdocs.pm/rendro/viewer_evidence.html

Use this template when the viewer cannot validate digital signatures. This example highlights Apple Preview's limitations in validating /Sig digital signatures.

```json
{
  "apple_preview": {
    "status": "explicit_deferral",
    "evidence_deferred": "Apple Preview does not validate /Sig digital signatures and append-save invalidates signature dictionaries; signed-artifact viewer promotion requires Acrobat or pdfium-cli structural lanes."
  }
}
```

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

### Deferral for PDF.js Forms

Source: https://hexdocs.pm/rendro/viewer_evidence.html

Use this template when promotion is blocked by missing upstream viewer capability. This example specifically addresses PDF.js's lack of AcroForm signature widget editing.

```json
{
  "pdfjs": {
    "status": "explicit_deferral",
    "evidence_deferred": "PDF.js does not implement AcroForm signature widget editing or unsigned placeholder rendering per mozilla/pdf.js#4202; promotion requires upstream signature-field support."
  }
}
```

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

### Record Viewer Evidence

Source: https://hexdocs.pm/rendro/viewer_evidence.html

Use this command to record new evidence for a specific viewer surface. Ensure you have the correct fixture file and provide your identifier.

```shell
mix rendro.viewer_evidence record <surface> <viewer> \
  --fixture test/fixtures/<surface>_support_fixture.pdf \
  --recorded-by <your-identifier>

```

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

### Example of Section-Local Page Numbering

Source: https://hexdocs.pm/rendro/changelog.html

This snippet shows how to use section-local page numbering variables within the documentation. These variables are useful for dynamic content generation based on document structure.

```markdown
 `{{section_page_number}}` / `{{section_total_pages}}`
```

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

### Build Statement (with Options)

Source: https://hexdocs.pm/rendro/Rendro.Recipes.html

Builds a statement document with options. Forwards options verbatim to the underlying document function.

```elixir
statement(data, opts)
```

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

### Generate Launch Artifacts with Custom PDFium Path

Source: https://hexdocs.pm/rendro/Mix.Tasks.Rendro.LaunchArtifacts.Gen.html

Use this command to generate launch artifacts when `pdfium-cli` is not in your system's PATH. Specify the direct path to the `pdfium` binary.

```bash
mix rendro.launch_artifacts.gen --pdfium /path/to/pdfium
```

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

### Get PDF Form Fields

Source: https://hexdocs.pm/rendro/Rendro.Adapters.Pdfium.html

Retrieves form field observations from a PDF file using the `pdfium form --output-type json` command. Expects a file path and optional keyword arguments.

```Elixir
Rendro.Adapters.Pdfium.form_fields(file_path, opts \\ [])
```

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

### Build Branded Invoice (Basic)

Source: https://hexdocs.pm/rendro/Rendro.Recipes.html

Builds a branded invoice document. Delegates to the two-arity version with an empty options list.

```elixir
branded_invoice(data)
```

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

### document(data, opts \\ [])

Source: https://hexdocs.pm/rendro/Rendro.Recipes.BrandedInvoice.html

Assembles and returns a fully composed branded Rendro.Document. It takes data and optional keyword arguments to create the document.

```APIDOC
## document(data, opts \\ [])

### Description
Assembles and returns a fully composed branded `%Rendro.Document{}`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **data** (map) - Required - The data for the invoice, including branding information.
- **opts** (keyword) - Optional - Additional options for document assembly.
```

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

### Statement Escape-hatch with Page Template and Sections

Source: https://hexdocs.pm/rendro/recipes.html

This snippet demonstrates using the escape-hatch mechanism to get the page template and sections separately. This is useful for more advanced customization or integration scenarios. Ensure data includes period, account, opening balance, and lines.

```elixir
# docs-contract: recipes-statement-escape-hatch
data = %{
  period: %{from: ~D[2026-06-01], to: ~D[2026-06-30]},
  account: %{name: "Beta LLC"},
  opening_balance: Decimal.new("500.00"),
  lines: [
    %{date: ~D[2026-06-05], description: "Service fee", amount: Decimal.new("150.00")}
  ]
}

template = Rendro.Recipes.Statement.page_template()
sections = Rendro.Recipes.Statement.sections(data)

assert template.name == :statement
assert is_list(sections)
assert length(sections) > 0
```

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

### Attach PDF in a Pipe with Error Handling

Source: https://hexdocs.pm/rendro/integrations.html

Demonstrates attaching a PDF within a pipe, including handling potential errors during the process.

```elixir
email
|> Rendro.Adapters.Mailglass.attach_pdf(doc, "invoice.pdf")
|> case do
  %Swoosh.Email{} = email_with_pdf -> MyApp.Mailer.deliver(email_with_pdf)
  {:error, reason} -> handle_error(reason)
end
```

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

### List Viewer Evidence and Verify Docs Contract

Source: https://hexdocs.pm/rendro/viewer_evidence.html

Lists viewer evidence and runs tests to verify the documentation contract. Your cell should appear in the table without a 'legacy: missing evidence' note, and the docs-contract lane must pass.

```shell
mix rendro.viewer_evidence list

```

```shell
mix test test/docs_contract/viewer_evidence_claims_test.exs

```

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

### new

Source: https://hexdocs.pm/rendro/Rendro.EmbeddedFileRegistry.html

Creates and returns a new, empty Rendro.EmbeddedFileRegistry.

```APIDOC
## new()

### Description
Creates a new, empty embedded file registry.

### Response
#### Success Response
- **t()** - Returns a new, empty registry.
```

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

### Run Livebook Check Task

Source: https://hexdocs.pm/rendro/Mix.Tasks.Rendro.Livebook.Check.html

Executes the `mix rendro.livebook.check` task to convert and run a Livebook notebook. The task processes the specified notebook path using `Livebook.live_markdown_to_elixir/1` and executes the output script with `RENDRO_LIVEBOOK_LOCAL=1`.

```bash
mix rendro.livebook.check
```

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

### Building a Document with the Builder API

Source: https://hexdocs.pm/rendro/readme.html

This snippet demonstrates how to create a document using the Rendro builder API. It defines page templates, regions, and sections, then renders the document to PDF. Ensure Rendro is imported.

```elixir
import Rendro.Document

doc =
  Rendro.Document.new()
  |> add_template(
    Rendro.page_template(
      name: :report,
      regions: [
        Rendro.region(name: :header, role: :header, anchor: :top,   x: 24, y: 24,  width: 372, height: 24),
        Rendro.region(name: :body,   role: :body,   anchor: :flow,  x: 24, y: 72,  width: 372, height: 451),
        Rendro.region(name: :footer, role: :footer, anchor: :bottom, x: 24, y: 547, width: 372, height: 24)
      ]
    )
  )
  |> set_template(:report)
  |> add_section(Rendro.section(name: :heading, region: :header, content: [
    Rendro.block(Rendro.text("Account Statement", size: 14))
  ]))
  |> add_section(Rendro.section(name: :body_text, region: :body, content: [
    Rendro.block(Rendro.text("Summary paragraph here.", size: 12), width: 372)
  ]))
  |> add_section(Rendro.section(name: :footer_text, region: :footer, content: [
    Rendro.block(Rendro.text("Generated by Rendro", size: 10))
  ]))

{:ok, _pdf} = Rendro.render(doc)
```

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

### prepare_options Type

Source: https://hexdocs.pm/rendro/Rendro.Sign.html

Represents a list of prepare_option, used to configure the prepare function.

```elixir
@type prepare_options() :: [prepare_option()]
```

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

### Record Forms Viewer Evidence (Automated)

Source: https://hexdocs.pm/rendro/viewer_evidence.html

Use these commands to record evidence for forms viewer compatibility using automated tools like pdfium-cli. Ensure the target fixture and recorded-by information are correctly specified.

```bash
mix rendro.viewer_evidence record forms chrome_pdfium \
  --fixture test/fixtures/forms_support_fixture.pdf \
  --recorded-by ci:viewer-evidence-live-proof
```

```bash
mix rendro.viewer_evidence record forms apple_preview \
  --fixture test/fixtures/forms_support_fixture.pdf \
  --recorded-by ci:viewer-evidence-live-proof
```

```bash
mix rendro.viewer_evidence record embedded_files adobe_acrobat_reader \
  --fixture test/fixtures/embedded_artifact_support_fixture.pdf \
  --recorded-by ci:viewer-evidence-live-proof
```

```bash
mix rendro.viewer_evidence record links adobe_acrobat_reader \
  --fixture test/fixtures/embedded_artifact_support_fixture.pdf \
  --recorded-by ci:viewer-evidence-live-proof
```

```bash
mix rendro.viewer_evidence record links apple_preview \
  --fixture test/fixtures/embedded_artifact_support_fixture.pdf \
  --recorded-by ci:viewer-evidence-live-proof
```

```bash
mix rendro.viewer_evidence record protection apple_preview \
  --fixture test/fixtures/protection_support_fixture.pdf \
  --recorded-by ci:viewer-evidence-live-proof
```

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

### render

Source: https://hexdocs.pm/rendro/Rendro.html

Renders the document to a binary format. This is a basic rendering function that returns the document's content as a binary string.

```APIDOC
## render(doc, opts)

### Description
Renders the document to a binary.

### Parameters
#### Path Parameters
- **doc** (Rendro.Document.t()) - Required - The document to render.
- **opts** (render_options()) - Optional - Options for rendering the document. Defaults to `[]`.
```

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

### Build Branded Invoice (with Options)

Source: https://hexdocs.pm/rendro/Rendro.Recipes.html

Builds a branded invoice document with options. Forwards options verbatim to the underlying document function.

```elixir
branded_invoice(data, opts)
```

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

### Configure Rendro to use HarfBuzz Adapter

Source: https://hexdocs.pm/rendro/Rendro.Adapters.HarfBuzz.html

To use the HarfBuzz adapter, ensure `{:harfbuzz_ex, "~> 1.2", optional: true}` is in your mix.exs. Then, configure Rendro in your `config/config.exs` to use this adapter.

```elixir
config :rendro, shaper: Rendro.Adapters.HarfBuzz
```

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

### Generate Invoice Document with Default Template

Source: https://hexdocs.pm/rendro/index.html

Use the `document/1` function from the Invoice recipe for a fully assembled document ready for rendering. This is the common case for standard business invoices.

```elixir
data = %{
  id: "INV-2026-001",
  date: ~D[2026-04-30],
  items: [
    %{name: "Consulting Services", qty: 10, price: 2_500},
    %{name: "Support Plan",        qty: 1,  price: 500}
  ]
}

doc = Rendro.Recipes.Invoice.document(data)
{:ok, pdf} = Rendro.render(doc)
```

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

### prepare Function Signature

Source: https://hexdocs.pm/rendro/Rendro.Sign.html

The prepare function takes an artifact and prepare options, returning either an OK result with a modified artifact or an error.

```elixir
@spec prepare(Rendro.Artifact.t(), prepare_options()) ::
  {:ok, Rendro.Artifact.t()} | {:error, Rendro.Error.t()}
```

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

### Legacy Rendro Flow with Header and Footer

Source: https://hexdocs.pm/rendro/index.html

This code demonstrates the legacy style of passing `header:` and `footer:` as keyword arguments to `Rendro.flow/2`. It is supported for backward compatibility but not recommended for new code.

```elixir
# Legacy style — supported for backward compatibility, not recommended for new code
Rendro.flow(
  [Rendro.block(Rendro.text("Body content"))],
  header: [Rendro.block(Rendro.text("Header"))],
  footer: [Rendro.block(Rendro.text("Footer"))]
)
```

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

### List Adoption Signal Issues

Source: https://hexdocs.pm/rendro/adoption.html

This command lists all issues with the 'adoption:signal' label. Use this to identify and track adoption signals.

```bash
gh issue list --state all --label "adoption:signal" \
  --json number,title,author,createdAt,url,labels

```

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

### Verify Threadline Integration (Happy Path)

Source: https://hexdocs.pm/rendro/integrations.html

Render a document and confirm the audit row arrived in Threadline. Detach the handler afterwards.

```elixir
# docs-contract: integrations-threadline-happy-path
Rendro.Adapters.Threadline.attach()

{:ok, _pdf} = Rendro.render(
  Rendro.flow([Rendro.block(Rendro.text("Test invoice", size: 12))])
)

Rendro.Adapters.Threadline.detach()
```

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

### Rendro.Protect supported_permissions() Function

Source: https://hexdocs.pm/rendro/Rendro.Protect.html

Retrieves a list of all permissions supported by Rendro.Protect.

```elixir
@spec supported_permissions() :: [permission()]
```

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

### sections/2

Source: https://hexdocs.pm/rendro/Rendro.Recipes.Certificate.html

Returns a list of %Rendro.Section{} structs for the certificate body, based on the provided data and options.

```APIDOC
## sections(data, opts \\ [])

### Description
Returns a list of `%Rendro.Section{}` structs for the certificate body.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **data** (map) - Required - Certificate data including title, recipient, and date.
* **opts** (keyword) - Optional - Additional options for section generation.

### Request Example
```elixir
data = %{title: "Certificate of Completion", recipient: "Jane Smith", date: ~D[2026-05-29]}
sections = Rendro.Recipes.Certificate.sections(data)
```

### Response
#### Success Response (200)
* **[Rendro.Section.t()]** - A list of section structs representing the certificate body.
```

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

### Define Render Options Type

Source: https://hexdocs.pm/rendro/Rendro.html

Defines a list of render options.

```Elixir
@type render_options() :: [render_option()]
```

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

### render_with_diagnostics

Source: https://hexdocs.pm/rendro/Rendro.html

Renders the document and returns the binary along with the fully populated document struct, including diagnostics. Useful for inspecting layout or reading populated diagnostics.

```APIDOC
## render_with_diagnostics(doc, opts)

### Description
Renders the document and returns the binary along with the fully populated document struct. Useful for inspecting layout or reading populated diagnostics.

### Parameters
#### Path Parameters
- **doc** (Rendro.Document.t()) - Required - The document to render.
- **opts** (render_options()) - Optional - Options for rendering the document. Defaults to `[]`.

### Response
#### Success Response
- **binary** (binary()) - The rendered document as a binary.
- **document** (Rendro.Document.t()) - The fully populated document struct with diagnostics.
```

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

### Validate Live PDF Tools (Elixir/Mix)

Source: https://hexdocs.pm/rendro/viewer_evidence.html

Run these Elixir Mix tests to validate committed fixtures using live PDF tools. This command includes specific test files for various viewer evidence types.

```elixir
mix test --include live_pdf_tools \
  test/rendro/adapters/forms_viewer_evidence_live_test.exs \
  test/rendro/adapters/embedded_files_viewer_evidence_live_test.exs \
  test/rendro/adapters/links_viewer_evidence_live_test.exs \
  test/rendro/adapters/protection_viewer_evidence_live_test.exs \
  test/rendro/adapters/signature_widget_viewer_evidence_live_test.exs \
  test/rendro/adapters/signed_artifact_viewer_evidence_live_test.exs \
  test/rendro/adapters/trust_sensitive_viewer_evidence_live_test.exs
```
Tokens:
Raw