Images
Standard markdown images work out of the box. sitemd adds modifiers for resizing, cropping, filtering, and layout — plus a built-in lightbox for fullscreen viewing. For vector graphics, see Icons.
Basic images
Use standard markdown syntax:
Images are block-level, responsive (max-width: 100%), and lazy-loaded automatically.
Image modifiers
Add +modifier flags to the image URL — same pattern as +newtab on links.
Width
Set a max width in pixels:
Height
Set a fixed height (image crops to fit):
Crop
Crop to exact pixel dimensions:
Circle
Circular crop — great for avatars and profile photos:
Square
Square crop with 1:1 aspect ratio:
Rectangle
Landscape rectangle with 3:2 aspect ratio:
Black & white
Sepia
Rotate
Rotate the image 90 degrees clockwise. Use +rotate:1 for 90°, +rotate:2 for 180°, or +rotate:3 for 270°.
Expand (lightbox)
Click the image below to open it fullscreen. Press Escape to close.
Corner rounding
Control corner rounding per image with +corner:. Three named options:
| Value | Effect |
|---|---|
+corner:none |
Square corners (0px) |
+corner:subtle |
Default rounding (6px) |
+corner:curve |
Heavy rounding (16px) |
To set the default for all images globally, add imageCorners to settings/theme.md:
# Image corner rounding: none, subtle (default), or curve
imageCorners: subtle
Per-image +corner: overrides the global setting.
Combining modifiers
Stack any number of modifiers together. Order doesn't matter.
Image row
Display multiple images in a row at equal height. Images stretch to fill the row regardless of their original aspect ratios.
image-row:
On mobile, images wrap to two per row.
Image row with modifiers
Modifiers work on individual images within a row. Add +expand to enable lightbox — left/right arrows navigate between the expanded images in the same row.
image-row:
Gallery
Display images in a responsive grid. All gallery images automatically open in a lightbox when clicked — navigate with left/right arrow keys or the on-screen arrows.
gallery:
Gallery with modifiers
Image modifiers work inside galleries:
gallery:
Gallery with custom corners
Override corner rounding for an entire gallery:
gallery +corner:curve:
gallery +corner:none:
Static gallery (no lightbox)
Use +noexpand to disable the lightbox. Images display as a static grid. Flags can be combined.
gallery +noexpand:
Local vs URL images
All modifiers work on both local images and external URLs:
Place local images in the media/content/ directory. They're copied to the output during build and served at /media/content/filename.ext.
Modifier reference
| Modifier | Effect |
|---|---|
+width:N |
Max width in pixels |
+height:N |
Fixed height (crops with cover) |
+crop:WxH |
Crop to exact dimensions |
+circle |
Circular crop |
+square |
Square crop (1:1) |
+rect |
Landscape rectangle (3:2) |
+bw |
Black and white filter |
+sepia |
Sepia tone filter |
+rotate:N |
Rotate 90° clockwise N times (1–3) |
+corner:name |
Corner rounding: none, subtle, curve |
+expand |
Click to open fullscreen lightbox |
Notes
- Image syntax inside fenced code blocks is displayed as text, not rendered.
- Modifiers are order-independent —
+bw +circleand+circle +bwproduce the same result. - Modifiers work on card images too — append them to the
card-image:URL. - The lightbox supports keyboard navigation:
Escapeto close,Left/Rightarrows to navigate within a group. - Gallery images are displayed at 4:3 aspect ratio with
coverfit. - Image rows equalize height across all images in the row automatically.
- Set
imageCornersinsettings/theme.mdto change the global default for all images, image rows, and galleries. - Use alignment fences (
center://center,right://right) to center or right-align images, image rows, and galleries.
Image optimization
Enable build-time image optimization in settings/build.md:
# settings/build.md
imageOptimization: optimize
imageMaxWidth: 1920
imageQuality: 80
| Setting | Default | What it does |
|---|---|---|
| imageOptimization | false |
false disables optimization. optimize enables resizing, compression, and WebP generation. |
| imageMaxWidth | 1920 |
Images wider than this are resized down. Height scales proportionally. |
| imageQuality | 80 |
Compression quality for JPEG and PNG output. Lower values reduce file size. |
What happens at build time:
Optimization runs after the main build, in the same async post-build step as OG image generation. For every image in site/media/:
- If wider than
imageMaxWidth, the image is resized down - The original is recompressed at
imageQuality - A
.webpvariant is generated alongside the original (photo.jpg→photo.webp) - All
<img src="/media/...">tags in the HTML output are wrapped in<picture>elements:
<picture>
<source srcset="/media/content/photo.webp" type="image/webp">
<img src="/media/content/photo.jpg" alt="...">
</picture>
Browsers that support WebP receive the smaller file automatically. Browsers that don't fall back to the original.
Source images are never modified. Optimization operates on the copies in site/media/ (the build output), leaving your media/ source files intact.
Results are cached by content hash in site/media/.image-cache.json. Unchanged images are skipped on subsequent builds — only new or modified images are reprocessed.
Requires Sharp. If Sharp is not installed, optimization is skipped silently. Use Media Hosting to serve optimized images from a CDN.