b64 (image embed)
Rewrites local image references into self-contained data: URIs so a page carries
its images inline. This mirrors the pymdownx.b64 Markdown extension and is
useful for single-file HTML exports, email-friendly pages, or eliminating extra
image requests.
Both Markdown images and inline HTML <img> tags are handled:
<img src="/img/logo.svg" alt="Logo">
Remote (http://, https://), protocol-relative (//…), and existing data: URIs
are left untouched. Supported extensions: .png, .jpg/.jpeg, .gif, .svg,
.webp, .avif, .bmp, .ico.
Enabling
The plugin runs after snippets/macros, so images pulled in via includes embed too.
Add it to the plugins array:
{ "name": "b64", "options": { "default": false } }
Toggling per site or per page
Embedding is off by default. You control it at two levels:
| Level | How | Wins |
|---|---|---|
| Site | "default": true plugin option |
Applies to every page… |
| Page | embed_images: true / false front matter |
…unless a page overrides it. |
---
title: Release notes
embed_images: true
---
Options
| Option | Type | Default | Description |
|---|---|---|---|
default |
bool | false |
Embed images on every page unless a page opts out. |
base_path |
array | — | Extra directories (relative to the project root) searched for image files. |
Image paths are resolved in this order: next to the Markdown source file, then each
base_path, then the docs directory. Root-absolute paths (/img/x.png) resolve
against the docs directory.
Page weight
Base64 data is ~33% larger than the binary and is not cached separately by the
browser. Prefer per-page embed_images for a handful of pages rather than turning
default on for an image-heavy site.
Attribution
Behavior is modeled on pymdownx.b64 from Facelessuser's PyMdown Extensions
(MIT License). See Attributions.