Skip to main content

Lobotourisme

Deploying a static Hugo website on Github Pages

# Last updated: 01/11/2023 #

(This post was automatically translated with www.DeepL.com/Translator)

The site you are viewing consists of a static Hugo website hosted on Github :

Github provides the ability to expose a static web site for each public repository in the account. All that is required is:

  • html+css in the repository;
  • The Github Pages feature enabled.

The static code of each repository will then be accessible at the url: https://MONLOGINGITHUB.github.io/MONDEPOT/

Hugo is a generator of static web sites : You write pages in markdown, you launch Hugo, and it generates all the html and the structure of site that Github will expose.

List of updates:
_- 01/11/2023: Updated the action script with the latest version available on Hugo - hosting on github. - 19/02/2022: I switched to the Anubis theme which is lighter and cleaner.
- 06/02/2022: Updated the action script with the latest version available on Hugo - hosting on github.

How it works:

Hugo

Installation

Under Ubuntu the version available in the repositories is outdated. The easiest way is to get the last .deb in the releases Hugo :

https://github.com/gohugoio/hugo/releases

Then :

wget https://github.com/gohugoio/hugo/releases/download/v0.82.1/hugo_extended_0.82.1_Linux-64bit.deb
sudo dpkg -i hugo_extended_0.82.1_Linux-64bit.deb

if dependency errors :

sudo apt-get install -f

Create a site base 

mkdir MYSITE
cd MYSITE
hugo new site .

Choose and download a theme : Hugo Themes

I use hugo-clarity which is very complete and works well on mobile:

cd MONSITE/
git submodule add https://github.com/chipzoller/hugo-clarity.git themes/hugo-clarity

To create a test page and check that it works:

hugo new post/testpage.md
hugo server -D

Open: http://localhost:1313/

Note: The hugo-clarity theme requires a lot of configuration. Rather than starting from scratch I followed the advice given in its install doc and deployed the sample site, which I then modified:

cd MYSITE
cp -R themes/hugo-clarity/exampleSite/* .
hugo server -D

Github

Create the repository

  1. Create a Github account “MONLOGINGITHUB” if not already done;
  2. Create a public repository ("New repository") that will contain our pages.

Github Tip:

By default repositories are exposed in https://MONLOGINGITHUB.github.io/NOMDUDEPOT/.

But if you name your repository “MONLOGINGITHUB.github.io”, it will be accessible at the root, in https://MONLOGINGITHUB.github.io/.

If you want, this allows you to have several “project” repositories in the subdirectories and a “personal page” at the root:

Repositories                    Corresponding sites
------------                    -------------------
dayofthetentacle.github.io      https//dayofthetentacle.github.io/
├── ifeel                       ├──  https//dayofthetentacle.github.io/ifeel/
├── likeicould                  ├──  https//dayofthetentacle.github.io/likeicould/
├── takeovertheworld            ├──  https//dayofthetentacle.github.io/takeovertheworld/

If you are creating a Github account just to host your site, then you can just use the MONLOGINGITHUB.github.io repository.

First commit to activate Github Pages

Let’s put our site Hugo on the MONSITE repository:

cd MONSITE
echo "# MONSITE" >> README.md
git init
git add .
git commit -m "first commit
git remote add origin https://github.com/MONLOGINGITHUB/MONSITE.git
git branch -M main
git push -u origin main

Go to Settings > Pages and activate Pages with the following source:

[Branch: gh-pages] [/root]

Generate the static html directly on the Github side

Note: This technique and the script below are taken from the Hugo doc: hosting on github.

We could generate the static html and push it to Github, but we can also have it done by Github :

By adding an action script to our sources, at each git push we will make it:

  • Run a Hugo to generate the html ;
  • Write the generated public/ directory in a dedicated gh-branch that Github Pages will read.

Create the conf file :

cd MONSITE
mkdir -p .github/workflows/
touch .github/workflows/hugo.yml

2 - Put in the conf (I have enabled the “extended = true” option with respect to the template, for the purposes of the Clarity theme):

# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches:
      - main

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.115.4
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb                    
      - name: Install Dart Sass
        run: sudo snap install dart-sass
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v3
      - name: Install Node.js dependencies
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
      - name: Build with Hugo
        env:
          # For maximum backward compatibility with Hugo modules
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"                    
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: ./public

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

We send everything to Github and normally it works 

cd MONSITE
git add .
git commit -a -m "init
git push

In the “Action” tab of the repository we can see the processing going on (and possibly crashing if we did something wrong). The gh-pages branch must have been created.

Go to the resulting Github Pages site: MONLOGINGITHUB.github.io/MONSITE

In theory everything is there.

Docs about Hugo on github :

Markdown references:

22/04/2021
https://loboto51.github.io/lobotourisme/en/post/d%C3%A9ployer-un-site-web-statique-hugo-sur-github-pages/ Loboto