How Local Markdown Files Handle Images and Relative Links

A Markdown document can look complete on one computer and lose every image or link when it is opened somewhere else. The Markdown is usually valid. The problem is that local images and relative links depend on the file's location.

Consider a small documentation folder:

project/
├── README.md
├── images/
│   └── architecture.png
└── guides/
    └── setup.md

Inside README.md, this image uses a relative path:

![System architecture](images/architecture.png)

The path does not identify an image by itself. It means “start in the folder containing this Markdown file, then open images/architecture.png.” Move README.md, upload it without the images folder, or publish it at a new web address, and that relationship changes.

Relative Paths Are Resolved From a Base Location

Markdown renderers eventually turn links and images into HTML. A browser then resolves each relative URL against a base location. What counts as the base depends on where the document is being rendered:

Where Markdown is rendered	Likely base for relative paths
GitHub repository	The file's directory in the repository
Local editor	The Markdown file's folder
Website	The URL of the rendered page
Standalone online viewer	The viewer's page URL, unless it imports related assets

That is why the same images/architecture.png reference can work on GitHub and fail in an online preview. GitHub knows the repository tree. A viewer given only one .md file does not automatically receive its sibling folders.

Opening a local file also does not grant a website access to the rest of your disk. Browsers deliberately restrict that access. Selecting README.md therefore cannot be assumed to select images/architecture.png as well.

./, ../, and Root-Relative Links

These three links point to different places:

[Setup guide](./guides/setup.md)
[Parent documentation](../docs/index.md)
[Website documentation](/docs/index.html)

• ./guides/setup.md starts beside the current Markdown file.
• ../docs/index.md moves up one directory before entering docs.
• /docs/index.html starts at the root of the current website, not at the computer's filesystem root.

The leading slash is especially easy to misunderstand. On https://example.com/projects/readme, /docs/index.html becomes https://example.com/docs/index.html. It does not refer to a local /docs folder.

Anchor-only links are different:

[Jump to installation](#installation)

They stay on the current rendered page and usually travel well, provided the destination heading generates the expected ID.

Why Local Images Disappear After Sharing

Suppose a document contains:

![Deployment diagram](./assets/deployment.png)

If you share only the Markdown text, the recipient gets the reference but not deployment.png. Publishing the Markdown at a URL may also make the browser request something like /s/assets/deployment.png, where no image exists.

There are three reliable solutions:

1. Use an absolute HTTPS image URL. Host the image somewhere accessible and reference its full address.
2. Publish the complete folder through a repository or documentation site. Preserve the relative directory structure.
3. Replace the image with portable source when appropriate. For architecture and flow diagrams, a fenced Mermaid block keeps the diagram inside the Markdown document.

For private documents, do not move an image to a public host merely to make the preview work. Choose storage whose access rules match the document's audience, and confirm the image is still accessible in a signed-out or recipient-equivalent browser session.

A Portable Image Example

An absolute URL does not depend on the Markdown file's folder:

![System architecture](https://docs.example.com/assets/architecture.png)

This is more portable, but it introduces an external dependency. If the image is renamed, deleted, access-controlled, or blocked from hotlinking, it will still fail. Stable asset URLs and meaningful alt text make the document more resilient.

Avoid file:///... paths. They expose machine-specific locations, do not work for other readers, and are commonly blocked when referenced from a web page.

How to Test a Markdown File Before Sharing

Use a short portability check:

1. Preview the file where it was written and verify every image.
2. Search the source for ]( and ![ to find links and images.
3. Identify references beginning with ./, ../, /, or file:.
4. Open the final shared page—not only the local preview.
5. Test important links and inspect broken images in a private browser window.
6. Confirm that private assets are neither inaccessible to intended readers nor accidentally public.

You can paste or open the Markdown at mdview.io to inspect the rendered document. If a local image is missing, check the path before changing the Markdown syntax: the renderer may have the document but not the separate image file it references.

The Rule to Remember

A relative link is a relationship, not a complete address. It works only while the Markdown file, its base location, and the linked asset keep the expected structure. For a self-contained shared document, use stable web URLs or embedded diagram source. For a repository, preserve the folder tree and test the README in repository context before publishing.