How to create an image gallery in markdown

Question

Is there a recommended approach for creating image galleries in markdown? Or maybe some extensions?

I am referring to groups of 1, 2 or 3 images usually displayed horizontally and optionally with a caption.

Answer

Markdown doesn’t have anything specific for groups of images, however, after considering different solutions, I present the approach that I find more meaningful and simple.

Use this markdown:

![first image](/path/to/image1.png)
![second image](/path/to/image2.png)
*This is the caption for the above images.*

The trick is to avoid the extra spaces (empty lines) between the images, so that everything goes into one paragraph when markdown is rendered to HTML.

Then you can use CSS to select the paragraphs that have multiple consecutive images (i.e. the gallery) and style it:

.markdown-content {
  img {
    max-width: 90%;
  }
  p:has(img) {
    em {
      display: block;
    }
  }
  p:has(img + img) {
    img {
      max-width: 45%;
    }
  }
}

With the above CSS you will get two images per line when they are grouped together (i.e. multiple images are wrapped in a single paragraph), while the images displayed alone (i.e. an image is wrapped in its own paragraph) can still use the larger width available.

Finally there is also some CSS that styles the caption (em).