I decided to have yet another attempt at adding a blog to my website.

All of my previous attempts have been using server-side blog packages, e.g. WordPress, b2evolution, etc. These have generally died when I've had to migrate to a new server (for various reasons), and have not copied across MySQL databases etc. The constant requirement to update WordPress to keep it secure was another admin burden that I didn't want.

This time, I decided to go with something really simple.

Scatter seemed to fit the bill. It is written in C#, so I would not need to install any more dev tools to compile it. It uses a simple templating system and article content is written in Markdown.

Scatter comes with a sample template, but otherwise practically no documentation. I've got it working through trial and error, so I'm going to document my experiences here!

Building Scatter

Scatter is provided as source code on GitHub. There are no binaries available for download.

I used the Download ZIP option to retrieve the source. The resulting archive was missing the MarkdownSharp project, which is linked as a git submodule and required to build the solution. I downloaded the MarkdownSharp source and extracted the entire archive into the /MarkdownSharp/ folder in the Scatter solution.

After that, it was as simple as opening in Visual Studio and clicking Build.

Structuring my website project

I decided to set up the following folder structure for the project:

• /dist/ - contains the generated output. Not checked into source control.
• /scatter/ - contains the Scatter binaries necessary to perform generation.
• /src/ - contains the Scatter templates and static content necessary to generate the site.
• /build.cmd - short batch file to clean the dist folder and then run Scatter to generate the site.
• /config.txt - Scatter configuration file - see below.

Within the /src/ directory, there should be two folders:

• /static/ - contains static files and folders that will be copied, unmodified, into the root of the generated site.
• /template/ - contains the HTML and XML templates used to generate the site.

This directory is also where any Scatter pages (.page) and posts (.post) files should be placed. These are written in Markdown and can be placed in subdirectories.

Config

There doesn't appear to be any documentation or inline comments describing how to use the config.txt file!

My final config was:

email: <redacted>
url: http://benjaminowen.uk/
path: /
title: Ben Owen
data_path: ./src/
static_path: ./src/static/
template_path: ./src/template/
web_path: ./dist/

I discovered that a trailing slash is v. important in paths - otherwise, generated files may end up being placed at the root of the disk (i.e. instead of D:\Working\Website\dist\index.html, I was seeing D:\index\index.html)

The path variable seems to be relative to the URL root, e.g. /ben/ corresponds to http://savoch.net/ben/ when uploaded to the server.

Custom index page

The index.html template provides the container HTML for all pages and posts. I wanted a custom layout for my home page which would include additional content without being wrapped in either the page or post templates.

To achieve this I forked Scatter and added a SiteIndexTemplate class to Scatter which is used to generate the root index.html page. This uses a separate siteindex.html template. This does mean there is a certain amount of duplication since both the Index and Site Index templates define the full container HTML. Once I'm more familiar with Scatter I might revisit this.

Markdown code blocks

Using the version of MarkdownSharp that I originally downloaded, code blocks (starting and ending with ```) were not preserving line breaks. I solved this by switching to a fork which supports Github-style code blocks. The main difference here seems to be that the output <code> tags are wrapped in a <pre> tag.

Layout and style

In keeping with the theme of simplicity, I didn't want a multi-megabyte (OK, I'm exaggerating slightly), 'kitchen sink' UI framework like Bootstrap or Foundation. I chose Skeleton, which provides a responsive grid and a handful of styles - plus a nice default font - out of the box. I've added a couple of custom CSS classes for icon hyperlinks, but mostly I've just left it all default.

For the icons, I used Font Awesome.

Template

I've built a template project including most of the changes I've described above (structure, config, custom index pages, markdown code block support and Skeleton grid layout). You can grab it from the scatter-skeleton repository on GitHub.