Writing for The Gap Chess Club

Posted on March 28, 2018

Introduction

This blog is built using Hakyll, a static site generator written in Haskell.

If you haven’t used Hakyll before, this will walk you through what you need to know to get going.

If you have used Hakyll before, there are some customizations that we’re using that you should probably know about - so keep reading.

How to write a post

The first step is to checkout the from github.

The blog posts are all in the posts directory, so that’s where we add new ones.

If you’re working on a draft that you want to share with people in order to get feedback, you can put it in the drafts directory. It will be treated just like a regular post, but it won’t be linked from any of the other pages.

Similarly, you can add content to the links directory if you have information that you want to share with people that would be noisy or off-topic if it were linked from the other pages.

In either case, the content will be viewable by anyone who has the URL of the content (or anyone clicking through the github repository for the blog), but otherwise won’t be discoverable by people clicking around on the blog.

They are written using Pandoc’s Markdown syntax, which is worth getting familiar with.

There is also support for LaTeX. This can include the use of arbitrary packages, but there are currently a few steps involved in adding new packages. I’ll work on making this a bit smoother shortly.

The property block for blog posts

The posts need to start with a property block, that looks like this:

---
title: Chess is best
date: 2017-04-01
authors: tmorris
---

The title and date fields are mandatory. The blog will fail to build if you leave them out, but it’ll let you know why.

The authors field is optional. If it is set, it should be set to a comma-separated list of nicknames of the authors.

If the field is present, the post will be linked from the main page for each author. The post will also have footer entries which link to that main pages of each author along with a small blurb.

How to test out changes locally

There are two directories in the blog repository.

The generator directory has the site generator, and the content directory has the site content.

If you have Nix installed, you can use

nix-build release.nix -A generator

to build the site generator, which will be available in result/bin/site.

After that you can head to the content directory and run

../result/bin/site build

to build the site in _site, or

../result/bin/site watch

to set up a preview server on localhost:8000 that will update as you work on your posts.

Adding things

Adding a new author

There are three things to do to add a new author to the blog.

At the moment these are pretty free-form, but in the future we might add more structure for standard sections / features - like photos of the team members, etc…

1. Write an author page

Write a page about the author at ./people/<author-nickname>.md with the following property block at the start of the document:

---
title: <Author name here>
---

2. Write a snippet for the page listing members

This goes in ./snippets/people/<author-nickname>/page.md and requires the following property block at the start of the document:

---
title: <Author name here>
order: <What position on the page the blurb will appear at>
---

The blurbs will be sorted in ascending order by the numerical value of the order property. It is probably worth using the highest number not already taken.

3. Write a snippet for blog posts

This goes in ./snippets/people/<author-nickname>/posts.md and requires the following property block at the start of the document:

---
title: <Author name here>
---

Adding a new LaTeX package

At the moment this is a bit manual.

The blog currently makes the prftree package available.

If you want to add a new LaTeX package, you can add it to the lists of packages in default.nix and src/Site.hs that already contain prftree.

This will be made a bit easier later on.

Adding other content

Anything in the ./share directory will be served up as static content.

Conclusion

Blog early and often. Just have fun with it.

> Tony Morris

Tony is the Treasurer of The Gap Chess Club.