Easy Way to Play With a Hugo Theme’s Example Site
Updated 2021-May-3

Page contents

News

2021-May-02  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-05-03/
    ├── 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-05-03/.

 

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] replace “Code” with “Atom” or “IntelliJ IDEA” or whatever.  

  1. Browse 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 themename-2021-05-03. 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-05-03/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-05-03"

    Or something like this in a config.yaml:

    themesDir: ../..
theme: themename-2021-05-03

    Note that the dee in themesDir is upper case.

  5. Open Code’s built-in terminal emulator and make sure the terminal’s working directory is themename-2021-05-03/exampleSite/.

  6. In the built-in terminal window, run hugo server -D, which is equivalent to hugo server --buildDrafts.

  7. In a web browser, view http://localhost:1313.

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

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

💡
If a theme 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 -fyaml 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…

 

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. Make sure your editor includes an integrated terminal emulator.

Comments & reactions 👍 👎 📝

To comment or react, you must be signed in to GitHub.