Easy Way to Play With a Hugo Theme’s Example Site
Updated 2021-June-8

Page contents

News

2021-May-2  Hugo v0.83.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.

 

Create a HugoPlayground directory

To make it clear that you are playing with a Hugo theme, create a directory named something like HugoPlayground and put the theme you want to play with — along with its exampleSite subdirectory — in this HugoPlayground directory. After you follow the steps below, the directory structure will look something like this:

HugoPlayground/
└── themename-2021-06-15/
    ├── 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-06-15/.

 

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. If you are using a different editor,⁠[3] 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-06-15. 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-06-15/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-06-15"

    Or something like this in a config.yaml:

    themesDir: ../..
theme: themename-2021-06-15

    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-06-15/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.⁠[4]

  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.⁠[2]

 

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

  2. In Code, view and edit the files in the archetypes/, assets/, layouts/, static/, and other non-⁠exampleSite directories.

💡
If a theme’s root includes an images/ directory, it is used by the themes.gohugo.io website and — AFAICT — it is not needed by theme users (such as you and me).

 

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 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 general, I recommend surfing the web with JavaScript turned off.
3. These steps work only if your editor includes an integrated terminal emulator.
4. 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 👍 👎 📝

Please comment so I know (maybe) that I'm not all alone in an infinite void.