Hosting Your Hexo Site on Github - A Lesson Learned

I absolutely love Hexo - it does a great job of creating a basic blog with static pages written in Markdown, that can be deployed to any host and easily updated from a command line or any text editor capable of reading and writing markdown (so just about any text editor then).

I decided to host my new blog at Github Pages and found a really interesting little quirk if using a custom domain with that service.

There are a clear set of instructions on how to deploy to Github in the Hexo documentation, and Github also maintains a useful help file for managing a custom domain for your Github Pages. I managed to follow all of these instructions, and also the DNS update instructions at my domain registrar and eventually ended up with my pages hosted on Github under this very domain.

All was well, I thought, until I regenerated my Hexo site and ran 'hexo deploy' to deploy the changes to my Github pages repo. The deployment completed successfully, with the Hexo commands having logged me in to my Github account and helpfully confirmed that indeed my 'public' folder was deployed. A quick trip to to look at my changes rendered for me in Safari, and 'whoah' what's this - a 404 !? All was fine immediately prior to deployment so what had gone wrong ?

Cue the tip that will save you from the time that I subsequently invested in tracking down the cause of my woes!

Here's the rub - when you create the CNAME file in your Github repo (in which resides your domain name) per their instructions and merge it to your master branch, your repo will be set up to work with your custom domain. The minute you regenerate and deploy your Hexo site to Github, that file will be deleted in the deployment commit, and your site will immediately fall back to pointing to the default Github url. The trick is to make a copy of the CNAME file and place it in the 'sources' folder of your local Hexo instance at the top level. This then results in the file being copied to public and uploaded to Github each time your Hexo site is generated and deployed - voila and doh !

Show Comments