Images in Dokly are first-class. Drag a file from your desktop, paste a screenshot from your clipboard, or use the slash menu — they all upload, optimize, and render the same way.
Three ways to add an image#
Screenshot needed
short screen recording showing drag-and-drop image upload from desktop into the editor
What happens on upload#
- The image is uploaded to your project's Supabase storage bucket.
- Dokly generates optimized variants (WebP, multiple sizes for responsive serving).
- The original is preserved — you can always download the source.
- The MDX renders an
<img>tag withsrcsetandloading="lazy".
You don't see any of this. The image just appears.
Captions#
Add a caption by clicking the image and typing in the caption field below it. Captions render as <figcaption> and are styled smaller and muted.
Alt text#
Click an image and the inspector shows an Alt text field. Fill it in. Alt text is required for accessibility — empty alt text gets flagged in the editor.
If the image is purely decorative, type decorative in the alt field — Dokly translates this to alt="" in the rendered HTML, which tells screen readers to skip it.
Markdown source#
The Markdown for an image is the standard syntax:
The visual editor expands this into the inspectable image block above.
Storage limits#
| Plan | Image storage |
|---|---|
| Free | 0 (no uploads) |
| Starter | 500 MB |
| Pro | 2 GB |
| Scale | 10 GB |
| Enterprise | Unlimited |
If you hit your limit, new uploads fail with a clear error. Existing images stay served. To free up space, delete unused images in Project Settings → Storage.
Lightbox#
Clicking an image on the live site opens it in a lightbox at full resolution. There's no setting — it's always on.
Image best practices#
- Crop tightly. Screenshots with 80% browser chrome and 20% content waste vertical space. Crop to the content.
- Keep file sizes reasonable. Even with optimization, a 5MB screenshot is a 5MB upload. Compress before uploading if you can.
- Don't embed text-heavy images. Code, terminal output, and tables should be real text, not screenshots — they're searchable and accessible.
- Use captions for context. A screenshot without a caption is a screenshot the reader has to interpret on their own.