How to Effectively Paste Images on Markdown with VSCode

Introduction

Nowadays I use mostly markdown files when taking notes on a subject, and this is often done through VS Code. Markdown is an excellent format for writing standard text and for easy and effective access to special formatting options such as computer code or math notation, however, in many situations it is much more effective to simply paste an image on the document.
The naive way to do so would be to pause your writing, copy an image to your VS Code project space, move this image to a directory and then type the image link to your markdown file. This would completely switch my concentration focus and help to break the thought flow, especially when dealing with multiple images.
After a frustrating Sunday afternoon spent fiddling with abandoned VS Code extensions and going through goofy attempts to create my own, I remembered to resort to two resources that should be much more appreciated by the software community in 2025: simplicity and Stack Overflow.

The Problem We're Trying to Solve

Given the break in cognitive flow during a note-taking process, we need to have a more convenient way to paste images located in our computer, stored at the current clipboard, into our markdown file and then move on.
So our solution should have the following properties:

• When focusing on a Markdown document in VS Code, we should be able to paste a file in the document without switching off focus of this document.
• Once pasted, the pasted image should be available at the current VS Code project directory tree.
• Once pasted, a link to the pasted image in the project should be automatically built in our focused Markdown file, preserving the image's original name if one exists (alt text will be a human responsibility).
• The properties of this behavior, such as defining where in the project the image should be stored, should be easily customizable.

How We're Going to Solve It

After reading a 2023 discussion in StackOverflow, I have learned that, since version 1.79, VS Code itself provides a way to paste files from the clipboard into a Markdown document.
The default behavior for this feature is like this:

• Once a Markdown file is focused, there is an image stored at the current clipboard and the user pastes this clipboard content in the Markdown document, the clipboard content is copied to the same directory as the focused markdown document, and a markdown link to this pasted content is automatically built, which also preservs the original file name (it defaults to 'image' in case the clipboard image is nameless). This might seem trivial and maybe already solves your problem, but this feature seems to be currently somewhat obscure, and many of us (such as myself) don't really bother to update VS Code, so let's see how to effectively use it.

Usage Example

For starters, make sure your VS Code version is 1.79 or above; I am currently using 1.84 and it works perfectly.
We want to paste our images in a markdown document in a way that they are always stored under the markdown-images directory, and a textual link to the image is automatically added to the document's text.
This is how we can set it up:

• Open configurations (Ctrl+, and Cmd+, on a Mac)
• Select Open Settings (JSON) at the top-right icon of the settings window
• Append the following line to the settings:

"markdown.copyFiles.destination": {
    "**/*": "markdown-images/${fileName}"
}

Basically, the json key "**/*" registers in which markdown file location the feature for pasting images should be applied (in this case, the whole project; see the release notes linked above for an example of a scoped rule) and the json value "markdown-images/${fileName}" specifies where and how to save the image (in this case it states that the image should be saved under a markdown-images directory created at the same level as the markdown file, and that the original file name should be kept).

Before and After Pasting

Let's suppose we copy a file, pasted-markdown-image.png, located somewhere in our computer, and want to paste at the currently focused markdown document.

Take a look at our VS Code before pasting; it only consists of a README.md file, some typed markdown content and the file preview:

Now, after pasting pasted-markdown-image.png to the document:

Note that it is visible in the left screen (the project directory tree explorer) how an image named pasted-markdown-image.png was added under the markdown-images directory.
Also in the middle screen (the Markdown document composition), a link to this pasted image was created and the image's original name was kept; alt text still has to be filled by us, but hey, at least no one shoe-horned chatbots here.
Finally, the screen to the right (the rendered markdown preview) shows us the image of some crowded platforms, confirming it worked.

Final Notes

Notice that this creates links to any type of file, not just still images. Also notice that Mac and Windows both offer ways to transfer screenshots to the clipboard, and your Linux GUI should provide one as well.
In summary, by updating VS Code to version 1.79+ and adjusting a simple configuration, you can streamline your note-taking workflow and easily paste images into Markdown files without losing focus.
Hope this helps you as much as it did help me!