Hosting Webpage on GitHub

This note puts together steps I follow to create my personal webpage on GitHub using the template `starter-academic’ for Hugo.

I first cloned the template to my local computer. I then customized my GitHub page before deploying the website to GitHub. Everything is done in terminal in Fedora Linux.

Clone the template

On local computer

Intall GO and Hugo-extended

In terminal:

sudo dnf install golang

Note, I did not install Go by snap as suggested here.

Next, I downloaded the hugo-extended from https://github.com/gohugoio/hugo/releases. After decompressing the .gz file, I moved the binary hugo to /usr/bin/hugo, which replaces hugo installed by dnf install hugo.

Create local folder for all source files

In terminal:

git clone https://github.com/wowchemy/starter-hugo-academic.git myAcademicSite
cd myAcademic
git submodule update --init --recursive

This clones the starter-academic theme template to local folder myAcademic. Remove the folder public/ if there is one:

rm -r public/

In terminal, if not already in the folder myAcadmicSite, do:

cd myAcademicSite

Then

hugo server --disableFastRender

Copy the http address http://localhost:1313/ and paste it in browser address bar. This will start the starter-academic original website on my local computer.

Hit keyboard Ctrl+c to stop hugo server.

Configure and Edit Website

Next, I configure and edit my website by modifying configuration files and folders. It is important to know the file structure of Hugo templates:

• content/ holds the content of all web pages and web page sections.
• assets/media/ holds media file, e.g. image and videos.
• config/_default/ holds site configuration files.
  • config.yamlconfigures Hugo, such as site title, url, Hugo options, enable page features.
  • params.yaml configures Wowchemy options, e.g., SEO, site features.
  • menus.yaml layouts menu links, used if the menu is enabled in params.yaml.

First, in folder myAcdemicSite, in the file config/_default/config.yaml, set the baseurl to my website address:

baseurl = "https://shutaocao.github.io/"

Edit my site

Edit the following files

• content/_index.md.
• config/_default/config.yaml.
• config/_default/menus.yaml.
• config/_default/params.yaml.

Content Blocks

File content/_index.md list all web page sections in one place, each section is a content block. I use the existing blocks which include collection, portfolio, about, markdown. Web page sections are displayed in the order the content blocks are stacked in content/_index.md.

Introducing myself can be done in content/authors/admin/_index.md.

Navigation Menu

The navigation bar on the top of my website is customized in config/_default/menus.yaml. It is straightforward to customize it. There are two things worth of mentioning.

• The url option.

  • url: '#publications' refers to the id publications of block Publications listed in content/_index.md.
  • url: 'publication/' refers to the folder content/publication/.

• A drop-down menu in navigation bar can be built by following template Online Courses at https://wowchemy.com/templates/.

Deploy the Website to GitHub

I already have my personal GitHub page, on the main branch. I removed all files for my old GitHub page, from terminal by using git rm.

Push website to GitHub

In terminal:

cd myAcademicSite
git submodule add -f -b main https://github.com/shutaocao/shutaocao.github.io.git public

It creates folder myAcademic/public/ that will have all contents to be pushed to GitHub. If the shutao.github.io is on the gh-pages branch, then replace main with gh-pages in the last line of command above.

Next, in terminal:

cd myAcademicSite
hugo

This generates content of the website to be published on GitHub and copy them to public/. In case public/ did not exist, hugo would create it.

Finally, depoly contents in public/ to GitHub

cd public
git remote set-url origin git@github.com:shutaocao/shutaocao.github.io.git
git add .
git commit -m "Build website"
git push
cd ..

This now has deployed my website to GitHub.

The push above uses SSH key to access GitHub and push files.

Alternatively, GitHub Actions is new and can be used, but I did not use it.

Update contents

In terminal:

hugo --gc
cd public
git add .
git commit -m "first deploy"
git push origin main
cd ..

Two things to note:

• Executing hugo builds the website from source files.
• git push needs SSH key that should have already been setup to access to GitHub from terminal.

Update the template

To update the starter-academic template to the latest version, use the file go.mod.

In terminal:

cd myAcdemicSite
hugo mod get -u

This will update go.mod to the latest releases of wowchemy theme and modules. Re-run `hugo’ to update the website template.

To update or migrate to the latest configuration YAML releases, can use Hugo Scripts.

More details are documented at https://wowchemy.com/docs/hugo-tutorials/update/

Main references:

• https://wowchemy.com/docs/getting-started/get-started/

• https://wowchemy.com/docs/hugo-tutorials/deployment/

• https://gohugo.io/getting-started/quick-start/

• https://gohugo.io/hosting-and-deployment/hosting-on-github/

Acknowledgement

Thanks to George Cushen for making the academic template an open source.