Why move?

Originally this blog was hosted in Blogger, which I used between 2008 and 2012. It then fell in to disrepair until I ported it to an Umbraco site running on Azure, where I spent six months building the site and about ten minutes writing posts for that version of the blog. Add to that the suprisingly expensive hosting costs and it's easy to see why I lost interest again after another six months.

So, this time I wanted a platform that was going to be reliable, free, hastle free to build, and require no coding when I created new posts.

Enter Wyam

I first heard about Wyam when Scott Hanselman wrote about it a few years back. Wyam is a static site generator, but has so many more potential uses. Using Wyam inbuilt 'recipie' for a blog allows me to author markdown files and have them turned it to the shineyness you see before you now with minimal effort.

Dev setup

Installation was a breeze. Firstly I installed Wyam as a global dotnet tool

dotnet tool install -g Wyam.Tool

With the tool installed, I then uses it to create the blog

wyam --recipe Blog --theme stellar

This ran a series of pipelines which ultimately created a set of css and html files in an /output folder based on content I created in an /input folder.

Following the official docs and other blogs I came unstuck at a number of points. Mainly this was my fault for not reading these articles correctly, but I thought the most helpful thing I could do would be to share teh config.wyam file that I used for this site, because if you've ended up here you are likely stuck as well.

👨‍🏫 Pro Tip

Not sure how config.wyam should be set up. Head on over to the GitHub. site. There's loads of examples.

config.wyam

Here is my final config file...

System.Globalization.CultureInfo.DefaultThreadCurrentCulture
    = System.Globalization.CultureInfo.CreateSpecificCulture("en-GB");

#recipe Blog
#t Stellar

Settings["host"] = "www.gaisford.me.uk";
Settings[Keys.LinksUseHttps] = true;
Settings[BlogKeys.Title] = "On Software Engineering";
Settings[BlogKeys.Intro] = "My name is James. I am a Software Dev ✔ | Tech Lead ✔ | Devops Evangelist ✔ | Infrequent Speaker ✔ | DIY Master ❌";
Settings[BlogKeys.Description] = "On Software Engineering";
Settings[BlogKeys.IgnoreFolders] = "drafts";
Settings[Keys.DateTimeInputCulture] = "en-GB";

Most of the settings are fairly descriptive, but there's a few things to point out here...

Wyam has a number of settings defined in it's config file, which are split by keys generic to all Wyam builds (Keys) and those specific to the blog recipe (BlogKeys).

Settings[Keys]

Settings["host"] is used when generating links in your HTML, so it needs to match the URL of the site your hosting on.

Settings[BlogKeys]

Settings[BlogKeys.IgnoreFolders] allows certain folders to be ignored when Wyam is creating the blog. This allows me to create draft posts which don't end up on the live site until I move them in to the posts folder.

The path (or paths) in this setting are relative to the input folder. In my case the drafts folder which I ask Wyam to ignore is at /input/drafts.

Settings[Keys.DateTimeInputCulture] I had a bit of trouble getting posts to generate in my first nine or ten attempts. I was getting a message " ../ghostscript.md error while reading published date for feed"

I eventually figured out that by setting the DateTimeInputCulture explicitly and DefaultThreadCurrentCulture I was able to use the published date to the standard UK format of DD/MM/YYYY.

👨‍🏫 Pro Tip

Not sure how or where the settings are used in the blog recipe. Take a look at the GitHub page for the theme your blog is using. In my case, it's the Stellar theme.

Front matter aka post metadata

Front matter is a concept that allows you to add additional data describing your post to the same document as the main post. Front matter is added to the top of the post and is used throughout the recipe.

The docs here relate more to the use of Front matter in Wyam as a concept rather than specifically to the blog recipe, so that threw me off a little. If in doubt, consult GitHub to see where the recipe uses the Front matter.

Below shows the front matter contained in this post

Published: 22/5/2019
Lead: This blog is now hosted in Azure for free using Blob Storage and a CDN with a free SSL cert. There were a number of bumps in the road and this post highlights the issues with getting started with Wyam - which was used to build the site.
Tags: 
 - Azure
 - Wyam
---

Worth noting is the following;

  1. Date format in the Published property must match that set in your config.wyam.
  2. Lead: is used by the recipe to show an overview of your post in the Archive, on the front page of the site, and on the top of the page for the post itself.
  3. Tags: used to tag the post, but the format is as above for more that one tag, but can also be like this for a single tag - Tags: SQL Server

And that's about it. The site is up and running on Azure, with the workflow I was hoping for. It's hosted in blob storage with SSL (post soon?) and it's also set it up with CD using Azure Devops (post soon!), so feeling pretty please with myself.