Widget: Recent posts

A most common widget is the "recent posts" widget. Usually on the left or right side of a screen.

It is a simple widget that is a nice illustration of how to do some Liquid programming.

(Remember from yesterday that the top level "default" layout includes the right-aside)

The right-side.html looks as follows:



Yup, nothing special.

The widget itself looks as follows:



Btw, my site is in Dutch, so the <h1> text may look a little odd to you ;-)

The first Liquid tag "for" iterates over all posts that are present in the site. Note that the posts are in reverse chronological order. The "site.posts" is a site variable provided by Jekyll.

The "forloop" is a Liquid object containing attributes of the enclosing for loop. The "index" attribute refers -of course- to the index of the for loop. In contrast to many languages, the index attributes starts at 1 (i.e. not at zero!).

The "break" statement is used to abort the loop one the number of links is greater than 3.

The "post" variable is created in the for loop and refers to a post. Note that you can use any name, it does not have to be 'post'. Though it does kind-of make sense. Through the 'post' variable we have access to the predefined tags and the tags defined in the front matter for that post. The 'url' and 'date' attributes are predefined. The 'title' is read from the front-matter.

I also filter the 'date' with the Liquid "date" filter to obtain only the Year-Month-Day part of the date as I am not interested in the time.

All in all a simpel introduction into Liquid for a very useful widget.

Oh, I almost forgot, there is of course an associated SCSS file for this widget:



In showing you this SCSS it occurs to me that I have to clean up the layout SCSS, as the fix for the layout problem in the narrowLayout should not be at this level! Sorry for that...

A classic website design

In a previous post I have shown which design I wanted for my website.

In Jekyll I use three different "layers" for this design. The first layer is found in the "_layout" folder, the second in the "_includes" folder and the third in the "_includes/widgets/" folder.

The default layout for my site looks as follows (note: This is not final!):



At the "_layout" level I like to use "panels" for positioning. The design is simple at this level, and there are only two things worth noticing:

1) The "right-aside.html" file is included twice.

I quite dislike doing this, but I currently see no other option to have one and the same content to appear in two places. Only one of those places will be actually shown in the browser. Based on the width of the browser window. The only reason why I think this is acceptable at all is because the contents of the right-aside.htlm is pretty short. Its just a few hundred bytes, so it does not inflate the file too much.  When compared to an image it is negligible.

2) The  tracking code at the end.

Most people will want to track the usage of their site. When developing we have to view the results again and again, and having these test-viewings also download the tracking code every time is simply not necessary. It will also skew the results and create additional load on your development machine. Hence I use a Liquid statement to test the environment variable to see if this is a production build or a development build.

By testing for "production" we make sure that the "$ jekyll serve" will not include the tracking-code.html.
For production we have to build the site with "$ JEKYLL_ENV=production jekyll build" to have the tracking code included.

Btw: The tracking code from Google is javascript... so much for my attempt not to use JS.

The "navbanner-panel"

This panel has a dual function. Originally I wanted to keep the navbar and the banner in separate  panels, but that was not possible due to the constraints on the CSS ":checked" selector. That selector can only used on siblings and child elements. Hence the banner -which contains a checkbox- had to be at the same level as the navigation bar (which is resized by the checkbox).

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.

Creating a classic layout

For my site I will be developing a classic layout as shown below:

As you can see, it will be a RWD layout for three sizes: Big, Small and Narrow.
The big layout will show a banner (grey), below that a navigation bar (Orange), below that three columns: a left aside column (yellow) a right aside column (blue) and the main content (green). Below this all will be a footer (pink-ish).
The small and narrow layout will not show the navigation bar when initially shown, but will instead have a menu-button in the banner. When that button is activated, the navigation will appear in the indicated position.

I was not up-to-date with HTML5 and CSS3. So right of the bat I could see that I needed to solve a couple of fundamental questions:

1. What mechanism do I need to differentiate between the three layouts?
2. What mechanism do I need to implement the hiding/unhiding of the navigation?
3. What mechanism do I need to change the ordering of the panels?

Not being a complete novice it was obvious that I could solve this in javascript. But that was not the route I wanted to take. Remember from yesterday's post that I wanted to avoid javascript.

The first thing I always do is to google. Well... yes... but... that works, but the solutions found that way tend not to be... "up to date". Web technology still changes at a pretty pace, so most solutions you find right away deal with yesterday's technology. So I spend a couple of days scrounging the web and ultimately I found what I believe are the right methods for the job:

