"My weblog is getting pretty old" was the first thing I thought when I tried to update it to the
latest technology. And it's true, I've started my weblog on community server, moved it to wordpress,
tried to run it on Ghost and finally made the move to static HTML with Octopress.
The final move to a static HTML website has provided me with the best experience
so far. If you can afford to mess with HTML, Markdown and CSS than generating a weblog
based on markdown and some templates is by far the most flexible and most performant way
to run a weblog.
The downside for me is that octopress right now is very outdated on my machine. The buildscripts
that I use are a few years old and lack the necessary bugfixes to run them on Windows. Which
I still use at work.
After some searching however I found a good alternative to Octopress called Hexo. In this post
I will take you through the basics steps to set up a Hexo blog with a theme and a few plugins
to host the website on Github pages.
Step 1: Download Hexo and configure your website
The first step is to install Hexo on your machine. For this you need to install the hexo-cli
module using NPM:
npm -g install hexo-cli
The Hexo CLI module is designed to give you the necessary commandline tools to create a new static
website in a folder and generate the static HTML for that website among other utility functions that
you normally need to maintain a website.
To create a new website, execute the following set of commands:
hexo init [website]
cd [website]
npm install
The first command genrates a new folder with some basic configuration and templates.
Since hexo is essentially a set of node modules you need to run npm install to get
everything setup correctly.
After initializing the website you need to do some basic configuration for it.
You can find the site configuration settings in the _config.yml file which is located
in the root of the website.
In this file you need to specify the name and URL of the website and some basic information
about you as the author of the website.
You can check the website by running the following set of commands
hexo generate
hexo server
Open your browser and go to http://localhost:4000/ to see the results.
Step 2: Select a theme for your website
Hexo uses a set of templates to render the pages of your website. Templates for the
website are normally located inside a theme that you configure in the _config.yml
file.
The default theme is okay, but if you like to use something else, you can find quite a
few good themes on hexo.io.
To switch themes you need to find a new theme, go to its github repository and clone it
into the themes folder of your website. Once that is done you configure the new theme
in \_config.yml and run hexo generate to generate the website with the new theme.
Hexo themes have some configuration that comes along with them, so check out the \_config.yml
file inside the theme for additional settings. Some themes come with sample configuration files
that you may have to rename to configure the theme correclty.
Here's a tip for working with themes if you use GIT to store your website sources.
Make sure you either fork the theme or remove the .git folder from the theme folder so that you
manage the theme through the repository that holds the sources of your website.
Otherwise you will lose configuration settings that are required to properly generate the website.
Step 3: Install additional plugins
When you initialize a basic Hexo website it comes with very few plugins. Just a few basic ones
that you need in order to make things look right in combination with the landscape theme.
I had to add a few plugins to make the website look right for my weblog. Here's a short list
of my favorites:
hexo-renderer-marked
All of my blogposts contain weird line breaks to make the thing look right on screen without
me having to enable line wrapping in my favorite text editor. Hexo has the weird habit of rendering
those linebreaks.
The hexo marked renderer is a markdown rendering engine that enables you to configure how your markdown
should be processed. The module follows commonmark specs as much as possible.
My configuration for this module looks like this:
# Marked renderer
marked:
gfm: true
pedantic: false
sanitize: false
tables: true
breaks: false
smartLists: true
smartypants: true
You can download this module by running npm install hexo-renderer-marked --save
hexo-generator-category
If you like, you can include a page for every category you use on your weblog.
Add a property to your markdown files that specify in which category the post
belongs and install this module to generate a page for that category.
You can install the module by running npm install hexo-generator-category --save
hexo-generator-tag
I don't have a tag page in my navigation, but you can select a tag and go to a page
listing all the posts that are tagged with that particular tag. The hexo-generator-tag
module is required for this functionality, so I suggest you install this if you like
to enable people to browse your site by tag.
To install the module, you guessed it, use npm install hexo-generator-tag --save
hexo-generator-cname
One of the interesting features of github pages is the fact that you can use a custom
domain name for your github pages website. All you need to do is add a CNAME file with
your custom domainname in it and link the Github IP-Address in your DNS registration
to your domainname.
Hexo however, doesn't generate a CNAME file by default. So to get one, you need to
add the hexo-generator-cname module to your website.
The module uses the URL setting from your website configuration to generate the CNAME file,
so make sure that the URL corresponds to the custom domainname you have linked to the github
pages IP-address.
Step 4: Setup deployment to github
With everything set up it's time to deploy your new website. For this you need to add
one final plugin to Hexo. Install the hexo-deployer-git module using NPM and add the following
bits of configuration to your _config.yml file to set it up:
deploy:
type: git
repository: https://github.com/[username]]/[username].github.io
branch: master
Replace the [username] bits with your username and save the configuration.
Now you can run the following set of commands to generate and deploy your website:
hexo generate
hexo deploy
This will generate the HTML files and deploy them to the master branch of your personal github
pages website. Notice that the deployer will use a force push to update the branch on github.
If you plan on relying on the history of your master branch than I suggest you don't use this plugin
but deploy everything manually. In most cases however I wouldn't worry about it, because the generated
stuff matches what you've seen locally.
Final step: Moving over old stuff
Now that you've seen what you need to do to set up a hexo based static website it's time to move over your old stuff.
Since I was using octopress I had a relatively easy job. Copy over my markdown files to the \_posts folder and generate the website.
If you are coming from wordpress or some other blog platform you may want to take a look at the migrator plugins that are available.
There's a plugin for blogger, wordpress, joomla and if that doesn't work you can always try to use the RSS migrator plugin which works
well for the more obscure blog platforms.
If you haven't tried this stuff yet for yourself, please take 30 minutes and give it a shot! It may surprise you how easy it actually is.