Jocodoma

Joco's Tech Blog

0%

Personal Website using Hugo and Academic Framework

Posted on In , Disqus:
Symbols count in article: 8.2k Reading time ≈ 7 mins.

Introduction

In addition to Linkedin, I was looking for somewhere to host a site for my academic/working experience with a bit more details. It turns out that using Hugo with Academic theme/framework fits my needs, and it looks pretty nice and clean. So, here is how I setup it up.

What is Hugo?

Hugo is a static site generator written in Go. Hugo is developed by Bjørn Erik Pedersen, Steve Francia, and other contributors. Hugo is an open source project licensed under the Apache License 2.0.

Hugo takes data files, i18n bundles, configuration, templates for layouts, static files, and content written in Markdown and renders a static website. Some notable features are multilingual support, image processing, custom output formats, and shortcodes. Nested sections allow for different types of content to be separated. E.g. for a website containing a blog and a podcast.

– from Wikipedia - Hugo

What is Academic Framework?

The Academic framework enables you to easily create a beautifully simple website using the Hugo static site generator in under 10 minutes. You can see the demo here: View the Demo!

Academic Kickstart provides a minimal template to kickstart your new website by following the simple steps.

Setup Academic Framework using Hugo

My Environment

Hugo

Download and install Hugo via Homebrew (for macOS users):

1
$ brew install hugo

You may also download the appropriate version for your platform from Hugo Releases.

Homebrew is the simplest method and will require the least amount of work to maintain. The drawbacks aren’t severe. The default package will be for the most recent release, so it will not have bug fixes until the next release (i.e., unless you install it with the –HEAD option). Hugo brew releases may lag a few days behind because it has to be coordinated with another team. Nevertheless, brew is the recommended installation method if you want to work from a stable, widely used source. Brew works well and is easy to update.

Academic Kickstart

  1. Fork the Academic Kickstart repository to your GitHub.

  2. Clone your fork:

    1
    2
    cd <MY_WORKSPACE>
    git clone https://github.com/josephchen3/academic-kickstart.git <MY_HUGO_SITE>

  3. Setup upstream for syncing a fork (sync a fork of a repository to keep it up-to-date with the upstream repository):
    a. List the current configured remote repository for your fork.

    1
    2
    3
    4
    5
    cd <MY_HUGO_SITE>
    git remote -v

    origin  https://github.com/josephchen3/academic-kickstart.git (fetch)
    origin  https://github.com/josephchen3/academic-kickstart.git (push)

    b. Specify a new remote upstream repository that will be synced with the fork.

    1
    $ git remote add upstream https://github.com/sourcethemes/academic-kickstart.git

    c. Verify the new upstream repository you’ve specified for your fork.

    1
    2
    3
    4
    5
    6
    git remote -v

    origin	https://github.com/josephchen3/academic-kickstart.git (fetch)
    origin	https://github.com/josephchen3/academic-kickstart.git (push)
    upstream	https://github.com/sourcethemes/academic-kickstart.git (fetch)
    upstream	https://github.com/sourcethemes/academic-kickstart.git (push)

    d. Fetch the branches and their respective commits from the upstream repository. Commits to master will be stored in a local branch, upstream/master. Check out your fork’s local master branch. Merge the changes from upstream/master into your local master branch. This brings your fork’s master branch into sync with the upstream repository, without losing your local changes. If your local branch didn’t have any unique commits, Git will instead perform a “fast-forward“.

    1
    2
    3
    git fetch upstream
    git checkout master
    git merge -S upstream/master

    More details:
    https://help.github.com/articles/configuring-a-remote-for-a-fork/
    https://help.github.com/articles/syncing-a-fork/

  4. Initialize the theme:

    1
    git submodule update --init --recursive

  5. Update academic/theme to the latest changes:

    1
    git submodule update --remote --merge themes/academic/

    In case if you want to check out a certain version of the theme, you can do:

    1
    2
    3
    cd <YOUR_HUGO_SITE>/themes/academic/
    git log --no-walk --pretty=oneline --tags --abbrev-commit --decorate  ## show all tags
    git checkout tags/xxx   ## where xxx is the version number

    Here’s my script to check and update academic theme.

    [Updated on 2019/02/27]: Here’s the official update script.

Demo content

For inspiration, refer to the Markdown content which powers the Demo.

If you wish to initialize your site with the demo content, copy the contents of the themes/academic/exampleSite/ folder to your website root folder, overwriting existing files if necessary. The exampleSite folder contains an example config file and content to help you get started. The following command can be used to accomplish this:

1
rsync -vau ./themes/academic/exampleSite/* ./

Preview Your Site Locally

1
hugo server    # alias: hugo serve

Configure Hugo

You can find my full config settings at config.toml, menus.toml, and params.toml.

For more information on config files, please see https://gohugo.io/getting-started/configuration/

Hosting and Deployment on GitHub

Deployment on GitHub Pages Directly

  1. Check in or stash all the changes in your local git worktree.

  2. Remove public/ from .gitignore file.

  3. Setup Git sub module.

    1
    2
    3
    4
    5
    rm -irf public
    git submodule add -f -b master https://github.com/josephchen3/josephchen3.github.io.git public
    git add .
    git commit -m "Add submodule"
    git push -u origin master

    In case if you use git instead of https for adding sub module, change to following:

    Line #2
    1
    $ git submodule add -f -b master git@github.com:<USERNAME>/<USERNAME>.github.io.git public

  4. Generate static files and check in to the GitHub Pages repo.

    1
    2
    3
    4
    5
    6
    hugo
    cd public
    git add .
    git commit -m "YOUR COMMIT MESSAGE"
    git push origin master
    cd ..

  5. The previous step (Step 4) can be done by the following script.

    deploy.sh
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    #!/bin/bash

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

    echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

    # Build the project.
    hugo # if using a theme, replace with `hugo -t <YOURTHEME>`

    # Go To Public folder
    cd public
    # Add changes to git.
    git add .

    # Commit changes.
    # msg="rebuilding site `date`"
    msg=":rocket: Hugo Academic site update on `date`"
    if [ $# -eq 1 ]
      then msg="$1"
    fi
    git commit -m "$msg"

    # Push source and build repos.
    git push origin master

    # Come Back up to the Project Root
    cd ..

Now, you should be able to see your Hugo site on your GitHub Pages, which in my case is https://josephchen3.github.io/. Yay!!

References:
Host on GitHub - https://gohugo.io/hosting-and-deployment/hosting-on-github/
Deployment on GitHub Pages - https://sourcethemes.com/academic/docs/deployment/#github-pages

Deployment on html(gh-pages) Branch

This method is specifically for the case where the sub URL of the site is used. In this case, we need an additional branch from Hugo academic-kickstart repo, called html branch.

  1. Check in or stash all the changes in your local git worktree.

  2. Create an orphan branch for generated static pages.

    1
    2
    3
    4
    5
    6
    7
    git checkout --orphan html
    git rm -rf --cached $(git ls-files)
    git reset --hard && rm -irf *
    echo .DS_Store >> .gitignore
    git add .
    git commit -S -m "Initializing html branch. Add gitignore file."
    git push origin html

  3. Remove public/ from .gitignore file.

  4. Setup Git subtree for public/ folder.

    1
    2
    3
    4
    5
    git checkout master
    git submodule update --init --recursive
    rm -irf public
    git subtree add --prefix=public origin html --squash
    git subtree pull --prefix=public origin html --squash

    Note that here I am using origin, because my target subtree comes from the same repository but different branch.

  5. Generate static files and check in to the git repo (master branch).

    1
    2
    3
    4
    hugo
    git add .
    git commit -S -m 'Generate static files under public/ folder.'
    git push origin master

  6. Update the change to html branch.

    1
    git subtree push --prefix=public origin html --squash

Reference:
Git subtrees: A tutorial - https://medium.com/@v/git-subtrees-a-tutorial-6ff568381844

Add Submodule to GitHub Pages (for html branch approach)

Setup git submodule in your GitHub page working tree. In my case, it’s like following:

1
2
cd jocodoma.github.io/
git submodule add -f -b html https://github.com/jocodoma/academic-kickstart.git cv

To update git-submodule, do:

1
2
cd jocodoma.github.io/
git submodule update --remote --merge cv/

Finally, make sure you commit the code and push back to remote repo. Now, you should be able to see your Hugo site on your GitHub Pages, which in this case is https://josephchen3.github.io/cv/. Yay!!

References

https://sourcethemes.com/academic/docs/install/
https://sourcethemes.com/academic/docs/get-started/
https://sourcethemes.com/academic/docs/deployment/
https://sourcethemes.com/academic/docs/