ScreenshotNeo
Sign in Get a free key

BlogHTML to image & PDF

How to Preserve Relative Links in DOCX and PDF Documents

Learn how to keep web, internal, and relative file links working when you create DOCX files, export PDFs, move folders, and assemble documents.

By the ScreenshotNeo team1 October 202610 min read

Short answer: create and verify every hyperlink in the DOCX, keep linked files in a deliberate folder structure, export through a converter with documented link-preservation settings, and test the final PDF after it is moved into its delivery folder. A PDF can contain a visible link annotation while its relative file destination still fails in a particular viewer or after relocation.

There is no universal rule that guarantees a relative file link created in Word will resolve identically in every DOCX version, PDF converter, operating system, or PDF reader. Treat link preservation as a workflow you verify, not as a single export checkbox.

A relative link omits part of a path and relies on a base location to fill in the missing part. For example, a PDF in project/docs/guide.pdf might link to ../assets/schema.pdf. The link only works if the reader resolves that path from the expected base location and permits opening local files.

Microsoft describes relative URLs in the context of a containing location. Its support material also documents relative file-link defaults for Excel workbooks; that Excel behavior should not be presented as a guarantee for Word DOCX files. The exact storage and resolution rules for relative file hyperlinks in DOCX are not settled by the sources available for this guide.

Separate these link classes because export behavior can differ:

Link type Example What to verify
External web link https://example.com/docs It remains clickable and opens the intended URL.
Internal destination Bookmark, heading, table-of-contents entry The destination survives export and points to the correct page or section.
Relative file link ../assets/schema.pdf The PDF and target file remain in the intended folder relationship and the reader allows local-file access.

1. Design the folder layout first

Decide where the DOCX, exported PDF, and linked files will live when readers receive them. A simple package might look like this:

release/
  docs/
    guide.docx
    guide.pdf
  assets/
    schema.pdf
    diagrams/
      architecture.pdf

If the PDF is in release/docs/ and the target is release/assets/schema.pdf, the intended relative path is ../assets/schema.pdf. Do not move files casually after authoring; relocation changes the base relationship.

  1. Open the DOCX and list every external, internal, and file hyperlink.
  2. Use Word’s Edit Hyperlink command to inspect the destination, not only the visible link text. Word lets you edit the displayed text independently from its destination.
  3. Use descriptive visible text such as Download the schema instead of exposing an ambiguous path.
  4. For internal links, confirm that the bookmark or heading still exists and has not been renamed.
  5. For file links, compare the stored destination with the folder layout you plan to deliver.

Word supports links to web pages, files, and locations in the current document. The available documentation does not establish one universal rule for how Word stores every relative file path in a DOCX, so record the arrangement you actually use and verify the exported artifact.

Conversion settings are route-specific. Choose one whose documentation covers hyperlinks and then review its options:

Route Relevant behavior Use carefully
Adobe Acrobat PDFMaker for Word PDFMaker documents an Add Links option and link recognition for hyperlinks, internal document links, and tables of contents. Confirm that Add Links and recognition options are enabled for the profile you use.
LibreOffice Writer export The Writer Guide documents an option to export defined relative links into PDF. Enable the relative-link export option and test the resulting PDF in the target reader.
Microsoft Office PDF export Microsoft documents PDF export but warns that hyperlinks may not convert correctly with Best for printing. Do not assume that print-oriented output preserves all hyperlinks.
Adobe Experience Manager PDF Generator with PageOverlay Adobe documents a specific case where hyperlinks disappear unless forms and annotations are embedded. For that configuration, set embedFormsAndAnnots to true.

These are documented behaviors for named products and routes, not guarantees for every converter or later processing step. Microsoft also explains that PDF is a fixed format that stores page content but does not necessarily preserve all relationships among those objects.

4. Inspect the generated PDF

  1. Open the PDF in the reader your audience will use.
  2. Click at least one representative external link, internal link, and file link.
  3. Move the PDF and its linked files together into the intended delivery folder arrangement.
  4. Repeat the checks on the target operating system and reader.
  5. If the PDF is optimized, merged, overlaid, signed, or otherwise assembled after export, test the final assembled file again.

A link annotation being present proves only that the PDF contains a clickable object. It does not prove that a relative file destination resolves after relocation or that security settings allow the target to open.

A DOCX is a ZIP package. The following Python script lists external hyperlink relationships from the document XML and flags links that are not external relationships. It does not claim to resolve Word’s relative file semantics; it gives you an auditable inventory before conversion.

#!/usr/bin/env python3
from pathlib import Path
from zipfile import ZipFile
import xml.etree.ElementTree as ET

NS = {
    "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
    "r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
    "pr": "http://schemas.openxmlformats.org/package/2006/relationships",
}

def inspect_docx(path: str) -> None:
    with ZipFile(path) as docx:
        document = ET.fromstring(docx.read("word/document.xml"))
        rels = ET.fromstring(docx.read("word/_rels/document.xml.rels"))
        targets = {
            rel.attrib["Id"]: (rel.attrib.get("Target", ""), rel.attrib.get("TargetMode", ""))
            for rel in rels.findall("pr:Relationship", NS)
        }
        count = 0
        for hyperlink in document.findall(".//w:hyperlink", NS):
            rel_id = hyperlink.attrib.get(f"{{{NS['r']}}}id")
            text = "".join(node.text or "" for node in hyperlink.findall(".//w:t", NS))
            target, mode = targets.get(rel_id, ("", ""))
            count += 1
            print(f"{count}. text={text!r} relationship={rel_id!r} target={target!r} mode={mode!r}")
            if not target:
                print("   Check this hyperlink: it may be an internal destination or an unresolved relationship.")

if __name__ == "__main__":
    inspect_docx("guide.docx")

