ii.com: Easy Way to Play With a Hugo Theme’s Example Site

News

2021-July-5 Hugo v0.85.0 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.

Hugo is installed on your system.⁠^[2]
You know how to download or clone a Hugo theme from a git hosting provider such as GitHub.com.
You use a text editor with an integrated terminal emulator, for example…
- Code, which is also known as Visual Studio Code and VS Code,
- IntelliJ IDEA Ultimate or Community Edition,
- or Atom.
You have a web browser with JavaScript enabled.⁠^[3] JavaScript is needed by the LiveReload feature of Hugo’s built-in web server.

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 eight steps below, the directory structure will look something like this:

HugoPlayground/
└── themename-2021-07-18/
    ├── archetypes/
    ├── assets/
    ├── exampleSite/
    ├── layouts/
    └── static/

💡	If you are on Windows, you might want to put a shortcut to this `HugoPlayground` directory on your desktop. To learn about this tip, see Infinite Ink’s Windows Desktop Shortcuts Give me Quick Access to Anything.

‼	For the steps below to work, do not move the theme’s `exampleSite` directory. It must be a subdirectory of `themename-2021-07-18/`.

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.

Browse themes.gohugo.io and find a theme you like that includes…
- an exampleSite directory
- and a README with clear detailed instructions.
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-07-18/. This is useful if you play with a lot of themes on a lot of days over many years (as I have done).
Launch Code so that the directory themename-2021-07-18/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.
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-07-18"
```
Or something like this in a config.yaml:
```
themesDir: ../..
theme: themename-2021-07-18
```
Note that the dee in themesDir is upper case.
Open Code’s integrated terminal emulator and make sure the terminal’s working directory is themename-2021-07-18/exampleSite/.
In the terminal window, run hugo server -D, which is equivalent to hugo server --buildDrafts.
In a web browser, view http://localhost:1313.⁠^[5]
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.

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

the theme’s README
and gohugo.io’s Quick Start.

💡	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`

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