When you export a Notion page to Markdown, images do not embed directly into the .md file. Instead, Notion places a Markdown image reference that points to a separate image file stored in an adjacent folder. This behavior often surprises users who expect images to appear inline or be attached as base64 data. The root cause is that the Markdown specification does not support binary image data within plain text files. This article explains exactly how Notion handles images during Markdown export, what the output structure looks like, and how to work with the exported files.
Key Takeaways: Notion Markdown Export and Image Handling
- Export format > Markdown & CSV: Notion exports images as separate files in a folder named after the page, not embedded in the .md file.
- Image reference syntax: The .md file contains
pointing to the adjacent image file. - Supported image types: PNG, JPEG, GIF, and WebP are preserved; SVG and HEIC may be converted or skipped.
Why Notion Exports Images as Separate Files Instead of Embedding Them
Notion stores images as binary blobs in its cloud database. When you trigger a Markdown export, Notion cannot embed binary data into a plain-text .md file because the Markdown specification does not allow inline binary content. Instead, Notion extracts each image as a separate file and writes a Markdown image reference in the .md file. The reference uses standard Markdown syntax: an exclamation mark, alt text in square brackets, and the filename in parentheses. The exported folder will contain the .md file plus a subfolder named after the page title, which holds all image files. Notion names the image files with a hash-based identifier to avoid name collisions. If the same image appears multiple times on the page, Notion exports only one copy and references it from each location.
What Determines the Image Filename
Notion generates the image filename from a content hash of the image data. Two identical images uploaded separately will produce different hashes if their metadata differs. The filename pattern is typically a 32-character hexadecimal string followed by the file extension, for example a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.png. This naming scheme prevents overwrites but makes it hard to identify images by name.
Which Image Formats Are Preserved
Notion preserves the original file extension for common formats: PNG, JPEG, GIF, and WebP. SVG images are converted to PNG during export because Markdown viewers rarely support SVG inline. HEIC images from Apple devices are also converted to JPEG. Animated GIFs remain animated. If you upload a TIFF or BMP, Notion converts it to JPEG. The conversion happens server-side during the export generation, and you cannot control the output format.
Steps to Export a Notion Page to Markdown and Verify Image Output
- Open the page you want to export
Navigate to any page in your Notion workspace that contains at least one image. The export applies to the current page only, not the entire workspace. - Open the export dialog
Click the three-dot menu in the top-right corner of the page. Select Export from the dropdown menu. A dialog box appears with export options. - Set export format to Markdown & CSV
In the Export format dropdown, choose Markdown & CSV. If you select HTML or PDF, the image handling behavior changes. For image embedding testing, Markdown is the correct choice. - Configure additional options
Check Include subpages if you want to export child pages as separate .md files. Leave it unchecked to export only the current page. The Create folder for each page option is enabled by default and recommended because it groups each page’s images in its own folder. - Click Export and wait for the download
Notion generates a ZIP file containing the .md file and a folder with images. The download starts automatically. If the page has many large images, the export may take several seconds. - Extract the ZIP file and inspect the output
Unzip the file. You will see an .md file and a folder with the same name as the page. Open the folder to confirm that all images from the page are present as separate files. Open the .md file in a plain text editor to verify the image references.
Common Issues With Notion Markdown Export and Images
Exported .md File Shows Broken Image Links
If you open the .md file in a Markdown viewer that does not have access to the adjacent image folder, the images will appear as broken links. The image reference in the .md file uses a relative path such as . To fix this, keep the .md file and the image folder in the same directory. If you move the .md file to a different location, update the image paths accordingly. Some Markdown editors allow you to set a base path for images.
Image Quality Decreases After Export
Notion does not recompress images during export. The exported image is the original file you uploaded. If the image appears lower quality, check whether the original file was compressed before upload. Notion applies its own compression when you upload images through the web interface, but the export preserves the compressed version. To retain maximum quality, upload images as PNG or WebP without prior compression.
Large Images Cause Export to Fail
Notion limits the total export size to 50 MB per page. If your page contains many high-resolution images, the export may fail with a timeout or incomplete ZIP file. To work around this, reduce image dimensions before uploading, or export the page in sections by removing some images temporarily. Alternatively, export the page as PDF, which embeds images directly into the file without the 50 MB limit.
Notion Markdown Export vs HTML Export: Image Handling Differences
| Item | Markdown Export | HTML Export |
|---|---|---|
| Image location | Separate folder | Embedded as base64 in the .html file |
| File size | Smaller .md file, images separate | Larger single .html file |
| Portability | Must keep folder structure intact | Single file, no external dependencies |
| Image format preservation | Preserves original extension for PNG, JPEG, GIF, WebP | Converts all images to base64, no format change |
| Suitability for version control | Good, images are separate files | Poor, large base64 blobs bloat diffs |
Notion’s Markdown export keeps images as separate files, which is ideal for version control systems like Git because each file changes independently. HTML export embeds images as base64 data within the HTML file, making it easier to share as a single file but harder to track changes. Choose Markdown when you plan to edit the content with a text editor or use a static site generator. Choose HTML when you need a self-contained file for offline viewing or email.