Sentry Software
Sentry Maven Skin 7.0.00
-
Home
- Writing Documentation
Images
Images in your documentation are automatically enhanced with click-to-zoom and WebP conversion.
Adding Images
Place images in src/site/resources/images/ and reference them with standard Markdown syntax:
Auto-Zoom Thumbnails
By default, images are displayed as clickable thumbnails:
Default behavior:
- Thumbnail display at reduced size
- Click-to-zoom lightbox overlay
- Smooth zoom animation
Inline Images (No Zoom)
For icons or small images that should display at actual size, use inline as the alt text:
Comparison
| Alt Text | Behavior |
|---|---|
 |
Zoomable thumbnail |
 |
Inline, no zoom |
Automatic WebP Conversion
All images are automatically converted to WebP format during the build for better performance.
| Source Format | WebP Type | Quality |
|---|---|---|
| PNG, GIF | Lossless | Perfect quality |
| JPG, JPEG | Lossy | Optimized size |
Benefits:
- Smaller files: WebP is typically 25-35% smaller than JPEG/PNG
- Better Lighthouse scores: Faster page loads improve performance metrics
- Automatic fallback: Browsers without WebP support use the original
No configuration required - conversion is automatic.
WebP conversion significantly improves Lighthouse performance scores by reducing image file sizes by 25-35%.
Image Validation
The build fails if a referenced image does not exist, catching broken image links early.
Configuration
All image features can be configured globally in site.xml or per-page using frontmatter:
| Setting | Description | Default |
|---|---|---|
checkImageLinks |
Verify image files exist during build | true |
convertImagesToWebp |
Convert images to WebP format | true |
setExplicitImageSize |
Add width/height attributes to images | true |
convertImagesToThumbnails |
CSS selector for zoomable images | img:not([alt=inline]):not([uib-carousel] img) |
Disable Image Validation
To allow missing images without build failures:
Site-Wide (site.xml)
<custom>
<checkImageLinks>false</checkImageLinks>
</custom>
Per-Page (Frontmatter)
checkImageLinks: false
# Draft Page
Missing images won't cause build failures.
Disable WebP Conversion
To keep images in their original format:
Site-Wide (site.xml)
<custom>
<convertImagesToWebp>false</convertImagesToWebp>
</custom>
Per-Page (Frontmatter)
convertImagesToWebp: false
# Legacy Screenshots
Images stay in original format.
Disable Explicit Image Size
To prevent automatic width/height attributes on images:
Site-Wide (site.xml)
<custom>
<setExplicitImageSize>false</setExplicitImageSize>
</custom>
Per-Page (Frontmatter)
setExplicitImageSize: false
# Page with Responsive Images
Images will not have explicit dimensions.
Disable Auto-Zoom
To disable the zoomable thumbnail feature completely:
Site-Wide (site.xml)
<custom>
<convertImagesToThumbnails>false</convertImagesToThumbnails>
</custom>
Per-Page (Frontmatter)
convertImagesToThumbnails: false
# Simple Page
All images display at full size without zoom.
Zoom Only Specific Images
Use a custom CSS selector to control which images become zoomable thumbnails.
Zoom only images with “zoom” in the filename:
Site-Wide (site.xml)
<custom>
<convertImagesToThumbnails>img[src*=zoom]</convertImagesToThumbnails>
</custom>
Per-Page (Frontmatter)
convertImagesToThumbnails: img[src*=zoom]
# Selective Zoom
Only images with "zoom" in filename are zoomable.
With this setting:
→ Zoomable thumbnail→ Displays inline, no zoom
Zoom only images in a specific folder:
<custom>
<convertImagesToThumbnails>img[src*=screenshots]</convertImagesToThumbnails>
</custom>
Best Practices
- Use descriptive alt text for accessibility
- Place images in
src/site/resources/images/ - Use
inlinefor icons and badges (under 50px) - Use zoom (default) for screenshots and diagrams
- Prefer PNG for diagrams, JPG for photos
See Also
- Configuration Reference[1] - All configuration options
- Code Highlighting[2] - Format code blocks
- UI Components[3] - Tabs and accordions