I recently moved my blog (this one) from BlogEngine.NET to a Jekyll site on GitHub Pages. I tried to keep all of my posts working with the same URLs for the content. I didn’t worry about the tags, categories, etc. pages remaining the same. I figured that no one linked to those anyway, so the redirects would only be important on the posts.
Hopefully this post will help you migrate an old site from any platform (not just BlogEngine.NET) to Jekyll on GitHub Pages.
Exporting Existing Blog Content
Before we can create all of the posts on the new site, we’ll need to export the posts from our existing site. For this, most sites have an export function. In BlogEngine.NET, you’ll want to got to the Admin Dashboard by navigating to
/admin/ or clicking on
Dashboard in the Admin widget.
From here, we need to open up
Settings -> Import export then click on the
Export button in the
Export section of that page.
When we click this button, the site will create a
BlogML.xml and your browser will download it. That’s an XML containing your posts, comments, metadata, etc. from your site.
Setting Up Jekyll Site on GitHub Pages
Now I needed a new GitHub repository to host the content for my site, so I created benrick.github.io to host my site.
Types of GitHub Pages sites
For GitHub Pages, you can set up
Project sites to be hosted by GitHub Pages.
I did a user site with repository name
benrick.github.io, which followed the required repository name pattern of
[username].github.io (will be the same as the address).
If I’d done a site for my
DevChatter organization, it would’ve been
devchatter.github.io, following the
If I did a project site, it could’ve had any name, but would be hosted at
[organization].github.io/[project-name]. So if you’re going to do this, be warned of the subfolder, which can be avoided with a custom domain (discussed below).
Configuring the Repository as a GitHub Pages Site
Navigate to the
Settings of the repository and click on the
Pages menu item in the
Code and automation section of the sidebar navigation.
- Source should be set to
Deploy from a branchfor our simple case.
- I set Branch to
mainand I keep the site in the root, so folder of
- Don’t fiddle with the Custom domain yet, we’ll come back to that later.
Now that it’s configured, make sure that everything is working. Create an
index.md file in the root of your GitHub repository with anything you like. Here’s an example:
Next, we’ll make our
_config.yml file in the root of your GitHub repository with these initial values:
If you created these files directly on GitHub, you can just wait, but if you created these locally, push them to GitHub. Now you’ll want to wait a few minutes for it to deploy, and try to visit your site at the
*.github.io address that you chose earlier. If all is set up, you’ll see your
Choosing and Customizing a Theme
Selecting a theme can offer a lot of benefits. Setting it up to work locally will require setting up ruby, installing the gems for the theme and its dependencies, etc.
If you’re just planning to deploy without running it locally, you can skip those for now (you can add local running later).
Here are a few places to find free themes (there are many more):
And if you want to (and have the money to) support content creators, there are many paid Jekyll themes as well.
Once you’ve chosen a theme, you’ll either be setting the
remote_theme: in the
_config.yml file in the root of your site. Most of the themes you find will have their own instructions, which are often for running it locally. Setting these properties will let it work with the GitHub Pages workflow.
Converting Blog Posts to Jekyll Markdown Posts
After exporting your content from your previous blog, check to see if there’s a tool created to convert that export into markdown files. Once completed, you’ll put all of those markdown files (if the tool didn’t do it) into the
_posts directory in your repository.
For my conversion from BlogML.xml (the data exported by BlogEngine.NET), I started with this blogml.rb file and made a few tweaks to it. You can start with that one, but it’s written for Octopress, a framework based on jekyll. It’s close enough to Jekyll to get you started. Alternately, you can use my tweaked version of the BlogML.xml to Jekyll import script.
Regardless of the one you’re using, with ruby installed on your computer and the
BlogML.xml file and the
blogml.rb file in the same folder, run the following command in that folder.
ruby -r './blogml.rb' -e Jekyll::BlogML.process('BlogML.xml')
After running this, you should have a
_posts folder full of your posts.
Be sure to check through your pages, articles, etc. since you’ll want to be sure they transferred correctly. There could be issues in the “frontmatter” (metadata at the top of the file), so be sure to check titles, permalinks, and tags.
Some of these issues can be fixed by hand, but anything that happened in a large number of files will require some clever finding and replacing.
Migrating Files and Images from BlogEngine.NET to Jekyll
In the root of your new site, create two folders named
images. These are where your files and images will go.
/App_Data/files folder from your old BlogEngine.NET site. Use whatever means you have of accessing your old site’s file system. I used FTP access to it.
You now need to split the files and images into their respective folders, maintaining the original structure.
To make this easier, I recommend that you put a copy of the files into each of the two folders. Then delete the images from the
/files folder and the files from the
Deploying and Verifying
Commit your changes and push them all to the GitHub repository. As we’re using GitHub Pages default deployment, you should be able to navigate to the
Actions section on the repository before it completes the deployment to see that it is building and deploying the static site.
You should see deployments from our previous changes to the repository.
After confirming that it has a deployment (it should be green), you’ll want to navigate to your
*.github.io site as we did earlier and confirm that the site has your content.
Setting up Custom Domain (Optional)
If you want to have a custom domain, you’ll need to set up your DNS to point to your GitHub Pages and then tell your GitHub Pages repository about your custom domain. By doing it in this order, GitHub will be able to verify that your DNS settings are pointing to the GitHub Pages site.
Set Up DNS A Records
TO set up the A Records for your domain, create it with these IP Addresses pointing at GitHub Pages, so it looks like these:
For the first record, leave the
Host name blank, set the
Type to “A”, and the
Data to the first IP Address. In some DNS systems you add more records (like this one), but in other systems, you create 4 separate A records with these addresses.
You can check the GitHub Pages Custom Domain Docs for the most up-to-date list of IP Addresses.
Set Up DNS CNAME Record
Next, you’ll set up a CNAME Record to point to the subdomain you have at GitHub, mine is
benrick.github.io. Create the CNAME record like this:
Just be sure that you set the
Host name to “www”, the
Type to “CNAME” and the
Data to your “*github.io” subdomain.
Set Custom Domain in GitHub
After configuring DNS, we need to tell GitHub by going to the
Settings tab in your repository, and clicking on the “GitHub Pages” link in the sidebar navigation.
Now change the Custom domain to your domain name that we just configured and save that change, which causes GitHub to run a check of the DNS settings.
After verification, the page will look like this:
If you want full instructions for setting up the custom domain name for GitHub using Google Domains, check my post about how to set up a custom domain from google domains for GitHub pages.