Practical guide

Fix Markdown links and images after document conversion

Converted Markdown often preserves link labels and image references without guaranteeing that their destinations will work in the new repository, CMS, or knowledge base. Resolve relative paths, migrate image assets, write useful alt text, remove unsafe or temporary URLs, and test every important link in the final publishing environment.

Last reviewed July 17, 2026 · Release 2026-07-17-adsense-r9

Who this guide is for

• Editors moving converted Markdown into GitHub, a CMS, or a documentation site
• Developers repairing relative paths after HTML or ZIP conversion
• Knowledge-base teams validating source links and image evidence
• Reviewers checking accessibility and long-term asset ownership

Why do converted links break?

A source document can contain relative paths, bookmarks, application-specific references, temporary signed URLs, local file paths, or redirects that only work in the original environment. The visible label may survive conversion even when the destination does not. Treat every link as a separate publishing dependency.

How should relative and internal links be handled?

Decide the canonical destination structure first. Convert relative paths to repository-relative or absolute URLs that match the target system, update renamed headings and anchors, remove session parameters, and avoid links to local drives or temporary export folders. Test links from the rendered page, not only from the editor.

How should image assets be migrated?

Store images in an owned, durable location; use stable filenames; preserve permission and attribution requirements; and update Markdown paths after the assets move. Large screenshots may need compression, while diagrams may need a text explanation so readers and retrieval systems understand the point without relying on pixels alone.

What makes useful image alt text?

Describe the information or purpose of the image in context, not its decorative appearance. Avoid filenames such as image1.png as alt text. If the surrounding paragraph already explains the image completely and it is decorative, an empty alt attribute may be more appropriate in the final renderer.

Which URL schemes or references should be removed?

Reject javascript:, vbscript:, untrusted data: URLs, temporary blob: URLs, credentials embedded in URLs, expired signed links, and private network paths. Review mailto and tel links for unintended personal information. A converter should not turn an unsafe destination into a trusted link merely because the Markdown syntax is valid.

Before and after example

Converted references

[Runbook](../drafts/runbook.docx)
![image1](file:///Users/name/Desktop/chart.png)
[Open](javascript:alert(1))

Published references

[Runbook](/docs/runbook)

![Monthly incident trend chart](/assets/incident-trend.png)

Unsafe script link removed.

Review checklist after conversion

• Open every high-value link from the final rendered page.
• Resolve relative links and heading anchors against the target site structure.
• Remove local file, temporary, signed, tracking, and unsafe script URLs.
• Move images to an owned durable location and verify permissions.
• Write meaningful alt text and add text explanations for evidence-heavy diagrams.
• Check image size, format, captions, and mobile rendering.
• Run an automated link checker, then manually test authentication-sensitive destinations.

Risk boundary

A working URL is not proof that the destination is safe, authorized, accurate, or permanent. Do not publish private links, credentials, customer portals, local paths, or restricted assets. Keep source attribution and licensing information when moving images or documents.

Frequently asked questions

Why does a relative link work locally but fail after publishing?

Its base path changed. Resolve the link against the final repository, site, or CMS location.

Should every image have alt text?

Informative images need useful alt text. Decorative images may use empty alt text in the final accessible renderer.

Can embedded Word or PDF images be copied automatically?

Sometimes references can be extracted, but asset naming, location, permissions, and captions still need review.

Are data URLs safe to keep?

Large or untrusted data URLs are difficult to audit and may carry unsafe content. Prefer owned files with explicit formats.

How do I test Markdown links?

Render the Markdown in its destination and use an automated link checker plus manual tests for redirects, anchors, and authenticated pages.

Should tracking parameters be preserved?

Usually not for durable documentation. Remove unnecessary tracking parameters unless a documented analytics requirement exists.

Related workflows

These links provide the next format, privacy, or review step for this guide.