Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsTo keep anchor links working in a DOCX conversion, preserve both sides of each link: the destination bookmark or heading target, and the hyperlink that points to it. Then test links in the converted document—not just the source—after opening, saving, and reopening it in Word. DOCX stores this navigation structure in WordprocessingML, so a conversion that retains visible link text but drops bookmark markup or target names can leave links that look intact but do not work.
What an anchor link means in a DOCX
An anchor link is an internal hyperlink that takes a reader to a location in the same document, commonly a heading or a named bookmark. Word supports links to headings and bookmarks. In a DOCX package, which is a ZIP archive, a bookmark is represented in WordprocessingML by paired w:bookmarkStart and w:bookmarkEnd elements in word/document.xml. An internal hyperlink points to its target by name. External hyperlinks use relationship data, so they should not be confused with internal anchor targets.
The important distinction is between what the reader sees and what makes navigation work. Link text such as “See installation” can survive as ordinary text even if the target bookmark has disappeared. Likewise, a bookmark may remain in the document while the link that should point to it has been lost or renamed. Reliable conversion must preserve the destination and the reference together.
Microsoft’s Open XML example also shows that Word documents can contain a hidden _GoBack bookmark. Its presence is not, by itself, evidence that a conversion has created a broken link; check the names and matching bookmark boundaries relevant to your own links.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstall#1 Best Overall
Choose targets that survive source edits
Use heading targets for ordinary navigation
If a link only needs to reach a section in the same document, a heading target is convenient. Apply actual heading styles rather than merely making a paragraph look like a heading. Word can use heading styles as hyperlink destinations, and headings also support document navigation. A conversion path that understands document structure has a better chance of retaining this relationship than one that flattens everything into unstructured text.
Use named bookmarks for stable destinations
Choose an explicit named bookmark when the destination needs an identifier independent of the visible heading wording—for example, when links are generated automatically or are referenced from multiple places. Give important targets unique names, and keep those names stable when you revise heading text. The name attached to the hyperlink must match the bookmark name in the resulting DOCX.
Microsoft’s hyperlink guidance describes linking to headings or bookmarks, and python-docx documents internal links as jumps to another document location using a bookmark name as the anchor. These are two ways to establish an internal destination; they are not a guarantee that every converter will preserve either one. Validate the generated output.
A conversion workflow that preserves links
- Inventory important links. List the links readers need most: table-of-contents entries, body cross-references, links inside tables, and destinations that are referred to by name. Record the intended target for each one. This gives you a test set rather than relying on a quick visual scan.
- Create stable targets in the source. Use real heading structure for navigation that can follow heading text, and explicit, unique bookmark names where stable identifiers matter. Avoid relying on the appearance of a heading alone to make it a target.
- Use a format-aware conversion path. Choose a converter that writes valid DOCX/OpenXML and can retain document structure. Pandoc’s user guide specifies that DOCX output must be appropriate OpenXML. Where the converter supports a reference DOCX or template, use it to control styles and document formatting; a template does not, by itself, prove that bookmarks survived.
- Keep targets and references paired. Check that the converter carries bookmark names and corresponding bookmark boundaries into the output, and that internal hyperlinks still point to those names. Do not treat preserved link labels as proof of a preserved destination.
- Open and test in Word. Use Word’s bookmark list to inspect named targets. Activate representative links from the table of contents and body, including links placed in tables. Save the output, close it, reopen it, and test again so you are checking the delivered file rather than an unsaved editing state.
- Inspect the package if a link fails. Make a copy of the DOCX, unzip it, and inspect
word/document.xml. Look for the relevant bookmark start and end elements and their names, then find the hyperlink element and check that it targets the intended bookmark. If you are examining external links, inspectword/_rels/document.xml.relsas well; an internal anchor should not have been turned into an accidental external relationship. - Repeat after later processing. If another tool edits, cleans, merges, or post-processes the DOCX, rerun the link checks on that final artifact. Package-level edits can break otherwise sound markup.
Inspect bookmark markup with a small Python check
When Word’s interface does not explain why a link fails, this standard-library script reads the main document XML from a DOCX and reports bookmark IDs, names, and internal hyperlink anchor names. It does not repair the file or prove that Word will navigate correctly; use it to spot missing or mismatched targets, then verify the result in Word.
from collections import Counter
from zipfile import ZipFile
import xml.etree.ElementTree as ET
DOCX = "converted.docx"
NS = {"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"}
W = "{" + NS["w"] + "}"
with ZipFile(DOCX) as docx:
xml = docx.read("word/document.xml")
root = ET.fromstring(xml)
starts = root.findall(".//w:bookmarkStart", NS)
ends = root.findall(".//w:bookmarkEnd", NS)
links = root.findall(".//w:hyperlink", NS)
start_ids = [node.get(W + "id") for node in starts]
end_ids = [node.get(W + "id") for node in ends]
names = [node.get(W + "name") for node in starts if node.get(W + "name")]
anchors = [node.get(W + "anchor") for node in links if node.get(W + "anchor")]
print("Bookmark starts:", len(starts), "bookmark ends:", len(ends))
print("Start IDs without a matching end ID:", sorted(set(start_ids) - set(end_ids)))
print("End IDs without a matching start ID:", sorted(set(end_ids) - set(start_ids)))
print("Duplicate bookmark names:", sorted(name for name, count in Counter(names).items() if count > 1))
print("Internal hyperlink targets with no bookmark name:", sorted(set(anchors) - set(names)))Run it with Python on a copy of the converted file. A target reported as absent deserves investigation, but the output is not a complete conformance validator: documents can include heading-based navigation and other structures, and XML-level presence alone does not establish that every viewer will behave the same way. Also, do not assume every bookmark is user-authored; Word may include hidden bookmarks such as _GoBack.
Or skip the browser setup
ScreenshotNeo is a website screenshot API, not a DOCX converter, and it does not preserve Word bookmarks. If your workflow also needs a page capture, one GET request can return a screenshot; it will not perform or validate the DOCX steps above. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The Free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000 shots. Every feature is on every plan. Learn more at ScreenshotNeo, or sign up for 1,000 free screenshots a month with no card.
Troubleshoot links that did not survive
The link text remains, but clicking does nothing
Check that the intended bookmark or heading target exists in the converted file, and that the hyperlink still refers to it. If the bookmark was dropped or renamed, the visible link label cannot restore its destination. Compare the source target name with the name present in the DOCX.
Word reports an invalid bookmark
Inspect for duplicate bookmark names, a missing matching w:bookmarkEnd, or malformed XML introduced by a converter or a later post-processing step. If the source is sound, generate a fresh DOCX and test it before applying any subsequent document transformations.
Only some links fail
Compare failing links with working ones instead of assuming the whole document is affected. Check whether the failed destinations involve punctuation in heading text, duplicate IDs, bookmarks spanning multiple runs, placement in a table, tracked edits, or proximity to converted fields and generated tables of contents. These are useful edge cases for a converter-specific test set.
Rank #4
Links work in Word but not in another viewer
Different document viewers may not handle Word bookmarks and internal hyperlink anchors identically. Test in the actual application and delivery environment your readers use. If the DOCX is consumed by multiple viewers, include those viewers in acceptance testing rather than treating success in Word as universal compatibility.
Links break after saving, merging, or editing
Compare the file before and after the operation that preceded the failure. Recheck both bookmark boundaries and hyperlink targets in the final package; a later tool may rewrite or remove XML even if the initial conversion was correct. Keep a known-good output so you can identify which processing stage changed the navigation structure.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Make conversion testing repeatable
For a one-off document, manually test representative links in Word and reopen the saved file. For a recurring publishing pipeline, keep a small fixture DOCX or source document containing the cases most likely to expose a failure: a heading with punctuation, a named bookmark, a link in a table, a target spanning several text runs, a link near a generated table of contents, and content with tracked edits. After each converter or post-processing change, regenerate the DOCX and check both its XML and the links in the relevant reader applications.
Choose a conversion path by more than visual similarity. Compare target fidelity (bookmark names, IDs, and destinations), template and style control, automation suitability, access to package XML for inspection or repair, and behavior in the Word versions and other viewers your audience uses. A reference DOCX can help control styling where supported, but actual link tests determine whether navigation survived.
Limits of what can be assumed
There is no preservation-rate statistic established here that can predict how a particular converter handles every document. Link survival depends on the source structure, converter, subsequent editing steps, and reader application. Treat each conversion pipeline as something to validate, especially when internal links are part of a published manual, generated report, or regulated document. A successful visual conversion is not a substitute for navigation testing.
Frequently Asked Questions
Does a DOCX need a separate relationship file entry for an internal bookmark link?
Internal anchor targets and external hyperlink relationships are different cases. Inspect the actual hyperlink markup and target rather than assuming every hyperlink belongs in the relationships file.
Can bookmark checks alone guarantee every reader will navigate correctly?
No. Structural checks can reveal missing names or unmatched bookmark boundaries, but the target application must still be tested because viewer behavior can differ.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
