Markdown files and assets
How to Keep Images Working in Markdown
By KenRich ยท Last updated: September 19, 2026
Markdown image syntax is simple. File paths are where most problems begin. This guide shows how to arrange a document and its images so they still work after you rename a folder, move a project, or send it to someone else.
Why a Markdown image works on one computer and breaks on another
An image in Markdown is a link to a file. The image bytes are usually not stored inside the Markdown document. If the file moves or the path points to a folder that only exists on your computer, the editor has nothing to display.
This often goes unnoticed while the document stays in its original folder. The problem appears later, after the Markdown file is emailed by itself, copied into a repository, or opened on another operating system.
The alt text describes the image. The path tells the editor where to find the file.
The alt text describes the image. The path tells the editor where to find the file.
NoteKeep the image path under version control or in the same backup as the Markdown file.
Use a relative path for documents that need to travel
A relative path starts from the Markdown file's folder. If `report.md` and an `assets` folder move together, `assets/chart.png` still points to the same image.
An absolute path starts from a drive or a user directory, such as `C:\Users\Mina\Pictures\chart.png` or `/home/mina/Pictures/chart.png`. That path is tied to one machine and usually breaks when someone else opens the document.
| Path | Example | Portable? |
| --- | --- | --- |
| Relative | `assets/chart.png` | Yes, when the folder moves with the document |
| Parent folder | `../shared/logo.png` | Only when the surrounding folders stay together |
| Absolute | `C:\Users\Mina\Pictures\chart.png` | No || Path | Example | Portable? |
|---|---|---|
| Relative | assets/chart.png |
Yes, when the folder moves with the document |
| Parent folder | ../shared/logo.png |
Only when the surrounding folders stay together |
| Absolute | C:\Users\Mina\Pictures\chart.png |
No |
NoteA short relative path is usually the safest choice for a project document.
Keep an assets folder beside the document
A small folder convention prevents most path mistakes. Put the Markdown file at the project root and store its screenshots, diagrams, and photos in a nearby `assets` folder.
For a single article, one assets folder is enough. For a larger documentation set, use a clear subfolder for each guide. Avoid deep paths unless the project already has a stable structure.
```text
release-notes/
|-- release-notes.md
`-- assets/
|-- install-window.png
`-- update-dialog.png
```
release-notes/
|-- release-notes.md
`-- assets/
|-- install-window.png
`-- update-dialog.png
NoteCopy or archive the outer folder, not the Markdown file alone.
Choose file names that survive small changes
Use names that describe the image rather than the moment when you captured it. `settings-pdf-export.png` is easier to maintain than `Screenshot 2026-09-19 143812.png`.
Lowercase names with hyphens avoid quoting and case-sensitivity surprises. Linux treats `Diagram.png` and `diagram.png` as different files. A path that works on Windows may therefore fail after a project moves to Linux.
```text
Good: assets/settings-pdf-export.png
Good: assets/relative-path-example.webp
Risky: assets/Final Screenshot NEW (2).PNG
```Good: assets/settings-pdf-export.png
Good: assets/relative-path-example.webp
Risky: assets/Final Screenshot NEW (2).PNG
NoteRename the file before adding it to a long-lived document, then keep the Markdown path in sync.
Move and share the document as a folder
When a document contains local images, treat the Markdown file and its assets as one package. Move the parent folder, commit the whole folder to Git, or create an archive that contains both parts.
After moving it, open the Markdown file from the new location and inspect the preview. This quick check catches missing files, letter-case changes, and paths that still point back to the old folder.
## Before sending the folder
- [ ] Copy the Markdown file and its assets together
- [ ] Open the copy from its new location
- [ ] Check each important image in preview
- [ ] Keep alt text for readers and broken-image casesBefore sending the folder
- [ ] Copy the Markdown file and its assets together
- [ ] Open the copy from its new location
- [ ] Check each important image in preview
- [ ] Keep alt text for readers and broken-image cases
NoteTest the copy you plan to send, not only the original on your computer.
Check missing images before export
A missing image may leave only its alt text or a broken-image marker. Scan the preview before HTML or PDF export, especially after changing a file name or reorganizing folders.
If an image is gone, read the path from the Markdown source and start from the document's folder. Check every folder name and the file extension. On a case-sensitive system, also check the capitalization.
Remote images need a different check. Open the URL directly and make sure the document is allowed to depend on an external server. A local copy is safer when the image must remain available with the document.
How VeloWrite opens local images
When you open a saved Markdown file in VeloWrite Desktop, relative image paths are resolved from that file's folder. A reference such as `assets/chart.png` can therefore appear in preview without changing the Markdown source.
The web editor cannot read arbitrary files from your computer. Browsers block that access for security. Use a hosted image for a temporary browser draft, or move the document into the desktop app when it depends on nearby local assets.
VeloWrite does not yet move or rename image files automatically. Keep the document and its assets together, then check the rendered preview after any folder change.
This site path works on velowrite.app. A local project should use a nearby path such as `assets/app-icon.png` instead.
This site path works on velowrite.app. A local project should use a nearby path such as assets/app-icon.png instead.
NoteThe right path depends on where the Markdown file will live.