---
title: "PDF comparison highlights the entire page"
url: https://recursiveai.org/onediff/articles/pdf-comparison-highlights-entire-page/
description: "A PDF comparison usually highlights the whole page when missing text, a different reading order, or garbled extraction makes the files read differently."
date: 2026-11-18
author: OneDiff team
---

# PDF comparison highlights the entire page

A PDF comparison usually highlights the whole page when missing text, a different reading order, or garbled extraction makes the files read differently.

November 18, 2026 · OneDiff team

OneDiff, a free, open-source .NET library from Recursive AI ([MIT](https://github.com/recursive-ai-oss/onediff-csharp/blob/6443915c4136cc8c5a49fa2543322011665f309e/LICENSE-MIT) or [Apache-2.0](https://github.com/recursive-ai-oss/onediff-csharp/blob/6443915c4136cc8c5a49fa2543322011665f309e/LICENSE-APACHE)), compares text and documents. [OneDiff.Pdf on NuGet](https://www.nuget.org/packages/RecursiveAI.OneDiff.Pdf/1.0.1) · [OneRender.Pdf on NuGet](https://www.nuget.org/packages/RecursiveAI.OneRender.Pdf/1.4.0) · [GitHub](https://github.com/recursive-ai-oss/onediff-csharp) · [Docs](https://recursiveai.org/onediff/docs/)

*Set up the console project*

```
dotnet new console
dotnet add package RecursiveAI.OneDiff.Pdf --version 1.0.1
dotnet add package RecursiveAI.OneRender.Pdf --version 1.4.0
```

`RecursiveAI.OneRender.Pdf` is needed only to generate the synthetic test pair.

To see what changed, put two digital PDFs named `old.pdf` and `new.pdf` beside the project, replace `Program.cs`, and run it with .NET 10. To generate a test pair instead, use the [full example below](#synthetic-pair).

*Program.cs — compare two PDFs · .NET 10*

```
using OneDiff.Documents;
using OneDiff.Documents.Model;
using OneDiff.Pdf;
 
var source = new PdfDocumentSource();
var oldDoc = source.Read(DocumentInput.FromBytes(File.ReadAllBytes("old.pdf"), "old.pdf"));
var newDoc = source.Read(DocumentInput.FromBytes(File.ReadAllBytes("new.pdf"), "new.pdf"));
var diff = Comparison.Of(oldDoc, newDoc);
foreach (var change in diff.Changes)
    Console.WriteLine($"{change.Kind}: [{change.Old.Text}] -> [{change.New.Text}]");
```

*Observed output when only 10.8 changes to 10.9 · Console*

```
Replace: [10.8] -> [10.9]
```

## Find out where the page-wide difference starts

1. Copy the text from each PDF, or run `pdftotext file.pdf -` with Poppler for each file. Empty or garbled output where you see words means the text layer isn’t usable. Empty output can come from a scan or outlined text (letters drawn as shapes). For a supported scan, try the [OCR adapter](https://recursiveai.org/onediff/docs/ocr/) and check the recognized text. **OneDiff error note:** No text anywhere is `NoTextLayer`. No readable page or no content streams (page drawing instructions) can mean `Malformed`. `PdfDocumentSource.Read` throws `InvalidDataException`; [`PdfSourceErrors.FailureOf(error)`](https://github.com/recursive-ai-oss/onediff-csharp/blob/6443915c4136cc8c5a49fa2543322011665f309e/src/OneDiff.Pdf/PdfSourceOptions.cs#L68-L81) reads the reason from the exception’s `Data` property. See the [pinned error and recovery behavior](https://github.com/recursive-ai-oss/onediff-csharp/blob/6443915c4136cc8c5a49fa2543322011665f309e/docs/pdf.md#L87).
2. **Read the extracted text in order.** Check for columns joined across the gutter, repeated headings pulled into the body, or words split at different points. The page can look right while the extractor reads a different sequence. OneDiff uses [reading order and inferred blocks](https://github.com/recursive-ai-oss/onediff-csharp/blob/6443915c4136cc8c5a49fa2543322011665f309e/docs/pdf.md#L5-L24) (groups of lines it reads as paragraphs or other units), not a screenshot. If the sequence is wrong, try a fresh export from the source with selectable text, and check the extraction again. A clean one-column re-export can isolate a column-order problem; it does not recover arbitrary PDFs.
3. **Compare the change list to the visible marks.** If the list already reports large replacements, the viewer is not what made the changes broad. If it lists just one edit, inspect the annotation in another viewer and check whether it is attached to the right text. In OneDiff, the marks are [annotations on the original pages](https://github.com/recursive-ai-oss/onediff-csharp/blob/6443915c4136cc8c5a49fa2543322011665f309e/docs/pdf.md#L56-L75), not changes to page content. One band may merge neighboring word boxes; the whole-token rule marks the full word or number even if only part changed, and whitespace across a line break may anchor to its block. None of those alone explains a whole page of changed paragraphs.

## What one real edit looks like

This local control changes only `10.8` to `10.9`, without changing the page layout. Replace `Program.cs` again and run without arguments to generate the pair and mark the change. OneRender only makes the two synthetic inputs; OneDiff compares and marks them.

*Program.cs · .NET 10*

```
using OneDiff.Documents;
using OneDiff.Documents.Model;
using OneDiff.Pdf;
using OneRender.Pdf;
 
static byte[] MakePdf(string number) => HtmlPdf.ToPdf($"""
    <p>The delivery terms remain unchanged.</p>
    <p>See Exhibit {number} for the full schedule.</p>
    <p>All notices must be in writing.</p>
    """);
 
byte[] oldPdf = args.Length == 2 ? File.ReadAllBytes(args[0]) : MakePdf("10.8");
byte[] newPdf = args.Length == 2 ? File.ReadAllBytes(args[1]) : MakePdf("10.9");
if (args.Length == 0)
{
    File.WriteAllBytes("old.pdf", oldPdf);
    File.WriteAllBytes("new.pdf", newPdf);
}
 
var source = new PdfDocumentSource();
var oldDoc = source.Read(DocumentInput.FromBytes(oldPdf, args.Length == 2 ? args[0] : "old.pdf"));
var newDoc = source.Read(DocumentInput.FromBytes(newPdf, args.Length == 2 ? args[1] : "new.pdf"));
var diff = Comparison.Of(oldDoc, newDoc);
Console.WriteLine($"Verified: {diff.Verification.Passed}");
foreach (var change in diff.Changes)
    Console.WriteLine($"{change.Kind}: [{change.Old.Text}] -> [{change.New.Text}]");
 
using var output = File.Create("marked.pdf");
var result = PdfRedline.OnPages.MarkNewDocument(diff, newPdf, output);
Console.WriteLine($"Marks: {result.Marks.Length}");
foreach (var mark in result.Marks)
    Console.WriteLine(mark.Kind);
```

*Observed output · Console*

```
Verified: True
Replace: [10.8] -> [10.9]
Marks: 1
Highlight
```

Poppler’s `pdftotext` extracted these nonblank lines from the originals, in this order:

*Observed extracted text · Poppler*

```
old.pdf
The delivery terms remain unchanged.
See Exhibit 10.8 for the full schedule.
All notices must be in writing.
new.pdf
The delivery terms remain unchanged.
See Exhibit 10.9 for the full schedule.
All notices must be in writing.
```

Reading the markup back with PyMuPDF found one Highlight on page 1; the text inside its rectangle was `10.9`. Both neighboring paragraphs were outside it. That matches OneDiff’s [whole-token rule](https://github.com/recursive-ai-oss/onediff-csharp/blob/6443915c4136cc8c5a49fa2543322011665f309e/docs/pdf.md#L89-L91): the decimal is one token. `Verified: True` checks the comparison of the extracted documents; it does not certify that the extraction matched everything a human sees on the page.

## What a bad text layer looks like

This is an observed result from a local test. `bad.pdf` was made outside .NET with PyMuPDF: it contains a picture of the unchanged `old.pdf` page with three unrelated lines of invisible, selectable text on top. `pdftotext bad.pdf -` printed the three lines about bananas, boats, and sparrows, not the delivery terms. Comparing those synthetic inputs with the same program gave this result:

*Compare the synthetic pair · Shell*

```
dotnet run -- old.pdf bad.pdf
```

*Observed output · Console*

```
Verified: True
Insert: [] -> [Bananas orbit distant moons.]
Insert: [] -> [Purple boats gather under quiet stars.]
Insert: [] -> [Sparrows count bright pebbles.]
Delete: [The delivery terms remain unchanged.] -> []
Delete: [See Exhibit 10.8 for the full schedule.] -> []
Delete: [All notices must be in writing.] -> []
Marks: 6
Highlight
Highlight
Highlight
Caret
Caret
Caret
```

OneDiff treated the whole extracted page as inserted and deleted text, not as a small edit. The three highlights follow the invisible text, so they don’t reliably match the letters you see. If the new file had no text at all, the digital PDF reader would reject it instead of producing this change list.

## Know when to change what you compare

Use a text comparison for wording. Images, vector graphics, annotations, and form fields are [outside the PDF text model](https://github.com/recursive-ai-oss/onediff-csharp/blob/6443915c4136cc8c5a49fa2543322011665f309e/docs/pdf.md#L27). If your concern is a moved logo, a changed diagram, or other visual content, compare rendered pages instead. If your concern is missing text, go back to the source, get a better export, or review OCR output before trusting a redline.
