devkuma – Hugo

Hugo Blog

kc@example.com (kc kim) — Tue, 29 Nov 2022 21:42:00 +0900

Docusaurus Documentation Generator

kc@example.com (kc kim) — Tue, 29 Nov 2022 21:42:00 +0900

Make Hugo Count Korean Words Correctly in Page Summaries (hasCJKLanguage, isCJKLanguage)

kc@example.com (kc kim) — Sun, 14 May 2023 16:06:00 +0900

On Hugo post list pages, the beginning of an article is displayed as a summary limited to a specific number of words, usually 70 words. However, this word count is calculated based on languages such as English by default, so Korean and other CJK text is not counted correctly, and summaries may be displayed too long.

Configure in the Settings File

To count Korean characters correctly and display short summaries, set hasCJKLanguage to true in the settings file as follows.

For config.toml

hasCJKLanguage = true

For config.yaml

hasCJKLanguage: true

With this, Hugo’s internal .Summary and .WordCount work correctly for Korean, and shorter summary text is displayed.

Configure Per Page

If you want to configure it for each page, set isCJKLanguage to true in the front matter as follows.

---
title: Post title
date: "2023-05-14"
isCJKLanguage: true
---

Post body

Use hasCJKLanguage in the settings file and isCJKLanguage in the front matter of Markdown files.

Getting Started with Hugo

kc@example.com (kc kim) — Sun, 14 May 2023 15:36:00 +0900

Specify the Hugo Source Directory Path - Command Option (hugo server --source)

kc@example.com (kc kim) — Sat, 13 May 2023 02:25:00 +0900

Specify the Source Directory Path

When running the hugo command, you can start it by specifying the source directory path with the -s (--source) option.

Example: Start the Hugo server using the source code in ~/mysite

$ hugo server -s ~/mysite

Example: Create a new article in ~/mysite

$ hugo new sample.md -s ~/mysite

Setting a Command Alias

In the example above, the source directory was specified after the command with the -s ~/mysite option, but Hugo also works if it is specified before the command.

Using this, if you set a command alias (alias) like the following, it is convenient because you can run the command immediately from any directory. ~/.bash_profile

alias hugo-mysite=hugo -s ~/mysite

For example, you can use it as follows.

$ hugo-mysite new sample.md  # Create a post
$ hugo-mysite server         # Start the Hugo server
$ hugo-mysite                # Build the site (output to ~/mysite/public)

How to Create Hugo Posts

kc@example.com (kc kim) — Fri, 05 May 2023 23:34:00 +0900

Creating a New Post File

Website posts published with Hugo are created as Markdown files in the content directory, for example sample.md. You can create a post file from an empty text file, but by using the hugo new command, you can automatically generate a Markdown file based on a post archetype file (archetypes/default.md).

Create a post file (Markdown file).

% hugo new sample.md
Content "/Users/user/my-site/content/sample.md" created

When you run it as above, the sample.md file is created in the content directory. At the beginning of the created file, a header called front matter is written as shown below. This header is automatically generated based on archetypes/default.md.

content/sample.md

---
title: "Sample"
date: 2023-05-05T23:50:09+09:00
draft: true
---

Then rewrite the title (title) as you like, and write the article body after the front matter header. When the article has reached a publishable level, delete the draft: true line in the header.

Archetypes

Now let’s look at the archetypes/default.md file that serves as the basis.

archetypes/default.md

---
title: {{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }}
draft: true
---

The title field is automatically filled with the name specified by the hugo new command, and the date field is automatically filled with the current time. From this, you can see that the post file is created based on the contents of this file.

Start Editing in an Editor While Creating a Post

When creating a post file with the hugo new command, specifying the --editor option opens the file in the specified editor at the same time the post file is created.

Example: Create an article file and open it in vim

% hugo new sample.md --editor vim

When you run it for the first time, you may see an error like the following.

% hugo new sample.md --editor vi
Content "/Users/user/hugo-tutorial/my-site/content/sample.md" created
Editing "/Users/user/hugo-tutorial/my-site/content/sample.md" with "vi" ...
Error: access denied: "vi" is not whitelisted in policy "security.exec.allow"; the current security configuration is:

