Jekyll project structure

With Jekyll we need to differentiate between two folder/file structures. The folder/file structure of the project itself, and the folder/file structure of the website.

When a new Jekyll project is created the project folder/file structure looks like this:

BTW: This was created with the command: $ jekyll new zvt

When compiled with either "jekyll serve" or "jekyll build" Jekyll will add a "_site" folder/file structure containing the website that should be copied to a server.

Here is the same folder structure, now including the generated website (in "_site"):

The Jekyll site itself has a good description of the project directory structure and what file/folder does what, so I am not going to repeat that here.

In using Jekyll I noticed the following:

1) The Liquid "include" statement will only look inside the project "_includes" directory. There does not seem to be a way to add other directories to this. Thus when we want to create separate folders for different kinds of includes, we should do so as subfolders of the "_includes" directory. For example I created a "widgets" folder in "_includes/widgets/" to keep widgets that I may share between projects. In Liquid code these can be included as "widgets/<widgetname>".

2) Initially I started to use the "permalink" tag in the front end matter to specify where I wanted a page or post to land inside the website. That was a bad idea. Very soon I started editing the permalinks again and again to accommodate for minor changes. I got tired of that pretty quick. Jekyll is flexible enough and can map project file/folder structures onto website file/folder structures. I now use that instead and try to avoid the permalink tag as much as I can.

3) For posts, Jekyll will prefix the location of the post in the website with the categories that are specified in the front matter. I dislike that very much as it causes root-level directories to exist in the website that are content-oriented. I want my root-level folders to be function oriented.
Luckily Jekyll will create categories automatically if a post is located in a folder structure like "garden/beans/_posts/2016-02-13-plant-now.md". Note that the folder structure "_site/garden/beans/..." will be copied for this post resulting in a content oriented folder at the site root level. However, creating a folder called "posts/_posts/" and putting all posts in that will cause Jekyll to place all posts in "_site/posts/...". Resulting in a much more functionally oriented folder structure at the site root level. I thus do not use the default "_posts" directory at all.
There is a small drawback to this, all posts will now also have the category "posts". Thus if we want to do something in Liquid with the categories we need to filter this pseudo category out.

4) As I like to keep the root level of the website functionally orientated, I put all pages in a "pages" folder. For example the "about.md" is moved there. Note that it is necessary to remove the 'permalink' YAML code from the "about.md" file.

5) We also need a place to put stuff like images, sounds etc. These I will put in a resources folder (called "res") at root level. This way Jekyll will simply copy them without further processing (they do not contain YAML front matter)

The final file/folder organization looks like this:

Note that I did not put anything inside "subject-2" so Jekyll did not generate that folder in the generated site.

Note 2: the "_posts" folder can be removed as it will remain empty.

The generated site is relatively clean with just two files and four subdirectories. This will not remain so. As functionality is added more files and folders will appear. But at least this way I will have functional folders at the root level instead of content oriented folders.