Your Markdown Is Portable Until You Add an Image

Markdown stores an image as a reference, not embedded bytes. Your sentences travel anywhere because the words are inside the file. The picture only follows if you also keep the file the reference points to. Own those files, keep them in a consistent relative folder, and write standard links, and the seam closes.

This is the one place the promise "your notes are just plain text" quietly fails. The text is portable. The attachment is a separate object the text merely names. Move the note without moving what it names, and you are left with intact prose and a row of broken image icons.

The fix is not a plugin or a setting. It is understanding what the format actually does, then keeping three small habits that make your attachments as durable as your words.

Why a Markdown image is a pointer, not a picture

A Markdown image is an instruction to go fetch a file, never the file itself. The CommonMark specification is explicit: "Syntax for images is like the syntax for links, with one difference. Instead of link text, we have an image description."¹ An image inherits everything links do, and a link is by definition a pointer to something stored elsewhere.

You can see it in the rendered output. The spec's own example shows ![foo](/url "title") becoming <img src="/url" alt="foo" title="title" />.² That src is the whole story. The note holds a path; the bytes of the picture live at the other end of it. Nothing about the picture is sealed inside your .md file.

So portability splits in two. The text moves with the file, always. The attachment moves only if the path keeps resolving — and a path is a relative direction, not a possession.

The path breaks when the base it counts from moves

A relative path is measured from somewhere, and "somewhere" changes the moment you move the file or open it in a different tool. The picture has not gone anywhere. The instruction for finding it now points at the wrong place. This is the exact failure people hit when notes "lose" their images on a move or an export.

It is not one app's quirk; it is how renderers resolve paths. Visual Studio Code's own issue tracker carries a documented, recurring case — issue #103343, "Markdown preview no longer shows images with path relative to project root," opened in 2020 with 17 comments.³ When the base directory a relative path counts from shifts, the same link that worked yesterday stops finding the file.

Absolute paths fail the same way, faster. A link like ![](file:/home/felix/photos/x.png) works only on the one machine with that exact folder, which is why note-takers keep asking how to "change local file location for several or all images in a markdown file" the day they switch computers.⁴

How apps store the attachment — and where the seam appears

Each app decides on your behalf where the picture lands and how the link names it, and the defaults rarely keep the note and its image together. The convenience is real inside the app. The seam appears at the boundary, the moment you export the note and open it somewhere that does not share the app's assumptions.

Take the clearest documented example. Obsidian's help says, "By default, attachments are added to the root of your vault."⁵ It offers four "Default location for new attachments" modes — "Vault folder", "In the folder specified below", "Same folder as current file", and "In subfolder under current folder"⁵ — and each resolves differently when the note travels. The default scatters images away from the notes that use them.

There is a second seam: the link syntax. Obsidian's own embed example is ![[Engelbart.jpg]]⁶ — exclamation plus double brackets. That is a deliberate, useful in-app convenience, not a defect. But it is Obsidian's internal-link format, not CommonMark, so a plain Markdown renderer elsewhere does not know what to do with it.

The vendors document the seam themselves

The most honest evidence that attachments leave as separate files is the vendors' own export documentation. Nobody is hiding this. The platforms tell you, in their help pages, that the picture is a distinct object that gets packed alongside the text rather than inside it.

Notion is precise about it. Its export help states that "Full page databases will be exports as a CSV file, with Markdown files for each subpage,"⁷ and that on export, asset folders "will also contain the images and other assets on your pages saved separately."⁷ Saved separately is the entire point: even the vendor's own export hands you the text and the images as different things you must keep together.

This is not an accusation against any app. It is the format being honest about itself. As Steph Ango, who leads Obsidian, puts it: "Apps are ephemeral, but your files have a chance to last."⁸ A picture only gets that chance if it is a file you keep, not a reference you assume will resolve forever.

The escape hatch nobody should reach for

There is one way to truly embed a picture inside a Markdown file — encode the image as base64 text and inline it — and it is almost always the wrong trade. It makes the note self-contained at a steep cost. Name the tradeoff honestly before you consider it; do not let "fully portable" tempt you into it.

Inlining an image as base64 turns the picture into a long wall of characters living directly in the file. The note becomes genuinely portable in the narrow sense that the bytes travel with the text. But it bloats the file, and it makes the raw source unreadable — open the .md in a plain editor and you find paragraphs of gibberish where a one-line ![](path) used to sit. You traded the seam for a worse problem.

The durable answer is not to embed the picture. It is to own the file the picture is and keep it next to the note that names it.

Three habits that make attachments as durable as words

