Knowledge Base › Ultimate Markdown › Image Import

Importing Markdown Files with Local Images Using a ZIP Archive

Ultimate Markdown Pro can import Markdown files that reference local images. To do this, you must package the Markdown file and its associated images into a ZIP archive.

ZIP uploads are supported only in specific import contexts. You can upload ZIP archives when using the import operations available in the Tools menu and when using the Import Markdown section in the post editor sidebar.

When you upload a ZIP file containing a Markdown file and its related images, the plugin extracts the images from the archive, uploads them to the WordPress Media Library, and updates the image URLs in the resulting content accordingly.

When to Use ZIP Image Import

Use this method when your Markdown file references local images that are not publicly accessible.

This is the recommended approach when:

  • You are working with files stored on your computer
  • You receive content from contributors as a package
  • You want to import content and images in a single upload
  • Your images are not available via public URLs

Example ZIP File Structure

Consider the following example ZIP file structure:

my-markdown-import.zip
├── document.md
└── images
    ├── image1.jpg
    └── image2.png

In this example, document.md is the Markdown file that references two local images (image1.jpg and image2.png) located in the images folder.

The content of document.md might look like this:

## Sample Document

The first image:

![Image 1](images/image1.jpg)

The second image:

![Image 2](images/image2.png)

When referencing local images, you should always use relative paths. The paths used in the Markdown file must match the structure of the ZIP archive exactly.

For example, if the images are located in the same folder as the Markdown file, you can reference them like this:

![Image 1](image1.jpg)

or:

![Image 1](./image1.jpg)

If the images are located in a subfolder named images, you can reference them like this:

![Image 1](images/image1.jpg)

or:

![Image 1](./images/image1.jpg)

Avoid using leading slashes (/) when referencing local images in ZIP uploads. In URLs, a leading slash (/) refers to the root path of the current domain. When working with ZIP archives, there is no equivalent concept of a site root, so leading slashes in image paths are ambiguous and may prevent images from being correctly resolved.

How the Plugin Technically Handles ZIP Files with Local Images

During the ZIP import process, the plugin will:

  1. Extract the Markdown file and images from the ZIP archive
  2. Upload the local images to the WordPress Media Library
  3. Replace relative image paths (for example, images/image1.jpg) with the corresponding WordPress Media Library URLs (for example, https://example.com/wp-content/uploads/2025/12/image1.jpg)
  4. Create a document or a post using the updated content with the correct image URLs from the media library

Note that you can also upload multiple ZIP files during the upload process. Each ZIP archive must contain only one Markdown file, along with its related images. Do not include multiple Markdown files in the same ZIP archive.

Public image URLs included in the Markdown file are not downloaded during ZIP imports. Only local images contained in the ZIP archive are processed. If your Markdown file references publicly available images and you want them to be automatically downloaded and added to the Media Library, use the method described in Importing Public Images from Markdown.

Best Practices

  • Ensure that image paths in the Markdown file exactly match the ZIP archive structure. Double-check image paths before uploading. If referenced images are not found, they will be skipped during import.
  • Keep paths simple and avoid deeply nested folder structures. When possible, place images in the same folder as the Markdown file or in a single subfolder.