Easy Way to Play With a Hugo Theme’s Example Site
Updated  2023-May-24

Page contents

News

Ongoing  According to Repology, the latest packaged Hugo is version newest packaged version of Hugo. To keep up with Hugo releases, see github.com/gohugoio/hugo/releases or discourse.gohugo.io/c/announcements. To learn about upcoming Hugo releases, see github.com/gohugoio/hugo/milestones.

2023-April-12  As of today, this evolving⁠[1] article has been on the web for 2 years.🎂🎂

 

About Hugo

To learn about the Hugo static site generator, see Infinite Ink’s #gohugo Portal.

 

Hugo themes

There are hundreds of Hugo themes available at…

Most of these themes include an example site in a directory named exampleSite.

 

Why play with a Hugo theme’s example site

Playing with a Hugo theme’s example site is a good way to…

  • learn about Hugo in general,

  • decide if you want to use a particular theme for your website,

  • and learn how to implement a feature of a theme.

 

Prerequisites

This article assumes the following.

Editor, browser, etc.

  • You use a text editor with an integrated terminal emulator, for example…

  • You have a web browser with JavaScript enabled.⁠[3] JavaScript is needed by the LiveReload feature of Hugo’s built-⁠in web server.

  • You know how to download or clone a Hugo theme from a Git hosting provider such as GitHub.com.

  • Extended Hugo is installed on your system. Details about this are in the next section.

 

Extended Hugo

Since many Hugo themes require extended Hugo, you are more likely to have success playing with a Hugo theme if you install extended (rather than unextended) Hugo.

 

Install extended Hugo

To learn how to install extended Hugo, see Infinite Ink’s Installing Extended Hugo.

 

Check your hugo with the hugo version command

To check that the hugo command is on your path and is an extended version, run this at a command-line prompt:

hugo version

You should see something like this:

hugo v0.112.3-ba6f74e40420d76f15fc8c2358be90f7aca98e0e+extended windows/amd64 BuildDate=2023-05-24T14:42:50Z VendorInfo=gohugoio
                                                         👆

 

Create a HugoPlayground directory

To make it clear that you are playing with a Hugo theme, create a directory named something like HugoPlayground. After you follow the first two steps below, the directory structure will look something like this:

After step 2
HugoPlayground/
└── themename-2023-05-24/
    ├── archetypes/
    ├── assets/
    ├── exampleSite/
    ├── layouts/
    └── static/

 

‼
For the steps below to work, do not move the theme’s exampleSite directory. It must be a subdirectory of themename-2023-05-24/.

 

Eight steps to start playing with a theme’s example site

ℹ

The steps in this and the next section assume you are using Visual Studio Code, which is also known as Code. If you are using a different editor,⁠[4] mentally replace “Code” with “Kate” or whatever.  

 

  1. Browse a Hugo themes directory (for example themes.gohugo.io) and find a theme that you like that includes…

    • an exampleSite directory

    • and a README with clear detailed instructions.

  2. Download the theme, put it in your HugoPlayground directory, and rename the theme’s directory so that it includes the date you downloaded it (for example, name it themename-2023-05-24). This is useful if you play with a lot of themes on a lot of days over many years (as I have done).

  3. Launch Code so that the directory themename-2023-05-24/exampleSite/ is the project root. On some systems, you can do this by doing Shift+RightClick on the exampleSite directory name in a file browser and choose Open with Code from the pop-up context menu.

  4. In Code, open the config file that is in the root of this exampleSite directory and edit it so that the themesDir and theme configuration settings are set to something like this in a config.toml:

    themesDir = "../.."
theme = "themename-2023-05-24"

    Or something like this in a config.yaml:

    themesDir: ../..
theme: themename-2023-05-24

    Note that the dee in themesDir is upper case.

  5. Open Code’s integrated terminal emulator and make sure the terminal’s working directory is themename-2023-05-24/exampleSite/.

  6. In this terminal pane, run hugo server -D, which is equivalent to hugo server --buildDrafts.

  7. In a web browser, view http://localhost:1313.⁠[5]

  8. Edit some of the example site’s files and view the LiveReload results of your edits in the web browser. Note that LiveReload works only if JavaScript is enabled in the web browser.⁠[3]

 

Two steps to start playing with a theme’s layouts and other non-⁠exampleSite files

To view the code that makes a theme work, do the following.

  1. Launch another instance of Code so that the directory themename-2023-05-24/ is the project root. On some systems, you can do this by right clicking this themename-2023-05-24/ directory in a file browser and choose Open with Code from the pop-up context menu.

  2. In this instance of Code, edit some of the files in the assets/, layouts/, static/, and other non-⁠exampleSite directories, and view the LiveReload results of your edits in the web browser.

 

Possible next step

When you find a theme you would like to use, create a website skeleton with this command if you prefer a hugo.toml configuration file:

hugo new site SITENAME

Or this command if you prefer a hugo.yaml configuration file:

hugo new site SITENAME -f=yaml

Either of the above two commands will create the following directory structure.

SITENAME/
├── archetypes/
├── assets/
├── content/
├── data/
├── layouts/
├── public/
├── static/
├── themes/
└── hugo.EXTENSION

Where SITENAME is a directory name that you choose and EXTENSION is either toml or yaml.

After you create the SITENAME skeleton, put your chosen theme’s directory inside the skeleton’s themes/ directory, i.e.:

SITENAME/
├── archetypes/
├── assets/
├── content/
├── data/
├── layouts/
├── public/
├── static/
├── themes/
│   └── themename/     ⟵👀
└── hugo.EXTENSION

To continue creating your website, see…

 

‼

With this default directory structure, you do not need to specify themesDir in your config.EXTENSION file. For example, your config file might include…

fragment of config.toml
# themesDir not needed
theme = "themename"

or…

fragment of config.yaml
# themesDir not needed
theme: themename

 

See also

For more about Hugo, see Infinite Ink’s…

 

Endnotes

1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.
2. In Vim 8.1+, the :terminal command launches an integrated terminal window.
3. In general, I recommend surfing the web with JavaScript turned off.
4. These eight steps work only if your editor includes an integrated terminal emulator.
5. In some terminal emulators, you can Ctrl-Click the URL’s port number and the URL will be launched in your default web browser. For example, to launch http://localhost:1313/ in your default web browser, Ctrl-Click 1313.

Discuss or share this page 📝 🤔 🐘