Related documentation
Images & Image Galleries
Roe makes it really easy to create image galleries in Posts or Pages with Markdown. All gallery images have a light-box feature automatically (click to enlarge) with a carousel/slideshow options as well.
Uploading Images
In order to add images to your Post/Pages, you’ll need to upload them. There are 2 ways to do this:
MEDIA ▼ button in The Editor
Opens a media browser in the editor and you can insert media directly at your cursor.
Admin → Media
On this page, you can:
- rename the file (double click on the name)
-
COPY URL- this is gives you thepathyou need to use images in Cards and Settings. -
MARKDOWN LINK- this is the exact syntax you need to add that image to a Post/Page.
Just one image, on it’s lonesome
If you want an image on it’s own, just use a standard Markdown image:
Use the MEDIA ▼ button in The Editor to open the media browser and drop an image directly at your cursor.
Simple Gallery
When you place 2 or more images consecutively (without blank lines between them), they automatically become a gallery:
↑ This creates a 3-column grid like this ↓
Note: This won’t work inside of a footnote. If you’re inside a footnote, use the Fancy Gallery syntax by wrapping the images in a gallery block ↓
```gallery
```Fancy Gallery
By wrapping the images in a gallery block, you can:
- control the layout of the images
- feature images
- add captions to individual images
- add a single caption for the whole gallery
- set the aspect ratio of the images
- display them as a carousel/slideshow
```gallery
```Rather than typing the block out by hand, click the GALLERY button in The Editor. It opens a little menu where you can switch on a carousel, choose an aspect ratio, and add a gallery caption — then it drops the finished block in at your cursor with a placeholder ready for your images.
Use the MEDIA ▼ button in The Editor to add your images where __PLACEHOLDER__ is.
This allows you to do some fancy things such as…
Featured/Hero Image
If you want an image to be full-width, just put it on it’s own line like so ↓
```gallery
```↑ That will look like this ↓
- Row 1: 1 image (full width)
- Row 3: 3 images (33% width each)
Carousel (slideshow)
Instead of a grid, add slideshow: true at the bottom of the gallery to make it carousel/slideshow like so ↓
```gallery
slideshow: true
```↑ that will look like this ↓
Captions
Add captions to any image using this syntax (*caption-here*) immediately after the image ↓
```gallery
(*House on Ilkley Moore*)
```↑ This will produce an image with a caption ↓
Gallery Caption
The (*...*) syntax above captions a single image. To add one caption for the whole gallery instead, put a caption: line inside the block ↓
```gallery
caption: A weekend on the moor
```↑ That adds a single caption beneath the whole gallery ↓
You can use both kinds at once — per-image (*...*) captions and a gallery caption: — in the same block.
Aspect Ratio
By default, each image takes the shape your theme gives that layout. Add an aspect_ratio: line to give every image in the gallery the same shape ↓
```gallery
aspect_ratio: film
```↑ That crops each image to a film ↓
The default theme gives you:
-
square— 1:1 -
portrait— 3:4 -
tv— 4:3 (alias:landscape) -
wide— 16:9 -
cinema— 21:9 super wide (alias:film) -
original— keep each image’s natural shape (alias:auto)
These match the ratios used by product collections, so the same names work in both places. Which ratios are available comes from your theme’s CSS, so a theme can offer its own.
Note: aspect ratio doesn’t apply to a carousel (slideshow: true) — those images are sized by height instead.
Combine all these features
Let’s create a Gallery with 3 rows and captions. We’ll have:
- A hero image on top
- 3 images in the middle
- 2 on the bottom
- all with captions
Here is to the code to achieve that:
```gallery
(*House on Ilkley Moore*)
(*House on Ilkley Moore*)
(*House on Ilkley Moore*)
(*House on Ilkley Moore*)
(*House on Ilkley Moore*)
(*House on Ilkley Moore*)
```↑ This code will look like this ↓
Column Limits
Galleries support 1-3 columns per row. If you place more than 3 images on a single row, they will wrap.
Responsive Behavior
Right now, all gallery layouts are maintained even at small sizes. Room for improvement.
Spacing
Gallery spacing is controlled by the --space-gallery CSS variable in your theme. Set to 0rem for no gaps between images, or increase for more spacing.