fulgur-cli 0.3.1

HTML/CSS to PDF conversion CLI
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

# Fulgur

An HTML/CSS to PDF converter written in Rust.

Integrates [Blitz](https://github.com/nickelpack/blitz) (HTML parsing, CSS style resolution, layout) with [Krilla](https://github.com/LaurenzV/krilla) (PDF generation) through a pagination-aware layout abstraction.

## Features

- HTML/CSS to PDF conversion
- Automatic page splitting with CSS pagination control (`break-before`, `break-after`, `break-inside`, orphans/widows)
- Text shaping via Parley
- Background colors, borders, and padding
- Deterministic output (same input always produces same PDF)
- Image embedding (PNG / JPEG / GIF)
- Custom font bundling
- External CSS file injection
- Page sizes (A4 / Letter / A3) with landscape support
- PDF metadata (title, author)

## Installation

```bash
cargo install --path crates/fulgur-cli
```

## CLI Usage

```bash
# Convert from file
fulgur render -o output.pdf input.html

# Read from stdin
cat input.html | fulgur render --stdin -o output.pdf

# With options
fulgur render -o output.pdf -s Letter -l --title "My Document" input.html

# Custom fonts and CSS
fulgur render -o output.pdf -f fonts/NotoSansJP.ttf --css style.css input.html

# With images
fulgur render -o output.pdf -i logo.png=assets/logo.png -i photo.png=assets/photo.png input.html
```

### Options

| Option | Description | Default |
|---|---|---|
| `-o, --output` | Output PDF file path (required) | — |
| `-s, --size` | Page size (A4, Letter, A3) | A4 |
| `-l, --landscape` | Landscape orientation | false |
| `--title` | PDF title metadata | — |
| `-f, --font` | Bundle font files (repeatable) | — |
| `--css` | External CSS files (repeatable) | — |
| `-i, --image` | Bundle image files (name=path or path, repeatable) | — |
| `--stdin` | Read HTML from stdin | false |

## Library Usage

```rust
use fulgur::engine::Engine;
use fulgur::asset::AssetBundle;
use fulgur::config::{PageSize, Margin};

// Convert with default settings
let engine = Engine::builder().build();
let pdf = engine.render_html("<h1>Hello</h1>")?;

// Custom configuration
let engine = Engine::builder()
    .page_size(PageSize::A4)
    .margin(Margin::uniform_mm(20.0))
    .title("My Document")
    .build();

let pdf = engine.render_html(html)?;
engine.render_html_to_file(html, "output.pdf")?;

// With images
let mut assets = AssetBundle::new();
assets.add_image_file("logo.png", "assets/logo.png")?;

let engine = Engine::builder()
    .page_size(PageSize::A4)
    .assets(assets)
    .build();

let html = r#"<img src="logo.png" style="display:block;width:100px;height:100px">"#;
let pdf = engine.render_html(html)?;
```

## Architecture

```text
HTML/CSS input
  ↓
Blitz (HTML parse → DOM → style resolution → Taffy layout)
  ↓
DOM → Pageable conversion (BlockPageable / ParagraphPageable / ImagePageable)
  ↓
Pagination (split Pageable tree at page boundaries)
  ↓
Krilla rendering (Pageable.draw() per page → PDF Surface)
  ↓
PDF bytes
```

## Project Structure

```text
crates/
├── fulgur/        # Core library (conversion, layout, rendering)
└── fulgur-cli/    # CLI tool
```

## Development

```bash
# Build
cargo build

# Test
cargo test

# Run CLI directly
cargo run -p fulgur-cli -- render -o output.pdf input.html
```