Goal

• Personal websites that are easy to create and maintain
• Yet flexible and beautiful
• Free

Two frameworks

• hugo and jekyll
• Static sites generators
• Content written in Markdown, some configuration in YAML
• Build the corresponding html pages
• Various themes for your applications
  • blogs, portfolios, research group, résumé, project documentation, etc.

Hosting

• GitHub Pages
• Automatic build with GitHub Actions

We want to avoid

• writing html
• lots of manipulations to update your website

Hugo and Academic theme with GitHub Actions

See demo website

Structure:

• front page organized in widgets
• excellent management for publications, talks, etc
  • tags, projects, sorting, featured, links, etc.

allows math without any work

Other themes: lots for blogging, project docs; see also Resume, Avicenna and the Academic variations (Résumé, Research Group, Online course)

Setting up Hugo

See this guide

Setting up Git, GitHub and local repository

(Inspired from this guide)

Install git

We will create two repos:

• some-name: will hold content (Md, YAML, reference to theme); should be a fork of the Academic theme
• <your-username>.github.io: will hold the actual website (html, css, js)

Clone locally and initialize submodules (reference to theme)

git clone https://github.com/<USERNAME>/my-wowchemy-site.git My_Website
cd My_Website
git submodule update --init --recursive

Add the build repo as a submodule to the content repo:

git submodule add -f -b master https://github.com/<USERNAME>/<USERNAME>.github.io.git public

You’ll probably get some warnings, you can ignore them.

First build

Change base URL in config/_default/config.yaml

baseurl = "https://<USERNAME>.github.io/"

Serve locally

hugo server

Check your website at the address privided (e.g., http://localhost:1313/)

First build

hugo

Now check that public has been populated

Deploy to GitHub

From the content local repo, commit and push (this only pushes the content):

git add .
git commit -m "Initial commit"
git push -u origin master

Then push the built website

cd public
git add .
git commit -m "First build"
git push origin master
cd ..

Check out the remote repo

Wait for GitHub to apply changes, and check out your new website!

<USERNAME>.github.io

Update workflow

To get any cahnge on the website, you need to update the remote repo <USERNAME>.github.io; changing the remote content repo will do nothing. Here are two approahces:

Local build, push both

sequenceDiagram
    participant lc as Local Content 
    participant lw as Local Website
    participant rc as Remote Content
    participant rw as Remote Website
    rc ->> lc: pull
    lc ->> lc: Update content
    lc ->> lw: Build with hugo
    lc ->> lc: Update content
    lc ->> lw: Build with hugo
    lc ->> rc: push
    lw ->> rw: push

Automatic deployment

With proper automatization, updating can be as simple as:

sequenceDiagram
    participant lc as Local Content 
    participant lw as Local Website
    participant rc as Remote Content
    participant rw as Remote Website
    rc ->> lc: pull
    lc ->> lc: Update content
    lc ->> rc: push
    rc -->> rw: Build with hugo and push (automatic)

In particular, you don’t even need hugo on your machine, only git!

This also allows to edit directly on GitHub (useful for typos and small updates!). Don’t forget to pull locally, though!

(Based on this tutorial)

To achieve this, we need to use GitHub Actions.

First, we need to create a public/private key pair (see this guide)

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
# You will get 2 files:
#   gh-pages.pub (public key)
#   gh-pages     (private key)

Go to repository settings:

• In build repo: Go to Deploy Keys and add your public key with Allow write access
• In content repo: Go to Secrets and add your private key as ACTIONS_DEPLOY_KEY

In the /.github/workflows/ folder of the content repo, add the following gh-pages.yml file (can also be done in the Actions tab on the GitHub website):

name: GitHub Pages with Hugo

on:
  push:
    branches:
    - master

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2

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

    - uses: actions/cache@v2
      with:
        path: /tmp/hugo_cache
        key: ${{ runner.os }}-hugomod-${{ hashFiles('**/go.sum') }}
        restore-keys: |
                    ${{ runner.os }}-hugomod-

    - name: Build
      run: hugo --minify

    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
        external_repository: fontaine618/fontaine618.github.io
        publish_branch: main
        publish_dir: ./public

Hugo Academic and BibTeX

Creating content may be long, especially if you have many publications (one file per publications and requires to fill in entries). Fortunately, there exist a tool taking a .bib file doing everything for you:

See this tutorial

Customization

See the documentation

Jekyll and GitHub Pages

Jekyll works very similarly to hugo, but has slightly better GitHub Actions support by the community. Templates are generally simpler than Academic Hugo, however.

Preparation

• Satisfy all requirements
• Select a template: we will use al-folio as it has a nice publications features. (see the github repo for examples and features)
• Fork the repo
• Rename to <USERNAME>.github.io

Local build

Clone, install and build:

git clone https://github.com/<USERNAME>/<USERNAME>.github.io.git
cd <USERNAME>.github.io
bundle install
bundle exec jekyll serve

You can check out your local website at the specified address (e.g., http://127.0.0.1:4000/)

• like hugo the serve command listens to changes so it will dynamically update!

Deploy on GitHub Pages

In _config.yml, change url to

url: https://<USERNAME>.github.io/

and set baseurl to nothing

baseurl: 

Commit and push your website

On the GitHub website:

• Actions > Enable GitHub Actions (the al-folio comes with Actions!)
• Repository settings > Pages > set branch to gh-pages

Wait for GitHub to apply changes, and check out your new website!

<USERNAME>.github.io

Other templates may not have built-in actions, you can look at this tutorial (note that you no longer need to create the GITHUB_TOKEN).