:::grid is the blog’s image gallery container directive. It arranges ordinary Markdown images in a responsive grid with a consistent aspect ratio and automatically enables lightbox viewing. Use it for article images, screenshots, portfolios, or small albums.
Images in the same gallery use the same card ratio. By default, center cropping fills every card and keeps each row tidy; clicking an image opens the complete original in a lightbox. Every gallery has its own lightbox group and does not mix with other images in the post.
This post is both feature documentation and a visual test page. View the examples at desktop, tablet, and mobile widths, then click any image to verify lightbox grouping.
Minimal Syntax
Write Markdown images directly between :::grid and the closing ::::
:::grid
:::Each image must occupy its own paragraph, with a blank line between images. Keep only images in a gallery; write paragraphs, lists, and code blocks outside the container.
Here is the result of the minimal syntax. Without parameters, the grid uses three columns, a 16/10 ratio, and cover by default.
Parameters at a Glance
Write all parameters in braces after the opening directive: :::grid{parameter="value"}.
| Parameter | Allowed values | Default | Purpose |
|---|---|---|---|
columns | Integers from 1 to 6 | 3 | Number of columns per row on desktop. Invalid values fall back to 3. |
aspect | A positive ratio, such as 16/9, 3/4, or 1/1 | 16/10 | The displayed card ratio, not the original image ratio. |
fit | cover, contain | cover | Image fitting mode. cover crops to fill; contain preserves the complete image and may leave empty space. |
Complete example:
:::grid{columns="3" aspect="16/9" fit="cover"}
:::The following result uses the three-column landscape syntax above. Compare the card ratio, column count, and the way a title takes precedence over alt text as the caption:
Captions and Alt Text
An image’s alt text serves both as accessible alternative text and as its default caption. When an image has an optional title, the title is used as the caption instead:
In the same row, captions align to the bottom of every card. A wrapping caption does not make the others float at a different height. Ratio text such as 3:4 and 16:9 can be written directly in body text, headings, and alt text without escaping.
This example demonstrates the default alt-text caption, an explicit title caption, and bottom alignment for a longer caption:
Layout and Cropping
Desktop layouts use the number of columns specified by columns. Below 768px, grids use at most two columns; below 480px, they switch to one column. The card wrapper fixes the aspect ratio and clips rounded corners, while the image fills the card without the theme’s default image margins.
- Choose
cover: the recommended default. Images are cropped from the center to fill the card, making the gallery look consistent. - Choose
contain: the full original image is shown without cropping. When its ratio differs from the card, the theme background remains visible; use this for images that cannot be cropped. - To preserve the complete image without empty space, set
aspectclose to the original image ratio or place the image in a grid of its own.
The following examples place the same portrait images in 16/9 cards with cover and contain. The first crops them; the second preserves the full image and leaves background space.
:::grid{columns="3" aspect="16/9" fit="cover"}
:::
:::grid{columns="3" aspect="16/9" fit="contain"}
:::
Default Configuration
Without attributes, the default is three columns, a 16/10 ratio, and cover cropping. These three portrait images verify default cropping and captions.
:::grid
:::Three-Column Portraits: 3:4
With aspect="3/4", the three portrait images fill consistently proportioned vertical cards. If an original image has a different ratio, cover crops its edges from the center.
:::grid{columns="3" aspect="3/4"}
:::Three-Column Landscapes: 16:9
This set demonstrates a common video-cover ratio in a three-column layout. Cropping is minimal when the landscape images are close to the card ratio.
:::grid{columns="3" aspect="16/9"}
:::
Two-Column Squares: 1:1
Two columns work well when larger preview cards are needed. The third image moves to the next row. The final row keeps its grid-track width instead of stretching images to fill the row.
:::grid{columns="2" aspect="1/1"}
:::
Four Columns with contain
fit="contain" does not crop the original image. When the image ratio differs from the card ratio, the theme background remains visible. This is intentional, not a layout issue. It also verifies that four-column grids and separate lightbox groups do not interfere with each other.
:::grid{columns="4" aspect="16/9" fit="contain"}
:::Single-Column Detail Image
One column is suitable when an image needs a larger reading size. It remains one column on desktop, tablet, and mobile, and the original is still available in the lightbox.
:::grid{columns="1" aspect="16/9"}:::Sparse Five-Column Row
Five columns verify a higher supported column count. With only three images, the final row remains left-aligned instead of stretching the images.
:::grid{columns="5" aspect="1/1"}
:::Mixed Images in Six Columns
Six columns are the current maximum. Mixing landscape and portrait images verifies cover cropping, captions on narrow cards, and a dense desktop layout. For readable article content, two to four columns are usually preferable.
:::grid{columns="6" aspect="1/1"}
:::Four-Column Squares: 1:1
Four square images with the same ratio are a typical four-column layout. Desktop displays all four in one row; tablet collapses to two columns and mobile to one.
:::grid{columns="4" aspect="1/1"}
:::
Six-Column Landscapes: 16:9
Six landscape columns work well for thumbnail previews, portfolios, and screenshot indexes. Even if original ratios differ slightly, cover fills every 16/9 card consistently.
:::grid{columns="6" aspect="16/9"}
:::
Three-Column Portraits: 3:4
This group of six portrait images demonstrates a common layout for people, posters, or mobile screenshots. The images form two rows of three, with captions aligned to the bottom.
:::grid{columns="3" aspect="3/4"}
:::
Edge-Critical Content: cover and Lightbox
These images contain important text or details near their edges. cover keeps the grid tidy but may crop those edges; click an image to view the uncropped original in the lightbox. Use clear captions for edge-sensitive images, or use contain below.
:::grid{columns="3" aspect="16/9" fit="cover"}
:::
Extreme Ratios with contain
For banners, long screenshots, and other extreme image ratios, contain displays the complete original. Unlike cover, it may leave theme-background space, but it never crops content.
:::grid{columns="3" aspect="16/9" fit="contain"}
:::
Transparent Images
Transparent images reveal the card’s theme background. This single-column contain example makes the transparent areas, original edges, and lightbox behavior easy to inspect.
:::grid{columns="1" aspect="16/9" fit="contain"}:::
Lightbox Navigation
Click any image in a grid to open the Fancybox lightbox. There you can zoom, rotate, enter fullscreen, view thumbnails, and navigate with the arrow keys. Navigation is limited to the current :::grid container: for example, clicking “16:9 test image one” only opens the other two landscape images in that section.
Ordinary Markdown images in the same post continue to be handled separately; they are not added to any grid gallery.
Checklist
- Images in each grid have consistent dimensions, with captions below the cards.
- Images scale slightly on hover; after clicking, they can be zoomed, rotated, and navigated with the keyboard.
- Clicking “16:9 test image one” lets the lightbox browse only the other two landscape images in that section.
- Below 768px, grids use at most two columns; below 480px, they use one column.
- Portrait images in “Four Columns with
contain” are fully visible with empty space and no cropping. - Five- and six-column grids retain their specified column count on wide screens, then collapse to two or one column according to the responsive rules.
If this article helped you, please share it with others!
Some information may be outdated