# 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](/docs/icons).
## Basic images
Use standard markdown syntax:
```markdown
```
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:
```markdown
```
### Height
Set a fixed height (image crops to fit):
```markdown
```
### Crop
Crop to exact pixel dimensions:
```markdown
```
### Circle
Circular crop — great for avatars and profile photos:
```markdown
```
### Square
Square crop with 1:1 aspect ratio:
```markdown
```
### Rectangle
Landscape rectangle with 3:2 aspect ratio:
```markdown
```
### Black & white
```markdown
```
### Sepia
```markdown
```
### Rotate
Rotate the image 90 degrees clockwise. Use `+rotate:1` for 90°, `+rotate:2` for 180°, or `+rotate:3` for 270°.
```markdown
```
```markdown
```
### Expand (lightbox)
Click the image below to open it fullscreen. Press `Escape` to close.
```markdown
```
### 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) |
```markdown
```
```markdown
```
To set the default for all images globally, add `imageCorners` to `settings/theme.md`:
```yaml
# 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.
```markdown
```
```markdown
```
```markdown
```
## Image row
Display multiple images in a row at equal height. Images stretch to fill the row regardless of their original aspect ratios.
```markdown
image-row:
```
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.
```markdown
image-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.
```markdown
gallery:
```
gallery:
### Gallery with modifiers
Image modifiers work inside galleries:
```markdown
gallery:
```
gallery:
### Gallery with custom corners
Override corner rounding for an entire gallery:
```markdown
gallery +corner:curve:
```
gallery +corner:curve:
```markdown
gallery +corner:none:
```
gallery +corner:none:
### Static gallery (no lightbox)
Use `+noexpand` to disable the lightbox. Images display as a static grid. Flags can be combined.
```markdown
gallery +noexpand:
```
gallery +noexpand:
## Local vs URL images
All modifiers work on both local images and external URLs:
```markdown
```
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 +circle` and `+circle +bw` produce the same result.
- Modifiers work on [card images](/docs/cards#image-modifiers-on-cards) too — append them to the `card-image:` URL.
- The lightbox supports keyboard navigation: `Escape` to close, `Left`/`Right` arrows to navigate within a group.
- Gallery images are displayed at 4:3 aspect ratio with `cover` fit.
- Image rows equalize height across all images in the row automatically.
- Set `imageCorners` in `settings/theme.md` to change the global default for all images, image rows, and galleries.
- Use [alignment fences](/docs/content-alignment) (`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`:
```yaml
# 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/`:
1. If wider than `imageMaxWidth`, the image is resized down
2. The original is recompressed at `imageQuality`
3. A `.webp` variant is generated alongside the original (`photo.jpg` → `photo.webp`)
4. All `` tags in the HTML output are wrapped in `` elements:
```html
```
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](/docs/media-hosting) to serve optimized images from a CDN.
` tags in the HTML output are wrapped in `