carbonpdf/lib.rs
1//! # CarbonPDF
2//!
3//! Production-ready HTML to PDF conversion using Headless Chrome.
4//!
5//! CarbonPDF provides a safe, ergonomic API for converting HTML content to PDF documents
6//! using Headless Chrome via the Chrome DevTools Protocol. It's designed for backend
7//! services, CI/CD pipelines, and any application requiring high-quality PDF generation.
8//!
9//! ## Why Headless Chrome?
10//!
11//! - **Accurate rendering**: Chrome's rendering engine ensures PDFs match web output exactly
12//! - **Modern web standards**: Full support for CSS3, JavaScript, web fonts, and flexbox/grid
13//! - **Battle-tested**: Leverages the same engine used by billions of users daily
14//!
15//! ## Architecture
16//!
17//! CarbonPDF uses a layered architecture:
18//! - **Public API**: Ergonomic builder pattern for common use cases
19//! - **Renderer trait**: Abstraction allowing multiple backend implementations
20//! - **Chrome backend**: Production-ready Chrome DevTools Protocol integration
21//!
22//! ## Quick Start
23//!
24//! ```rust,no_run
25//! use carbonpdf::{PdfBuilder, PageSize, Result};
26//!
27//! #[tokio::main]
28//! async fn main() -> Result<()> {
29//! // Convert HTML string to PDF
30//! let pdf = PdfBuilder::new()
31//! .html("<h1>Hello, PDF!</h1>")
32//! .page_size(PageSize::A4)
33//! .margin_all(1.0)
34//! .build()
35//! .await?;
36//!
37//! std::fs::write("output.pdf", pdf)?;
38//! Ok(())
39//! }
40//! ```
41//!
42//! ## Feature Flags
43//!
44//! - `chrome` (default): Enable Chrome backend via chromiumoxide
45//! - `cli`: Build the `carbonpdf` CLI tool
46
47#![warn(missing_docs, clippy::all)]
48#![deny(unsafe_code)]
49
50pub mod config;
51pub mod error;
52pub mod input;
53pub mod builder;
54pub mod renderer;
55pub mod utils;
56
57// Re-export commonly used types
58pub use builder::PdfBuilder;
59pub use config::{PdfConfig, PageSize, Orientation, Margins};
60pub use error::{Error, Result};
61pub use input::InputSource;
62pub use renderer::PdfRenderer;
63#[cfg(feature = "templates")]
64pub mod template;
65
66#[cfg(feature = "templates")]
67pub use template::render_template;
68
69#[cfg(feature = "cli")]
70pub mod cli;
71
72#[cfg(feature = "chrome")]
73pub use renderer::chrome::ChromeRenderer;
74
75/// Library version
76pub const VERSION: &str = env!("CARGO_PKG_VERSION");