Images Material
Images Material
Section titled “Images Material”Syntax
Section titled “Syntax”| Form | Syntax | Usage |
|---|---|---|
| Image |  | Standard image. |
| Alignment | align=left / align=right | Float. |
| Size | width, height | Dimensions. |
| Large | .full-width / .full-width-centered | Large figure. |
| Mini | .mini-width align=right | Compact figure. |
| Caption | /// caption | Caption. |
| Loading | loading=lazy | Lazy loading. |
| Lightbox | lightbox | Open the image in a small modal window. |
| Theme | data-light, data-dark | Sources light/dark. |
| Responsive URLs | src-mobile, src-tablet, src-desktop | Use a different source for each viewport. |
| Responsive profile | responsive=carte | Ask Asset Manager for three adapted formats. |
Responsive URLs by viewport
Section titled “Responsive URLs by viewport”Use src-mobile, src-tablet, and src-desktop when the composition or the source file must change according to the available screen width. src-smartphone is accepted as an alias for src-mobile.
{
src-mobile="https://dummyimage.com/600x900/7c2d12/ffedd5?text=Smartphone"
src-tablet="https://dummyimage.com/1000x700/134e4a/ccfbf1?text=Tablet"
src-desktop="https://dummyimage.com/1400x700/172554/e2e8f0?text=Desktop"
}The renderer creates a <picture> with these breakpoints:
| Viewport | Selected source |
|---|---|
| Smartphone | src-mobile up to 767px. |
| Tablet | src-tablet from 768px to 1199px. |
| Desktop | src-desktop from 1200px. |
The Markdown URL remains the desktop fallback when src-desktop is omitted. If src-tablet is omitted, the desktop URL is reused. If src-mobile is omitted, the tablet URL is reused. This explicit-source mode works with ordinary static files and does not require Asset Manager. Responsive images default to loading="lazy" and decoding="async"; both attributes can be overridden explicitly. A responsive image using lightbox opens the source currently selected by the browser.
Asset Manager responsive profiles
Section titled “Asset Manager responsive profiles”When the same source and composition work at every size, responsive=profile adds one Asset Manager preset per viewport:
{ responsive=carte }The simplified generated HTML is:
<picture class="frontmark-optimized-picture frontmark-responsive-picture">
<source
media="(max-width: 767px)"
srcset="/images/hero-fallback.webp?preset=small"
>
<source
media="(max-width: 1199px)"
srcset="/images/hero-fallback.webp?preset=card"
>
<img
src="/images/hero-fallback.webp?preset=medium"
alt="Description"
loading="lazy"
decoding="async"
>
</picture>The profiles map each viewport to the following Asset Manager presets. Every profile uses three distinct, increasing preset widths:
| Profile | Smartphone preset | Tablet preset | Desktop preset | Usage |
|---|---|---|---|---|
icone | micro (64px) | icon (128px) | miniature (256px) | Icons and small avatars. |
avatar | icon (128px) | miniature (256px) | thumbnail (320px) | Profiles and authors. |
miniature | miniature (256px) | thumbnail (320px) | small (480px) | Lists and previews. |
carte | small (480px) | card (640px) | medium (800px) | Cards, products, and news. |
contenu | card (640px) | large (1024px) | article (1200px) | Embedded content images. |
article | medium (800px) | article (1200px) | xl (1600px) | Main article image. |
banniere | large (1024px) | xl (1600px) | hero (1920px) | Horizontal banners. |
hero | article (1200px) | hero (1920px) | 2.5k (2560px) | Full-width images. |
herohd | hero (1920px) | 2.5k (2560px) | 4k (4096px) | High-density displays. |
These are requested widths. Asset Manager cannot create missing source detail: use an original at least as wide as the largest preset when the desktop output must reach that resolution.
Accented and separated profile spellings are normalized: icône, bannière, and hero-hd are accepted. For a one-off mapping, provide exactly three Asset Manager identifiers in smartphone, tablet, desktop order:
{ responsive="micro,thumbnail,2.5k" }The profile can also be combined with three different Asset Manager URLs. FrontMark appends the appropriate preset to each URL and preserves any existing query parameters and fragment:
{
src-mobile="https://assets.example.com/mobile.webp?tenant=docs"
src-tablet="https://assets.example.com/tablet.webp?tenant=docs"
src-desktop="https://assets.example.com/desktop.webp?tenant=docs"
responsive=carte
}Asset Manager formats
Section titled “Asset Manager formats”| Format | Identifier | Width | Quality |
|---|---|---|---|
| Micro | micro | 64px | 75 |
| Icon | icon | 128px | 78 |
| Miniature | miniature | 256px | 80 |
| Thumbnail | thumbnail | 320px | 80 |
| Small | small | 480px | 81 |
| Card | card | 640px | 82 |
| Medium | medium | 800px | 83 |
| Large | large | 1024px | 84 |
| Article | article | 1200px | 85 |
| XL | xl | 1600px | 85 |
| Hero | hero | 1920px | 85 |
| 2K | 2k | 2048px | 88 |
| 2.5K | 2.5k | 2560px | 89 |
| 4K | 4k | 4096px | 90 |
| 6K | 6k | 6144px | 91 |
| 8K | 8k | 8192px | 92 |
| Original | original | Source width | 90 |
Lightbox
Section titled “Lightbox”{ width="420" lightbox lightbox-caption="Lightbox preview" loading=lazy }Left aligned
Section titled “Left aligned”{ align=left width="260" }
In a technical guide, a left-aligned image can support a short explanation without breaking the reading flow. Text flows to the right when horizontal space is sufficient.
On mobile, the image returns to full width to preserve comfortable reading and avoid overly narrow columns.In a technical guide, a left-aligned image can support a short explanation without breaking the reading flow. Text flows to the right when horizontal space is sufficient.
On mobile, the image returns to full width to preserve comfortable reading and avoid overly narrow columns.
Heading after aligned image
Section titled “Heading after aligned image”{ align=left width="260" }
This paragraph flows beside the image. The following heading clears the wrap and starts below the image if it is still taller than the nearby text.
### New heading that clears alignment
This text is no longer placed beside the previous image. The `clear` applied to headings stops the float from this point.This paragraph flows beside the image. The following heading clears the wrap and starts below the image if it is still taller than the nearby text.
New heading that clears alignment
This text is no longer placed beside the previous image. The clear applied to headings stops the float from this point.
Right aligned
Section titled “Right aligned”{ align=right width="260" }
A right-aligned image is useful for a secondary screenshot, reminder diagram, or illustration that should not interrupt the main paragraph.
The syntax preserves the HTML `align` attribute, which keeps the Markdown portable to MkDocs Material.A right-aligned image is useful for a secondary screenshot, reminder diagram, or illustration that should not interrupt the main paragraph.
The syntax preserves the HTML align attribute, which keeps the Markdown portable to MkDocs Material.
HTML figure with caption
Section titled “HTML figure with caption”<figure markdown="span">
{ width="320" loading=lazy }
<figcaption>Caption produced from an HTML `figure` block compatible with MkDocs Material.</figcaption>
</figure>Caption with /// caption
Section titled “Caption with /// caption”{ width="320" }
/// caption
Caption produced by the `pymdownx.blocks.caption` syntax, useful when you want to keep a classic Markdown image.
///Full width left aligned
Section titled “Full width left aligned”{ .full-width align=left loading=lazy }Full width right aligned
Section titled “Full width right aligned”{ .full-width align=right loading=lazy }Full width centered
Section titled “Full width centered”{ .full-width align=center loading=lazy }Full width centered with border
Section titled “Full width centered with border”{ .full-width-centered loading=lazy }Mini width left
Section titled “Mini width left”{ .mini-width align=left width="260" loading=lazy }
Text stays beside the image in mini left-aligned mode when page width allows it.Text stays beside the image in mini left-aligned mode when page width allows it.
Mini width centered
Section titled “Mini width centered”{ .mini-width align=center width="260" loading=lazy }
Mini centered mode keeps the block centered in the main column without overflowing toward the table of contents.Mini centered mode keeps the block centered in the main column without overflowing toward the table of contents.
Mini width right
Section titled “Mini width right”{ .mini-width align=right width="260" loading=lazy }
Text stays beside the image in mini right-aligned mode when page width allows it.Text stays beside the image in mini right-aligned mode when page width allows it.
Lazy loading
Section titled “Lazy loading”{ loading=lazy width="420" }
The `loading=lazy` attribute is passed directly to the image.The loading=lazy attribute is passed directly to the image.
Light and dark mode
Section titled “Light and dark mode”
The `#only-light`, `#only-dark`, `#gh-light-mode-only` and `#gh-dark-mode-only` fragments are hidden according to the active theme.
The #only-light, #only-dark, #gh-light-mode-only and #gh-dark-mode-only fragments are hidden according to the active theme.
Inline image followed by text
Section titled “Inline image followed by text”- {: width="32" style="vertical-align:middle; margin-right: .45rem; border: 2px solid #0f766e; border-radius: 6px;"} Architecture civile / ponts, maisons...
- { width="48" style="vertical-align:middle; margin-right: .45rem; border: 3px solid #f97316; border-radius: 999px;" } Texte **gras** avec [un lien](/docs/images-material/).
Architecture civile / ponts, maisons...Texte gras avec un lien.
Free attributes
Section titled “Free attributes”{ width="360" style="border-radius: 8px; border: 2px solid #818cf8;" loading=lazy .image-demo #image-demo-stylee }
The `width`, `height`, `style`, `class`, `id`, `title`, `align`, `loading`, `lightbox`, `lightbox-caption`, `lightbox-src` and `lightbox-group` attributes are preserved.The width, height, style, class, id, title, align, loading, lightbox, lightbox-caption, lightbox-src and lightbox-group attributes are preserved.