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 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!
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.
/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.
There doesn't appear to be any documentation or inline comments describing how to use the
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
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
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.
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.