Just recently I’ve been struggling with Ghost. It’s always worked flawlessly, but since I added SSL support its become kind of flakey, the site would be working and then BOOM nothing, Now this might be nothing to do with Ghost, it might be the way I have LetsEncrypts certificate set to automatically renew; it might be… but honestly I didn’t check.
Now this blog isn’t really anything more of a sounding board for things I’ve learnt, so missing traffic doesn’t bother me. What I have been looking for though is a little side project and recently I’d heard about Middleman (through the Changelog). Its a long-developed ruby based static site generator that supports modern development technologies such as:
- Optimisation techniques during the build process
- LiveReload during development
- Templates, including partials
Middleman runs on ruby and can be installed using a Gem:
$ gem install middleman
if your on OSX (like myself) then this should work out of the box. Once that was installed I did a quick google to see if I could find something that would replicate my existing theme, thankfully I found “Middleman Casper”. This provides a template fully compatible with Middleman using the Casper theme from Ghost, installation as with Middleman was simple:
$ middleman init -T danielbayerlein/middleman-casper ./squired.co.uk
Okay, so I have Middleman installed and a template, but I have no idea how to write Ruby and I have no content, tricky stuff. A quick look at the Github page for the template reveals some config options and a further look at the directory structure it created reveals a single markdown file (in the source/articles folder), the standard ghost “start here” post. This got me thinking; what if I could export my existing blog as markdown? Googles… and finds
[Ghost to md](https://www.npmjs.com/package/ghost-to-md).
Perfect! This little tool lets you take the export from ghost:
admin > labs > export
and builds individual markdown files. Firstly lets install it
$ npm install -g ghost-to-md
then lets point it at the exported data:
$ ghost-to-md ghost-export-file.json
this will generate a folder of “.md” files, so you’ll need to move them into the “source/articles” you found earlier. Now the template is programmed to find articles which are in the format:
and our new markdown files end in .md and don’t have .html in the filename so you’ll want to rename them either manually or using a tool of some description (I like Namechanger).
Next we should test our site and see how its looking. One of the great features of Middleman is the built in server, so lets simply run:
$ bundle exec middleman server
It should tell you the local URL you can view the site on, for example:
At this point I was able to see my content, but the formatting was broken within each of my own posts and none of the site images worked. Looking at the sample article I can see in the header some “FrontMatter” syntax, but my exported articles don’t have all the same properties… so I went through and added the “cover” and “layout”, below is an example from this post:
--- title: Ghost to Middleman slug: ghost-to-middleman date_published: 2016-06-12T16:00:00.000Z date_updated: 2016-06-12T16:00:00.000Z tags: ghost, ruby, optimisation layout: post cover: 2016/06/ghost.jpg ---
notice how the cover image is relative to the “source/images” folder? Bare this in mind when you add images to your markdown. After each file save the local development server will reload and you should see proper post formatting and cover images.
Next I started looking into how I might run the Middleman blog on my server, I use Apache normally and that integrates well with Lets Encrypt… fine, but how do I export the static site? Middleman has that covered as well:
$ bundle exec middleman build
You should find a folder “build” with a static representation of the site. You’ll also find a couple of settings in the ‘config.rb’ which allow you to optimise the resultant output, namely:
simply uncomment the lines and re-run the build command to see the affect.
We now have our formatted ghost articles in a static form and we want to get it onto a server, how do we do that? Middleman has a number of plugin solutions which you can install and test, however, I opted to SCP my files into the relevant directory, for example:
scp -r . firstname.lastname@example.org:/var/www/squired.co.uk/public
(I’m not going into any further detail about this because its out of the scope of the article and there are literally hundreds of different ways you can deploy code.)
I love it. Middleman and middleman-casper have helped me to quickly convert my blog from dynamic to static. A site I can now:
- Store in a git repository, without committing DB files
- Develop locally
- Customise the ghost theme easily
- Deploy to an S3 bucket for almost infinite scaling
- No longer have to worry about hackers breaching the ghost admin system
- Worry about updating the Ghost blogging platform
I might have to actually learn some of this thing they call “Ruby”…