Embedding Base64 Images in Markdown: What Works, What Gets Stripped, and Per-Platform Fixes

You dropped a data URI into a markdown file — ![diagram](data:image/png;base64,...) — and the preview shows it perfectly. Then the README looks blank on github.com, the Notion API call fails, or the image vanishes from your WordPress post the moment you hit save. Nothing is wrong with your Base64 string in most of these cases: several of the most popular markdown hosts and editors structurally refuse or strip data URIs. Here is the full compatibility picture, and what to do on each platform.

Compatibility matrix: who renders Base64 markdown images

The pattern to remember: local renderers show it, publishing platforms strip it. The same restrictions apply to email clients — see our guides on Base64 images in Outlook and Gmail signatures.

GitHub: data URIs are banned, not broken

GitHub Flavored Markdown allows only a short whitelist of URL schemes in image sources — http, https, mailto and relative paths. data: is not on the list, so a Base64 <img> or ![]() is structurally blocked on github.com: READMEs, issues, pull requests, discussions, wikis. This is the spec working as written, and no repository setting changes it. If the same file renders in Typora or VS Code but shows nothing on GitHub, that is exactly what is happening.

Fixes that work on GitHub

1. Commit the image and use a relative path. In READMEs and other in-repo markdown files, ![logo](docs/assets/logo.png) resolves against the file's location. (In issues and PR descriptions relative paths don't resolve — use the next option there.)
2. Upload through the GitHub editor. Drag-and-drop an image into an issue, PR or the web file editor and GitHub hosts it on a githubusercontent.com URL you can reference anywhere.
3. For badges and diagrams, use hosted services. Shields.io badges, hosted chart images or an mermaid code block cover most of the reasons people reach for Base64 in the first place.

If you still want a Base64 string for local previews of that same README, generate one in the browser with the Image to Base64 converter — and remember you will need the hosted fallback for GitHub itself.

Notion: the API only accepts hosted URLs

Notion's API is unambiguous: image blocks take an external HTTPS URL (or a file previously uploaded through Notion). There is no field for inline Base64, and passing a data:image/...;base64, string fails. The File Upload API added in 2025 doesn't change this for block content — it still doesn't accept inline data URIs. Automation builders keep hitting this wall: the n8n and Latenode community forums are full of "why can't I push this base64 image into Notion" threads.

Fixes that work in Notion

1. In automations: decode, host, then link. Decode the Base64 to a binary file, upload it to any host that returns an HTTPS URL (S3, Cloudinary, a GitHub raw URL), then create the image block with that URL. Tools like the Base64 payload builder show the encode direction; the decode side is a one-line Buffer.from(str, 'base64') or base64 -d.
2. Manual: paste or upload in the app. Notion re-hosts pasted images as attachments, which is why the app works while the API doesn't.
3. For markdown imports, use real URLs. Notion's importer fetches and re-hosts remote images, but a data URI inside imported markdown does not survive — convert your images to hosted URLs first.

WordPress: three places data URIs get stripped

WordPress is the subtlest of the three because the behavior depends on who is editing and where the HTML ends up. The symptom is always some flavor of "the image was there in preview and gone after save" — but the culprit differs:

1. The wp_kses sanitizer. Users without the unfiltered_html capability — authors and contributors, and editors on multisite — get data: removed from src attributes on save. Administrators usually keep their images, which makes the bug look random. If an admin sees the image and an author doesn't, this is it.
2. Editor round-trips. Switching between visual and code editing, or between the block and classic editors, can mangle very long attribute values. A 50 KB data URI is a long attribute.
3. SMTP and email-log plugins. Plugins that send or log transactional HTML often sanitize the message body — your post renders fine in the editor but the Base64 images vanish from the sent email. WordPress.org support threads document exactly this, including in mail-logging contexts.

Fixes that work in WordPress

1. Allow the data protocol for KSES — in a plugin or theme functions file:

   add_filter( 'wp_kses_allowed_protocols', function ( $protocols ) {
       $protocols[] = 'data';
       return $protocols;
   } );

   One caution: this whitelists data: everywhere KSES applies, including links. data:text/html URLs are a known phishing vector, so on multi-author or open-registration sites prefer the next option.
2. Use the Media Library instead. Hosting through WordPress's own media system is the platform-native path, avoids the sanitizer entirely, and performs better: large data URIs bloat the HTML of every page view and delay first paint.
3. Diagnose by role and destination. Admin sees it, author doesn't → wp_kses. Editor fine, sent email stripped → the mail plugin. Preview fine, gone after save → editor round-trip.

Where Base64 in markdown works well

The legitimate use case is single-file portability — a markdown document that travels with its images intact: notes emailed as one .md, archived documentation, a self-contained spec that renders in Typora, Obsidian or a pandoc-generated standalone HTML file. In those environments data URIs are genuinely useful.

• Typora renders them natively.
• Obsidian renders them in reading view when the MIME type is exact.
• VS Code preview mostly works — but if one string fails while another renders, you are probably hitting the known parsing bug, not a bad encoding.

Watch the weight: Base64 inflates files by ~33%, and a few screenshots can turn a 20 KB document into a megabyte slug. Compress first (see the PNG and JPG compressors) and check the result with the size calculator. If you inherit a document stuffed with data URIs, the Base64 extractor pulls them back out as files.

Universal pitfalls that break data URIs anywhere

Even on renderers that fully support data URIs, four mistakes account for most "my Base64 image doesn't show" reports:

1. Wrong MIME type. data:image/jpg;base64, is invalid — the registered type is image/jpeg. Strict renderers (Obsidian, VS Code preview in some versions) refuse the whole URI over this.
2. Line breaks in the payload. Many CLI encoders wrap Base64 at 76 characters by default, and markdown renderers do not strip those newlines inside the URI. Use base64 -w 0 on Linux (see the per-language conversion guide) or a browser encoder that outputs one line.
3. Stray whitespace or a BOM picked up during copy-paste — invisible in an editor, fatal to the parser.
4. Assuming your editor's renderer is the target. The single most common trap in this whole topic: testing in Typora or VS Code and shipping to GitHub or Notion. Always verify in the renderer that will actually display the file.

For corrupted strings rather than blocked ones — truncation, missing padding, stray characters — the invalid Base64 data guide covers diagnosis step by step.

Frequently asked questions

Need a clean, single-line data URI to drop into a markdown file? Encode it locally with the Image to Base64 converter, size it with the calculator, and check the platform matrix above before you ship.