- Easing the management of images (and other files) attached to Markdown posts
- How does it work?
- Installation
- Usage
- Contributing
- License
- Thanks
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.
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.
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!
- Easy to store, everything is in one single folder.
- Easy to write, no path to add to file links
- Easy to update
- Easy to move from
_drafts/to_posts/, without anything to change in the Markdown content - Easy to edit in any editor with live preview
Some 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.htmlJekyll 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'
endThen 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.
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.
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent