Markdown image not showing? Check these five things
If an image is missing from a Markdown preview, start with the reference and the file it points to.
Here is a simple example:
The exclamation mark identifies an image. The square brackets hold its description. The parentheses hold its destination.
The image file still has to exist somewhere the viewer can reach. The Markdown reference does not store the picture inside the document.
1. Check the syntax
Without the exclamation mark, you have a link:
[Diagram of the review process](images/review-process.png)That may work perfectly as a clickable link while failing to display a picture. Before changing folders or reinstalling anything, check that small character.
Also look for a missing closing bracket or parenthesis. If you copied the reference from somewhere else, make sure you copied the whole thing.
2. Check where the path begins
In a typical local-file workflow, images/review-process.png points into an images folder beside the Markdown file. A publishing tool can use a different base, so check its path rules.
Imagine article.md in a project folder, with a neighboring folder named images containing the picture. Moving the article into another folder can change what its relative path points to.
The reference has not changed. Its starting location has.
Open the file browser and trace the path from the document. If the viewer has its own asset system, follow that tool’s documentation instead of assuming ordinary filesystem behavior.
3. Match the actual filename
Check the extension and capitalization as well as the spelling.
review-process.png is different text from Review-Process.PNG. Some systems treat those names as equivalent; others do not.
For new web assets, a consistent lowercase naming convention removes one source of friction. Something like review-process.png is easy to read and type.
If you rename an existing image, update the documents that reference it. A cleaner filename is only helpful when the links still work.
4. Check access and viewer support
An image can exist and still be unavailable to the destination.
A website generally cannot display a picture that only lives in a private folder on your computer. A remote image address may require a signed-in session or stop working when access expires. The viewer may also restrict the image format or remote content.
Try opening the destination through the same environment that will display the document. A successful local preview tells you about the local setup. It does not prove that a published page has the same access.
If the picture comes from another website, do not assume its address will remain stable. Keep an appropriate local copy when you have permission and your publishing workflow supports it.
5. Bring the related files
When you move or share a document, include the images it references and preserve the relationship between their paths.
A project folder can be a useful unit to transfer. That gives you a place for the Markdown source and its assets. The destination still needs to interpret those paths correctly.
After the move, open the document again. Check the picture, then check any links to neighboring documents. One working image does not prove every attachment traveled.
Change one thing at a time
Work through syntax, path, filename, access, and transfer. Changing all five at once makes it harder to learn what went wrong.
Once the image appears, give the description another look. “Image” is technically a description, but “Diagram showing the three review stages” tells the reader something useful when the picture is unavailable.
Fix the reference, check the destination, and keep the assets with the work. Most missing-image problems become much easier to reason about that way.
Source
- CommonMark specification: images: image syntax and descriptions.
Keep exploring
Read the Markdown images for more examples.