For problem 1: the "@media" CSS rule
For problem 2: the ":checked" CSS selector
And for problem 3: the display property with value "flex" and the "order" property

Btw: There is an excellent blog article on Flexbox principles here: https://css-tricks.com/snippets/css/a-guide-to-flexbox/.

However, before I dive into the design, next I want to talk about structuring the project in Jekyll first.

Installing Jekyll and first use.

Installing Jekyll was a breeze for me. All the prerequisites were in place so installing went without an hitch. The install procedure is documented here.
A tip: before you install Jekyll, first update the existing (Ruby) gems with:

$ sudo gem update

Of course you will need to do this in a terminal window.

Then you can install Jekyll:

$ sudo gem install jekyll

And that was all. Ready to create our first Jekyll project.

Make sure that the command prompt is in a directory where the project directory must be created. However keep in mind that this is the development directory, so don't create it in the place where the website will be placed.

Type the following:

$ jekyll new MyGreatSite 

Then cd to the new directory:

$ cd  MyGreatSite 

Again, that is all you need. Next we start the Jekyll build-in server with:

$ jekyll serve 

Now point your browser of choice to: http://localhost:4000.

You should be rewarded with a website with the looks of the default Jekyll template.

Jekyll Templates

Now, at this point you may want to start hunting for nice looking templates or theme's. But I would suggest that you don't. Downloading templates at this early a stage will complicate things before you are ready for it. At least it did so for me, I almost gave up on Jekyll. Luckily I knew I went too far and I backtracked to just the plain Jekyll install.

Instead I suggest you take the time to learn each of the tools used by Jekyll.

First become familiar with HTML and CSS. It is not necessary imo to go in depth, but you do need a working knowledge. As a free resource http://w3schools.com is hard to beat imo. Note that we will be building a site with HTML and CSS so having a good grip on them will be mandatory. However just to start out a rudimentary knowledge should suffice.

Assuming you are somewhat familiar with HTML and CSS, learn SASS in the SCSS flavour. Read through the documentation at: http://sass-lang.com/documentation/file.SASS_REFERENCE.html. Again, just become familiar with the concept, you will learn the true depths as you go along.

Then take a look at Kramdown, the online resource is at: http://kramdown.gettalong.org/documentation.html. Same rule here, just the skinny of it.

I saved the best for last: Liquid. If you are a programmer, a quick scan of the documentation at https://docs.shopify.com/themes/liquid-documentation/basics will suffice. If you are not a programmer, hmm, then make sure you become familiar with it as it is the real power behind Jekyll. This is what you really need to create your own site template (theme).

With this under your belt it is time to attack the default site head on. Study the workings of it, add a post, add a page. Then start changing the theme itself and implement your own design. That is a lot of work, but you will know exactly how the site works and how the tools interact. Which imo is invaluable.

You could now start looking for a theme (for example at http://jekyllthemes.org). Personally I did not find a suitable theme, and besides I really like the challenge of creating my own.

Besides, there are additional questions that needs to be answered before creating a design or adopting one: which market do you want to reach? Do you need to support as many browsers as possible? or is it acceptable to write for the most recent versions? Can you use javascript or do you want to avoid it? Must it be RWD?

The site I will be creating will be made with HTML5 and CSS3. I will try to avoid Javascript.

More about that design in the next post.

Jekyll, what is it?

Jekyll calls itself "A blog aware static site builder".

OK, so what is a blog aware static site builder?

To be honest I am not quite sure about the "blog aware" yet. But the static site builder is something I can wrap my head around. The main idea is that Jekyll is a transformation engine that takes some input files, processes them, and then spits out the (static) files for the website.

Why "static"?, well because there is no interpreter running on the server to process the files before they are sent on their way to the requesting browser. This makes the site fast. No, it makes the site VERY FAST. My old mac mini that I use as a web server did take its own sweet time in serving up PHP Wordpress content. But serving up the pages from a static site is near instantaneous. Very fast indeed!

But, what with dynamic content? Well, dynamic is overrated... no kidding. Yes some websites must be dynamic. But it turns out we can do an awful lot with static websites that include dynamic functionality from third parties. Often for free. So if we want users to be able to comment on our blogs, that is not really a problem. Just find a suitable service provider. I would hazard a guess that most private users and even small companies (that don't do web-based-business) can do just fine with a static website.

Back to Jekyll. So it processes input files. What input files?

This did take me some time to figure out. I thought that it would take some CSS files, some HTML files and then spit out the site. But I was thinking way... to simplistic. Yes, Jekyll is more than a simple merging of CSS and HTML files. It can do some real transformation along the way. So far I have discovered the following types of transformation.

1) It transforms files written in a Markdown flavour (I use Kramdown) to HTML pages. This is very handy when creating content. It is much quicker to create a post or page in Markdown than it is to create the corresponding HTML. The downside is that you have to learn the Markdown syntax, but that is rather easy, and it does take out the headache of writing every post or page in HTML.

2) It creates CSS from SCSS. If you are a web developer you are already familiar with SASS/SCSS. For us programmers, SASS or SCSS is a way better method to write CSS than CSS itself. It has familiarities with object oriented programming. I find it actually easier to learn CSS via SCSS than learning SCC in itself. But yes, it does mean that you have to learn SCSS as well.

