[self writeBlog];

From Ghost to Hugo. Easier Blog Hosting with Github Pages

With the publication of this post, my transition from Ghost to Hugo will be complete and this blog will be solely run with static HTML files compared to the dynamic Ghost installation I used before.
Let me explain why I did this and how you can do this as well.

Starting Position

I started off with a Ghost installation that was hosted on uberspace.de. While uberspace.de is a great hoster and probably the cheapest option to host a Ghost installation, I hated that updates to Ghost itself would be troublesome and that in addition to uberspace.de I had to maintain the domain somewhere and make the whole connection. All I really wanted, was an easy way to publish content and be able to modify styles and enhance theme specific elements.
Hugo seemed to be the perfect solution for that, as the standard Ghost theme casper was available and it would create static HTML files, so I could be able to host my site virtually anywhere as I wouldn’t need to be able to run node js on the server.


Alternatives would have been:

Yet, GitHub Pages with another theme would have destroyed the design I used to have and to be fair, I really liked the minimalist Ghost Design.
Keeping Ghost and using buster, would have been the next best solution, in fact, it would have been easier and I would still have been able to host my blog on GitHub Pages or any other webserver as buster bruteforces and creates static HTML files for you. I avoided that option as I felt this wouldn’t be a good approach that would completely satisfy my needs for a easy and stable to use blogging platform.
And Ghost Pro was simply out of the picture. On average I spent about 5€/month on uberspace and another 3-4€/month on all-inkl which make it around 8-9€ total for the Ghost blog I used to run. Ghost Pro though, starts at 19€/month which was too expensive for my needs.

Outlined Path

After weighing all my alternatives I decided to go with Hugo as it comes closest to meet all the requirements I set out, most importantly I could host it on GitHub Pages and still be able to easily modify my theme and write content.
All I had to then would be to make the transition like this:

1.) Setup a barebone Hugo installation
2.) Add casper for hugo theme
3.) Add content from my existing Ghost installation
4.) Setup Github Pages with your Hugo setup 5.) Reroute iFlorian.com to work with my Github Pages repo

Migrate Ghost to Hugo

Let’s go through this step by step:

1.) Setup a barebone Hugo installation

This one is pretty easy. Hugo has a easy to understand Quickstart guide that helps you with your first setup.

  • Open a Terminal
  • cd into your workspace (e.g. Repository for your project)
  • (Install hugo if you haven’t done that yet. brew install hugo if you have homebrew)
  • Create your site hugo new site imnotFlorian.com
  • cd into the newly created directory imnotFlorian.com that hugo created

Hugo just created a barebone site for you. If you would run hugo locally to serve the HTML files to you, you wouldn’t see a thing yet. So keep on reading.

2.) Add caspter for hugo theme

To give your web presence a nice look, we’re going to add the casper theme to hugo by issuing the following commands:

  • Change into the themes directory cd themes/
  • Add the casper time as git submodule (so Github Pages won’t complain) git submodule init git submodule add https://github.com/vjeantet/hugo-theme-casper casper

3.) Add content from my existing Ghost installation

I thought this one would be the hardest step and require quite some time, but it turns out someone already did the legwork for this one.

  • Open your existing Ghost instance admin panel. Go to Settings -> Labs -> Click on Export.
  • Install ghostToHugo https://github.com/jbarone/ghostToHugo
  • Use ghostToHugo on your exported Ghost backup from the step above. You may want to adjust the dateformat like I had to ghostToHugo --dateformat "2006-01-02 15:04:05" export.json

4.) Setup Github Pages with your Hugo setup

Before we keep going, we want to test our Hugo setup via hugo server. If there are no significant errors when issuing that command, you should be able to see your blog when navigating to http://localhost:1313. If all is fine, we can keep finalize the current state and move it to Github pages.

Github Pages for your personal website serves HTML files or generates those HTML files for you if your project is a jekyll project. In any case, if you want to run Github Pages for your personal website, you would create a repository that’s name follows their scheme: .github.io. In my case, that’s caffeineflo.github.io. The repository can either be public or private, in any case it will be published under the same address. For personal projects, you need to have your HTML files in the master branch, while your hugo specific files can be anywhere else e.g. another branch or another repository.

My intended solution has my hugo files in the sources branch and the html files hugo will generate go into the master branch. This solution will become extra elegant when using the git worktree command to checkout master -> /public and sources to the root / of my caffeineflo.github.io directory.

Hugo will by default generate all your HTML files to /public if you tell it to create your HTML files by issuing hugo. So all we need to do is setup git.

  • git branch sources to create the sources branch where we want to keep our sources
  • git checkout sources to move to the sources branch
  • rm -rf public/ to remove the currently existing public folder
  • git worktree add -B master public origin/master to checkout the master branch to /public
  • git push origin sources Push the current branch
  • rm -rf public/* Note the asterisk.
  • hugo to generate our HTML files in /public
  • cd public git add -A git commit -m "Deleted sources on master and generated HTML files" git push origin master
  • The last step should have generated all necessary HTML files and pushed them to our Github Pages repo.

Now if you would navigate to your Github Pages instance, you should see your blog back in old glory again.

NOTE: Please note that I left out a few basic commands in the process like pushing to master to create the Github Pages instance and/or checking the functionality of our Hugo setup. Please check that again when following this tutorial.

5.) Reroute iFlorian.com to work with my Github Pages repo

One last thing is left to do. Setting our DNS records on our custom domain (iflorian.com) to point to our Github pages site.

  • dig caffeineflo.github.io to get the IP Address of the server github hosts us on.
  • Change your A DNS record on our domain to point to the address from the step above.

Now depending on how you’ve configured your baseurl in your config.toml (btw. you should configure that one …), you could also set the baseurl to your custom domain and map those domains against each other to be accessible from both domains.


Read more posts by this author.

Atlanta, USA + Stuttgart, Germany https://iflorian.com/