[security]
  enableInlineShortcodes = false

  [security.exec]
    allow = ['^dart-sass-embedded$', '^go$', '^npx$', '^postcss$']
    osEnv = ['(?i)^((HTTPS?|NO)_PROXY|PATH(EXT)?|APPDATA|TE?MP|TERM)$']

  [security.funcs]
    getenv = ['^HUGO_']

  [security.http]
    methods = ['(?i)GET|POST']
    urls = ['.*']

As the message indicates, copy the default policy into config.toml and add '^vim$' to the allow array.

[security]
  enableInlineShortcodes = false

  [security.exec]
    allow = ['^dart-sass-embedded$', '^go$', '^npx$', '^postcss$', '^vim$']
    osEnv = ['(?i)^((HTTPS?|NO)_PROXY|PATH(EXT)?|APPDATA|TE?MP|TERM)$']

  [security.funcs]
    getenv = ['^HUGO_']

  [security.http]
    methods = ['(?i)GET|POST']
    urls = ['.*']

Then try again and it should run. However, because the post file is created before the editor opens, you may see a message saying the file already exists.

% hugo new sample.md --editor vim
Error: /Users/user/hugo-tutorial/my-site/content/sample.md already exists

In that case, delete the existing file and run the command again.

Hugo Overview and Installation

kc@example.com (kc kim) — Wed, 19 Oct 2022 08:22:00 +0900

What Is a Static Site Generator?

A Static Site Generator (SSG) is a tool for creating websites based on static pages. It reads content and files and converts them appropriately into HTML.

You can check the available types of SSGs here. Among them, the major SSGs often used with GitHub are as follows.

Jekyll
- Ruby-based
- Currently the most popular (the largest number on GitHub)
- Has the most Korean reference documents
- Builds are relatively slow
- Windows is not officially supported
Hexo
- Node.js-based
- Has many Chinese documents
- Has many Korean reference documents
Hugo
- Golang-based
- Builds quickly
- Well documented
- Does not have many Korean reference documents

What Is Hugo?

Hugo is one of the static site generators, like Jekyll and Hexo, that makes it easy to create websites. It can be considered a kind of blog engine.
Pages can be written in Markdown, and many blog themes are available, so you can choose and use the theme you want.

Installing Hugo

Download and install the package for your OS from the site below.

https://github.com/gohugoio/hugo/releases

Alternatively, refer to the site below and install it.

https://gohugo.io/getting-started/installing/

Installing with Homebrew on macOS

With Homebrew, the package manager for macOS, you can easily install Hugo with the following single command.

The command to install with Homebrew is as follows.

brew install hugo

Run the actual command.

% brew install hugo
==> Downloading https://ghcr.io/v2/homebrew/core/hugo/manifests/0.104.3
######################################################################## 100.0%
==> Downloading https://ghcr.io/v2/homebrew/core/hugo/blobs/sha256:3b355290c70c54cf0637a9ed70342d289c9f022e4d085e18cb0e4651e3bbe21b
==> Downloading from https://pkg-containers.githubusercontent.com/ghcr1/blobs/sha256:3b355290c70c54cf0637a9ed70342d289c9f022e4d085e18cb0e4651e3bbe21b?se=2022-10-18T23%3A
######################################################################## 100.0%
==> Pouring hugo--0.104.3.arm64_monterey.bottle.tar.gz
==> Caveats
zsh completions have been installed to:
  /opt/homebrew/share/zsh/site-functions
==> Summary
🍺  /opt/homebrew/Cellar/hugo/0.104.3: 48 files, 55.8MB
==> Running `brew cleanup hugo`...
Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP.
Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).

If Hugo is already installed and you want to update it to the latest version, run the following command.

% brew upgrade hugo

After installation, if you can check the version, the installation was successful.

% hugo version
hugo v0.104.3+extended darwin/arm64 BuildDate=unknown

Installing on Windows

