I remember one of the first ever ASP.NET projects I worked on, we were tasked with rebuilding a website for a company whose site was published as static HTML files. After editing their content in a CMS tool and hitting publish it would generate the entire site as a load of html files, doing the processing up front and then FTPing them all over to their hosting site. Surely replacing this with a nice new dynamic ASP.NET website with a database for the content was how you built modern sophisticated sites.
It’s funny how the world of technology is so cyclical. As quickly as statuc site generation tools went out of fashion, they come back around again. Recently when setting up this blog and looking into CMS options I found myself coming accros static site generators once more.
Static site generators have some very compelling benefits:
- Performance - static files are much faster to serve.
- Security - there is no risk of someone being able to gain access to your CMS and change your content.
- Hosting Costs - I’ve had problems in the past trying to run .NET based CMS platforms on cheap hosting with limited memory and compute resources. Even with cloud hosting costs can still add up. There are actually many free options for hosting static files.
- Design Flexibilty - In my experience many CMS platforms make it uncessarily complicated to create custom themes. Wordpress is a good example, making you dig through a mess of PHP code to change the html. Static site generators get you back to basics making this much easier.
Popular Static Site Generators:
There are many static site generators out there, for a list of options see https://staticsitegenerators.net/.
Always one to take a new challenge I set to work with one of the most popular generators called Jekyll.
Getting started with Jekyll
While docs are a useful reference, if you want to quickly get up and running with a basic site then there are plenty of how-to guides out there. The guide I found most useful was Smashing Magazine - Build A Blog With Jekyll And GitHub Pages
This link will talk you through the process of creating a site and hosting it on GitHub pages. So it’s a great start, If you just want to get a basic site together then you can fork an existing theme as described in the article. I came across a couple of great themes here:
However, I really wanted to use my own theme and quickly came across a few issues around posts grouped into categories with tags and a feedback form. I had to piece it all together from various articles on the web, so I just wanted this blog post to be my account of working through these more advanced features.
Organising blog posts by category and working with draft posts
To start creating blog posts you just need to a create special markdown files, if you are not familiar with markdown then here is a great cheatsheet https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
Most how-to guides talk you through the process of creating a folder called ‘_posts’ to put you markdown files into, but what I didn’t realise is that there can be more than one _posts folder. In fact, if you put a _posts folder within another folder it will use that folder name as the blog category. This is great because it means I can use the folder structure to organise my posts into categories.
Another useful fact is that you can create a folder called _drafts to store posts which are a work in progress. Then in development you can run jekyll with the following command to run the site and include any draft posts:
Listing Blog Posts (With Pagination)
One of my first challenges was listing the blog posts, but instead of an ever growing list of posts I wanted to page the results. We can do this using paginator.posts. The sample below shows looping through our pages of posts and listing some of the information about each blog post:
The obvious question here is what is the page size? We set this in our _config.yml file:
This will mean that our code above will only show 5 posts at a time. So the next thing we need are some buttons to navigate through the pages.
Using Blog Post Categories and Tags
One of the things I really struggled with was tagging and organising my posts into categories. I then wanted to create pages which list the posts within a category or with a certain tag.
To do this I first needed to label the posts. At the top of the markdown we can include a section to specify variables, so in this post I have the following header:
You can see from the above that I have given this post three tags. The category comes from the fact that this file is within a folder called /Development/_posts/.
The following code lists all the available categories with a link to a category specific page:
Category Landing Page
To create a specific category page I used the idea outlined in this blog post to first create a reusable layout
So the above code goes into a file called articlesbycategory.html in the _layout folder. Then for every category folder I have I just insert a file called index.html with the following content:
Tag Landing Page
I am also tagging posts, but didn’t want to have to create a new page for every tag I created in the same way I do with categories, so instead I just created one page which has all tags with the blog posts grouped below them. I can then just link to the tag within that page using an anchor. This page helped me with the following code to achieve this:
Tag clouds are a little bit old school, but I needed a way to list out the tags somewhere and came across this blog post and thought why not. So here is the code I am using:
Pretzel, A .NET version of Jekyll
While researching static site geneation tools I also came across a great C# .Net option called Pretzel. As a developer who spends most of his time with C# this looked perfect. One nice feature is that as well as using the Liquid templating language you can use .cshtml pages.
However there were a few sticking points for me. The first being that I couldn’t host the site on GitHub pages unless I used Liquid instead of cshtml which seemed a shame. Secondly I found that although most Jekyll/Liquid features are supported, some are not. I quickly got stuck with categories for example.
Jekyll has been a great learning experience, but hopefully Pretzel will catch up and at some point I will be able to start using that instead.
Recently there are a couple of very interesting Pretzel developments which I will be keeping my eye on: