Local post assets with Jekyll

I was wondering how other people are organising their assets for individual posts when using Jekyll. For example, if a post has an image, do you just dump it in a shared images folder? I don't really like the idea of doing this - it means that an image is completely separated from a post, when I think they should be paired.

I wrote a plugin to let me organise assets in subdirectories easily:
https://github.com/samrayner/jekyll-asset-path-plugin

{% asset_path my-image.png %}

in post 2013-01-01-post-title would output:

/assets/posts/post-title/my-image.png

in page my-first-page would output:

/assets/my-first-page/my-image.png

I prefer to think of images as stand alone assets that are included in zero or more pages. Most of the time, my images show up in a single page. There are times when I want to have them in multiple pages and in other cases I don't link an image at all. If your workflow is to put each image in a directory with a post, finding them starts to require a significant amount of searching and you have to come up with something different for images that don't belong to a specific post.

The approach I use is on the opposite side of the spectrum. I have a single image directory (served from "/images") and 100% of my images are housed there. Benefits of this are:

1. When I'm adding an image to a post it's easy to know what path to use. It's always:

    /images/{image-name}
   

   For example: http://alanwsmith.com/i/aws-20111017--0906-02. This makes it possible to write a plug-in so all you have to enter is the image name and the rest of the known path is filled out automatically.

2. With an application like Photo Mechanic, it's incredibly easy to browse the single directory locally and see every image. If I want to include an image on another page, this drastically reduces the time to find it.

3. There isn't a separate location/process if I want to send an image to someone without actually including it in a page (i.e. send them a direct link to the image file). I just throw the image in the standard directory and send the direct link.

If you want to get a little more advanced, keeping all your images in a single directory makes some nice tweaks possible as well. For example, even though the URLs for my images start with "/images", the images are actually stored in a directory outside of the ones jekyll uses. In my case, the top of my source tree looks like this:

./html
./source-files
./image-files

All of my images are stored in the "./image-files" directory. In my apache config, I've setup an alias so that the URL "/images" points to the "./image-files" directory. For example:

Alias /images /webroot/image-files

When I run jekyll, it process everything in "./source-files" and drops it in "./html". Because all of the images are outside those two directories, jekyll never sees/touches them. As your image library grows this will help speed things up and will prevent a tremendous amount of unnecessary file copying.

Another tweak I like in Apache is turning on:

Options +MultiViews

This lets you call your images without having to use the file extension (e.g. no '.jpg', '.png', etc...). You can see that in the example link I provided above. It doesn't really matter for performance. I just like the way it looks and it saves me from having to type the extension every time I'm calling an image.

MultiViews also makes it possible to replace an image of one format with another without having to recode anything else. For example, if you remove "some-image.gif" and replace it with "some-image.png", you wouldn't have to touch any HTML. It would still be served form "/images/some-image". Needing to make changes like that is probably exceedingly rare. I just think it's an interesting thing to be able to do.

Finally, you can make a single decision about allowing or disallowing your image directory to be browsed. Personally, I only want my images to show up where I place them. So, I've set the .htaccess file in my images directory to:

Options -Indexes

If you are going to be working on a site with many thousands or tens of thousands of pages and images, this might not scale. For a normal sized, personal site, I find that this approach makes maintaining images easier.

I have now managed to develop a Jekyll plugin that helps keep posts assets alongside the Markdown file: https://nhoizey.github.io/jekyll-postfiles/

Just like you, I really hate having all images in one single shared folder.

Most, if not all, of my images are useful in one single post, and keeping them alongside the Markdown file is really better for posts management:

• I can drop a new post as one single sub-folder of /_posts/ in one step, without having to put the Markdown at one place and the image(s) at another
• When I want to edit the image(s) of an existing post, I don't have to find the right image in a huge /assets/ folder, it is located just near the Markdown file
• In my Markdown, I can use the image file name directly, without any path
• If I want to use any Markdown editor with live preview, it works, no need for a specific assets folder configuration

I tried to have this for my blog (example post here).

For responsive images, I used the Jekyll Picture Tag plugin, but I had to fork it, because the Pull Request to deal with such paths was not accepted.

Now that Jekyll 3 is there, I wish it could let us use images both in a post folder AND in the /assets/ one, looking for an image marked with ![alt](image-file-without-path.jpg) in both, in that order.

For JavaScript and CSS, you may want to consider an asset pipeline. You can get a good performance improvement through bundling and compression. I also use CoffeeScript and Sass, so I needed a preprocessor to convert my assets. I use Jekyll Asset Pipeline to manage this whole process automatically when I run the jekyll command.

For images/video, I recommend you develop a convention for naming folders in your project. I generally have an "assets" folder then subfolders with the date of each post that holds the images related to those posts. If you have multiple posts per day, you might consider including the name of the post.

This answer:

• Does not use plugins (works with GitHub Pages)
• Allows you to keep images directly next to their relevant posts
• Allows you to edit using Typora locally and see the images WYSIWYG

Just name your folders like _posts/2020-10-10-My-Title/ and include files like index.md and hero.svg or other images.

Then set your permalink: key in _config.yaml to :path.

Caveats:

• Your folder names must be sluggified
• Your images must all be SVG