Outline and links

Add bookmarks and links

The outline (the bookmarks readers show beside the pages) is a tree of items, each with a title and a destination. A link is a rectangle of a page that goes to a destination or opens a web address:

var document = new PdfDocument();
var cover = document.Pages.Add(PdfSize.A4);
var content = document.Pages.Add(PdfSize.A4);

var chapter = document.Outlines.Add("Chapter 1", PdfDestination.Fit(content));
chapter.Children.Add("Section 1.1", PdfDestination.Xyz(content, left: 0, top: 500));

cover.Annotations.AddLink(new PdfRectangle(50, 50, 250, 80), PdfDestination.Fit(content));
cover.Annotations.AddLink(new PdfRectangle(50, 100, 250, 130), new Uri("https://www.meziantou.net"));

• Outlines.Add adds an item at the top level, and Children.Add an item under another one.
• Annotations.AddLink adds a link to a page: the rectangle is the area that can be clicked, in the coordinates of the page. A link is invisible: draw what it is on, such as an underlined text, with the content builder.

Destinations

A destination is a page and how it is shown:

A coordinate or a zoom left null keeps the current one of the reader. PDF/UA-2 requires destinations that also name the structure element they show: see WithStructureElement in Tagged PDF and PDF/UA.

Style the outline

var summary = document.Outlines.Add("Summary", PdfDestination.FitHorizontally(page, top: 800));
summary.IsBold = true;
summary.Color = PdfColor.FromRgb(0.6, 0, 0); // an RGB color
summary.IsOpen = true; // its children are shown when the document is opened
summary.Children.Add("Key figures", PdfDestination.Xyz(page, left: 0, top: 600, zoom: 1.5));

// The outline is a list: items can be inserted, moved and removed
document.Outlines.Insert(0, new PdfOutlineItem("Cover", PdfDestination.Fit(page)) { IsItalic = true });

• IsBold, IsItalic and Color (an RGB color, null for black) style the title.
• IsOpen shows the children of the item when the document is opened.
• Outlines and Children are lists: Insert, Remove, RemoveAt, Clear and the indexer change them. An item is in one list at most, once: adding an item that is already in a list, or to its own descendants, throws InvalidOperationException. Remove it first to move it.
• Setting the destination of an item or a link read from a file replaces its action, whatever its kind: an item has a destination or an action, not both.
• A link to a web address is written in ASCII: an internationalized host in its xn-- form, the other non-ASCII characters percent-encoded.

Read the bookmarks and links

var document = PdfDocument.Open(file);

// The outline: a tree of items, each with its title and destination
var bookmarks = new List<string>();
foreach (var item in document.Outlines)
{
    bookmarks.Add(item.Title);
    bookmarks.AddRange(item.Children.Select(child => "  " + child.Title));
}

// The links of a page: a web address or a destination in the document
var targets = new List<string>();
foreach (var link in document.Pages[0].Annotations.OfType<PdfLinkAnnotation>())
{
    if (link.Uri is not null)
    {
        targets.Add(link.Uri.AbsoluteUri);
    }
    else if (link.Destination is not null)
    {
        targets.Add("page " + (document.Pages.IndexOf(link.Destination.Page) + 1));
    }
}

• The Destination of an item is null when it has none, or when it has an action of another kind; the other entries of an item read from a file, such as its action, are kept when the document is saved.
• The Uri of a link is null when the link opens no web address or when its address is not a valid URI; its Destination is set when it goes to a page of the document.
• PdfPage.Annotations holds every annotation of the page: links (PdfLinkAnnotation), file attachments (PdfFileAttachmentAnnotation), and the other kinds as PdfAnnotation, with their Subtype, Rectangle, Contents and Dictionary. Remove removes one.