Portability for attachments is a discipline, not a feature you switch on. The format keeps storing images by reference no matter which app you use, so the durability comes from how you organize and link the files yourself. Three habits do almost all of the work, and all three leave your notes readable anywhere.

1. Keep attachments in a consistent relative folder next to the note. As the Consistent Attachments and Links plugin documentation argues, "Ideally, all attachments should be located in the note folder or its subfolders… you can easily export a note to a separate folder outside of your vault, knowing that all its attachments are with it."⁹ When the picture lives beside the note, moving one moves both.
2. Write standard ![](path) links, not app-specific embeds. The same plugin documentation is blunt about why: "Disabling [[Wikilinks]] in favor of [Markdown Links](Markdown%20Links.md) makes your vault more compatible with other markdown editors."¹⁰ The standard reference renders anywhere; the proprietary embed renders in one place. (Note-to-note links have their own version of this trap — see why wikilinks aren't plain Markdown.)
3. Own the files — treat the relative path as a promise you keep. A path is only as good as the files behind it. The whole reason the plugin exists, in the maintainers' words, is "to have all links between notes and attachments in strict accordance with the markdown format and support their relative paths. This is useful when you want to open a note in another program that does not know where your vault folder is."⁹

That two plugins — Consistent Attachments and Links (374 GitHub stars) and Local Images Plus (536 stars) — exist solely to keep attachments together and rewrite links on a move is the proof that the seam is real and worth handling deliberately.⁹ (Star counts are point-in-time as of June 2026.)

What to actually do tomorrow

You do not need to migrate, install, or move anything to start. The seam closes with three small choices you make as you write, and each one leaves your notes openable in any editor. The discipline costs a folder convention and a link habit, and it buys you pictures that survive every future move.

Set your app to store new attachments in the same folder as the note, or a subfolder beside it, instead of a shared dump. Write images with standard ![alt](path) syntax so the link travels. And on any move or export, take the picture along with the note and confirm it still renders — the same export-before-you're-forced-out drill you run for the text applies doubly to attachments.

A note app that stores plain Markdown on your own device, works offline, and needs no account already keeps the words yours by default — the attachment discipline is what extends that ownership to the pictures. That is the kind of foundation MNMNOTE (mnmnote.com) is built on: open Markdown, on your device, where the files are genuinely yours to keep beside each other.

Frequently Asked Questions

Why do my images break when I move my Markdown notes?

Because Markdown stores an image as a reference, not embedded bytes. The note holds a path like ![](images/x.png); the picture lives in a separate file at that path.¹² Move the note without moving the image, or open it where the relative path counts from a different base, and the path stops resolving.³ The text survives; the link does not.

Why aren't images embedded inside the .md file?

A CommonMark image is a src reference by design — "syntax for images is like the syntax for links," pointing at a file stored elsewhere.¹² Keeping the bytes outside the text keeps the file small and readable. The only way to truly embed an image is to inline it as base64, an unreadable wall of characters.

How do I stop Obsidian's ![[...]] embeds from breaking elsewhere?

Switch to standard Markdown image links. The ![[file.png]] form is Obsidian's own internal-embed syntax,⁶ convenient inside the app but not CommonMark, so a plain Markdown renderer elsewhere may not show it. The Consistent Attachments and Links documentation notes that using [Markdown Links](...) instead "makes your vault more compatible with other markdown editors."¹⁰ Standard ![alt](path) links render anywhere.

Where should I keep image attachments so they don't get lost?

In a consistent relative folder beside the note, not a shared root dump. As the Consistent Attachments and Links documentation puts it: "all attachments should be located in the note folder or its subfolders… you can easily export a note to a separate folder outside of your vault, knowing that all its attachments are with it."⁹ Then a move can't orphan it.

How do I add an image in Markdown so it stays portable?

Write ![alt text](path), using a relative path to a file you keep next to the note, and own that file. The syntax is portable; the file is what you must keep.¹ Avoid absolute paths like file:/home/you/photo.png, which only work on the one machine with that exact folder, and avoid app-specific embeds if you ever plan to read the note elsewhere.

Is Markdown actually portable, then?

Yes for the text, conditionally for attachments. Your words live inside the .md file and move anywhere a plain text editor reaches. Images, PDFs, and other attachments are stored by reference, so they are only as portable as your discipline in keeping the files and using relative links.²⁷ Honest portability means owning both halves.

Plain text keeps its promise for the words; it only keeps it for the pictures if you treat each attachment as a file you own. Portability was never automatic — it is something you keep, one relative folder at a time.