Table of Contents Hyperlink Extraction Prompt Template

This prompt is designed for document platform engineers who need to extract and validate interactive Table of Contents (TOC) links from digital PDFs. The primary job-to-be-done is not extracting the static text of a TOC page, but rather parsing the underlying link annotations—the clickable entries that point to internal pages or external URLs. Use this prompt when your pipeline must programmatically verify that every TOC entry resolves to a correct destination, build a navigation map for a document viewer, or detect broken references before a document is served to end users. The ideal user is an engineer who has already used a PDF parsing library like PyMuPDF or pdfplumber to extract raw link annotation data and now needs an LLM to normalize, validate, and structure that data into a consistent schema.

This prompt is not a substitute for a PDF parsing library. It does not read raw PDF bytes or perform OCR on scanned images. It assumes you have already extracted the raw link annotations and their associated display text. Do not use this prompt for static TOC text extraction from documents without interactive links, for generating a TOC from heading text, or for resolving cross-references in the body of a document. Those tasks require different prompt templates, such as the Table of Contents Parsing Prompt Template or the Cross-Reference Resolution Prompt Template. Additionally, this prompt is not designed for documents where the TOC is a scanned image; in that case, you need an OCR-aware processing pipeline before link extraction can occur.

Before integrating this prompt into a production system, confirm that your PDF parsing step reliably extracts both the link rectangle coordinates and the displayed text for each TOC entry. Common failure modes upstream include missing link annotations for entries that appear visually clickable, misaligned bounding boxes that capture adjacent text, and external URLs that are incorrectly parsed as internal page references. If your raw extraction data is noisy, add a pre-processing validation step to filter out entries with empty text or null destinations before sending data to the model. For high-stakes document workflows—such as legal filings or regulatory submissions—always include a human review step for entries flagged as broken or ambiguous by the model's output.

This prompt template is designed to be pasted directly into your AI harness. It instructs the model to process a structured representation of a PDF's Table of Contents, extracting both the displayed text and the underlying hyperlink destination for each entry. The core job is to pair the human-readable label with its machine-actionable target, which is essential for building reliable navigation, validating document structure, and automating link integrity checks in a document platform.

codeCopy
You are an expert document structure analyst. Your task is to process a provided Table of Contents (TOC) data structure from a digital PDF and extract the hyperlink destinations.

**INPUT DATA:**
[TOC_DATA]

**INSTRUCTIONS:**
1.  Parse the [TOC_DATA], which is a JSON array of TOC entries. Each entry has a `title` (the displayed text) and an `action` (the hyperlink's internal destination or an external URL).
2.  For each entry, extract the `title` and the `destination` from the `action` object. The destination could be a page number, a named destination, an external URL, or null if no link is present.
3.  Classify each link as `internal` (points to a page or named destination within the document) or `external` (a URL to an outside resource).
4.  Flag any entry where the `title` text and the destination's target title are mismatched, or where the link is broken or missing.

**OUTPUT_SCHEMA:**
Return a valid JSON object with a single key `toc_links`. The value should be an array of objects, each with the following fields:
- `entry_title`: (string) The displayed text of the TOC entry.
- `link_type`: (string) One of `internal`, `external`, or `none`.
- `destination`: (string or null) The extracted destination value.
- `flags`: (array of strings) A list of issues like `broken_link`, `external_url`, or `title_mismatch`. Empty array if no issues.

**CONSTRAINTS:**
- Do not invent destinations. If the `action` is missing or malformed, set `destination` to `null` and `link_type` to `none`.
- If a link is an external URL, always set the `flags` array to include `external_url`.
- Ensure the output is strictly valid JSON.

To adapt this template, replace the [TOC_DATA] placeholder with the parsed TOC object from your PDF processing library. The prompt's strength lies in its explicit output schema and constraints, which make the output directly usable by downstream validation code. The classification and flagging instructions turn the model into a first-pass data quality filter, catching common issues like external URLs masquerading as internal references before they break your application's navigation logic. After generation, always validate the JSON structure against the defined schema and run a reconciliation script to ensure no entries from the input were dropped in the output.

This prompt is designed to be called once per document after a digital PDF has been parsed to extract its internal link annotations. The implementation harness must supply the model with a structured representation of the TOC page's interactive links—specifically, the displayed text and the raw destination target for each link. Do not pass raw PDF bytes or page images to this prompt; the upstream PDF parser (such as pdfplumber, PyMuPDF, or a cloud document AI service) is responsible for extracting the link annotations and normalizing them into the [TOC_LINK_LIST] input format. The model's job is to reason about mismatches, classify link types, and produce a clean, validated TOC structure—not to perform OCR or layout analysis.

Wire this prompt into your application as a post-extraction validation and normalization step. The typical call flow is: (1) parse the PDF to extract all link annotations on pages identified as the table of contents; (2) assemble each link as a JSON object with display_text and raw_destination fields; (3) pass the array as [TOC_LINK_LIST] to the prompt; (4) validate the model's JSON output against the expected schema before ingestion. Schema validation should check that every entry has a non-empty display_text, a destination_type from the allowed enum (internal_page, external_url, named_destination, broken), and a confidence score between 0 and 1. Reject or quarantine outputs that fail schema validation and retry with a more explicit [CONSTRAINTS] block rather than silently accepting malformed entries.

For production deployments, add a post-processing step that cross-references extracted internal page links against the PDF's actual page count. If a link claims to point to page 47 but the document has only 32 pages, flag it as broken with a resolution_note explaining the mismatch. External URLs should be checked with a HEAD request (where safe and permitted) to distinguish live links from dead references, but avoid blocking the pipeline on network calls—log URL reachability asynchronously and update the TOC metadata later. Log every extraction run with the document identifier, model version, prompt version, and validation pass/fail status so that regressions can be traced to prompt changes or PDF parser updates. For high-stakes document workflows, route entries with confidence below 0.85 or destination_type: broken to a human review queue rather than silently ingesting them into navigation systems.

Model choice matters here. This task requires instruction-following precision and structured output reliability more than creative reasoning. Use a model with strong JSON mode or structured output support (such as GPT-4o with response_format, Claude 3.5 Sonnet with tool-use-shaped output, or Gemini 1.5 Pro with controlled generation). Avoid models that struggle with long-context instruction adherence or that frequently drop fields from structured outputs. Set temperature to 0 or near-zero to minimize variation in link classification. If your PDF parser produces hundreds of TOC links, consider batching the link list into groups of 50–75 entries per call to stay within reliable context windows and reduce the risk of the model truncating or summarizing the output. Each batch should be processed independently and the results merged with a deduplication check on display_text to catch overlaps.

The primary failure mode in production is not the model misclassifying a link type—it is the upstream PDF parser failing to extract link annotations correctly. If the [TOC_LINK_LIST] contains garbled text or missing destinations, the model can flag issues but cannot recover the original data. Build a pre-validation step that checks for empty display_text fields, destinations that are raw byte offsets instead of human-readable targets, and link lists shorter than expected for the document's length. If pre-validation fails, log the document for parser review and do not call the prompt. The second most common failure is the model inventing destinations for broken links rather than marking them as broken. The [CONSTRAINTS] block in the prompt template explicitly forbids fabrication, but you should still add an eval that samples 5% of internal_page destinations and verifies the page number exists in the source PDF. If fabrication is detected, tighten the constraint language or switch to a model with stronger instruction adherence.