Adding link annotations to a PDF document

Adding link annotations to PDFs programmatically enables teams to automate document navigation, build interactive table of contents systems, and implement cross-referencing workflows. Whether you’re creating navigable documentation, building multipage reports with internal links, implementing automated bookmarking systems, or creating user guides with jump-to-section functionality, link annotations provide precise control over clickable areas and navigation targets. Link annotations can point to specific pages within a document at exact coordinates, enabling fine-grained navigation control for complex documents.

How Nutrient helps you achieve this

Nutrient Python SDK handles PDF link annotation structures and destination management. With the SDK, you don’t need to worry about:

  • Parsing link annotation dictionaries and action structures
  • Managing destination arrays and coordinate transformations
  • Handling named destinations and action chains
  • Complex annotation border styles and appearance properties

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

Complete implementation

Below is a complete working example that demonstrates adding internal link annotations to a PDF. The following lines set up the Python application. The import statements bring in all necessary classes from the Nutrient SDK:

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

The main() function defines the entry point that will contain the link annotation creation logic. The Document.open() call opens the PDF document. The context manager(opens in a new tab) syntax ensures the document is automatically closed when you’re done, preventing resource leaks. The following code creates a PDF editor, accesses the page collection, ensures at least one page exists by adding a letter-size page (612×792 points) if the document is empty, and retrieves the annotation collection from the first page:

def main():
    try:
        with Document.open("input.pdf") as document:
            editor = PdfEditor.edit(document)
            pages = editor.get_page_collection()


            if pages.get_count() == 0:
                pages.add(612.0, 792.0)


            page = pages.get_first()
            annotations = page.get_annotation_collection()

Adding a link to another page

The following code adds a new page to the document and creates a link annotation at coordinates (50, 600) with dimensions of 200×20 points. The add_link() method creates a clickable rectangular area on the first page. The set_destination() method configures the link’s navigation target with three parameters: the destination page number (2, zero-indexed), the x-coordinate on the destination page (0.0, left edge), and the y-coordinate (792.0, top of page in points). When users click the link area, their PDF viewer will navigate to page 2 and scroll to the top-left corner:

            pages.add(612.0, 792.0)


            page_link = annotations.add_link(
                50.0, 600.0, 200.0, 20.0  # x, y, width, height
            )
            page_link.set_destination(2, 0.0, 792.0)

The following code demonstrates creating a table of contents navigation system with three clickable links. First, two additional pages are added to the document to provide navigation targets. Then three link annotations are created at vertically stacked positions (550, 520, 490 on the y-axis), each with dimensions 150×20 points. Each link is configured with set_destination() to navigate to a different page (2, 3, and 4 respectively), all targeting the top-left corner (0, 792). The 30-point vertical spacing between links accommodates typical text line heights for labels like “Chapter 1,” “Chapter 2,” etc. This pattern is commonly used for interactive table of contents or navigation menus in multipage documents:

            pages.add(612.0, 792.0)
            pages.add(612.0, 792.0)


            link1 = annotations.add_link(
                50.0, 550.0, 150.0, 20.0  # x, y, width, height
            )
            link1.set_destination(2, 0.0, 792.0)


            link2 = annotations.add_link(
                50.0, 520.0, 150.0, 20.0  # x, y, width, height
            )
            link2.set_destination(3, 0.0, 792.0)


            link3 = annotations.add_link(
                50.0, 490.0, 150.0, 20.0  # x, y, width, height
            )
            link3.set_destination(4, 0.0, 792.0)

Existing link annotations can be reconfigured by calling set_destination() with new parameters. The following code demonstrates two modification patterns. The first call changes link3 to navigate to page 2 at coordinates (100, 500), providing precise scroll positioning for fine-grained navigation control. The second call changes link2 to navigate to page 4 while passing None for the x and y coordinates, which instructs the PDF viewer to use its default scroll behavior (typically fitting the page to the window). Using None coordinates is useful when the exact viewing position is less important than reaching the destination page:

            # Change link3 to point to page 2 with specific coordinates
            link3.set_destination(2, 100.0, 500.0)


            # Change link2 to point to page 4, letting the viewer choose scroll position
            link2.set_destination(4, None, None)

The final code block saves the document with all link annotations and closes the editor. The try-except block handles potential errors using NutrientException:

            editor.save_as("output.pdf")
            editor.close()
    except NutrientException as e:
        print(f"Error: {e}")


if __name__ == "__main__":
    main()

Conclusion

The link annotation workflow consists of several key operations:

  1. Open the document and create an editor.
  2. Access the page collection and ensure at least one page exists.
  3. Retrieve the annotation collection for the target page.
  4. Add pages to the document to create navigation targets.
  5. Create link annotations with add_link() specifying clickable rectangular areas.
  6. Configure link destinations with set_destination() specifying page number and coordinates.
  7. Create multiple links for table of contents navigation with vertically stacked positioning.
  8. Modify existing link destinations by calling set_destination() with new parameters.
  9. Use None coordinates to let the PDF viewer determine scroll positioning automatically.
  10. Save and close the editor.

Nutrient handles link annotation dictionary structures, destination array formatting, and coordinate transformation calculations so you don’t need to understand PDF link annotation specifications or manage action chains manually. The link annotation system provides precise control over clickable areas and navigation targets, enabling interactive document navigation for reports, manuals, and multipage documentation.