Written and tested by the MD Converter editorial team
Why Markdown Links Do Not Open — Syntax and Troubleshooting
Fix Markdown links that render as text, return 404, or fail in HTML and PDF by checking syntax, URLs, relative paths, anchors, and security settings.
Check the basic syntax first
A Markdown link uses [descriptive label](https://example.com). An initial exclamation mark creates an image. Use ASCII brackets and confirm that every delimiter closes.
External links should normally include https://; otherwise a domain may be treated as a relative path. Open the destination directly to rule out a moved or deleted page. Spaces, parentheses, invisible line breaks, and punctuation copied into a URL can also truncate it.
Relative links depend on the current file location and may break when exported HTML is moved. Do not distribute computer-specific file: or drive paths. Heading anchor rules differ among Markdown processors, especially for spaces, symbols, Japanese text, and duplicate headings, so inspect the generated ID.
Test links in the actual saved HTML and PDF. Some PDF workflows do not preserve all external or internal links, and viewers may block local files or unusual protocols. Finally, test private or intranet links with the permissions the recipient will have.
Diagnose the visible symptom
If the literal [label](URL) appears, the content was not parsed as Markdown or its delimiters are malformed. Check for full-width punctuation, missing closing parentheses, accidental code formatting, and a destination that treats the input as plain text.
If the link is clickable but returns 404, open the URL directly and check spelling, capitalization, redirects, and whether a relative path is being resolved from a different directory. A link that works only for its author points to authentication, VPN access, an expiring share token, or repository permissions.
If HTML links work but PDF links do not, test the saved file in another PDF viewer. Some print workflows flatten links, and some viewers warn before opening external or local destinations. Use ordinary HTTPS URLs and avoid unsafe schemes.
Test relative and absolute destinations
Relative links are useful inside a repository because branches and domains can change together. They become fragile when a standalone HTML file or PDF is distributed without the same folder tree. For external delivery, prefer a stable published HTTPS address. Never depend on a file: URL or a drive path from the author's computer.
For page anchors, inspect the generated HTML ID. Slug rules vary for punctuation, case, duplicate headings, and non-Latin text. Rename repeated headings to be specific, then update every anchor after a heading change.
Write useful anchor text
Use a label that describes the destination, such as “Markdown PDF page-break guide,” instead of “click here.” Descriptive labels help readers scan, give screen-reader users context, and make relationships between pages clearer to search engines. Do not reuse the same label for unrelated destinations.
Link preflight checklist
- Confirm ASCII brackets and balanced delimiters.
- Include
https://for external destinations. - Open every URL directly and in a private session.
- Avoid local computer paths and temporary sharing links.
- Verify generated IDs for heading anchors.
- Click links in the saved HTML and PDF.
- Test with recipient-level permissions.
- Use concise, descriptive anchor text.
For documents maintained over time, record when critical links were checked. Reference-style Markdown links can centralize repeated destinations, but verify that the target renderer supports them. Keep essential instructions in the document rather than making the reader depend entirely on a changeable external page.
Frequently asked questions
Why is punctuation included in the URL?
A copied closing parenthesis or period may be interpreted as part of the destination. Use Markdown link syntax with a clean URL instead of relying on automatic link detection.
Can printed readers use the link?
Paper cannot preserve a click target. For print-first material, include a readable short domain or an accessible QR code alongside essential links, and keep the descriptive label in the text.
Why does a heading link stop working after editing?
Changing the heading usually changes its generated ID. Duplicate headings can also receive numbered suffixes. Regenerate the document, inspect the destination ID, and update the source link. For a long document, an automatically generated table of contents reduces manual anchor maintenance.
Should links open in a new tab?
Standard Markdown does not provide a universal new-tab attribute. Let the browser or reader control navigation unless your publishing platform has a clear, accessible policy. A PDF viewer may always open web destinations externally.