How to setup a blog with Wyam and GitHub pages

Published on Saturday, 4 November 2017

Introduction

This guide will walk you through how to setup a basic blog and how to use git hub pages to host it. This is not as straight forward as Jekyll because GitHub doesn't support server side compilation for Wyam.

To work around this we can use the git subtree push command to push the contents of the output folder to the gh-pages branch.

This can then either be done from your workstation or a CI server.

Installing Wyam

Everything you do in Wyam is driven by its command line tool.

To get it download the package from here (or use the chocolatey).

https://wyam.io/docs/usage/obtaining

Setting up page

I won't give you a complete walk through on how to setup a wyam page as they do a pretty good job of that themselves on their web site.

I will however give you the basic commands to setup a blog.

Create an empty directory for your blog and then run the following command:

wyam new -r Blog

This will take a while to run as it needs to pull down a heap of files off nuget (leave it be for a few mins it hasn't hung).

Once it finishes you can verify that it builds with the following:

Wyam build

Then you can preview it in your browser with.

Wyam preview

This will give you a URL you can punch into your browser to test it. Hit ctrl + c when your done.

Setup Git

First we need to setup a repository locally. To do this run the following command.

git init

Create a file called .gitignore and put the following into it:

tools/
packages.xml
config.wyam.hash
config.wyam.dll

Note: Output is not in the file above. This is not a mistake, more on this later.

Add the current contents to the repository with:

git add .

git commit -m "initial version under source control"

Now setup a repository on github for your page, this can be private if you want. If you do not know how to do this GitHub has lots of documentation which you can read here.

Now add the GitHub remote with the following commands (replace the URL with the URL from your repository you just created):

git remote add origin https://github.com/username/reponame.git

git push -u origin master

This will now have pushed your current changes to the repository.

Cake Build

Next thing we are going to setup is cake build which is a build script system written in C#.

In the root directory of the blog which you should already be in run the following command.

Invoke-WebRequest https://cakebuild.net/download/bootstrapper/windows -OutFile build.ps1

Next create a file called build.cake in this directory and put the following contents in it:

#tool "nuget:?package=Wyam"
#addin "Cake.Powershell"

var RootDir = MakeAbsolute(Directory(".")); 
var buildtarget = Argument("target", "Default");
var waymexe = RootDir + "/tools/wyam/Wyam/tools/net462/Wyam.exe";

Task("Build")
    .Does(() => StartProcess(waymexe, "build"));

Task("Preview")
    .Does(() => StartProcess(waymexe, "-p -w"));

Task("Deploy")
    .IsDependentOn("Build")
    .Does(() => 
    {
        if(FileExists("./CNAME"))
            CopyFile("./CNAME", "output/CNAME");

        StartProcess("git", "checkout master");
        StartProcess("git", "add .");
        StartProcess("git", "commit -m \"Checking output in for subtree\"");
        StartProcess("git", "subtree split --prefix output -b gh-pages");
        StartProcess("git", "push -f origin gh-pages:gh-pages");
        StartProcess("git", "branch -D gh-pages");

    });

RunTarget(buildtarget);

To test that it works run the following commands:

.\build.ps1 -target Build

Should build the project like before.

.\build.ps1 -target preview

Should let you preview the web site.

Don't try run deploy yet, there are a few more steps to setup.

Create empty GitHub Pages branch Next we need to create an empty branch for github pages. To do this run the following command:

git checkout --orphan gh-pages

This will create a blank branch ready for the Output to be pushed into it.

Change back to the master branch with:

git checkout master

Deploy

Now everything is setup and ready to go. Check all of your changes in and push them with:

git add .

git commit -m "Finished setting my blog up"

git push

Now we are ready to test the deployment.

.\build.ps1 -target deploy

This should create the branch on Git Hub which will be shared out as a web page.

Viewing page You can now view your web page at the following url (replace username with your github username and repo with the name of your github repository):

https://username.github.io/repo/

You can also view this in the repository settings on github.

Note: If your page formating is all screwed up and you just see plain text this is caused by settings in config.wyam.

You need to change Settings[Keys.Host] = "host.com" to put your username.github.io (replacing username with your github username).

Next add the following 2 settings to the file (replacing repo with your repository name).

Settings[Keys.LinksUseHttps] = true;
Settings[Keys.LinkRoot] = "repo";

Using a custom domain name If you want to use a custom domain instead of a github domain you need to do the following:

  • Follow this guide on how to setup a www domain.

  • The CNAME file created in the guide with your domain in it can be put in the root of the repository on the master branch and the cake script will copy it in everytime it deploys.

  • Now update the config.wyam file mentioned in the previous section: Set the host to your custom domain:

    Settings[Keys.Host] = "yourcustomdomain.com"
    

    Remove the following lines if you set them:

      Settings[Keys.LinksUseHttps] = true;
      Settings[Keys.LinkRoot] = "repo";
    

This can take a while to take effect depending on the settings you have on your DNS.

There is one key limitation on custom domains and that is HTTPS support, git hub only supports this when your using their sub domain. In a future tutorial I will go through how to use Cloud Flare to cache your site and add SSL support so it has HTTPS (they have a free tier which is perfect for personal blogs).

How to make further changes

Now all you have to do is whenever you make any changes to the site run.

.\build.ps1 -target deploy

This even works off a CI server as cake will download itself and wyam to do the deployment :).