3) It processes layout specifications written in a mix of HTML and Liquid to produce the static HTML pages. Liquid looks like a programming language. It has control statements, loop statements, formatting filters, variables etc. As a programmer it is easy to learn.

Workflow

The complete workflow (assuming the site template is ready) is as follows:

Add a post or page written in Markdown to the site, run the Jekyll build command, copy the generated files to the web server, and ... well nothing. That is all there is. The site has just been updated.

So that was easy. You must provide the editor to create the new post cq page. A plain text editor with syntax colouring for CSS/HTML like TextWrangler or BBEdit comes in handy. Also it is necessary to use the command line in the Terminal. That may feel unfamiliar at first but is no real deal breaker.

Site Template

Building the site template is a little more difficult. This is where real sweat is necessary. IMO it is necessary to be somewhat of a programmer to really love this kind of work. If you are unfamiliar with programming, CSS and HTML (and possibly Javascript) then Jekyll may not be your thing.

But I will write more about this as it is the subject of this blog. More to come...

Disclaimer

Please remember that I am just a (novice) Jekyll user. Any insights that I have I have from using Jekyll. What I write helps me in understanding the tool, but may be incomplete or even wrong in the eye's of the Jekyll developers.

A new Jekyll user

Website development in the early day's was simple: just drum up some html pages configure your server, and voila a new site was born.

But then... oh then...

Gone are the days where a simple site would suffice, where a single content provider made a site. Dynamic content was key. In came php and a whole slew of 'Content Management Systems".

I used to ... wait a moment, it might still exist ... yes, it does: http://lugt.home.xs4all.nl/tnp/. Well, I wanted to say that I used to have a site that was a simple html thingy. But it seems I still have! lol.

Later in life I had a few other sites, but by then I used Wordpress. I remember that I quite liked the "Suffusion" theme. Then came the iPhone's and iPad's. And today the keyword is "Responsive Website Design" (RWD = A website that works well on any device). Well, Wordpress can do that just fine, though the first versions of suffusion did not support RWD (I think??) and anyhow the frequent updates of Wordpress keeps one quite nimble... not to mention the gazillion of plugins... case in casu, I switched to the default Wordpress Themes to reduce the work overload. The not-so-nice (IMO!!) layout was taken as 'unavoidable'.

That worked fine for a while. Keyword is "while". For reasons unknown to me up to this date, at about Xmas time I would loose the content of the WP-database for some sites. Curiously enough not all of them, just some. And it would happen twice in a row, with about two to four weeks time in between. The first year it happened I kind of shrugged it off. Things seemed to work fine after restoring the sites. Until that is last Xmas. Same thing happened. Why? I still don't know. But by this time I had quite enough of it, and I was getting tired of Wordpress anyhow. To many updates, too many plugins, too complex, too slow. I wanted to go back to the early days of simple HTML, but then of course in a modern way... after all, we now have CSS3 and HTML5.

Lo and behold, as if ordered there fell a booklet in my inbox: "Static Site Generators" by "Brian Rinaldi". (Its free)

Nice enough booklet and a quick read. So static site builders eh? Yes that was just what I was looking for, thank you Brian! Since I am developing my sites on a mac, the choice was not all that difficult, Jekyll seems to be the bully on the block, so Jekyll it is.