Hugo : Creating a new site from Template

September 1, 2024

Overview

Using Hugo for a while now, I realized I was constantly copy pasting code from one website to the other. To prevent this I have started creating my own template. I want to push all my functionnalities there, and when required, be able to pull the new version into my existing sites.

Method 1 : Git Submodule

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
hugo new site MyNewSite
cd MyNewSite

git init
git checkout -b main
git add *.*
git commit -m "Initial Upload"

cd themes
git submodule add https://git.fhahome.dev/Template/hugo-theme-fha.git
git submodule init

Edit the config.toml file and update the theme.

1
2
3
4
5
baseURL = 'https://fhanotes.netlify.app/'
languageCode = 'en-us'
title = 'Tech-Notes'
theme = "hugo-theme-fha"
enableEmoji = true

Then save the current status.

1
2
git remote add origin https://git.fhahome.dev/Template/hugo-theme-fha.git
git push origin main

To check for updates on the submodules use git status.

Pulling latest version of the Theme one of those commands will synchronize the repositories:

1
2
git submodule update
git pull --recurse-submodules

Or if the submodule were not Initialized properly, use

1
git clone --recurse-submodules

Those commands will pull the current project and all the submodules.

Project Initialization / cloning

When cloning the project, make sure to do the following :

1
2
3
4
git clone https://giturl/owner/repo.git
cd repo
git submodule init
git submodule update

Project use with Github and Netlify

The issue in Netlify during the automatic deployment is related to the submodule not being retrieve, so all the default layout, css, scripts, etc… are missing when building the Hugo static site.

This is a sample of the error retrieved :

1:49:02 PM: Starting to prepare the repo for build
1:49:02 PM: Preparing Git Reference refs/heads/master
1:49:04 PM: Failed during stage 'preparing repo': Error checking out submodules: Submodule 'themes/hugo-theme-fha' (https://git.fhahome.dev/Template/hugo-theme-fha.git) registered for path 'themes/hugo-theme-fha'
Cloning into '/opt/build/repo/themes/hugo-theme-fha'...
fatal: could not read Username for 'https://git.fhahome.dev': No such device or address
fatal: clone of 'https://git.fhahome.dev/Template/hugo-theme-fha.git' into submodule path '/opt/build/repo/themes/hugo-theme-fha' failed
Failed to clone 'themes/hugo-theme-fha'. Retry scheduled
Cloning into '/opt/build/repo/themes/hugo-theme-fha'...
fatal: could not read Username for 'https://git.fhahome.dev': No such device or address
fatal: clone of 'https://git.fhahome.dev/Template/hugo-theme-fha.git' into submodule path '/opt/build/repo/themes/hugo-theme-fha' failed
Failed to clone 'themes/hugo-theme-fha' a second time, aborting
: exit status 1: Submodule 'themes/hugo-theme-fha' (https://git.fhahome.dev/Template/hugo-theme-fha.git) registered for path 'themes/hugo-theme-fha'
Cloning into '/opt/build/repo/themes/hugo-theme-fha'...
fatal: could not read Username for 'https://git.fhahome.dev': No such device or address
fatal: clone of 'https://git.fhahome.dev/Template/hugo-theme-fha.git' into submodule path '/opt/build/repo/themes/hugo-theme-fha' failed
Failed to clone 'themes/hugo-theme-fha'. Retry scheduled
Cloning into '/opt/build/repo/themes/hugo-theme-fha'...
fatal: could not read Username for 'https://git.fhahome.dev': No such device or address
fatal: clone of 'https://git.fhahome.dev/Template/hugo-theme-fha.git' into submodule path '/opt/build/repo/themes/hugo-theme-fha' failed
Failed to clone 'themes/hugo-theme-fha' a second time, aborting
: exit status 1
1:49:04 PM: Error checking out submodules: Submodule 'themes/hugo-theme-fha' (https://git.fhahome.dev/Template/hugo-theme-fha.git) registered for path 'themes/hugo-theme-fha'
Cloning into '/opt/build/repo/themes/hugo-theme-fha'...
fatal: could not read Username for 'https://git.fhahome.dev': No such device or address
fatal: clone of 'https://git.fhahome.dev/Template/hugo-theme-fha.git' into submodule path '/opt/build/repo/themes/hugo-theme-fha' failed
Failed to clone 'themes/hugo-theme-fha'. Retry scheduled

Add the required inform,ation to .gitmodules file.

Update the netlify.toml to retrieve the submodules used in the project.

1
2
[build]
command = "git submodule update --init --recursive && hugo --gc --minify"

Method 2 : Git Subtree

First method I have tried, but on Windows 11 with VS Code, I had a very strange behaviour when updating an existing site, although my content website and the theme were in their own folders, everything was mixed up.

This exemple shows how to create a new project and adding the Theme as a Git Submodule. On an existing project, the git subtree add command can be run as a standalone.

1
2
3
4
5
6
7
8
9
hugo new site MyNewSite
cd MyNewSite

git init
git checkout -b main
git add *.*
git commit -m "Initial Upload"

git subtree add --prefix=themes/hugo-theme-fha https://git.fhahome.dev/Template/hugo-theme-fha.git main --squash