At the beginning of the new year, I decided to migrate my blog from Wordpress to Github Pages. Even though the process was pretty simple, thanks to a number of open-source tools, there were a couple of hurdles along the way, so I decided to create this step-by-step guide.
Setting Up the project
Start by creating a GitHub repository named
<username> is your GitHub username. In my case the repository is gromande.github.io:
Clone the repository to your computer:
Before creating the Jekyll site, you need to install Ruby along with the following gems:
- Jekyll (at the time of this post the latest version supported by GitHub pages was 3.8.4. Check out the list of supported versions here)
Once Ruby is install on you computer, run the following commands to install the gems:
You should now be able to create your Jekyll site with Bundler:
Jekyll allows you to run your site locally, which comes in very handy if you need to check how your posts look before making them public:
Open your browser and go to http://localhost:4000 to see the default homepage:
You can customize the site’s title, contact information, and social media links by updating the corresponding properties on the
_config.yml YAML file:
I also added the following property show an excerpt of my posts on the home page:
And changed the default post URLs to only include the title:
Some of this configuration parameters are theme specific. Check out the default theme for a full list of available settings.
Now is also a good time to put your Markdown skills to test and add your bio to the
Exporting Workdpress Posts
Fortunately, some people have gone down this path before and have created some useful tools to make the migration much easier.
For the most part, the steps below are described in this post in more detail.
Log into you Wordpress admin console and go to the following URL to export your Wordpress site:
Select “All Content” and download the export file to your computer:
The export file is in XML format and contains references to images and other assets. We can use the
jekyll-import Ruby gem to convert the exported files into HTML and download all images to the
Install the following Gems:
And run this command:
Lastly, use the following Ruby script to convert the HTML content to Markdown:
All you have to do now is copy the entire
assets folder to the root of your Jekyll project and move all the
.md files generate by the scrip from the
_posts folder into the
_posts folder of your Jekyll’s site.
Re-run you site locally and verify that all your posts are being listed on the home page:
From here, you can start customizing your site to your own needs. There are plenty of resources online so I am not going to cover customizations on this post. However, here are a couple of things you might want to do to “clean up” your posts.
If you open one of the Markdown files you’ll see a bunch of metadata fields at the top of the page:
--- layout: post title: 'Network Security - Part 1: Setting Up Your Environment' date: 2017-12-16 22:50:19.000000000 -06:00 type: post parent_id: '0' published: true password: '' status: publish categories: - InfoSec - Network Security tags: - pfsense - ubuntu - virtualbox meta: _edit_last: '1' _oembed_26e7131f86c1664c79f1dc834e460dbc: "" _wpas_done_all: '1' author: display_name: Guillermo Roman first_name: Guillermo last_name: Roman permalink: "/network-security-part-1-setting-up-your-environment/" ---
The following fields are not needed and can be removed from all your posts:
In addition, some posts might contain absolute URLs referencing other posts. Absolute URLs are discouraged since they make your site less portable. Run the following
sed command to replace absolute URLs with relative URLs. Replace
<your-domain> with the domain for your site: