DEV Community

Cover image for How to add a theme to my Hugo site
Ben Hanan Subendran
Ben Hanan Subendran

Posted on

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Create a new Hugo site

hugo new site newhugo
Enter fullscreen mode Exit fullscreen mode

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

To go inside the root of the directory, run:

cd newhugo
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Now we can add that theme as a git submodule.

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

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/. .        
Enter fullscreen mode Exit fullscreen mode

Configure config.toml file

Set the theme name like this:

theme = "mytheme"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Run Hugo site

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

hugo
Enter fullscreen mode Exit fullscreen mode

To serve the website, run this:

hugo serve
Enter fullscreen mode Exit fullscreen mode

This will render your page in localhost:1313

Discussion (0)