To install Hugo on Windows, download the zip archive (hugo_extendedx0.xxx.x_windows-amd64.zip) from the Hugo Releases page and install it.
If you use features such as Sass, be careful to use a file that starts with hugo_extended.

Place the distributed hugo.exe in an appropriate directory and add it to your path to complete the installation.

How to Reference Information Set in Hugo Configuration Files (config.yml)

kc@example.com (kc kim) — Sun, 14 May 2023 16:33:00 +0900

Configuration File Basics

General settings for a Hugo site are placed in the root directory and use one of the following configuration files. If multiple files exist, the first discovered one is selected.

File name	Description
`config.toml`	Written in TOML format (default)
`config.yaml`	Written in YAML format
`config.json`	Written in JSON format

Example config.toml

baseURL = "https://www.devkuam.com/"
languageCode = "ko-kr"
title = "My Blog"
themesDir = "../hugo_themes"
theme = "devkuma"

Configurable parameters and their default values are listed below.

Configure Hugo | Hugo

Referencing Setting Values

Referencing Parameters Defined by Hugo

Parameters set in the configuration file can be referenced in template files using the .Site variable. For example, values such as the title parameter and baseURL set in config.toml can be referenced as follows.

This site's title is <b>{{ $.Site.Title }}</b>.
This site's base URL is <b>{{ $.Site.BaseURL }}</b>.

Parameter names begin with uppercase letters, so use .Site.Title rather than .Site.title. You can see which property names correspond to each setting by checking the list of Site variables below.

To branch processing depending on whether a parameter is configured, write it as follows.

{{ with $.Site.GoogleAnalytics }}
  The Google Analytics tracking ID is <b>{{ . }}</b>.
{{ else }}
  The Google Analytics tracking ID is not configured.
{{ end }}

The example above uses the googleAnalytics parameter to check whether a tracking ID for Google Analytics has been configured.

Referencing Custom Parameters

To set custom parameters in the configuration file, add parameters under the params section.

config.toml

baseURL = "https://www.devkuam.com/"
languageCode = "ko-kr"
title = "My Blog"

[params]
  GitHubUser = "redfreek2c"
  Twitter = "kimkc"
  Subtitle = "Technical sharing"
  Description = "This section records detailed site information"
  SidebarRecentLimit = 5
  ListOfFoo = ["foo1", "foo2"]

Custom parameters can be referenced from template files in the form $.Site.Params.name.

The example below references the Description value of a custom parameter variable.
layouts/partials/head.html

<meta name="description" content="{{ if .IsHome }}{{ $.Site.Params.description }}{{ else }}{{ .Description }}{{ end }}" />

Here, the main first page (home page) references the configuration file setting ($.Site.Params.Description), while other pages reference the description value set in each page’s front matter.

Creating Hugo Posts

kc@example.com (kc kim) — Sun, 14 May 2023 15:36:00 +0900

Specify the Port When Starting the Hugo Server - Command Option (hugo server --port)

kc@example.com (kc kim) — Sat, 13 May 2023 02:32:00 +0900

When you start a Hugo server with the hugo server command, it starts a web server that uses port 1313 by default.

However, if you try to start multiple Hugo servers at the same time, later Hugo servers are assigned arbitrary port numbers. Port numbers from the private port range, 49152 to 65535, are used.

Specify the Port

To specify an arbitrary port number, use the -p (--port) option as follows.

Example: Start the Hugo server with port number 51234

$ hugo server -p 51234

Start Multiple Hugo Servers at the Same Time

When starting multiple Hugo servers at the same time, it is best to decide the port number each site will use.

Example: Start three Hugo servers at the same time

$ hugo server -p 50001 -s ~/mysite1
$ hugo server -p 50002 -s ~/mysite2
$ hugo server -p 50003 -s ~/mysite3

The websites started as above can be accessed at the following addresses.

http://localhost:50001/
http://localhost:50002/
http://localhost:50003/

How to Create Draft Posts in Hugo - Draft Page

kc@example.com (kc kim) — Sat, 06 May 2023 00:07:00 +0900

Draft Posts

Hugo’s draft feature temporarily stores unfinished article files in the same location as other articles. If draft: true is written in the front matter section of a page, that page is treated as a draft.

