Up and Running

Post Image
12/23/2016

At last! This site is now up and running.

For my first post, I will discuss what tools and technologies I used to build this site. I already created blogs in the past, starting with Blogger which allows you to quickly set up a blog without development knowledge. I then move on to WordPress and have to study a bit of PHP to be able to customize parts of my blog. Since I am more of a .NET developer, I started searching for a .NET based CMS and found several like DotNetNuke, OrchardCMS, and Umbraco. I ended up choosing Umbraco as I like how it treats contents as nodes of a tree that you can rearrange. It supports Razor for its templates that allow me to create custom functionalities like paging.

Now, it's 2016. I have planned to start a brand new personal site. My initial requirement for the engine I will choose is that it should be lightweight and only has the minimum features I will need to serve my posts. Umbraco and other CMS seems to be very feature-packed and I don't need 90% of their features. They provide update almost every week for components that don't affect or improve the parts that I am actually using. It's tedious to always perform updates to the engine so I initially think of creating my own blog engine from scratch. The problem with that is you need to know and guard against problems and security risks that current CMS and blog engines have already experienced and fixed. It wouldn't be wise to reinvent the wheel.

I have observed a proliferation of static site generators. They are most widely used for creating accompanying sites and documentations for open source libraries. Examples of these are Jekyll, GitBook, Octopress, and Gatsby. Unlike fully-fledged CMS, they are best used for serving static content, or content that doesn't change that often. This is why docs and blogs are perfect products of static site generators. They are also very lightweight and straightforward to use.

Using Wyam

Out of the available static site generators out there, I choose http://wyam.io/. It's made out of .NET and C# so I will have an easier time reading the documentation and source code of it to implement custom stuff. How it works is it treats contents as documents. Every document has a set metadata like such as title and description. Wyam has a collection of modules. These modules are capable of processing a document and emit a new document based off it. It can also add additional metadata for consumption of other modules. These modules are now lined up inside what's called a pipeline. You specify the list of modules inside the pipeline and they will be executed sequentially. You will find this concept similar to middlewares in Node.js and ASP.NET Core.

It's great because I can now use https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet to write the actual articles. If you are not familiar with Markdown, it is currently the most popular way to write formatted static content. It's easier than writing plain HTML. This Markdown file will then serve as our input document that we will feed into a Wyam pipeline using the ReadFiles module. The ReadFiles modules will emit the read documents and pass it to the next module in the pipeline. We then use the Markdown module to transform the passed Markdown documents into HTML that can be rendered by the browser. The result is finally then passed to WriteFiles module to write the file to the output folder. The contents of the output folder are what you will upload to the server and be served to the browser. To write the pipeline code, you prepare a file named config.wyam and this is what will automatically be read by Wyam. Here's an example code of a pipeline with the modules we have just discussed.

Pipelines.Add("Posts",
    ReadFiles("*.md"),
    Markdown(),
    WriteFiles(".html")
);

You can add additional modules in this Pipeline and there are lots of out of the box modules made available by Wyam. You can even create your own one written in C# using .NET's library. I can add another module called FrontMatter with the combination of the Yaml module to allow me to include pieces of information as YAML to my Markdown files.

---
Title:  "Up and Running"
PostDate:   2016-12-23
ShortDesc: My first post which discusses how I built this site.
---
My content begins here.
Pipelines.Add("Posts",
    ReadFiles("*.md"),
    FrontMatter(Yaml()),
    Markdown(),
    WriteFiles(".html")
);

FrontMatter will extract content until it sees the terminating line represented by --- and then pass the extracted content to Yaml module. The Yaml will convert individual lines into new metadata entries that can be used by further modules. One good example where you can use these metadata is in a Razor template. Yes, Wyam supports Razor templates and has a module to process that. Here's an extract of my default layout template.

... 
<head>
    <title>@Model["Title"]</title>
</head>
...

In Razor templates, the Model property will be of type IDocument and it has an indexer that access the MetaData property which in turn accesses an internal dictionary of metadata values that were collected from previous modules.

Threre's a lot more to discuss in Wyam than I can fit in a single post. Wyam is still fairly new as of this writing and it's gaining a lot of popularity really fast.

Using Cake for Building

If you would want to automate the building of your application via a Continuous Integration tool, then you will need a build tool for that. For .NET projects, MSBuild is typically used. I found an alternative one that uses C# to define its task. This is called http://cakebuild.net/ which is short for C# Build. With Cake, you have to create a build.cake file which is really just a C# file containing tasks. It has plugins or what is calls "script aliases" for common task like compiling solution projects, running unit tests, running other task runners like NPM, and communicating with Continuous Integration environment like AppVeyor (more on this later). It even has lots of extensions that was created by the community and again, you can create one yourself very easilly if a tool you need to use is not yet supported. The build.cake file is executed using a Powershell script that I just retrieved from the Cake build example repository.

As for Wyam, we need Cake to be able to call its executable to convert our input documents to output documents. Fortunately, the creator of Wyam created script alias for running the Wyam command. Here's an excerpt from this site's build.cake.

Task("Build")
    .IsDependentOn("Clean")
    .Does(() =>
{
    var wyamSettings = new WyamSettings();

    if (configuration == "Release")
    {
        Wyam(wyamSettings);
    }
    else
    {
        wyamSettings.Preview = true;
        wyamSettings.Watch = true;
        Wyam(wyamSettings);
    }
});

The WyamSettings class contains the options you can set when running the wyam command on the command line. When running the powershell script, you can pass a configuration argument so that you can define separate behaviors for Release and Development/Debugging. For my case, when I don't pass Release, then it means I am in Debug mode and I have set the Preview and Watch properties to true. The Preview option will run Wyam's development server on my local machine so I can look at my site prior to deployment. The Watch option will listen for changes in the input directory so I don't have to rebuild manually anytime I edit a Markdown file or any files within that input directory.

Using AppVeyor for Continuous Integration

For continuous integration (CI for short), I use https://github.com/randalvance/RandalVance.Website. With a CI like AppVeyor, I can connect my GitHub repo to it and listen for commits to the master branch. When I commit and push something to that branch, AppVeyor will check out that branch into its server and build it using a configured script file which is in my case, the Powershell script that will trigger the cake build. I can now see on every push if the build succeeds or fails and I will be notified in my email on the results of it. It's a nice thing to have a CI for your project as sometime later, you may not even know if your project still compiles because there could have been multiple updates to the libraries and tools your project is using that introduces breaking changes. Also, if you added unit testing in your cake build script, then CI will fail if a unit test fail and you will be notified immediately.

Deploying to Azure

There are great hosts out there for static sites that are free and easy to setup. One is GitHub Pages, which allows you to point to a certain branch with pages in it and it will be hosted by GitHub as a site. Another one is hosting to Azure which I end up choosing. I created a new Azure Web App and configured AppVeyor to automatically deploy the compiled artifact to azure once the CI succeeds. This gives me automatic deployment and I don't have to worry about manually uploading the output files via an FTP or Web Deploy. It's a breeze that you simply just have to commit your new post and push to GitHub and wait for a few seconds for it to be live on your actual site!