Unpdf 0.10.0

Unpdf

.NET bindings for unpdf - High-performance PDF content extraction to Markdown, text, and JSON.

Installation

dotnet add package Unpdf

Quick Start

The API is handle-based: parse once into an UnpdfDocument, query it, then dispose it.

using Unpdf;

using var doc = UnpdfDocument.ParseFile("document.pdf");

// Markdown
Console.WriteLine(doc.ToMarkdown());

// Plain text
Console.WriteLine(doc.ToText());

// JSON
Console.WriteLine(doc.ToJson(compact: false));

// Metadata
Console.WriteLine($"Title: {doc.Title}");
Console.WriteLine($"Author: {doc.Author}");
Console.WriteLine($"Pages: {doc.SectionCount}");

// Native library version
Console.WriteLine(UnpdfDocument.Version);

Parse from memory instead of a path with UnpdfDocument.ParseBytes(byte[]).

Advanced Usage

Markdown options

using var doc = UnpdfDocument.ParseFile("document.pdf");

var markdown = doc.ToMarkdown(new MarkdownOptions
{
    IncludeFrontmatter = true,
    EscapeSpecialChars = true,
    ParagraphSpacing = true,
});

Per-page extraction

using var doc = UnpdfDocument.ParseFile("document.pdf");

for (int page = 1; page <= doc.SectionCount; page++)
{
    Console.WriteLine(doc.PageToText(page));
}

Detecting scanned (image-only) PDFs

Empty output can mean a scanned document, a genuinely blank page, or a parse failure. The introspection surface tells them apart:

using var doc = UnpdfDocument.ParseFile("scan.pdf");

// Document level
if (doc.GetExtractionQuality().IsScanPdf)
    Console.WriteLine("Scanned document - OCR required");

// Page level (works for mixed documents too)
var stats = doc.GetPageStats(1);
if (stats.TextOpCount == 0 && stats.ImageOpCount > 0)
    Console.WriteLine("Page 1 is image-only (scanned)");
else if (stats.TextOpCount == 0)
    Console.WriteLine("Page 1 is genuinely blank");

Note: a searchable scan (page image plus an invisible OCR text layer) reports TextOpCount > 0 — combine the check with OcrTextSuppressed, which flags pages whose unreadable OCR layer was dropped.

Handling failures

UnpdfException.Kind says why a call failed, so you can branch on the reason instead of matching on Message:

try
{
    using var doc = UnpdfDocument.ParseFile("document.pdf");
    Console.WriteLine(doc.ToMarkdown());
}
catch (UnpdfException e) when (e.Kind == UnpdfErrorKind.Encrypted)
{
    Console.WriteLine("Password required");
}
catch (UnpdfException e)
{
    Console.WriteLine($"Extraction failed ({e.Kind}): {e.Message}");
}

UnpdfErrorKind values are part of the native ABI: new reasons take new numbers and existing ones are never renumbered, so treat an unrecognised value as a generic failure. A failure raised by the managed wrapper rather than the native library reports UnpdfErrorKind.Other.

Embedded resources

Resource extraction is off by default in this binding's parse path (it bounds peak memory on large PDFs), so ResourceCount is 0 and GetResourceIds() is empty for documents parsed through ParseFile / ParseBytes. Use GetPageStats to detect image-only pages rather than ResourceCount.

API Reference

UnpdfDocument

MarkdownOptions

ExtractionQuality

CharCount, WordCount, ReplacementCharCount, Encrypted, IsScanPdf, SuppressedOcrPages.

PageStats

Page, TextOpCount, ImageOpCount, OcrTextSuppressed.

UnpdfException

Message plus Kind (UnpdfErrorKind) — see "Handling failures".

License

MIT License