YAML format

---
draft: true
---

Body

TOML format

+++
draft = true
+++

Body

Posts written as drafts are not output as HTML files by default. To output draft posts as well, specify the -D (--buildDrafts) option with the hugo command.

Output draft posts

% hugo -D         # When generating the site
% hugo server -D  # When starting the server

Be Careful with Draft Posts Output to the public Directory

The hugo command outputs HTML files and other generated files to the public directory by default, but at that time it does not delete draft posts that already exist inside the public directory.

% hugo -D  # Generates the site including draft posts.
% hugo     # Even if generated later with draft mode off, existing draft posts are not deleted.

When publishing a website, be careful not to upload draft articles by mistake. Before uploading posts, it is safer to delete the public directory and regenerate it with the hugo command.

Linux / macOS

% rm -Rf public && hugo

Windows

C:\> rmdir /s /q public & hugo

Checking the List of Draft Posts

Checking from the Command Line

If you run hugo list drafts on the command line, you can see a list of posts in the content directory that are marked as drafts, meaning their front matter contains draft: true.

% hugo list drafts
content/draft.md
content/post/sample2.md

Reference: hugo list drafts | Hugo

Checking in a Template

To list links to draft posts in a template file, write the following first.

layouts/index.html

<h2>Draft Pages</h2>
<ul>
  {{ range (where .Site.Pages ".Draft" true) }}
    <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
  {{ end }}
</ul>

The part written as where .Site.Page ".Draft" true specifies the search condition for extracting draft posts.
It specifies that all pages in the site (.Site.Pages) whose page variable .Draft is true (".Draft" true) should be listed.

Then run the startup command with the -D option.

% hugo server -D

Determining Whether a Post Is a Draft

To check in a template file whether the currently rendered article is a draft, meaning draft: true is written in the front matter, refer to the page variable .Draft.

layouts/_default/single.html

<h1>{{ .Title }}</h1>
{{ if .Draft }}
  <b>Warning: This post is still a draft.</b>
{{ end }}

Of course, it will only be visible if you start Hugo with the -D option.

Creating a New Hugo Website

kc@example.com (kc kim) — Fri, 05 May 2023 18:17:00 +0900

Creating the Site Skeleton

First, install Hugo and prepare an environment where the hugo command can be used. Then, as shown below, use the hugo new site command to create the initial directory skeleton for the website.

Create a new website (my-site)

% hugo new site my-site
Congratulations! Your new Hugo site is created in /Users/user/hugo-tutorial/my-site.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

The generated files are very simple: only two files and a few directories, as shown below.

.
└── my-site
    ├── archetypes     : Template files used when creating new pages
    │   └── default.md
    ├── config.toml    : Site-wide configuration file
    ├── content        : Location for content. Place Markdown files that become site content here.
    ├── data           : Data used when generating the site
    ├── layouts        : Location for layout templates
    ├── public         : Location for generated HTML, CSS, images, and other deployed files
    ├── static         : Location for files, such as images, copied as-is during site generation
    └── themes         : Location for theme directories. The actual theme to use is specified in config.toml.

If you start the server in this state, it shows “Page Not Found”.

Installing and Configuring a Site Theme

After creating a new website in Hugo, configure a theme that defines its appearance. A site created with hugo new site does not include a theme, so you need to download one from the themes published on the site.

Here, we will apply a theme called mainroad.

Hugo themes can be stored by creating a theme directory under the themes directory. Because each theme is stored in a separate directory, you can download several themes in advance and easily switch the theme you use.
Themes are usually distributed on GitHub, so if Git is installed, you can apply one easily with git clone from the root path as follows.

% cd themes
% git clone https://github.com/vimux/mainroad

Or you can run the command all at once as follows.

% git clone https://github.com/vimux/mainroad themes/mainroad

If the themes/mainroad directory was created by the command above, next add the following content to the Hugo configuration file (config.toml) so that this theme is used.
config.toml

theme = "mainroad"

This completes the theme configuration.

Setting the Site Title and Language

