Light and Dark Mode Images in MkDocs Material¶
The MkDocs Material theme has built-in support for theme-aware images using standard Markdown syntax. No HTML is required.
Toggle the palette icon in the header to see the logo switch between its light and dark variants:
If you are using GitHub Markdown instead, see the companion post: Light and Dark Mode Images in GitHub Markdown.
How It Works¶
MkDocs Material recognizes two URL fragments in standard Markdown image syntax:
| Fragment | When It Renders |
|---|---|
#only-dark | Only shown when the dark palette is active |
#only-light | Only shown when the light palette is active |
This works with the standard ![]() syntax:
Include both images in sequence. MkDocs Material takes care of hiding the one that does not match the active palette.
The { .skip-lightbox } Attribute¶
If the site uses the glightbox plugin, images are wrapped in a lightbox overlay by default. For decorative images like logos, that behavior is usually unwanted. Adding { .skip-lightbox } to the image syntax tells the plugin to leave that image alone:
{ .skip-lightbox }
{ .skip-lightbox }
The attribute has no effect if the glightbox plugin is not installed or is disabled.
Note
The #only-dark and #only-light fragments are specific to the MkDocs Material theme. They will not work on GitHub, GitLab, or any other Markdown renderer. For GitHub, use the #gh-dark-mode-only and #gh-light-mode-only HTML approach described in Light and Dark Mode Images in GitHub Markdown.