ironpress

Pure Rust HTML/CSS/Markdown to PDF converter. No browser, no system dependencies.

Other Rust PDF crates shell out to headless Chrome or wkhtmltopdf. ironpress does it natively with a built-in layout engine. No C libraries, no binaries to install, just cargo add ironpress.

Table of Contents

• Quick Start
• API Reference
• Markdown to PDF
• HTML Elements
• CSS Support
• Images
• SVG
• Tables
• Fonts
• Streaming Output
• Async API
• Security
• How It Works
• WASM
• Testing
• License

Quick Start

use ironpress::html_to_pdf;

let pdf_bytes = html_to_pdf("<h1>Hello</h1><p>World</p>").unwrap();
std::fs::write("output.pdf", pdf_bytes).unwrap();

API Reference

One-liner functions

// HTML string to PDF bytes
let pdf = ironpress::html_to_pdf("<h1>Title</h1><p>Content</p>").unwrap();

// Markdown string to PDF bytes
let pdf = ironpress::markdown_to_pdf("# Title\n\nContent").unwrap();

// HTML file to PDF file
ironpress::convert_file("input.html", "output.pdf").unwrap();

// Markdown file to PDF file
ironpress::convert_markdown_file("input.md", "output.pdf").unwrap();

Builder API

use ironpress::{HtmlConverter, PageSize, Margin};

let pdf = HtmlConverter::new()
    .page_size(PageSize::LETTER)        // default: A4
    .margin(Margin::uniform(54.0))      // default: 72pt (1 inch)
    .sanitize(false)                    // default: true
    .convert("<h1>Custom page</h1>")
    .unwrap();

Custom fonts

use ironpress::HtmlConverter;

