tl;dr: In which Rik experiments with Hexo - learning how to start a new blog project with it, tweak the default theme, add Disqus to the mix for the comment-shiny, build the site locally, and deploy that build to an Amazon Web Services S3 Bucket.
Purpose
I’m on a bit of a learning binge at the moment and, for once, I want to document that learning as I go along. Thus the need for something where I can post my discoveries as I make them.
I wasn’t planning to build a new micro-blogging site. My original intention was to use a third party service. Things I looked at included:
- GitHub Pages - but Jekyll annoyed me.
- Google Cloud - simple enough, but I want to learn more about AWS st the moment, and going for the Wordpress option is overkill for my needs.
- Ghost - it looks gorgeous, and I’ve been wanting to play with it for ages, but for this exercise I don’t need the full admin console experience. Maybe next time.
I found Hexo by accident, going through a list of static site generators. The online documentation looked to be adequate and the setup seemed easy enough. There’s no console (out of the box) for preparing pages and posts; the creative writing happens in YAML files. It comes with a busy plugin page and some gorgeous themes.
I had to give this new shiny a closer inspection.
One thing I noticed was that a lot of the activity around Hexo seems to be coming from the Eastern Asia part of the world, which did impact on my research - my Chinese reading skills are seriously buggy; doing the copy/paste thing into Google Translator gets boring very quickly. But that is certainly no show-stopper: Hexo has a gentle enough learning curve to get it stood up and operational in no more than a couple of hours.
Hello Hexo, my new friend.
Hexo runs in NPM; the download is a set of cli commands which you use to create, build and manage your blog projects.
1 | $ npm install -g hexo-cli |
I was impressed! Everything just … worked. Even more impressive is that you can alter files and refresh the browser to see the changes in near-real life (no-toolchain heaven!)
Don’t forget the git
I’m not planning to host the code for this site on GitHub; doesn’t mean I can ignore the need to git my working directory. I added a .gitignore
file to the root directory (see below) and then initialized the git in the normal way - git init
.
1 | # excluded folders |
This theme ain’t good enough …
Hexo’s out-of-the=box functionality looks nifty; it’s theme less so. I did some investigating to see if there were things I could change. Turns out Hexo’s theming capabilities are very nicely modularized, and the CSS itself is very nifty. Under the hood Hexo seems to use Stylus for managing and building the code. Stylus was new to me, but I’m struggling to see much of a difference between it and LESS/SASS … well, my tinkering hasn’t broken anything yet.
I didn’t want to change the default theme’s code, so instead I created my own theme from it:
1 | $ cp -R ./themes/landscape ./themes/rikblogtheme |
The changes I made to my new theme were minimal. I decided I needed a banner that was a little more, well, me. To change the image I created something suitable (dimensions: 1920 x 1200), called it banner.jpg
and overwrote the original image in the /themes/rikblogtheme/source/css/images/
folder.
I also decided to make the base font size a lot bigger, and give links a better color. These values are set in Stylus variables in the appropriately named themes/rikblogtheme/source/css/_variables.styl
file:
1 | color-link = #800 |
Those changes don’t affect the header copy. To amend the header and strapline, and the menu links at the top of the site, I had to dig into the themes/rikblogtheme/source/css/_partial/header.styl
file:
1 | $logo-text |
To see these changes on the site, I needed to update Hexo’s nifty _config.yml
file.
Hexo’s nifty _config.yml file
The config file is at the heart of every Hexo-based blog site. It is pleasingly simple, with not too many options to worry about. Don’t misunderstand me: Hexo is a highly flexible blogging platform but, because much of its functionality comes from third-party themes and plugins, the core config file only has to worry about the essential stuff.
Before finalizing the config file I went away and set up an S3 bucket on AWS to host the production blog, alongside associated IAM and Route53 stuff to get the AWS magic to happen - material for a future blog post. The end result was a web address for my blog: http://code-blog.rikworks.co.uk/
- with such a snazzy name it will soon be charging towards the front page of the search engine results.
Rather than explain stuff, I’ll post the (almost complete) config file, with comments along the way:
1 | # Hexo Configuration |
Before moving on, I need to detail one gotcha which left me scratching my head for a while. Hexo has a cache. While this was not an issue while I was making changes to stuff locally - the server does admirable work catching those - I couldn’t understand why some changes wouldn’t deploy to AWS. The solution is simple: before building the site, get rid of the cache and public folder by running $ hexo clean
on the command line - problem solved!
Rik’s bespoke deployment-to-S3 code
Hexo has a community plugin to perform deployments to AWS S3 - hexo-deployer-aws-s3. I couldn’t get it to work; my .aws/credentials
file is too busy for the plugin, and I always forget to set the appropriate environment variables in the CLI before trying to do stuff.
Instead, I wrote my own solution. It involves adding 3 Javascript files to the project root folder and updating the project’s package.json
file so I can do the deployment from the command line.
Security warning: this solution involves hard coding my AWS keys into a file. Never commit a file with passwords, keys or any other security-related data to a git repository! When I was writing my .gitignore
file (above) I added a line to exclude any file matching the pattern *-env.js
which should be enough to keep me from sharing my credentials with the world … but mistakes can, and do, happen.
The following solution will, when supplied with a path to a folder and the name of an S3 bucket, upload the contents of that folder (but not the folder itself) to S3.
The solution uses Amazon’s wonderful and yet terrifyingly complex AWS Software Development Kit, which we first need to add to the code base by running a yarn command: yarn add aws-sdk
.
- Create a utilities file
utilities.js
where the bulk of the code will live:
1 | // Require statements |
- Create the deployment file
deploy.js
which node will run:
1 | // Require statements |
- Create the environment values file
aws-env.js
- this file must never be committed to a git repository
1 | const credentials = { |
We can test this code by calling it - hexo clean && hexo generate && node deploy.js
- to see what happens in the S3 bucket. If all goes well, I will get myself a working blog at http://code-blog.rikworks.co.uk/
- it works for me (and you: you’re reading it!)
Before this (very long) post finishes, I’ll share my package.json
file, where I’ve added a couple of scripts to save on typing. It’s not a proper toolchain, but it’s enough for my needs. To trigger the deployment, run yarn run deploy
on the command line. Magic!
1 | { |
Do you want to comment on this post?
By default, comments are not enabled in Hexo. To enable them you need to head off to see those nice people over at Disqus and get yourself a free tier account. Then you can come back to your code base and add just one single line to the _config.yml
file and rebuild the site and - comments!
After enabling comments for this site, I had to take a break and have a ciggie. Never has a comments system setup been so easy for me.
A big hat-tip and shoutout has to go to Ms/Mr Dreaming Engineer for their post explaining how to perform this special unicorn magic.
And now I’m done …