A broken Markdown image is usually not a Markdown rendering problem. It is a resource-location problem: the renderer understands the image syntax but cannot retrieve the referenced file.
Open the document in the Markdown viewer and use this checklist to isolate the cause.
Confirm the syntax
Do not omit the exclamation mark, closing bracket, or parentheses. Alt text should describe the information in the image so the document remains meaningful if loading fails.
Test the image address directly
Copy an absolute image URL into a browser tab. If it does not load there, the Markdown renderer cannot load it either. Check for a removed file, expired token, login requirement, or access restriction.
Understand relative paths
./images/demo.png means “find this file relative to the current document.” GitHub and local editors know the repository structure. A standalone online viewer normally receives only the Markdown file, so the adjacent image is absent.
For a portable document, replace the relative path with a reachable absolute URL. For private material, consider whether hosting the image externally is acceptable before changing the source.
Check casing and encoded characters
Verify uppercase and lowercase letters, spaces, parentheses, and special characters in filenames. Renaming Product Screenshot (1).png to a simpler filename such as product-screenshot.png reduces escaping and deployment problems.
Fix images before conversion
Do not generate a PDF or Word document until every important image appears in the preview. Export tools capture the resolved document; they cannot restore an asset the browser could not access.
After correcting the references, return to Markdown to PDF or Markdown to HTML and verify the output again.
Key takeaways
- Verify Markdown image syntax and filename casing
- Distinguish relative-path problems from network problems
- Use a browser preview to confirm the fix
Try the main MD Opener workflow
If this guide matches what you were searching for, the fastest next step is to use the MD Opener homepage to open your file immediately. The homepage is built for instant Markdown previews, clear formatting, and a low-friction browser experience.
You can also continue through the Beginner Guides cluster to explore more articles with similar search intent.
Frequently asked questions
Why does a Markdown image work on GitHub but not in an online viewer?
GitHub resolves relative paths against the repository. A standalone viewer receives only the Markdown file and may not have access to nearby assets.
Are image filenames case-sensitive?
They can be. A reference to `Diagram.png` may fail when the actual file is named `diagram.png`, especially after deployment to a case-sensitive server.
What image syntax should I use?
Use `` and ensure that the URL or path is valid in the environment where the Markdown will be rendered.