Wordpress has done a decent job of running my blog. But I’ve longed for something leaner for writing developer code stories as the rich HTML text editor tends to introduce too much complexity.
Initially I thought about writing a custom blog web app but decided it would be better to consider existing platforms that can handle my requirements. Ultimately I decided to migrate my Wordpress blog to GitHub Pages.
Here’s a bunch of things I like with GitHub Pages compared with my self-hosted Wordpress site:
You can setup a custom domain for both an apex domain and www subdomain and GitHub Pages will handle the redirect.
Add A Records with your DNS provider for apex domain (without www.):
| Domain | IP address |
|---|---|
| YOUR_DOMAIN.com. | 185.199.108.153 |
| YOUR_DOMAIN.com. | 185.199.109.153 |
| YOUR_DOMAIN.com. | 185.199.110.153 |
| YOUR_DOMAIN.com. | 185.199.111.153 |
Add one CNAME record for www subdomain.
| Domain | Canonical name |
|---|---|
| www | USERNAME.github.io. |
However there are some downsides during this process:
GitHub Pages is powered by Jekyll. To import your Wordpress XML archive and run Jekyll locally you will need to install Ruby 2.1 or better.
If you are migrating an existing blog you have to export your content from the Wordpress admin control panel.
The general form of the URL is as follows:
https://YOUR-USER-NAME.wordpress.com/wp-admin/export.php
Import the Wordpress XML archive file as mentioned on the import wordpress to Jekyll docs
Install Ruby Gems
gem install jekyll-import
gem install hpricot
gem install open_uri_redirections
Convert Wordpress XML archive to HTML files and download images to ‘assets’ directory.
ruby -rubygems -e 'require "jekyll-import";
JekyllImport::Importers::WordpressDotCom.run({
"source" => "C:/Users/USERNAME/Downloads/REPLACE_USING_YOUR_FILE_NAME.wordpress.YYYY-MM-DD.xml",
"no_fetch_images" => false,
"assets_folder" => "assets/images"
})'
Convert HTML files to Markdown files. You can try any number of tools to see what works best for you. I tried various ones including the reverse_markdown Ruby gem and the html2text Python script. To help batch process the files I created a Wordpress HTML to MD gist to find any *.html files in the ‘_posts’ directory and convert them all to *.md files using reverse_markdown gem.
‘wordpress-html-to-md.rb’ gist usage:
gem install reverse_markdown
ruby ./wordpress-html-to-md.rb "_posts"
html2text usage:
./html2text.py C:/Users/USERNAME/git/blog/_posts/YYYY-MM-DD-filename.html
NB. Don’t use “\” in path otherwise you will get file not found error, use “/” in path instead.
To show code syntax highlights you will need to add some styles for Rouge (GitHub Page’s syntax highlighter). You can use Rougify to copy GitHub’s code syntax highlighting to a stylesheet.
gem install rouge
rougify style github > _sass/styles/_rouge.scss
After this you might decide to apply one of the built-in GitHub Pages themes or use a remote theme or create your own theme. In my case I added the Foundation XY-Grid module for responsive design grid layouts. One thing I would like to see supported in GitHub Pages is support for npm packages. Everyone seems to have their own way for building this out and it would be nice just to provide a package.json file and let GitHub take take of the rest. One nice solution however might be to roll out the node_modules dependencies as part of a remote theme. But at this early stage I prefer to keep it all together in one repo until I have proved everything just works over time.
You can find the source code of this website on my GitHub Page’s blog repo. I’ve also included a list of references below which I found useful during the creation of this new GitHub Pages blog.
Disqus can be added to a Jekyll site to enable comments on blog posts.
I added the XY-Grid SASS classes for responsive design layouts.
A Jekyll generated JSON feed can be used as the search index for lunr.js.
One gulp command deploys the production build to my gh-pages branch!