Accessing Static Files in Jekyll

While investigating ways of using static files with Jekyll for a site prototype I was building, I learned that site.static_files was a thing. What is it and why you should care? Let me take a minute to share…

According to the official Jekyll documentation, “a static file is a file that does not contain any YAML front matter. These include images, PDFs, and other un-rendered content.”

The useful bit — every one of these static files becomes accessible to Jekyll when looping through site.static_files. There aren’t many reasons why you’d want to do this, but if building “plugin-free” image galleries is one of them — here’s how.

Organize Static Files

Let’s say you have a folder (named gallery-1) of images you want to display together on a post or page.

├── assets/
│   └── images/
│       └── gallery-1/
│           ├── foo.jpg
│           ├── bar.gif
│           └── yaz.png

Start a Loop

Using Liquid1 you’d start by looping through site.static_files and then narrow down the files based on their paths. In this case we only want to show those images that live together in assets/images/gallery-1.

{% for image in site.static_files %}
  {% if image.path contains 'assets/images/gallery-1' %}
    <img src="{{ image.path }}" alt="">
  {% endif %}
{% endfor %}

Which will generate into the following HTML:

<img src="assets/images/gallery-1/bar.gif" alt="">
<img src="assets/images/gallery-1/foo.jpg" alt="">
<img src="assets/images/gallery-1/yaz.png" alt="">

What if you’d rather spit out a group of thumbnail2 images that link to a full-size version? Completely achievable using the above method — if you are careful to name these files in a predictable way.

Start by creating thumbnail versions of each image however you’d like. The important part here is to be consistent with the naming of these files. For the sake of this example I’ll be adding the suffix -th to each filename and storing them in the same location as the full-size assets.

├── assets/
│   └── images/
│       └── gallery-1/
│           ├── foo.jpg
│           ├── foo-th.jpg
│           ├── bar.gif
│           ├── bar-th.gif
│           ├── yaz.png
│           └── yaz-th.png

Assuming a thumbnail and full-size image share the same base name, we can construct the gallery’s HTML with the following:

{% for image in site.static_files %}
  {% if image.path contains 'assets/images/gallery-1' %}
    {% unless image.path contains '-th.' %}
      <a href="{{ image.path }}">
        <img src="{{ image.basename | append: '-th' | append: image.extname }}" alt="">
    {% endunless %}
  {% endif %}
{% endfor %}

Now you may be wondering where basename and extname came from… simple. Each static file contains metadata accessible via Liquid with the following variables:

file.pathThe relative path to the file, e.g. /assets/img/image.jpg
file.modified_timeThe time the file was last modified, e.g. 2016-04-01 16:35:26 +0200
file.nameThe string name of the file e.g. image.jpg for image.jpg
file.basenameThe string basename of the file e.g. image for image.jpg
file.extnameThe extension name for the file, e.g. .jpg for image.jpg

Note: Filename Consistency is Paramount

Using this method to build a gallery of thumbnail images is fragile. The image objects inside of these loops are not validated by Jekyll at all. If you call in paths that don’t exist it will silently fail and leave you with missing images on the page.

Feedback and Improvements

In the end looping through site.static_files became an easy way spitting out a folder of files without having to hard code <img> elements. Sure there are a million different ways to do this with Jekyll, but this served a need and was a quick hack.

Curious if others are using static files in cool and interesting ways. Feel free to let me know in the comment section below if you are :smile:.

  1. Liquid is an open-source template language created by Shopify and written in Ruby. 

  2. Thumbnails are reduced-size versions of pictures, used to help in recognizing and organizing them, serving the same role for images as a normal text index does for words. 

Enjoyed this Content?

Help keep it free by sending a donation or purchasing something from my Amazon Wish List. You can also subscribe to various site feeds to get notified of new posts, follow me on social media, and more.



This is great! Thanks for share. I assumed that the “assets” folder is into jekyll site. But, what happend if you have a folder outside? I mean ├── folder/ ├── docs/ ├── _config.yml

And you want to retrieve that folder content?

Michael Rose

Don’t think that’s possible. GitHub Pages is treating the docs/ folder as its own contained Jekyll project and therefore can’t look outside of it.

Only option I can think of is to get crafty with Git submodules and pull in outside content.

Leave a Comment