James Thorpe

Moving to Wyam

Dec 04, 2018 Site Wyam

I'm in the process of rejigging out my web portfolio (website, email servers etc), and since my day job involves using AWS, I figured now was a good time to begin moving there. I'm also about to embark on some electronics projects, and I wanted to have somewhere to write about what I'm doing. I really don't use my personal site much, so I figured I wanted something simple and static(ish) that I could serve from S3, perhaps with a lambda function or two at some point.

Having seen what other people are doing with the likes of Jekyll, I thought I'd go for a statically generated site too. Being a .NET developer, I wondered what there was in the way of site generator engines that ran on top of .NET Core. A quick search found Wyam, and a Blog post from Scott Hanselman exploring it a little.

That was good enough for me.

So, here I am - writing my first post inside this world. To start with, I ran a few basic commands. First up, I installed Wyam itself:

dotnet tool install -g Wyam.Tool

I created a folder to work in, and continued to follow the basic usage instructions:

wyam new --recipe Blog

And then jumped right in with:

wyam --recipe Blog --theme CleanBlog
wyam -p

This got it to self-host the site on port 5080. I tried out a few different theme options, realising that I could specify a theme using #t ThemeName in the config.wyam file it had generated. At this point I also quickly learned that re-running wyam -p also does a full build, no need to perform the first step repeatedly.

Having tried a few themes, I got to the point where I wanted to go back to basics, so headed off to the GitHub repository to download the files for a basic blog theme, to essentially start styling from scratch. These files got put into a theme subfolder, and were automatically picked up by wyam on the next wyam -p.

Inspecting the output files, I found it still including a lot of assets and such from another theme, and looking through the console output, I saw

Input path(s):
    file:///C:/Users/JamesThorpe/.nuget/packages/Wyam.Blog.CleanBlog.2.0.0/content
    theme
    input

So it was still using the CleanBlog theme in addition to my custom files. A quick addition to config.wyam stopped that:

#theme theme

I noticed the default blog pipeline also includes a Less preprocessor, so followed my nose and experiemented. Within the theme subfolder, I created assests/css and stuck a pft.less file within it. The default build found it and added assets/css/pft.css to the output.

I then wrote the above, so there would be a decent amount of starting text to play with some styling :)

Stopping and restarting the preview server was getting annoying to test out the styling/templating tweaks, so I went looking and found the watch option. I'm now running with

wyam build -p -w

Saving files causes a (very fast) rebuild without me running Wyam again. And I also just realised that it's live reloading the site itself in front of me - very nice.

I'm liking the fact I went with Wyam - being .NET based, the templates can be Razor views; something I'm familiar with. I've already tweaked and added to them - for instance there's now a partial view being fed a post as its model in a few different places to keep tag generation consistent:

@{
    var tags = Model.List<string>(BlogKeys.Tags, new string[] {""});
    foreach (string tag in tags.OrderBy(x => x)){ 
        IDocument tagDocument = Documents[Blog.Tags].FirstOrDefault(x => x.String(BlogKeys.Tag)== tag && x.Get<int>(Keys.CurrentPage) == 1); 
        if(tagDocument != null) {
            <a class="tag-link" href="@Context.GetLink(tagDocument)">@tag</a> 
        } 
    } 
}

At this point, I wanted to start syntax highlighting the <code> blocks on the site. I spent some time researching, found out about Wyam's pipelines with some pages about how to essentially create entire pipelines from scratch. All I wanted to do was to add the prettyprint class to my <pre> tags so I can use prettify. I figured there must be a way to alter the pipelines already defined by the Blog recipe I wa using, and started following through various sections of the Wyam code. I eventually wound up on this page, which gave me enough information to finally add just this little snippet to my config.wyam:

Pipelines["Pages"].InsertAfter("MarkdownFiles",
    Replace("<pre><code>", "<pre class=\"prettyprint\"><code>")
);
Pipelines["BlogPosts"].InsertAfter("MarkdownPosts",
    Replace("<pre><code>", "<pre class=\"prettyprint\"><code>")
);

Syntax highlighting now works.

More styling work, and refactoring of the default razor templates - all lists of posts are now being done through another partial view, so the home page, archive and tag pages are all via the same block of markup:

@model IEnumerable<IDocument>

<ul class="posts">
    @foreach(var post in Model){
    <li>
        <a href="@Context.GetLink(post)">
            <h2>@post.WithoutSettings.String(BlogKeys.Title)</h2>
        </a>
        @Html.Partial("_PostTagList", post)
        @Html.Raw(post.String(BlogKeys.Excerpt))

        <a class="read-more" href="@Context.GetLink(post)">Read more...</a>
        <hr>
    </li>
    }
</ul>

Again, a bit of trial and error and digging into the Wyam recipe internals led me to the right explicit @model to use for this partial view - the others have "just worked", but this one was throwing up some errors during the Razor rendering process without it.

At this point, I'm fairly happy with the overall layout and process. No one can see it yet, as it's still just sat on my local machine - the next step is publishing it up to S3, and re-pointing my domain at it. If you're reading this, it means I've now done that!