How to generate GitHub Pages with Hexo, Hugo and Middleman static site generators

March 16, 2017

How to generate GitHub Pages with Hexo, Hugo and Middleman static site generators

About GitHub Pages

GitHub Pages is a fast and easy way to share information about you, your organization or your project with the rest of the world, without worrying about server infrastructure, configuration or databases. All you need to do is create a Pages project or branch in your Github project that will serve your website.

Enabling GH Pages for About Me/Organization

Just add a new project username.github.io and push the source code of your website from the master branch. The website will be available at

http://username.github.io

Enabling GH Pages for Project

GitHub Pages for project are enabled in the project settings by selecting the location of the source code:

  • gh-pages branch (needs to be created first)
  • master branch
  • master branch /docs folder

The website will be available at

http://username.github.io/projectname

Static site generator

Since GH Pages are in fact static websites, you can speed up the process of their creation with static site generators. By default, GitHub employs Jekyll, but if you use another generator you must first generate the website locally and then push it to GitHub.

How to use Hexo in GitHub Pages

Buddy lets you automate the process of building and deploying GH Pages to bare minimum. In this example on every change to the master branch, Buddy will generate a new static page with Hexo and push it to the same repository in the gh-pages branch.

  1. First, fork repository https://github.com/buddy-works/hexo-gh-page. It's a simple static page written in Hexo. It can be generated by running

     npm install
     hexo generate
    
     
    Once you fork it, create a new branch gh-pages that will host the source code:
  2. Go to https://buddy.works, sign up with your GitHub profile, and select the forked repository for the first project:

  3. Create a new pipeline and set the trigger mode to On every push on Master branch:


Hexo script

When your pipeline is ready, select and configure Hexo build action. Just paste this script in the Commands field:

git clone -b gh-pages https://${GITHUB_USER}:${GITHUB_PASSWORD}@github.com/USERNAME/PROJECT.git public || true
npm install
hexo generate
cd public
git config --global user.email "my@email.com" && git config --global user.name "Name"
git add . && git commit -am "Push generated files"
git push origin gh-pages --force$$$$$$$

The commands will create a clone of the repository in the Buddy filesystem. Npm install and hexo generate will generate the website in the public directory, which is then pushed to the gh-pages branch in your GitHub project.

You can use environment variables in the pipeline settings to store sensitive data like GitHub credentials.

Hexo action detailsHexo action details

How to use Hugo and Middleman in GitHub Pages

The process for Hugo and Middleman generators is the same as with Hexo, the only difference is that you choose a different action for each of them, and a different source directory for Middleman.

Hugo script

git clone -b gh-pages https://${GITHUB_USER}:${GITHUB_PASSWORD}@github.com/USERNAME/PROJECT.git public || true
npm install
hugo -c /${WORKING_DIR}
cd public
git config --global user.email "my@email.com" && git config --global user.name "Name"
git add . && git commit -am "Push generated files"
git push origin gh-pages --force$$$$$$$

Hugo action detailsHugo action details

Middleman script

git clone -b gh-pages https://${GITHUB_USER}:${GITHUB_PASSWORD}@github.com/USERNAME/PROJECT.git build || true
npm install
bundle install
middleman build
cd build
git config --global user.email "my@email.com" && git config --global user.name "Name"
git add . && git commit -am "Push generated files"
git push origin gh-pages --force$$$$$$$$

Meddleman action detailsMeddleman action details

Share:

Alexander Kus

Alexander Kus

Customer Success Manager

A story-teller and conversation-lover, Alexander decided to invest his skills to help his friends at Buddy transform the cold language of patch notes into exciting narratives. Also: an avid gamer, hip-hop DJ, Liverpool FC fan, absentminded husband, and the father of two.