Run it with python inspect_docx_links.py. Keep the output with the release notes so a later conversion or move can be compared with the source inventory.

Inspect PDF annotations with Python

Install the dependency with python -m pip install pypdf, then run:

from pathlib import Path
from pypdf import PdfReader

reader = PdfReader("guide.pdf")
for page_number, page in enumerate(reader.pages, start=1):
    for annotation in page.get("/Annots", []):
        obj = annotation.get_object()
        if obj.get("/Subtype") != "/Link":
            continue
        action = obj.get("/A")
        destination = None
        if action:
            destination = action.get("/URI") or action.get("/F")
        print({"page": page_number, "destination": str(destination)})

This identifies link annotations and their URI or file action when the reader exposes them. It still cannot prove that a specific viewer will permit a local file action.

Use a delivery package that preserves the relationship used during authoring:

package/
  guide.pdf
  assets/
    schema.pdf

If the PDF was authored with assets/schema.pdf as its base-relative destination, keep assets/ beside the PDF. If you rename the directory, upload only the PDF, or move the target to a different depth, the destination can no longer resolve.

Security controls also matter. Some readers warn about or block local-file links, especially when a PDF came from the internet or an email attachment. A failure in one reader does not prove that the PDF lacks an annotation; inspect the PDF and test the intended reader.

Common failures and fixes

Symptom Likely cause Fix
Visible text is correct but opens the wrong page The display text was edited without updating the destination. Use Edit Hyperlink in Word and verify the target directly.
External links vanish after export The selected converter profile did not add or recognize links. Enable the route’s link option, such as PDFMaker Add Links, then export again.
Links fail only with Microsoft’s print-oriented export Microsoft warns that Best for printing may not convert hyperlinks correctly. Use a link-aware export route and inspect the output.
Internal links point to the wrong place Bookmarks or headings changed between authoring and export. Rebuild or update the table of contents and internal destinations before conversion.
Relative file link works beside the author’s files but not after delivery The PDF or target file moved, changing the base relationship. Deliver the original folder structure and test from that location.
File link is present but blocked The PDF reader or operating system security policy blocks local-file actions. Test in the intended reader, document the requirement, or use a web URL when local linking is not acceptable.
Links disappear after a merge or overlay step A downstream assembler dropped annotations. Inspect the final artifact. In the documented AEM PDF Generator/PageOverlay case, set embedFormsAndAnnots to true.
LibreOffice PDF has no relative file links The relative-link export option was disabled or the source links were not defined as expected. Enable the Writer option for exporting defined relative links, then repeat the folder-based test.

Performance, reliability, and cost considerations

  • Conversion time: Link inspection and annotation checks add little compared with rendering, but exporting repeatedly after every edit can be expensive in automated pipelines. Validate a representative sample during development and the complete link inventory for release builds.
  • Reliability: The most reliable process is deterministic: fixed folder layout, one documented converter profile, a saved source inventory, and tests against the final PDF after every downstream transformation.
  • Portability: Web links are generally easier to move than local file links because they do not depend on a neighboring folder. Relative file links are appropriate when you control the whole package and reader environment.
  • Accessibility: Check that link text is descriptive and that bookmarks and headings survive export. Microsoft documents accessible PDFs with hyperlinks and bookmarks; accessibility should be checked on the final PDF, not inferred from the DOCX.
  • Cost: If a hosted conversion or capture service is used, account for conversion requests, retries, and downstream validation. Keep failed artifacts and logs so a broken link can be traced to authoring, export, or assembly.

Or skip the browser setup

If your workflow also needs screenshots of the source pages, ScreenshotNeo provides a single GET request for a PNG, JPEG, WebP, or PDF. Its capture flow accepts cookie and consent banners before removing more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result.

See the ScreenshotNeo API documentation for all options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://screenshotneo.com/docs/ -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://screenshotneo.com/docs/"}, timeout=90)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://screenshotneo.com/docs/' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo also offers full-page capture, element capture, custom CSS and JavaScript, waits, resource blocking, cookies and headers, PDF options, caching, signed links, asynchronous jobs, bulk capture, a usage API, and an MCP server for AI agents. One thousand screenshots per month are free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

Release checklist

  • Every link is classified as external, internal, or file-based.
  • Visible text and destinations were checked separately.
  • The DOCX and linked files use a deliberate folder arrangement.
  • The chosen converter’s link settings are documented and enabled.
  • The PDF was checked for annotations, destinations, bookmarks, and headings.
  • The PDF and linked files were moved into the intended delivery layout.
  • The final PDF was opened in the target reader and operating system.
  • Any merge, overlay, optimization, or signing step was followed by another link check.

FAQ

No. The available documentation does not establish consistent relative-file resolution or security behavior across viewers. Test the final package in the reader your audience will use.

No. Absolute local paths usually break on another computer. Use relative paths when you deliver a controlled folder package; use web URLs when the target should be reachable independently.

The export route may not have added or recognized the link, or a later assembly step may have discarded annotations. Inspect converter settings and the final PDF.

It can if the reader resolves the destination from the PDF’s location and your move also changes the relationship between the PDF and target. Re-test after renaming or moving.

A screenshot is an image and does not carry the clickable link relationships of a DOCX or PDF. Use a PDF export for navigable documents, and use screenshots only as visual evidence or previews.

Sources: Microsoft Support documentation on Word hyperlinks, PDF export, accessibility, and the “Best for printing” warning; Adobe documentation for Acrobat PDFMaker link recognition and Add Links; LibreOffice Writer Guide documentation for exporting defined relative links; and Adobe Experience League’s documented AEM PDF Generator/PageOverlay annotation case.

Keep reading

7 min read

How to Make PDF Hyperlinks

Learn how to add clickable web, file, email, and internal page links to existing PDFs or create them before export from Word or LibreOffice.