In the site configuration file, in addition to the theme setting, you should configure the site title (title) and the language used by the whole site (languageCode).

config.toml

baseURL = "http://devkuma.com/"
languageCode = "ko-kr"
title = "My New Hugo Site"
theme = "mainroad"

Info

The values configured here can be referenced in template files as `{{ .Site.Title }}`, `{{ .Site.BaseURL }}`, and `{{ .Site.LanguageCode }}`.

Writing a Post

Here, let’s write one example post. If you run the hugo new command as follows, a post file (Markdown file) is automatically created under the content directory. Run the command from the top-level directory of the project.

$ hugo new post/sample.md

This creates the content/post/sample.md file. Edit it in the following format.

content/post/sample.md

---
title: "Post Title"
date: 2023-05-05T23:19:43+09:00
#draft: true
---

Post body  
Post body  
Post body

If the draft: true line in the header is not removed or commented out, the page will not be output, so that line must be removed.

Starting the Hugo Web Server

After configuring the website theme and writing an article, run the hugo server command to start the web server.

% hugo server
Start building sites …
hugo v0.104.3+extended darwin/arm64 BuildDate=unknown

                   | EN
-------------------+-----
  Pages            |  7
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  5
  Processed images |  0
  Aliases          |  3
  Sitemaps         |  1
  Cleaned          |  0

Built in 7 ms
Watching for changes in /Users/user/hugo-tutorial/my-site/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /Users/user/hugo-tutorial/my-site/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

It takes only 7 ms to start the Hugo server. It is extremely fast.

With the Hugo server running, open http://localhost:1313/ in a web browser and the first page of the site will be displayed.

From then on, continue writing posts with the hugo new command. The Hugo server monitors changes in the content directory and automatically refreshes when posts are created or modified, so once the Hugo server has been started, it does not need to be restarted.

The way to customize posts differs slightly by theme, so refer to each theme’s site for details.

Insert Google Analytics Tracking Code in Hugo (googleAnalytics)

kc@example.com (kc kim) — Sun, 14 May 2023 16:33:00 +0900

With Google Analytics, you can analyze website access information from multiple angles. This article explains how to easily insert Google Analytics code into a website created with Hugo.

Set the Tracking ID in the Configuration File

First, in the Google Analytics admin screen, run “Add property” and add the address of the website you want to analyze. If you do not have a Google Analytics account, create one first. The tracking ID issued at this time, such as G-AB1CD2EFGH, is identification information for determining access to that website. Because this ID differs by website, it is best to set it in the Hugo configuration file.

Hugo provides the googleAnalytics parameter in advance as a configuration file parameter. Set the tracking ID issued by the Google Analytics site as follows.
config.toml

baseURL = "https://www.devkuam.com/"
languageCode = "ko-kr"
title = "My Blog"
theme = "devkuma"

googleAnalytics = "G-AB1CD2EFGH" # example code

With this setting, you can check the tracking ID in template files with .Site.GoogleAnalytics.

Configure Automatic Insertion of Tracking Code (JS)

To use Google Analytics, each page must include tracking code like the following before the head element.

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-AB1CD2EFGH"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'G-AB1CD2EFGH');
</script>

Here, use a Hugo partial template to include the HTML code above in each page. The part that specifies a tracking ID such as G-AB1CD2EFGH is replaced with the value specified by the googleAnalytics parameter in the configuration file.

layouts/partials/analytics.html