let ttf_data = std::fs::read("fonts/MyFont.ttf").unwrap();
let pdf = HtmlConverter::new()
    .add_font("MyFont", ttf_data)
    .convert(r#"<p style="font-family: MyFont">Custom font text</p>"#)
    .unwrap();

Page sizes

use ironpress::PageSize;

PageSize::A4         // 595.28 x 841.89 pt (default)
PageSize::LETTER     // 612.0 x 792.0 pt
PageSize::LEGAL      // 612.0 x 1008.0 pt
PageSize::new(width_pt, height_pt)  // custom

Margins

use ironpress::Margin;

Margin::default()                    // 72pt on all sides (1 inch)
Margin::uniform(54.0)               // same value on all sides
Margin::new(top, right, bottom, left)  // individual values in pt

Markdown to PDF

Built-in Markdown parser with zero external dependencies.

let pdf = ironpress::markdown_to_pdf(r#"
# Project Title

Some **bold** and *italic* text with `inline code`.

## Features

- Item one
- Item two
- Item three

1. First
2. Second

> A wise quote

---

[Link text](https://example.com)
"#).unwrap();

Supported Markdown syntax: headings (# to ######), bold (**), italic (*), bold+italic (***), inline code, fenced code blocks, links, images, unordered lists (-, *, +), ordered lists, blockquotes, and horizontal rules.

HTML Elements

CSS Support

Properties

All shorthand properties are supported. Margin and padding accept 1, 2, 3, or 4 values. Border accepts width style color shorthand.

<style> blocks

<style>
  p { color: navy; font-size: 14pt }
  .highlight { background-color: yellow; font-weight: bold }
  #title { font-size: 24pt }
  h1, h2 { color: darkblue }

  @media print {
    .screen-only { display: none }
  }
</style>

Selectors

Values

Media queries

@media print rules are applied (since PDF is print output). @media screen rules are ignored.

@page rule

Control page size and margins from CSS:

<style>
  @page { size: letter landscape; margin: 0.5in; }
</style>

Supported values: A4, letter, legal, landscape, custom dimensions (210mm 297mm), and individual margins.

Images

JPEG and PNG images are supported via data URIs and local file paths.

<!-- Data URI -->
<img src="data:image/jpeg;base64,/9j/4AAQ..." width="200" height="150">

<!-- Local file -->
<img src="photo.jpg" width="300" height="200">

Images are embedded directly in the PDF. JPEG uses DCTDecode, PNG uses FlateDecode with PNG predictors. Width and height attributes are converted from px to pt.

SVG

Inline SVG elements are rendered as vector graphics directly in the PDF (not rasterized):

<svg width="200" height="200" viewBox="0 0 100 100">
  <rect x="10" y="10" width="80" height="80" fill="#e74c3c" stroke="#333" stroke-width="2"/>
  <circle cx="50" cy="50" r="30" fill="#3498db"/>
  <path d="M 20 80 L 50 20 L 80 80 Z" fill="#2ecc71"/>
  <g transform="translate(50, 50) rotate(45)">
    <rect x="-10" y="-10" width="20" height="20" fill="#f39c12"/>
  </g>
</svg>

Supported elements: <rect>, <circle>, <ellipse>, <line>, <polyline>, <polygon>, <path> (full path command set: M, L, H, V, C, S, Q, T, Z with relative variants), <g> groups with transform (translate, scale, rotate, matrix), and viewBox scaling.

SVG content is automatically sanitized: <script>, <foreignObject>, <use>, <image>, and event handlers are stripped.

Tables

Full table support with sections, spanning, auto-sized columns, and styling.

<table>
  <thead>
    <tr><th>Name</th><th>Role</th><th>Status</th></tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="2">Alice</td>
      <td>Engineer</td>
      <td>Active</td>
    </tr>
    <tr>
      <td colspan="2">On project X</td>
    </tr>
    <tr>
      <td>Bob</td>
      <td>Designer</td>
      <td>Active</td>
    </tr>
  </tbody>
</table>

Column widths are automatically calculated based on content. Features: <thead>, <tbody>, <tfoot> sections, colspan and rowspan attributes, bold headers in <th>, cell borders, background colors, and padding.

Fonts

Standard fonts

ironpress includes the 14 standard PDF fonts (no embedding required). CSS font-family values are mapped to the closest match:

Each family includes regular, bold, italic, and bold-italic variants (12 fonts total).

Custom fonts (TrueType)

Embed any TTF font for pixel-perfect rendering:

use ironpress::HtmlConverter;

let font = std::fs::read("fonts/Inter.ttf").unwrap();
let pdf = HtmlConverter::new()
    .add_font("Inter", font)
    .convert(r#"<p style="font-family: Inter">Rendered with Inter</p>"#)
    .unwrap();

The TTF parser extracts character metrics for accurate text wrapping and embeds the font directly in the PDF.

@font-face

Load fonts directly from CSS (local files only, remote URLs are blocked for security):

<style>
  @font-face {
    font-family: "MyFont";
    src: url("fonts/MyFont.ttf");
  }
  p { font-family: MyFont; }
</style>
<p>Rendered with MyFont</p>

Requires .base_path() on the builder so the converter knows where to find font files.

Streaming Output

Write PDF output directly to any std::io::Write implementation instead of allocating a Vec<u8>:

use std::fs::File;

let mut file = File::create("output.pdf").unwrap();
ironpress::html_to_pdf_writer("<h1>Hello</h1>", &mut file).unwrap();

Also available on the builder:

use ironpress::HtmlConverter;
use std::fs::File;

let mut file = File::create("output.pdf").unwrap();
HtmlConverter::new()
    .convert_to_writer("<h1>Hello</h1>", &mut file)
    .unwrap();

Async API

Enable the async feature for async file I/O:

ironpress = { version = "0.9", features = ["async"] }

ironpress::convert_file_async("input.html", "output.pdf").await.unwrap();
ironpress::convert_markdown_file_async("input.md", "output.pdf").await.unwrap();

The HTML parsing, layout, and rendering remain synchronous (CPU-bound). Async is used for file reads and writes via tokio.

Security

HTML is sanitized by default before conversion:

• <script>, <iframe>, <object>, <embed>, <form> tags are stripped
• <style> tags are preserved but dangerous CSS (external url(), expression()) is removed
• @import and @font-face only load local files (remote URLs are blocked, paths sandboxed in base_dir)
• Event handlers (onclick, onload, etc.) are removed
• javascript: URLs are neutralized
• Input size (10 MB) and nesting depth (100 levels) are limited
• SVG sanitizer strips <script>, <foreignObject>, <use>, <image>, <style>, and event handlers inside <svg> blocks
• PNG IDAT accumulation capped at 50 MB to prevent decompression bombs
• CSS @import cumulative payload capped at 10 MB
• TTF parser validates font metrics and uses checked arithmetic

Sanitization can be disabled with .sanitize(false) if you trust the input.

How It Works

graph LR
    A[HTML / Markdown] --> B[Sanitize]
    B --> C[Parse<br/>html5ever]
    C --> D[Extract<br/>‹style›]
    D --> E[Style<br/>Cascade]
    E --> F[Layout<br/>Engine]
    F --> G[PDF 1.4]

    style A fill:#3498db,color:#fff,stroke:none
    style G fill:#27ae60,color:#fff,stroke:none

1. Sanitize:strip dangerous elements (<script>, <iframe>, event handlers, javascript: URLs)
2. Parse:build a DOM tree using html5ever, extract <style> blocks and @page/@font-face rules
3. Style cascade:resolve tag defaults → @media print rules → stylesheet rules → inline CSS, with inherit/initial/unset and CSS variable support
4. Layout:text wrapping with Adobe font metrics, flexbox, tables with colspan/rowspan, floats, page breaks, images, SVG, and the full CSS box model
5. Render:PDF 1.4 output with native Shading Dictionaries for gradients, per-side borders, border-radius, link annotations, embedded images, and TrueType font embedding

For Markdown input, a built-in parser converts Markdown to HTML first (no external dependencies).

WASM

ironpress compiles to WebAssembly for browser-side PDF generation:

cargo build --target wasm32-unknown-unknown --no-default-features

No system dependencies, no filesystem access needed in the core pipeline.

Testing

ironpress uses three layers of testing:

• Unit tests: 1500+ tests covering parsing, style computation, layout, and rendering
• Property-based tests: proptest verifies invariants across thousands of random inputs (no panics on arbitrary HTML/CSS/Markdown, valid PDF output, correct page structure)
• Fuzz targets: cargo-fuzz targets for HTML, CSS, Markdown, and the full pipeline (cargo +nightly fuzz run fuzz_html)

License

MIT