Highlighting hits in PDF files using annotations

How to display retrieved PDF documents with hits highlighted using annotations.

Remarks

Starting with version 2026.01, dtSearch introduces a new mechanism for displaying search hits in PDF files: adding highlight annotations directly to the PDF. This allows any PDF viewer to display the highlights, as they are embedded in the file itself. This is now the default method used in dtSearch Desktop/Network.

While all PDF viewers will display the highlights, programmatic hit navigation requires a viewer that can be controlled via code. dtSearch and the ASP.NET Core "WebDemo" sample both use the open-source External link PDF.js viewer for this purpose.

Options for Highlighting Hits in PDF Files

dtSearch supports several methods for highlighting search hits in PDF files:

Convert PDF to HTML with highlight markup. Converts the PDF to HTML, wrapping hits with highlight tags. This can be viewed in any browser, but images and most formatting may not be preserved.
Adobe Acrobat Reader plug-in. Displays the PDF in Adobe Acrobat Reader with highlights via a plug-in. This preserves the original appearance but requires both Acrobat Reader and the dtSearch plug-in installed on the user's machine. See Highlighting hits in PDF files using Adobe Acrobat.
PDF annotation (New in 2026). Generates a new PDF with embedded highlight annotations. This preserves the original appearance and works in any PDF viewer, with no special viewing software required.

API: Highlighting Hits with Annotations

To annotate a PDF with hit highlights using the dtSearch Engine API:

1. Convert Word Offsets to PDF Coordinates

Use CalcPdfHitRectsJob to convert search hit word offsets to PDF page coordinates.

2. Generate Highlighted PDF

Pass the resulting coordinates to FileConverter.PdfHitRects along with the input PDF to create a new PDF with highlight annotations.

Example

// Assume searchResults contains the results of a search and // the first document is a PDF file // Select the first search result searchResults.GetNthDoc(0); string fullPdfPath = searchResults.CurrentItem.Filename; // Generate PDF highlight coordinates from the word offsets CalcPdfHitRectsJob calcJob = new CalcPdfHitRectsJob(); calcJob.ResultsItemIndex = 0; calcJob.SearchResults = res; calcJob.InputFile = fullPdfPath; calcJob.Execute(); int[] rectData = calcJob.HitRects; // Use FileConverter to generate a PDF with highlight annotations using (FileConverter fc = new FileConverter()) { fc.SetInputItem(searchResults, 0); fc.InputFile = fullPdfPath; fc.PdfHitRects = rectData; fc.OutputFormat = OutputFormat.itPDF; fc.OutputFile = outputPdfPath; fc.Execute(); }

How Annotations Are Added

The PDF format allows for editing by appending data to the file. To highlight the hits, dtSearch generates a series of PDF annotation objects and appends them to the file. For details, see section 7.5.6 of Adobe's External link PDF specification.

Highlight Appearance

Highlights are yellow by default.

Use FileConverter.BeforeHit to specify a different color using the CSS #RRGGBB format like this: #ffff40. You can also highlight each term with a different color, as described in Highlighting each term using different attributes. In this case the BeforeHit string would contain sequence of color specifications delimited with the first character in the BeforeHit string, like this: "|#ffff40|#ff00ff|#00ffff".

Hit Navigation

Applications can generate highlighted PDFs without handling coordinates directly—just use CalcPdfHitRectsJob and FileConverter as shown above.

For hit navigation, applications need the page and coordinates of each hit, plus page boundaries. Implementation details depend on the PDF viewer.

dtSearch provides sample code for hit navigation with PDF.js in the examples\NetStd\WebDemo sample. The PdfHighlightItemTable class (PdfHighlightItemTable.cs) extracts data from the integer array returned by CalcPdfHitRectsJob and generates JavaScript tables:

HitPageTable: Zero-based page number for each hit
HitRectTable: Location of each hit (left, top, right, bottom) in PDF coordinates
HitPageRectTable: Page rectangle for each page
HitPageRotationTable: Page rotation (0, 90, 180, 270 degrees)

Group

Highlighting Hits