How to add a theme to my Hugo site

Hugo is one of the most popular open-source static site generators. The developers craft many themes (https://themes.gohugo.io/) for the Hugo community to use. Here's a quick guide on adding those themes to our Hugo sites.

Install Hugo

You can install Hugo on macOS, Windows, Linux, OpenBSD, FreeBSD, and on any machine where the GO(AKA Golang) compiler tool chain can run.

Here's the official installation guide: https://gohugo.io/getting-started/installing/

Install Extended Hugo on Windows via Chocolatey:

choco install hugo-extended -confirm

The extended version is nothing but has Sass/SCSS functionality.

• After installing it, check your Hugo version to ensure you have a suitable version for a particular theme. In some cases, you may need to have installed the extended versions for some themes to be worked perfectly. So keep an eye on this thing as well.

To check your version of Hugo, run:

hugo version

Create a new Hugo site

hugo new site newhugo

The above command will create a new Hugo project in the newhugo folder.

To go inside the root of the directory, run:

cd newhugo

Fork a Hugo theme

I'm using this theme for this tutorial. Anyway, you can find thousands of themes off of this page.

• It's always better to fork the particular theme before adding it to our sites. Your forked theme will not be deleted even if the upstream repo is deleted. So the theme will be persisted.

Add the forked theme to our newhugo site

Before adding a git submodule, we have to initialize the git repository. So run this:

git init

Now we can add that theme as a git submodule.

git submodule add https://github.com/apvarun/blist-hugo-theme.git themes/mytheme

Now our theme will be added to the folder themes/mytheme.

Copy the content from theme.

To copy all the content from the theme's exampleSite to our site, run this:

cp -a themes/mytheme/exampleSite/. .        

Configure config.toml file

Set the theme name like this:

theme = "mytheme"

Install Node Modules[if required]

Commonly Hugo theme doesn't require node modules unless it uses a tool like PostCSS.

Copy the package.json from the themes/mytheme, and paste it to our newhugo root folder. and run this:

npm install

Run Hugo site

To generate the build, run this(From the root folder):

hugo

To serve the website, run this:

hugo serve

This will render your page in localhost:1313