Customizing Gallery in Minimal Mistakes

Here are the customizations I’ve made to the gallery feature of Minimal Mistakes:

1. Add a columns parameter to each gallery to control the columns of a gallery such as:

   {% include gallery columns=6 %}

   The image size should be adjusted automatically.

2. Support adding images to a gallery by only using the image_path parameter or the URL in the front matter such as:

   gallery:
     - image_path: /assets/archive/image/foo/unsplash-gallery-image-1.jpg
     - /assets/archive/image/foo/unsplash-gallery-image-1.jpg
     - /assets/archive/image/foo/unsplash-gallery-image-1.jpg

   The gallery originally requires both url and image_path in order to have a pop-up view of the images. But I think it’s more convenient to write in this way. But you can still use both.

3. Use alt for title if title is unspecified.

4. Support Liquid links in the image title, e.g.,

   ---
   gallery:
     - image_path: https://i.postimg.cc/Vv8jFw8D/unsplash-gallery-image-1.jpg
       title: "Prompt: [[{{ site.baseurl }}{% post_url 2026-02-19-local-images %}][Local images]]"
   ---

All of these customizations are backward-compatible, that is, you can still write a gallery in the original way to get the original feel.

Here’s a demo gallery with the above customizations:

---
link_abbrs:
  - link_abbr: foo https://i.postimg.cc/Vv8jFw8D/
gallery:
  - image_path: foo:unsplash-gallery-image-1.jpg
    alt: "Use alt for title"
  - image_path: foo:unsplash-gallery-image-1.jpg
    title: "Link to post: [[{{ site.baseurl }}{% post_url 2026-02-19-local-images %}][Local images]]"
  - image_path: foo:unsplash-gallery-image-1.jpg
  - image_path: foo:unsplash-gallery-image-1.jpg
  - image_path: foo:unsplash-gallery-image-1.jpg
  - image_path: foo:unsplash-gallery-image-1.jpg
  - image_path: foo:unsplash-gallery-image-1.jpg
  - image_path: foo:unsplash-gallery-image-1.jpg
  - image_path: foo:unsplash-gallery-image-1.jpg
---

{% include gallery columns=6 caption="My custom gallery" %}

My custom gallery

Here are the steps to make the changes:

1. Copy the default gallery layout from the Minimal Mistakes gem (e.g. ~/.gem/ruby/3.1.3/gems/minimal-mistakes-jekyll-4.26.0/_includes/gallery) into your local _includes directory.

2. Apply these changes:

   diff -u minimal-mistakes/_includes/gallery josephs-blog/_includes/gallery
   --- minimal-mistakes/_includes/gallery	2023-12-15 19:03:51
   +++ josephs-blog/_includes/gallery	2026-03-01 23:18:56
   @@ -6,6 +6,8 @@
   
    {% if include.layout %}
      {% assign gallery_layout = include.layout %}
   +{% elsif include.columns %}
   +  {% assign gallery_layout = "custom-grid" %}
    {% else %}
      {% if gallery.size == 2 %}
        {% assign gallery_layout = 'half' %}
   @@ -16,6 +18,48 @@
      {% endif %}
    {% endif %}
   
   +{% if include.columns %}
   +
   +<figure class="{{ gallery_layout }} {{ include.class }}"
   +        style="grid-template-columns: repeat({{ include.columns }}, 1fr);">
   +  {% for img in gallery %}
   +    <figure>
   +      <a {% if img.url %}
   +           href="{{ img.url | relative_url }}"
   +         {% elsif img.image_path %}
   +           href="{{ img.image_path | relative_url }}"
   +         {% else %}
   +           href="{{ img | relative_url }}"
   +         {% endif %}
   +
   +         {% if img.title %}
   +         {% comment %} Parse Liquid syntax in titles {% endcomment %}
   +           title="{{ img.title | liquify | markdownify | remove: '<p>' |
   +                     remove: '</p>' | strip | newline_to_br | split: '<br />' |
   +                     join: '</p><p>' | prepend: '<p>' | append: '</p>' |
   +                     escape }}"
   +         {% elsif img.alt %}
   +           title="{{ img.alt }}"
   +         {% endif %}>
   +
   +        <img {% if img.image_path %}
   +               src="{{ img.image_path | relative_url }}"
   +             {% else %}
   +               src="{{ img | relative_url }}"
   +             {% endif %}
   +
   +             alt="{% if img.alt %}{{ img.alt }}{% endif %}">
   +      </a>
   +    </figure>
   +  {% endfor %}
   +  {% if include.caption %}
   +    <figcaption>{{ include.caption | markdownify | remove: "<p>" | remove: "</p>" }}</figcaption>
   +  {% endif %}
   +</figure>
   +
   +{% else %}
   +
   +<!-- Preserve the original style -->
    <figure class="{{ gallery_layout }} {{ include.class }}">
      {% for img in gallery %}
        {% if img.url %}
   @@ -33,3 +77,5 @@
        <figcaption>{{ include.caption | markdownify | remove: "<p>" | remove: "</p>" }}</figcaption>
      {% endif %}
    </figure>
   +
   +{% endif %}

3. Add these styles in your assets/css/main.scss:

   // Enable more columns in a gallery
   .page__content .custom-grid {
     display: grid;
     gap: 0.5em;
   }
   
   .custom-grid figure {
     margin: 0;
     width: 100%;
   }
   
   .custom-grid figcaption {
     grid-column: 1 / -1;
   }
   
   .custom-grid img {
     margin-bottom: 0;
   }

4. Create a new plugin file _plugins/liquify.rb to add a filter that evaluates Liquid syntax inside front matter strings:

   module Jekyll
     module LiquifyFilter
       def liquify(input)
         Liquid::Template.parse(input.to_s).render(@context)
       end
     end
   end
   Liquid::Template.register_filter(Jekyll::LiquifyFilter)