How to Fix Same-Document Hyperlinks in Aspose HTML-to-PDF
Repair broken #fragment links in Aspose HTML-to-PDF by adding page-level LocalHyperlink targets after conversion.
Direct answer: If an HTML link such as <a href="#page1"> stops working after Aspose HTML-to-PDF conversion, repair the link in the generated PDF. Create an Aspose.Pdf.LocalHyperlink, set its TargetPageNumber to the destination page, and assign it to the clickable TextFragment.Hyperlink before saving.
This is a page-level workaround documented for Aspose.PDF for .NET. The cited example does not show how to map an HTML id to an exact vertical position inside a PDF page, and the reviewed sources do not establish the current status of historical issue PDFNET-44113.
Why the HTML fragment link fails
In HTML, href="#page1" resolves in the browser against an element such as <div id="page1">. During HTML-to-PDF conversion, the output is a paginated PDF rather than a live DOM. A converter may render the text and layout without creating an equivalent PDF destination for every HTML fragment identifier.
An Aspose support report dated February 1, 2018 described a table of contents whose #page1 link did not navigate to content several pages later. Aspose staff said they reproduced the problem and logged it as PDFNET-44113. That report does not document a current fix or the ticket’s present status.
Choose the correct Aspose product and workflow
| Product | Relevant conversion API | When this guide applies |
|---|---|---|
| Aspose.PDF for .NET | HtmlLoadOptions, Document, Document.Save |
Use the documented LocalHyperlink.TargetPageNumber repair pattern. |
| Aspose.HTML for .NET | Converter.ConvertHTML(), PdfSaveOptions |
Conversion is configured differently; do not assume identical link behavior or APIs. |
Confirm the package and namespace in your project before applying code. The workaround below targets Aspose.PDF for .NET.
Repair a link after conversion
1. Convert the HTML
Load the source HTML with HtmlLoadOptions, create an Aspose.Pdf.Document, and save the PDF. The exact HTML loading options depend on your document and assets.
using Aspose.Pdf;
var loadOptions = new HtmlLoadOptions();
var document = new Document("input.html", loadOptions);
document.Save("converted.pdf");2. Determine the destination page
Inspect the generated PDF and identify the page containing the section represented by id="page1". TargetPageNumber is one-based. If the section begins halfway down a page, the cited API example does not provide an element-coordinate mapping; use the page destination or a lower-level PDF destination technique appropriate to your version.
3. Add a local hyperlink
Create the clickable text and attach a LocalHyperlink that points to the destination page.
using Aspose.Pdf;
using Aspose.Pdf.Text;
var output = new Document();
var page = output.Pages.Add();
var text = new TextFragment("Go to section");
var localLink = new LocalHyperlink
{
TargetPageNumber = 7
};
text.Hyperlink = localLink;
page.Paragraphs.Add(text);
output.Save("linked.pdf");This is the documented page-level pattern: create LocalHyperlink, set TargetPageNumber, and assign it to TextFragment.Hyperlink. Adapt the text, page, and destination values to your converted document.
4. Apply the repair to an existing converted document
When the table of contents already exists, locate or recreate the clickable text on the relevant page, attach the local hyperlink, then save a repaired copy. The exact method for finding an existing text fragment depends on how your PDF was generated and which Aspose APIs your release exposes.
using Aspose.Pdf;
using Aspose.Pdf.Text;
var document = new Document("converted.pdf");
var tocPage = document.Pages[1];
var repairedEntry = new TextFragment("Section 1");
repairedEntry.Hyperlink = new LocalHyperlink
{
TargetPageNumber = 7
};
tocPage.Paragraphs.Add(repairedEntry);
document.Save("converted-with-links.pdf");The sample demonstrates the hyperlink object and page target. It does not claim that adding a new fragment automatically replaces an existing rendered table-of-contents entry; preserve your layout and text placement when integrating it.
Handling exact section destinations
- Page-level navigation is sufficient: Use
LocalHyperlink.TargetPageNumber. - The section starts partway down a page: The cited workaround does not establish an HTML-ID-to-coordinate mapping. Investigate PDF destination or annotation APIs supported by your Aspose.PDF version.
- Pagination changes between documents: Calculate or inspect the destination page for each generated document instead of hard-coding a number globally.
- The target is in another PDF: A local hyperlink is for pages in the same PDF. Use an external link strategy for another file or URL.
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Clicking does nothing | The HTML fragment was rendered without a PDF destination. | Add a LocalHyperlink and set TargetPageNumber after conversion. |
| Link opens the wrong section | Page numbers changed during layout or the target number is wrong. | Inspect the final PDF and use its one-based destination page. |
Compiler cannot find LocalHyperlink |
Wrong product namespace or package. | Confirm you are using Aspose.PDF for .NET and import Aspose.Pdf. |
| Code works in one project but not another | Aspose.PDF and Aspose.HTML expose different conversion workflows. | Match the repair code to the product actually performing conversion. |
| Link jumps to the page but not the heading | The documented property targets a page, not a precise element offset. | Use page-level navigation or investigate coordinate-based destinations for your release. |
| Link disappears after another save | A later processing step regenerated or replaced the PDF. | Apply hyperlink repair after the final conversion and final document edits. |
Validation checklist
- Open the final PDF in the viewer used by your readers.
- Click every repaired table-of-contents entry.
- Confirm the destination page is correct after fonts, images, and page breaks load.
- Test links after any post-processing or merge operation.
- Check both the first-page table of contents and repeated navigation elements.
Performance, reliability, and maintenance
Repairing links after conversion adds a PDF editing step, so perform it once after the document’s layout is final. Hard-coded page numbers are fragile when content changes; regenerate or determine destinations as part of each build. Keep the Aspose product and version explicit in your build configuration because Aspose.PDF and Aspose.HTML are separate APIs, and the reviewed material does not establish identical behavior across releases.
Or skip the browser setup
If your actual requirement is to capture a web page as an image or PDF rather than preserve interactive HTML fragment links, ScreenshotNeo provides a single screenshot API request. Its cleanup step accepts consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. An MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf.
See the ScreenshotNeo API documentation for the available options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
FAQ
Does href="#id" always convert to a PDF link?
No. The reported Aspose.PDF case shows that an HTML fragment link can fail after conversion.
Is PDFNET-44113 fixed?
The reviewed 2018 forum report records reproduction and ticket creation, but does not establish the current status.
Can LocalHyperlink target an HTML element?
The documented property targets a page number. The cited example does not prove element-level positioning.
Should I use Aspose.HTML code with Aspose.PDF?
No. Use the conversion and link APIs for the product in your application.
