Jekyll's natural way to deal with static files attached to posts, like images or PDFs, is to put them all in a global assets/
(or downloads/
) folder at the site root. Read "Including images and resources" in Jekyll's documentation.
You can of course put files in subfolders of assets/
, but it will be really cumbersome to manage posts' Markdown files in _posts/
or a subfolder, and images elsewhere, and then use the good hierarchy in all Markdown image tags.
Imagine you have these files:
_posts/
2016-06/
2016-06-09-so-long-cloudflare-and-thanks-for-all-the-fissh.md
…
assets/
2016-06-09-cloudflare/
cloudflare-architecture.png
performance-report-sample.pdf
To use the image and PDF files in the post's Markdown, you will have to write this:
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
![Cloudflare architecture](/assets/2016-06-09-cloudflare/cloudflare-architecture.png)
Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.
Here is [an example of performance report](/assets/2016-06-09-cloudflare/performance-report-sample.pdf).
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
Painful to write.
Imagine you want to change the post's publication date, or one of the file names?
Painful to update.
What if you want to put new WIP Markdown files in _drafts/
, and the attached assets somewhere in a way they won't be copied to the destination _site/
folder next time you build the site? You can't put the files in the assets/
folder, so when you will publish the draft, you will have to change the assets location in the Markdown file.
Painful, and prone to errors.
And what about previewing the content while editing? If you use an editor like MacDown with live preview, how will it find the actual path to the images? What means /assets/…
for the editor?
Painful to preview.
What if instead, you could have the files stored like that:
_posts/
2016-06-09-cloudflare/
2016-06-09-so-long-cloudflare-and-thanks-for-all-the-fissh.md
cloudflare-architecture.png
performance-report-sample.pdf
And if you could write your Markdown like this:
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
![Cloudflare architecture](cloudflare-architecture.png)
Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.
Here is [an example of performance report](performance-report-sample.pdf).
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
Much easier!
_drafts/
to _posts/
, without anything to change in the Markdown contentSome Jekyll users will try to convince you it's a bad idea, because it means the asset is tightly linked to the post.
In my own experience, 95% of assets, at least, are used in one single post. And this is pretty common to find such requests from users of other static generators, like Hugo (fixed in May 2015), Nikola (already there, but not obvious or user friendly), Octopress, etc.
But it's true this might not be ideal for all assets (the remaining 5%), so you can of course continue using full assets paths with /assets/…
to have a few assets shared by several posts.
This plugin takes any file that is in posts folders, and copy them to the folder in which the post HTML page will be created.
Let's say you have these files:
_posts/
2016-06-09-cloudflare/
2016-06-09-so-long-cloudflare-and-thanks-for-all-the-fissh.md
cloudflare-architecture.png
performance-report-sample.pdf
And your Jekyll settings for permalinks are these:
# Permalinks
permalink: /:year/:month/:day/:title/
Jekyll with this plugin will generate the site content like this:
2016/
06/
09/
so-long-cloudflare-and-thanks-for-all-the-fissh/
index.html
cloudflare-logo.png
performance-report-sample.pdf
If you change your Jekyll settings for permalinks like these:
# Permalinks
permalink: /:year/:month/:day/:title.html
Jekyll with this plugin will generate the site content like this:
2016/
06/
09/
so-long-cloudflare-and-thanks-for-all-the-fissh.html
cloudflare-logo.png
performance-report-sample.pdf
Handy, isn't it?
Add gem 'jekyll-postfiles'
to the jekyll_plugin
group in your Gemfile
:
source 'https://rubygems.org'
gem 'jekyll'
group :jekyll_plugins do
gem 'jekyll-postfiles'
end
Then run bundle
to install the gem.
You don't have anything to do.
Just put the images (and PDFs, etc.) in the same folder as your Markdown files, or even subfolders, and use the standard Markdown image syntax, with a relative path.
:warning: This plugin is not supported by Github Pages, host your site on services like https://netlify.com which support third party plugins.
Thanks for your interest in contributing! There are many ways to contribute to this project. Get started here.
The gem is available as open source under the terms of the MIT License.
Inspired by this old Gist by @kevinoid.