Adding a custom page to a PDF document

Adding custom pages to PDF documents programmatically enables teams to automate document assembly workflows, build dynamic report generation systems, and implement flexible document packaging solutions. Whether you’re creating automated invoice systems that prepend cover pages with company branding, building legal document processors that insert divider pages between contract sections, implementing educational material generators that add blank pages for student notes, creating medical record systems that append signature pages to patient forms, or building presentation builders that inject title slides at specific positions, programmatic page insertion provides precise control over document structure and page positioning. Page insertion operations include adding pages at specific positions using zero-based indexing, specifying custom page dimensions in points (1 inch = 72 points), supporting both standard sizes (letter, A4, legal) and custom dimensions, inserting pages before or after existing content, and maintaining document integrity during page manipulation.

How Nutrient helps you achieve this

Nutrient Python SDK handles PDF page collection management, page insertion, and document format conversion. With the SDK, you don’t need to worry about:

  • Managing PDF page structure and internal page tree dictionaries
  • Calculating page dimensions and coordinate transformations for different page sizes
  • Handling document format conversion from Word, Excel, and PowerPoint to PDF
  • Complex page indexing and insertion position validation

Instead, Nutrient provides an API that handles all the complexity behind the scenes, enabling you to focus on your business logic.

Complete implementation

Below is a complete working example that demonstrates adding custom pages to PDF documents with specific dimensions at desired positions. The following lines set up the Python application. Start by importing the required classes from the SDK:

from nutrient_sdk import Document
from nutrient_sdk import PdfEditor
from nutrient_sdk import NutrientException

Opening a document

Create the main function and open a source document using a context manager(opens in a new tab) for automatic resource cleanup. The following code defines the main entry point and opens a Word document file using Document.open() with a file path parameter. The context manager pattern (using the with statement) ensures the document is properly closed after processing, releasing memory and file handles, regardless of whether page insertion succeeds or fails. The SDK supports opening documents from various sources, including file paths (shown here) or input streams for in-memory processing, providing flexibility for different integration scenarios. This guide demonstrates converting a Word document (.docx format) to PDF while adding custom pages, but the SDK supports multiple input formats, including PowerPoint presentations (.pptx), Excel spreadsheets (.xlsx), and existing PDF documents:

def main():
    try:
        with Document.open("input.docx") as document:

Creating a PDF editor and accessing pages

Create a PDF editor instance and retrieve the page collection for page manipulation operations. The following code uses the PdfEditor.edit() static method with the document parameter to create an editor bound to the opened document. This editor instance provides access to document modification operations, including page collection management, annotation manipulation, and content editing. The editor.get_page_collection() method retrieves the page collection object representing all pages in the document, enabling page insertion, removal, and reordering operations. The editor maintains the document state throughout the editing session, tracking all modifications until the save() or save_as() method is called to persist changes:

            editor = PdfEditor.edit(document)
            pages = editor.get_page_collection()

Adding custom pages

Add a custom page with specific dimensions at a desired position using the page collection API. The following code calls the pages.insert() method with three parameters: the position index (zero-based, where 0 is before the first page), the width in points, and the height in points (1 inch = 72 points, so 500 points ≈ 6.94 inches). The example inserts a page at index 0, which becomes the first page in the document (position 0 = first page, position 1 = second page, etc.). The dimensions 500.0 × 800.0 points create a custom-sized page approximately 6.94 × 11.11 inches, useful for specialized form layouts or custom stationery sizes. Standard page dimensions include US Letter (612 × 792 points), A4 (595 × 842 points), and Legal (612 × 1008 points):

            pages.insert(0, 500.0, 800.0)

Saving and exporting

Save the editor modifications and export the document as a PDF file. The following code calls editor.save() to persist all page insertion modifications to the document’s internal structure, making the new page part of the document. The editor.close() call releases resources associated with the editor, including memory buffers and temporary data. The document.export_as_pdf() method converts the modified document (originally a Word .docx file in this example) to PDF format and writes it to the specified output file "output.pdf". During export, the SDK renders the Word content with the newly inserted custom page into the PDF format, applying appropriate page dimensions, fonts, and formatting. The context manager automatically closes the document after export_as_pdf() completes, ensuring proper cleanup. The except block catches NutrientException instances for error handling:

            editor.save()
            editor.close()


            document.export_as_pdf("output.pdf")
            print("Successfully added page and exported PDF")
    except NutrientException as e:
        print(f"Error: {e}")


if __name__ == "__main__":
    main()

Error handling

The Python SDK raises NutrientException if document operations fail due to processing errors, invalid file formats, or resource issues. Exception handling ensures robust error recovery in production environments.

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

In production code, wrap the document operations in a try-except block to catch NutrientException instances, providing appropriate error messages to users and logging failure details, including exception messages and stack traces for debugging. This error handling pattern enables graceful degradation when document processing fails, preventing application crashes and enabling retry logic or user notification for manual intervention.

Conclusion

The custom page insertion workflow consists of several key operations:

  1. Open the source document using a context manager(opens in a new tab) for automatic resource cleanup.
  2. The SDK supports opening documents from file paths or input streams for different integration scenarios.
  3. Supported input formats include Word (.docx), PowerPoint (.pptx), Excel (.xlsx), and existing PDF documents.
  4. Create a PDF editor instance with PdfEditor.edit() to enable document manipulation operations.
  5. The editor maintains document state throughout the editing session until changes are saved.
  6. Retrieve the page collection with editor.get_page_collection() to access all document pages.
  7. Insert a custom page with pages.insert() using three parameters: position index (zero-based), width in points, and height in points.
  8. Page dimensions are specified in points where 1 inch = 72 points (e.g. 500 points ≈ 6.94 inches).
  9. Standard page sizes include US Letter (612 × 792 points), A4 (595 × 842 points), and Legal (612 × 1008 points).
  10. Zero-based indexing means index 0 inserts as the first page, index 1 as the second page position.
  11. Save editor modifications with editor.save() to persist page insertions to the document structure.
  12. Close the editor with editor.close() to release resources, including memory buffers and temporary data.
  13. Export the document as PDF with document.export_as_pdf(), which converts the source format with inserted pages.
  14. Handle NutrientException errors for robust error recovery including invalid indices, dimensions, or file format issues.

Nutrient handles PDF page structure management, page tree dictionary manipulation, page dimension calculations, coordinate transformations, document format conversion from multiple source formats, and page indexing validation so you don’t need to understand PDF internal structure or manage complex document rendering pipelines manually. The page insertion system provides precise control for automated invoice cover page generation, legal document divider insertion, educational material assembly with note pages, medical form signature page appending, and presentation title slide injection at specific positions.

You can download this ready-to-use sample package, fully configured to help you explore the page manipulation capabilities.