I’m about to roll out a new version of my website,
a version based on John Macfarlane’s excellent
Yst is a nice little program that takes some
yaml data files
(or csv, or SQL) and some templates and builds a static website.
The documentation on the github page is a little spare,
so I thought I’d write an introduction to the program.
This will be super basic, but I hope it will help some people
take their first steps.
This is the first of a projected series of posts on yst. The series will live in this category. I’m writing this more to get clear in my head what the structure is. It’s a little confusing at first because you need quite a few files working together to get things working.
First, what is yst and why would I use it?
Here’s what attracted me to the idea:
I can have, say, my list of publications
or my list of conference talks as yaml data.
I can then use yst to build a CV page for my website.
I can also use yst to generate a
for a pdf version of my CV.
This way, I don’t need to make the same edits in two different places when
I give another talk.
Yst uses Pandoc under the hood, so you could in theory also generate an ebook of your CV, or any number of other output formats that Pandoc supports. I can’t believe I just used the phrase “under the hood”.
What I am not going to is explain how to install Haskell, Cabal, Pandoc and Yst. The instructions on the yst site were enough for me, and I don’t really know any more about the process than I learned from reading that page. So I will jump straight to building a site with yst.
On the yst documentation it recommends running
yst create mysite
to generate a sample site for you to play with.
The documentation then goes through some of the cool stuff
that this sample site demonstrates.
I did this, but I found it a little complicated to get my head around
So here I’m instead going to start from scratch and build things up very slowly.
The intention here is that we will end up at a point
where you will be able to understand what the sample site is showing off.
Incidentally, the documentation is in the
README file in the
The first thing to do is to move to your new directory
and create a file called
This is the file that yst will look at to work out what’s going on.
Here is the
config.yaml that the starter site generates:
1 2 3 4 5 6
The important lines for now are
title will appear in the
<title> of your website.
You can change it to whatever you like,
but beware the “yaml gotchas” mentioned in the
The main page we will need is the
index.yaml file mentioned
Let’s make one of them now.
index.yaml file basically lists all your pages
that will appear on the site.
Here’s a very simple example.
1 2 3
All that’s listed here is the url of the page to make, the title it should have, and where its template lives. Later on we’ll see more complex versions of this scheme.
We now need to write
This will be where the main content of the page is written.
You can basically write this page in markdown.
Here’s my simple example.
1 2 3
Before we continue, we need one more file.
layout.html.st file is basically the place
where the html template for the site lives.
Copy the version from the starter site for now.
At this stage, I just want to point out one thing about this.
Look at the
It should say:
This uses string templates to replace the text between
dollar symbols with the right stuff.
$sitetitle$ is the title of the site,
as set by the
title line in
and then a dash and then
$pagetitle$ as set by the
of the page in
We’ll see some much cooler examples of string template’s
Note also that the
So you should now have a directory with the following files in it:
You should now copy the
of the sample site into
files/css/ of the basic site
we are creating.
The css is a mess, but it’s easier just to do this
yst inside this directory should
generate a very basic website.
It should generate a folder called
site with a file called
(and the css directory).
index.html file should appear more or less like this:
So this is the basic structure of files that
yst uses to build a website.
So far, this seems quite a round-about way of doing
something rather simple.
We needed a total of five files just to build a single
(That is, the four listed above, and a css file:
as things stand we actually needed a whole bunch of messy
css files, but that’s not important).
That seems overkill.
But things will make sense when we see the power of
the combination of yaml and string templates.
Next time, we’re going to see how to use other YAML files
to use some structured data and automagically have it added to our