Adding a custom page to a PDF document

Use page insertion to control document structure in generated PDFs.

Common use cases include:

• Inserting cover pages for invoices
• Adding divider pages between legal sections
• Appending signature pages to forms
• Inserting note pages into educational documents
• Adding title or section pages in generated reports

This guide shows how to:

• Insert a page at a specific index (zero-based)
• Define custom page dimensions in points (1 inch = 72 points)
• Export the final document as PDF

How Nutrient helps

Nutrient .NET SDK handles page collection management, insertion, and document conversion.

The SDK handles:

• PDF page structure and internal page tree dictionaries
• Page dimensions and coordinate transformations for different page sizes
• Document conversion from Word, Excel, and PowerPoint to PDF
• Page indexing and insertion position validation

Complete implementation

This example inserts a custom page and exports the result to PDF:

using Nutrient;

Opening a document

Open the input document with a using declaration(opens in a new tab) so the runtime disposes resources after processing.

In this sample, you open a Word file (.docx). The SDK also supports:

• PDF files
• Word binary files (.doc)
• PowerPoint files (.pptx) and PowerPoint binary files (.ppt)
• Excel files (.xlsx) and Excel binary files (.xls)
• Input streams

try
{
    using Document document = Document.Open("input.docx");

Creating a PDF editor and accessing pages

Create a PdfEditor and get the page collection.

Use this object to insert, remove, or reorder pages:

    using PdfEditor editor = PdfEditor.Edit(document);
    var pages = editor.PageCollection;

Adding custom pages

Insert a page with pages.Insert(index, width, height).

Parameters:

• index: zero-based insertion point (0 inserts before the first page)
• width: page width in points
• height: page height in points

In this example:

• The page is inserted at the beginning.
• 500.0 × 800.0 points is a custom page size.

Common page sizes:

• US Letter: 612 × 792 points
• A4: 595 × 842 points
• Legal: 612 × 1008 points

    pages.Insert(0, 500.0f, 800.0f);

Saving and exporting

Save the changes, then export the document as PDF:

    editor.Save();
    document.ExportAsPdf("output.pdf");
    Console.WriteLine("Successfully added page and exported PDF");
}
catch (NutrientException e)
{
    Console.Error.WriteLine($"Error: {e.Message}");
    Environment.Exit(1);
}

Error handling

The SDK reports failures through NutrientException.

Common failure scenarios include:

• The input file can’t be read due to file system permissions, path errors, or file locking by another process
• Document data is corrupted or uses an unsupported file format, preventing proper parsing
• Insufficient system memory for loading large documents or performing format conversion
• Invalid page insertion index (negative or beyond document bounds) causing index out of range errors
• Invalid page dimensions (zero or negative width/height values) preventing page creation
• PDF export failures due to incompatible document features or encoding issues

Nutrient .NET SDK handles errors with exception handling. The methods presented in this guide throw a NutrientException if a failure occurs. The using statements release the editor and document even when a step fails.

Conclusion

To add custom pages to a PDF workflow:

1. Open the source document.
2. Create an editor with PdfEditor.Edit(document).
3. Get pages with editor.PageCollection.
4. Insert a page with the insert method.
5. Save the editor.
6. Export the result with document.ExportAsPdf().
7. Handle SDK failures explicitly.

For broader document workflows, refer to the .NET SDK guides for format conversion and advanced editing.