How notion-to-md Handles Images and Files During Conversion

notion-to-md does not leave Notion-hosted images and files as-is by default. It exposes a media handling layer with three strategies — download, upload, and direct/buffer — and rewrites the links in the generated Markdown to point at wherever the media ends up. You choose the strategy through configuration; the library then processes each media block during conversion and updates the reference automatically. This applies to images and files embedded in Notion pages, not to arbitrary external URLs you paste as plain text.

The three media strategies

The strategy is a configuration choice, not a per-file decision you make by hand — you set it once and the converter applies it consistently across the page.

Download

Use this when the Markdown output should be self-contained. The converter retrieves each Notion-hosted asset and writes it to a destination you configure, then replaces the original Notion link in the Markdown with the new local path. The practical benefit is that your output no longer depends on Notion's signed, expiring URLs.

Upload

Use this when your destination is a CMS, static host, or object store. The converter fetches the asset and hands it to your upload target, then writes the resulting public URL into the Markdown. Because the upload step is yours to define, the returned link is whatever your storage layer produces — the library's job is to fetch, hand off, and substitute.

Direct / buffer

Use this when you want speed or when a downstream step will handle persistence. The asset is either left pointing at its Notion source or held in memory rather than written to disk. This is the lightest option, but it means the Markdown still references Notion-hosted URLs, which can expire — so treat it as an intermediate state rather than a final published form.

How links get updated

The link rewrite is the part that makes the strategy useful. During conversion, each media block is processed according to your configured strategy, and the Markdown that comes out references the post-processing location — a local path for download, your storage URL for upload, or the original source for direct. You do not need a separate find-and-replace pass over the output; the substitution happens as part of rendering.

A concrete example: a page contains an image whose Notion URL is a temporary signed link. With the download strategy configured to a local assets/ folder, the generated Markdown contains ![alt](assets/image-name.png) instead of the Notion URL. Run the same page through with upload configured, and the same image reference becomes your CDN URL. The page content is identical; only the media strategy changed the output.

Cleanup and configuration

Media handling is configured alongside the rest of the conversion options, and the library documents it as a distinct concept with its own configuration surface. Two things worth planning for:

• Cleanup of downloaded files. If you re-run conversions, downloaded assets can accumulate. Decide whether your pipeline overwrites, versions, or prunes the media directory, and wire that into your build rather than relying on the converter to manage lifecycle.
• Naming and collisions. Assets pulled from different pages can share names. Check how your configured destination handles collisions before you commit to a flat folder.

The library also ships a media strategy catalogue in its documentation, which is the right place to confirm the exact configuration keys and any strategy-specific options for the version you install — the plugin system is extensible, so available behavior can differ between releases.

Choosing a strategy

• Publishing to a static site or docs platform that serves its own assets → download, and commit or deploy the media folder with the Markdown.
• Content going to a CMS or CDN you control → upload, so links resolve to your infrastructure.
• Building a preview, a one-off export, or a pipeline where a later step re-hosts media → direct/buffer, accepting that links are temporary.
• Mixing sources (some pages public, some internal) → pick the strategy that matches your strictest destination, since the setting applies across the conversion.

If your output will be published and long-lived, avoid leaving Notion URLs in the Markdown; signed links expire, and the page will show broken media later.