Publish a Hexo Blog to Github Pages

Earth Epoch: 1509639245 (2017-11-02)

_ This log explains how to publish a blog created with the static site generator Hexo to Github Pages. _

Github pages
Github pages is a service from Github that allows publishing a website directly from your github repository.

For example, you create a github project as<username>/<username> Then it is published as https://<username>

Github pages support natively the Jekyll static site generator. To make long story short, when you push changes of your Jekyll project to the github repository, Github automatically compiles Jekyll files into HTML pages and present them via

Hexo generator

Well, I found Jekyll not so trivial to install and configure, especially if you are not coming from a Ruby background.

I found Hexo much more easy to setup and start blogging. And as I come from javascript background, npm packages are easier for me.

But the problem is that Github pages do not know how to compile a Hexo project to a static HTML site. So if you upload your Hexo project to this special Github repository, Github Pages won’t be able to display the HTML.

Luckily, Github page can display any static HTML site, as long as it is installed in the root of the project repository.

Installing Hexo to Github Pages

So the trick is keep two separate repositories. One repository for your Hexo project, and another one for the static HTML site generated by your Hexo project.

The trick is to use the<username>/<username> as the placeholder of your Hexo compile results.


Have your two repositories relative close.

For example: .../my-blog/my-hexo-project/ for your Hexo project and .../my-blog/<username> for the generated HTML pages.

Now all you have to do is to edit your _config.yml file in your hexo-project, so it generates the produce static HTML site into your <username> project. Edit the public_dir entry accordingly.

For our previous example layout:

# Directory
source_dir: source
public_dir: ../
tag_dir: tags
archive_dir: archives

And that’s it. Now when you do hexo generate, it will spit out the generated files in the project project. Push changes to Github Pages project and you’re done.

Captain out…