My site will have downloadable things such as PDF books and posters. I’m inclined to make assets/downloads but want to find out if there’s some standard convention for doing this so my site won’t be confusing for others to maintain.
I’d recommend keeping content files (including PDFs, etc) outside of /assets. Jekyll’s Gem-based theme system uses /assets to share a theme’s design assets (CSS, JS, fonts, icons, etc). Files put in /assets override the theme’s files, so there is always a small possibility of a name clash.
It seems that Jekyll’s documentation doesn’t specify a convention for where to place static files.
It seems that you can access them via liquid using the {{ site.static_files }} liquid tag but I think most use cases for static files probably do not require this functionality.
I’d say that /assets is likely a safe location provided you put them in a separate subfolder as you suggested doing (i.e. /assets/pdf or /assets/static-files). Something that gets the point across.
I believe the use of an /assets directory in Jekyll derives from Ruby-on-Rail’s asset system, which similarly uses /assets to store design/framework files (i.e. non-content files).
The rule of thumb I use is: If I delete _site/assets, is the site still usable? I.e. can I still navigate around the site and access all important pages/images/documents (despite the lack of styles, background images, fonts, etc). If the answer is no, then some important content-file was incorrectly placed in /assets.
Keeping /assets clear of content-files makes it easier to switch themes or convert a site into a theme. Of course, except for gem-themes, this interpretation of /assets is purely a traditional convention and need not be followed.
Rather then use a generic URLs, you might consider designing your URLs to be human readable and to match the site’s structure. For example, the URL /posters/star-wars.pdf is preferable to /assets/downloads/00012.pdf. Some URL design references, if you are interested:
1 Like
Wow, I hadn’t thought about that before. On my old site I’ve been keeping logos, content images used in articles, and probably other stuff that doesn’t belong in /assets/images. And I will in fact have to upgrade that site to a new version of minimal-mistakes or some other theme.
What I did may be a bit overcomplicated but works fine:
We didn’t want all downloadable files to have duplicates in the _site directory since that eats up too much space. Instead we have a downloads directory somewhere else and set a symbolic link to that directory in the _site folder. The symbolic link is in keep_files in the config so it won’t get clobbered during site construction.
Should the original downloads directory do exist but the symlink in _site does not then a Jekyll hook plugin will create it via
downloads = "[ -d '_site/downloads' ] || ([ -d '../downloads' ] && ln -s ../../downloads/ _site/.)"
%x( #{downloads} )
so we are always on the safe side without ever creating a dead symlink.
You could even move downloads into the source directory. In that case you should exclude it in the config file.
This also makes the build process faster since all the downloadable files do not need to be copied every time. Sure, you can set Jekyll to incremental build but that is a huge pain with includes, thus needs a regenerate: true in the front matter of every site that uses them, but honestly this breaks more than it fixes.
This also had the nice side effect that we could push the whole thing onto a git server without all the binary files in downloads, making the git repository pretty small. Only downside: If you work locally you don’t necessarily have access to the most recent version of said downloads directory. The files can lie somewhere on a server and be managed seperately. Once you push to master a git post receive hook manages pulling origin master into a specific git repository, updates the downloads and builds the site, ready to be deployed as a website.
I’m sure there is some way easier method to do all this. That is what we came up with. Maybe this helps 
I noticed that this article seems to encourage putting them under /assets. https://jekyllrb.com/docs/posts/
I didn’t do that because I want to upgrade or change themes eventually and want to try to keep my own content separate. For what it’s worth, I created a/downloads directory at the top level and put my PDFs there.