Merge, Split & Overlay

Combine multiple PDFs into one, extract or remove pages, layer one PDF on top of another, and embed file attachments — all through the fluent PdfEditor API.

Merging Documents

Append a File by Path

The simplest merge: append all pages from another PDF to the end of the current document.

PdfEditor.Open("part1.pdf")
    .MergeFile("part2.pdf")
    .MergeFile("part3.pdf")
    .Save("combined.pdf");

Append and Prepend from Bytes

When you already have PDF data in memory (e.g. from a database or an HTTP response), use AppendDocument or PrependDocument:

byte[] coverPage = await httpClient.GetByteArrayAsync(coverUrl);
byte[] mainContent = File.ReadAllBytes("report.pdf");
byte[] appendix = File.ReadAllBytes("appendix.pdf");

PdfEditor.Open(mainContent)
    .PrependDocument(coverPage)     // cover goes before everything
    .AppendDocument(appendix)       // appendix goes after everything
    .Save("full-report.pdf");

Import Specific Pages

Use ImportPages to insert selected pages from another PDF at a precise position:

byte[] source = File.ReadAllBytes("reference-data.pdf");

PdfEditor.Open("report.pdf")
    .ImportPages(source, pageRange: "3-5", insertIndex: 2)
    .Save("report-with-data.pdf");

Merging Many Files in a Loop

var files = Directory.GetFiles("C:\\Invoices\\2026\\March", "*.pdf")
                     .OrderBy(f => f);

var editor = PdfEditor.Open(files.First());

foreach (var file in files.Skip(1))
    editor.MergeFile(file);

editor
    .SetTitle("March 2026 Invoices")
    .Save("march-invoices-combined.pdf");

Splitting and Page Removal

Delete a Single Page

PdfEditor.Open("report.pdf")
    .DeletePage(0)          // remove the first page (cover sheet)
    .Save("report-no-cover.pdf");

Delete Multiple Pages

DeletePages accepts one or more indices. Internally, pages are removed from highest index to lowest so removals don't shift subsequent indices:

PdfEditor.Open("manual.pdf")
    .DeletePages(0, 1, 15)   // remove pages 1, 2, and 16
    .Save("manual-trimmed.pdf");

Insert a Blank Page

Add an empty page at any position. The default size is A4 (595.28 x 841.89 points):

PdfEditor.Open("report.pdf")
    .AddBlankPage(insertIndex: 0)                         // A4 blank as new first page
    .AddBlankPage(insertIndex: 5, width: 842, height: 595) // landscape blank at position 5
    .Save("report-with-blanks.pdf");

Extract Pages to a New File

Combine ImportPages with a fresh editor to extract a subset into a standalone document:

byte[] source = File.ReadAllBytes("big-manual.pdf");

// Extract pages 10-19 (chapters 3-4) into a new file
PdfEditor.Open(source)
    .DeletePages(Enumerable.Range(20, 80).ToArray())  // remove pages after chapter 4
    .DeletePages(Enumerable.Range(0, 10).ToArray())   // remove pages before chapter 3
    .Save("chapters-3-4.pdf");

Overlays and Underlays

Overlay places a PDF layer on top of existing content (useful for watermarks, stamps, headers). Underlay places a layer behind existing content (useful for backgrounds, letterhead).

Simple Overlay on All Pages

PdfEditor.Open("report.pdf")
    .OverlayFile(new LayerConfiguration
    {
        FilePath = "watermark.pdf"
    })
    .Save("report-watermarked.pdf");

Underlay a Letterhead Background

PdfEditor.Open("letter.pdf")
    .UnderlayFile(new LayerConfiguration
    {
        FilePath = "company-letterhead.pdf"
    })
    .Save("letter-branded.pdf");

LayerConfiguration Properties

Advanced: Overlay with Page Mapping

Apply the first page of a header PDF as a repeating overlay, but only on pages 2 through the end of the document:

PdfEditor.Open("report.pdf")
    .OverlayFile(new LayerConfiguration
    {
        FilePath = "header-footer-template.pdf",
        TargetPages = "2-z",           // skip the title page
        SourcePages = "1",             // use only page 1 of the template
        RepeatSourcePages = "1"        // repeat it for every target page
    })
    .Save("report-with-headers.pdf");

Combining Overlay and Underlay

PdfEditor.Open("report.pdf")
    .UnderlayFile(new LayerConfiguration
    {
        FilePath = "company-background.pdf",
        RepeatSourcePages = "1"
    })
    .OverlayFile(new LayerConfiguration
    {
        FilePath = "confidential-stamp.pdf",
        RepeatSourcePages = "1"
    })
    .Save("report-branded-and-stamped.pdf");

File Attachments

Embed files (XML invoices, spreadsheets, images, source data) inside the PDF. This is required for PDF/A-3 conformance with formats like ZUGFeRD and Factur-X.

Basic Attachment

PdfEditor.Open("invoice.pdf")
    .AddAttachment(new DocumentAttachment
    {
        FilePath = "invoice-data.xml",
        Description = "Machine-readable invoice data"
    })
    .Save("invoice-with-attachment.pdf");

DocumentAttachment Properties

PDF/A-3 Compliant Attachment (ZUGFeRD / Factur-X)

For electronic invoicing standards, you must set the Relationship property. This writes the /AFRelationship entry in the file specification dictionary and adds the file to the document-level /AF array:

PdfEditor.Open("invoice.pdf")
    .AddAttachment(new DocumentAttachment
    {
        FilePath = "factur-x.xml",
        Key = "factur-x.xml",
        MimeType = "application/xml",
        Description = "Factur-X invoice data (EN 16931 MINIMUM profile)",
        Relationship = DocumentAttachmentRelationship.Alternative
    })
    .Save("invoice-facturx.pdf");

DocumentAttachmentRelationship Values

Multiple Attachments

PdfEditor.Open("project-summary.pdf")
    .AddAttachment(new DocumentAttachment
    {
        FilePath = "budget.xlsx",
        Description = "Detailed budget spreadsheet"
    })
    .AddAttachment(new DocumentAttachment
    {
        FilePath = "timeline.png",
        Description = "Project timeline Gantt chart"
    })
    .AddAttachment(new DocumentAttachment
    {
        FilePath = "raw-data.csv",
        MimeType = "text/csv",
        Description = "Source data for all charts"
    })
    .Save("project-summary-complete.pdf");

Complete Example: Merge, Tag, and Attach

A realistic workflow that combines several operations into one chain:

PdfEditor.Open("cover.pdf")
    .MergeFile("chapter1.pdf")
    .MergeFile("chapter2.pdf")
    .MergeFile("appendix.pdf")
    .SetTitle("Product Specification v3.1")
    .SetAuthor("Engineering Team")
    .AddBookmark("Cover", pageIndex: 0)
    .AddBookmark("Chapter 1: Architecture", pageIndex: 1)
    .AddBookmark("Chapter 2: API Reference", pageIndex: 12)
    .AddBookmark("Appendix: Test Results", pageIndex: 28)
    .AddAttachment(new DocumentAttachment
    {
        FilePath = "test-results.json",
        Description = "Raw test result data",
        Relationship = DocumentAttachmentRelationship.Supplement
    })
    .Save("product-spec-v3.1.pdf");

Next Steps

• Metadata & Bookmarks — document properties and navigation
• Stamping & Watermarks — text and image stamps
• Page Manipulation — rotation, page boxes, linearization
• ZUGFeRD & Factur-X — electronic invoicing with PDF/A-3