markdown.bz

Markdown sharing guides / Share Markdown with images as a ZIP

How to share Markdown with images as a ZIP

If a README or manual references local images, the images will not appear when you share only the Markdown. Put the Markdown and its image folder in the same ZIP, and you can share it on markdown.bz with the relative paths intact.

1. Set up the right file structure

For reliable results, stick to a single Markdown file and put the images it references under the same folder.

project-guide/
├── README.md
└── images/
    ├── overview.png
    └── flow.webp

In this example, relative to README.md, the images are at images/overview.png and images/flow.webp. Do not put more than one Markdown file in the ZIP, so that it is clear which document you want to share.

2. Reference images with relative paths

Write the image paths in the Markdown relative to the Markdown file.

# Project overview

The overall architecture is shown below.

![Overall architecture](images/overview.png)

## Processing flow

![Processing flow](images/flow.webp)

Absolute paths on macOS or Windows cannot be resolved from the recipient's environment or from the share page. Do not use /Users/..., C:\Users\... or file://....

3. ZIP the Markdown and images

  1. Put README.md and the images folder in the same parent folder.
  2. Compress the whole parent folder into a ZIP, or select the Markdown and the image folder inside it and compress those.
  3. Open the ZIP and make sure it contains the Markdown and the images.

Supported image formats are JPEG, PNG, WebP and GIF. SVG cannot be uploaded for security reasons.

4. Upload the ZIP

  1. Open the Upload page.
  2. Drop the ZIP you created, or add it with Choose files.
  3. Click Preview & settings and check that every image appears in the document.
  4. Check the title, expiry and password.
  5. Click Publish, then share the resulting URL or QR code.

The Upload page matches the images referenced in the Markdown against the images in the ZIP by path. You can still preview the document if some images are not found, but check what is marked as missing before publishing.

5. If images do not appear

SymptomWhat to check
No images are foundCheck that the ZIP includes the image folder
Only some images are missingMake the file names, extensions and upper/lower case match what the Markdown says
Images show locally but not on the share pageChange absolute paths and file:// to relative paths
Images in another folder do not showInstead of relying on ../, gather them into an image folder under the Markdown file
Only SVG files are not addedConvert them to PNG or WebP before adding them to the ZIP

6. Limits and safety notes

  • Markdown can be up to 1MB, and each connection (IP address) can send up to 20MB of images per day
  • Up to 200 images; except for GIFs, they are processed in your browser before upload
  • ZIPs whose extracted data is too large are not accepted
  • Even with a password, the content is not end-to-end encrypted
  • Do not share personal information, confidential information, credentials or images that need long-term storage

To start with the basics of sharing Markdown, see How to share a Markdown file as a URL. For the currently supported formats, see Help / FAQ.

Share Markdown with images

Last reviewed: / Reviewed by the markdown.bz team