For the last month or so, I’ve been deeply investing my spare time into writing a website for a conference, the UK Exoplanet Community Meeting 2016, or UKEXOM 2016 for short. Early on we decided that the best way to host it would probably be to use Amazon’s pretty nifty S3 service. This comes with clear advantages. Very high uptime, low latency file hosting at a very low cost. This method also has a clear disadvantage, it does what it says on the tin. It is simply dumb file hosting. That means you get none of the finer things in life you can expect of modern web hosting, such as maybe a nice PHP or Node.js stack, MySQL or even an Apache server with which to do the most basic of configuration. It very quickly became apparent that to make the website nice to both read and write I’d need to find a pretty elegant fit for these constraints. Luckily, I managed to find one in the form of Wintersmith.
Hello, Wintersmith
When I first came across this problem, I thought I’d have to head to a place where I have never before ventures, that of build systems such as Grunt or Gulp. I’d never used these before, so I was less than keen to learn them just to tackle a quick turn around project I was working on in between other research related work. However, I then came across Wintersmith, which solves all of these problems. Wintersmith is described as a simple to use static site builder, and that’s just what it is. Based on your templates, code and content the package generates a static site for you in an instant. The most impressive part is that these sites contain some of the hallmarks of modern dynamic websites, such as a blog and RSS feeds. To get up and working with Wintersmith you’ll need an install of Node.js, complete with npm, on your system. Now, we can globally install Wintersmith using npm with the command
npm install -g wintersmith
This will globally install Wintersmith for your node installation. The next thing that my be useful to do would be to get the demo website to take apart and see how everything works. You can do this by navigating your shell of choice to the required folder and running:
wintersmith new <name>
where name is the name of the website you’d like to make. When this command has run you have a directory populated with the files necessary to put together a basic website with blog. The directory structure can be a little daunting, so I’ll briefly go through it now.
- contents – As it says on the the tin, this directory contains the content that is going in to your website. This contains things such as pages in the form of Markdown files, as well as any blog posts that you might want to publish. These are contained in articles, with each post getting it’s own folder. This way you can conveniently group together all the resources for a given blog post in the same directory, making it super easy to reference them in posts. The authors subdirectory contains JSON files describing the authors that are to be posting on the website. You can put all of your images, CSS, and Javascript files in here to. You can easily refer to these from within your templates using Wintersmiths content tree, so for example if I wanted to embed an image from the images directory within a Jade template, I could do it like so:
img(src=contents.images['image.png'].url)
- plugins – This is the directory that contains the plugins to be used by the plugin system of Wintersmith. By default the only plugin is a coffeescript file that manages pagination within the blog. I have not had much of a chance to play with this feature, however there are a plethora of plugins available on the Wintersmith Wiki.
- templates – This is where the templates that make up the pages on your website are actually contained. In the default install Wintersmith uses Jade for templating, which is my template language of choice anyway.
Inside the root directory, you will probably also notice the config.json file. This file contains the configuration information to be used throughout your website. This is settings such as which plugins to load, which node modules to use for Jade and Markdown compilation and even local variables that can be referred to anywhere in your site.
Now that we have the basics down, I’m going to take you through some of the basics of setting up your own website.
Setting up an Author
First job to get done is to set yourself up as an author. You can do this by going to the content/authors directory and making a new JSON file with your preferred username. For example, my username file is smorrell.json. Inside this file you should now type out the settings for your user. I’ll include my user file as an example:
{
"name" : "Sam Morrell",
"email" : "smorrell@astro.ex.ac.uk",
"bio" : "Postgraduate Research Student in the Astrophysics Group at University of Exeter."
}Now you’re ready to being writing content.
Writing your First Article
Now that you’re set yourself up as an author on your website, you can write your first article. To do this, go to contents/articles/ and create a new folder with the address for your article, so for example I will call it test-article. This will mean that the address of your article will be http://<address>/articles/test-article/. Inside this newly created directory, make a file called index.md. This is the file that will content the text for your article. Here’s an example of what should be in this file.
--- title: Testing Wintersmith author: smorrell date: 2015-12-02 12:00:00 template: article.jade --- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc sollicitudin tortor sed consequat fermentum. Donec tincidunt dui at arcu scelerisque, eget dictum nisl vestibulum. Nullam orci mi, maximus sit amet pharetra quis, scelerisque quis orci. Suspendisse et arcu rutrum, volutpat lacus at, vulputate ipsum. Maecenas ut orci maximus ante tincidunt vehicula nec ut mauris. Integer sed ante ipsum. Fusce facilisis ligula non elit euismod, vitae finibus nibh mattis. Quisque euismod sem sit amet dui rhoncus scelerisque. Quisque sed massa dolor. Nunc sit amet fringilla tellus. Nunc faucibus nunc sed ex lacinia, quis lacinia massa vulputate. In convallis, tellus a ultricies rutrum, arcu ligula ultricies sapien, ac tristique eros sem sed turpis. Duis ut tellus id orci feugiat porttitor. Aliquam erat volutpat. Sed sodales eros sit amet nulla lacinia interdum. Integer quis dolor neque.
I want to quickly draw your attention to the text contained between the —s at the top of the file. This is the header and contains all the meta data for the article. In this case it’s title, the author that wrote it, the date it was published and the template that you want it to be displayed in. You can also add images to these articles by placing them in the same folder and then using this snippet of Markdown:
You replace the text in the square brackets with the alt text that you want to correspond to the image and the text in the normal brackets with the file name of the image.
Another neat thing about Wintersmith is that when you give it articles, it automatically makes an rSS for you. If you navigate to http://<address>/feed.xml you should see the feed of all of your articles.
Making a Page
If you’ve cracked how to write articles, you almost certainly know how to write pages. The files take the same format as articles, but the difference is that you place them in the root of the contents directory. So for example if you wanted an about page, you would write the markdown for what you wanted to be on the page, complete with the little meta data header, and then save this to contents/about.md. In your final site, this page should be visible at http://<address>/about.html.
Previewing and Building
Wintersmith contains a really useful http server for previewing your site as you’re making it. This will render the pages as they are requested. You can startup a preview server from a terminal by typing:
wintersmith preview
in the root directory of your Wintersmith website. This should start an HTTP server on port 8080, which you can access by navigating to http://localhost:8080/ in to your favourite web browser.
When you’re happy with your site and want to export it and upload it to your web host of choice, simply use the command:
wintersmith build
in the root directory for your site and all the files you need are exported to the build directory. Simply upload the entire contents of this directory and away you go. When you want to update your site, just build again and repeat the process.
It’s no doubt that Wintersmith is a really useful tool to have in any web developers belt. If you want the flexibility of a dynamic site with the hosting constraints of a static site, Wintersmith is just the tool for the job.
