Migration to Hugo

Build a website using Hugo Academic

Why Hugo?

The main reason I switch to Hugo is that I find many researchers use Hugo Academic(now named as Wowchemy) to build their website rather than Jekyll. After finishing the migration to Hugo, I understand why. Essentially Hugo and Jekyll are both static content generators, but Hugo Academic has more good built-in features like publication pages, project pages, and presentation pages. The configuration for Hugo is also much easier since I don’t have to deal with those extensions. Although Hugo might not be as flexible as Jekyll, it can cover most of my demands without great effort.

Set Up

Hugo Academic does not work like other Hugo themes, so Hugo’s tutorial is not adequate. Wowchemy offers a tutorial on its website, but it’s based on its online platform using Netlify. To keep things simple, the best way to build a website is to directly clone their Github repository starter-academic and put it in your <user-name>.github.io repository. To preview the website, go to the repository’s folder and run hugo server. Running hugo can generate the website under the public folder, this behavior can be changed using --publishDir.

I use a Github Action to publish my website following the instruction from Hugo Tutorial. Whenever I commit to master branch, the action can be automatically triggered, running commands to publish the website to gh-pages branch. The action’s configuration file is in .github/workflows/gh-pages.yml:

name: github pages

on:
  push:
    branches:
      - master  # Set a branch to deploy

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.82.1'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          cname: lwruan.com

This workflow use actions-hugo and actions-gh-pages from Shohei Ueda, it does nothing more than using Hugo to generate the website, pushing the files to gh-pages branch, and adding CNAME file in the directory. This process only takes few seconds, after that the files in gh-pages branch are updated. The last thing is to tell Github to find the index.html in gh-pages branch, this can be done in repository’s settings.

Liangwang Ruan
Liangwang Ruan
Ph.D Student

I’m a Ph.D student from Peking University advised by Baoquan Chen.