Easy Way to Play With a Hugo Theme’s Example Site
Updated 2021-October-13

Page contents

News

2021-September-4  Hugo v0.88.1 released. To keep up with Hugo releases, see discourse.gohugo.io/c/announcements, github.com/gohugoio/hugo/releases, gohugo.io/news, old.reddit.com/r/gohugo/, or twitter.com/@GoHugoIO.

2021-April-12  Published this evolving⁠[1] article.

 

About Hugo

Hugo is the static site generator used to generate the new parts of the Infinite Ink website. To learn about Hugo, see Infinite Ink’s #gohugo Portal.

 

About Hugo themes

There are hundreds of Hugo themes available at themes.gohugo.io. Most of these themes include an example site in a subdirectory named exampleSite.

💡
 To filter Hugo themes by license, name, stars, tags, or update date, see PFHT: PointyFar’s Filterable Hugo Themes.

 

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,

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

  • and to 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 it (rather than unextended Hugo).

 

Install extended Hugo

Some ways to install extended Hugo are described in Infinite Ink’s Hugo Tutorial in section 0. Install extended Hugo. If you are using Windows, check out Infinite Ink’s Scoop: A Windows Package Manager (Featuring Hugo, Figlet, and Ruby+Asciidoctor Examples).

 

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.88.1-5BC54738+extended windows/amd64 BuildDate=2021-09-04T09:39:19Z 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 in the next section, the directory structure will look something like this:

After step 2
HugoPlayground/
└── themename-2021-10-13/
    ├── 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-2021-10-13/.

 

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

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

  1. Browse themes.gohugo.io and find a theme 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 themename-2021-10-13/. 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-2021-10-13/exampleSite/ is the project root directory. On some systems, you can do this by right clicking this exampleSite directory 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-2021-10-13"

    Or something like this in a config.yaml:

    themesDir: ../..
theme: themename-2021-10-13

    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-2021-10-13/exampleSite/.

  6. In the terminal window, 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 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-2021-10-13/ is the project root directory. On some systems, you can do this by right clicking this themename-2021-10-13/ directory in a file browser and choose Open with Code from the pop-up context menu.

  2. In 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 config.toml:

hugo new site SITENAME

Or this command if you prefer a config.yaml:

hugo new site -f=yaml SITENAME

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

SITENAME/
├── archetypes/
├── content/
├── data/
├── layouts/
├── static/
├── themes/
└── config.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. To continue creating your website, see…

 

💡

  • With this default directory structure, you do not need to specify themesDir in your config.EXTENSION file.

  • The following five hugo new site CLI flags are equivalent.

    • -f=yaml

    • -f yaml

    • -fyaml

    • --format=yaml

    • --format yaml

 

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+, :term launches an integrated terminal window.
3. In general, I recommend surfing the web with JavaScript turned off.
4. These 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.

Comments and questions 📝 👍 👎 🤔

Your public comment or question might immediately improve this page or help me to (eventually) improve this page.