{{ if not .Site.IsServer }}
{{ with .Site.GoogleAnalytics }}
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id={{ . }}"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', '{{ "{{" }} . }}');
</script>

{{ end }}
{{ end }}

Lines 1 and 2 of the template above control output so that tracking code is not printed when testing on a local Hugo server or when googleAnalytics is not configured.

Include the created partial template from a template file as follows. Here, it is included from the base template (baseof).
layouts/_default/baseof.html

<!DOCTYPE html>
<html lang="ja">
<head>
  {{- partial "analytics" . -}}
  <meta charset="UTF-8">
  ...omitted...
</head>
<body>
  ...omitted...
</body>
</html>

Now all pages include the Google Analytics tracking code.

Appendix: Hugo Built-in Template

In fact, Hugo provides a built-in internal template that includes Google Analytics tracking code.

You can easily insert tracking code by writing the following in any template file.

{{ template "_internal/google_analytics.html" . }}  <!-- synchronous version -->
{{ template "_internal/google_analytics_async.html" . }}  <!-- asynchronous version -->

However, built-in templates do not suppress code output when running on a local server, and they may not flexibly handle Google changes, so it is better to create a partial template if possible.

Hugo Commands

kc@example.com (kc kim) — Sun, 14 May 2023 15:36:00 +0900

When Page Changes Are Not Reflected in the Hugo Server (hugo server --ignoreCache)

kc@example.com (kc kim) — Sun, 14 May 2023 14:30:00 +0900

Ignore Cache Option

Even after starting the Hugo server and updating a page, changes may not be reflected even if you reload the web browser, especially in shared parts such as layouts and partials.

If the page build succeeds but changes are not reflected, it is a good idea to suspect the Hugo server cache. When running the hugo server command, using the --ignoreCache option renders the page without using the cache.

$ hugo server --ignoreCache

How to Configure Hugo Themes - Themes

kc@example.com (kc kim) — Tue, 09 May 2023 00:40:00 +0900

Downloading a Theme

When generating a website with Hugo, you need to configure a base theme for its appearance. If you output a website with the hugo command without setting a theme, a blank white page is displayed. You can create a theme yourself, but themes already created by others are published on the Hugo Themes page, so it is best to download and use one from there first. Usage differs slightly by theme, so read each theme’s description (README.md) for details.

How to Download a Theme ZIP File

For example, if you like the theme “Beautiful Hugo” below, click the Download button.

In general, you will be moved to the GitHub site. Click “Code” and then click “Download zip” to download the theme.

Place the downloaded theme in the project’s themes directory. In this case, place it in the themes/beautifulhugo directory.

How to Get a Theme from Git

Themes are managed on GitHub, so if you have an environment where you can use Git commands, it is simple to obtain one with git clone as shown below. Of course, you first need to know the repository URL. You can copy the URL displayed when you click the Code button on GitHub.

$ git clone https://github.com/halogenica/beautifulhugo.git beautifulhugo

If you manage your own site with Git, it is better to bring in the theme as a Git submodule as follows. The Git submodule command (git submodule) is a little difficult, but managing a theme as a submodule lets you apply updates from the theme side appropriately.

Get the theme as a submodule

$ git submodule add https://github.com/halogenica/beautifulhugo.git beautifulhugo

When fetching theme updates

$ git submodule update --remote --recursive

Theme-Specific Settings, If Needed

Some themes depend on external components and require initial setup. If a theme asks you to install related modules as shown below, run the commands as-is.

$ npm install
$ npm run build

For reference, npm is a package manager for Node.js and is installed together when you install Node.js.

Specify the Theme to Use

You can download several themes into the themes directory. Among them, set the theme you currently want to use in the Hugo configuration file as follows.

config.toml

theme = "beautifulhugo"

After setting the theme, generate the website with the hugo command. Based on the configured theme, files for upload such as HTML, CSS, and JS will be output to the public directory.

$ hugo

The hugo server command uses the theme configured in config.toml when starting the web server.

You can also specify the theme to use with the -t option when running the hugo command.

$ hugo -t theme_name         // When outputting the site
$ hugo server -t theme_name  // When starting the web server

Hugo Configuration

kc@example.com (kc kim) — Sun, 14 May 2023 15:36:00 +0900

Creating My Own New Hugo Theme - new theme

kc@example.com (kc kim) — Tue, 09 May 2023 00:40:00 +0900

Creating a New Theme

Hugo has many templates that are already publicly available, but you can also design and create a theme exactly as you want. To create a theme, first create a basic form with the following command.

$ hugo new theme {theme name}

For example, running the following creates the themes/my-theme directory.

$ hugo new theme my-theme

The generated files look like the following. The directory structure is created, but the file contents are almost empty. Create templates based on these files.

Form of the newly created theme

themes/my-theme
├── LICENSE   (MIT license)
├── archetypes
│   └── default.md
├── layouts
│   ├── 404.html
│   ├── _default
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── index.html
│   └── partials
│       ├── footer.html
│       ├── head.html
│       └── header.html
├── static
│   ├── css
│   └── js
└── theme.toml (basic configuration file)

Creating the First Page Layout (layouts/index.html)

The layouts/index.html file inside the theme directory is the template file for the site’s first page. If you are creating a site made up of only one HTML file (SPA: Single Page Application), you only need to create this file. Since nothing is written in the initial state, first modify it so that only the site name is displayed at startup.

themes/my-theme/layouts/index.html

<h1>{{ .Site.Title }}</h1>

As shown above, you can output the value of the Title field of the .Site variable, which holds site information. The text set in title in the site configuration file (config.toml) is displayed here.

After creating it up to this point, check the site using this theme. To specify the theme to use with the hugo command, use the -t {theme name} option.

$ hugo server -t my-theme

After starting the Hugo server as above, access http://localhost:1313/ to check the view.

Figure: First page using my theme

Displaying a List of All Pages on the First Page

Inside the first page template (layouts/index.html), you can refer to the .Data.Pages variable to obtain information for all pages (Page variables). If you loop through this information with range, you can output links to all pages.

themes/my-theme/layouts/index.html

<h1>{{ .Site.Title }}</h1>
<ul>
  {{ range .Data.Pages }}
    <li><a href="{{ .RelPermalink }}">{{ .Title }}</a> ({{ .Date.Format "2006-01-02" }})</li>
  {{ end }}
</ul>

Creating a Layout for Each Page (layouts/_default/single.html)

Each linked page is generated based on the layouts/_default/single.html template file, so this file must be created in advance. In this template, you can refer to fields of the Page variable. For example, .Title refers to the page title and .Content refers to the page body.

themes/my-theme/layouts/_default/single.html

<h1>{{ .Title }}</h1>

{{ .Content }}

Prepare the content of each page in the content/ directory as follows.

content/page1.md

---
title: "Page1 Title"
date: "2017-09-10"
---

Page1 Content

If you create the layout file and content as shown above, each page’s content will be displayed as follows.

Figure: Output with a single page template

From here, continue creating template code in the layouts directory in the same way to complete your theme. Shortcodes that can be used in Markdown files can also be provided as custom theme components (layouts/shortcodes).

Configure the Same Theme Directory Across Multiple Hugo Sites (themesDir)

kc@example.com (kc kim) — Sun, 14 May 2023 14:23:00 +0900

The ways to make multiple Hugo projects reference the same theme are as follows.

Create a theme repository on GitHub or elsewhere, and clone that repository into multiple Hugo projects.
Replace each Hugo project’s themes directory with a symbolic link to a shared theme directory.
Configure the settings file (config.toml) to reference the shared theme directory.

The first method is the most common, but when applying the same theme to each site with Git, it can be a little cumbersome during development. In that case, the second and third methods are recommended.

Specify a Shared Theme Directory with a Symbolic Link

On operating systems such as Linux and macOS where symbolic links can be created, it is easy to reference a shared theme directory with a symbolic link. For example, assume there is a shared theme directory (hugo_themes) and three Hugo projects that reference it (site1, site2, and site3) as follows.

.
├── hugo_themes (shared theme directory)
│   └── mytheme
│       ├── archetypes
│       ├── layouts
│       ├── static
│       └── ...
├── site1  (Hugo site 1)
├── site2  (Hugo site 2)
└── site3  (Hugo site 3)

If you replace each Hugo project’s themes directory with a symbolic link to hugo_themes, all sites can point to the same theme directory.

$ cd site1
$ rmdir themes
$ ln -s ../hugo_themes themes

Because setting the theme name to use is still required, set the theme name in each Hugo project’s configuration file (config.toml). site1/config.toml

theme = "mytheme"

Configure a Shared Theme Directory in the Settings File

You can also configure the shared theme directory in Hugo’s configuration file (config.toml). The theme directory is configured with a variable called themesDir, and this directory path can be set to a path above the Hugo project directory.
config.toml

themesDir = "../hugo_themes"
theme = "mytheme"

For example, if each Hugo project’s configuration file is set as above, the shared theme directory (hugo_themes/mytheme/) in the parent directory can be used.

Without using the configuration file, you can also specify the theme directory with the Hugo command option --themesDir.

$ hugo server --themesDir ~/gitwork/hugo_themes

If both the themesDir variable in the settings file and the command-line argument --themesDir are specified, the command-line argument takes precedence.

Check Unused Templates or Shortcodes in Hugo (hugo --printUnusedTemplates)

kc@example.com (kc kim) — Sun, 14 May 2023 15:32:00 +0900

To search for templates that are not used when building a Hugo site, use the --printUnusedTemplates option as follows.

% hugo --printUnusedTemplates
Start building sites …
hugo v0.111.3+extended darwin/arm64 BuildDate=unknown

...omitted...

WARN 2023/05/14 15:25:46 Template _default/list.rss.xml is unused, source file /Users/user/...omitted.../mysite/layouts/_default/list.rss.xml
WARN 2023/05/14 15:25:46 Template _default/single.html is unused, source file /Users/user/...omitted.../mysite/themes/docsy/layouts/_default/single.html
WARN 2023/05/14 15:25:46 Template blog/baseof.html is unused, source file /Users/user/...omitted.../mysite/docsy/layouts/blog/baseof.html

...omitted...

WARN 2023/05/14 15:25:46 Template swagger/single.html is unused, source file /Users/user/user/...omitted.../mysite/themes/mytheme/layouts/swagger/single.html
Total in 3146 ms

In the example above, you can see that several templates or shortcodes are not used.

How to Start and Stop Multiple Hugo Servers at Once

kc@example.com (kc kim) — Sun, 14 May 2023 14:52:00 +0900

About Starting Multiple Hugo Servers

This article explains how to start servers for multiple Hugo sites at the same time from a single command prompt.

Here, assume that several Hugo projects exist under the home directory as follows.

~/website/site1
~/website/site2
~/website/site3

To start the Hugo server for each Hugo project, you can start multiple Hugo servers by specifying different port numbers as follows.

$ hugo server -p 50001 -s ~/website/site1
$ hugo server -p 50002 -s ~/website/site2
$ hugo server -p 50003 -s ~/website/site3

However, as described above, one server process occupies one command prompt, so when starting multiple Hugo servers, you need to keep multiple command prompts open.

Start Multiple Hugo Servers from One Prompt

Windows

With the Windows start command, you can run the Hugo command in the background, so you can start multiple Hugo servers without opening additional command prompts.

For example, the following batch file starts three Hugo servers in the background.
start-servers.bat

@echo off
start /b hugo server -p 50001 -s C:/website/site1
start /b hugo server -p 50002 -s C:/website/site2
start /b hugo server -p 50003 -s C:/website/site3
title Hugo Servers

The final line changes the command prompt window title to “Hugo Servers” with the title Hugo Servers command. Setting the window title is recommended because it makes it easier to identify what the window is for just by looking at the taskbar.

To stop all Hugo servers running in the background together, use the taskkill command to terminate all hugo.exe processes.

stop-servers.bat

@echo off
taskkill /f /im hugo.exe

Linux and macOS

On Linux and macOS, you can easily start multiple servers in the background by adding & at the end when running the Hugo command as follows.
start-servers.sh

hugo server -p 50001 -s ~/website/site1 &
hugo server -p 50002 -s ~/website/site2 &
hugo server -p 50003 -s ~/website/site3 &

To stop the Hugo server processes together, you can easily terminate them with the killall command.
stop-servers.sh

killall hugo

Alternatively, instead of a shell script, you can define functions or aliases and use them quickly.
~/.bash_profile

function hugo-start {
    hugo server -p 50001 -s ~/website/site1 &
    hugo server -p 50002 -s ~/website/site2 &
    hugo server -p 50003 -s ~/website/site3 &
}

function hugo-stop {
    killall hugo
}