↓Skip to main content

Creating a Blog with Hugo: Setup Guide

·
Blog Hugo
Table of Contents
⚠️ Note: Auto-translated Article
This page was generated by AI-assisted automatic translation from the original Japanese article.

Setup Overview #

Following the plan from the previous post, prepare the environment with the steps below.

  1. Windows PC writing environment
    1. Prerequisites
    2. Install the Hugo application
    3. Create a Hugo site (folder)
    4. Install a Hugo theme
    5. Enable the Hugo theme
    6. Set up a new article folder
    7. Write an article
    8. Test the blog display on the Windows PC
  2. GitHub integration
    1. Initialize git in the Hugo site folder
    2. Commit and push to a GitHub repository
  3. Netlify publishing
    1. Initial Netlify registration
    2. Connect Netlify and GitHub
    3. Verify the Netlify build
    4. Blog publishing settings (DNS)

Windows PC Writing Environment #

Prerequisites #

Install Visual Studio Code as the writing environment. On recent Windows, it can be installed easily with the winget command.

winget install Microsoft.VisualStudioCode

The following extensions are also recommended for Hugo writing:

Install the Hugo Application #

Install via winget:

winget install Hugo.Hugo.Extended

Verify the version:

PS C:\> hugo version
hugo v0.132.2-3fd26c70dff5934ec1802b9563530130ed1bca75+extended windows/amd64 BuildDate=2024-08-14T16:17:21Z VendorInfo=gohugoio

Create a Hugo Site (Folder) #

Create the Hugo folder structure in a working directory. To place it under Dropbox management, specify the path as shown below.

cd "${env:USERPROFILE}\Dropbox"
hugo new site blog

On success, a “Congratulations!” message is displayed.

Congratulations! Your new Hugo site was created in C:\Users\XXXX\Dropbox\blog.

Just a few more steps...

1. Change the current directory to C:\Users\XXXX\Dropbox\blog.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>\<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

See documentation at https://gohugo.io/.

Initial Folder Structure (as of Hugo 0.132.2) #

Official docs: Directory structure

blog/            # Hugo site root folder
  |- archetypes/
  |- assets/
  |- content/    # Article files go here
  |- data/
  |- i18n/
  |- layouts/
  |- static/     # Static files (custom CSS, images, etc.)
  |- themes/     # Hugo theme folder
  |- hugo.html   # Configuration file

Folders Added After Build #

When publishing the site, only the contents of public/ need to be copied to the web server.

blog/
  |- public/     # Folder for web publication
  |- resources/

git Initial Setup #

Initialize git to version-manage the entire Hugo site.

cd "${env:USERPROFILE}\Dropbox/blog"
git init
# Create an initial empty commit
git commit --allow-empty -m "first commit"

Install a Hugo Theme #

Browse the Hugo theme site for a theme you like and place it under the Hugo site folder. To keep it under git management, expand it as a subtree as shown below.

Example: installing a sample theme

git remote add thenewdynamic-ananke https://github.com/theNewDynamic/gohugo-theme-ananke
git subtree add --prefix themes/ananke --squash thenewdynamic-ananke master

Some Hugo setup articles recommend using git submodule to include a theme, but since you may need to modify the theme structure, git subtree is a better fit.

Hugo Configuration File #

Initial configuration example: hugo.toml

baseURL = 'https://example.org/'
title = 'New Hugo Site'
languageCode = 'en'
defaultContentLanguage = "en"
theme = "ananke"                 # Specify theme name
hasCJKLanguage = false

[Params]
  date_format = "2006/01/02(Mon)"

Hugo Configuration Notes #

Writing Articles #

Articles are recognized as long as *.md files are placed under the content folder. There is no strictly enforced file layout pattern.

For maintainability, this blog uses the following structure:

blog/
  |- content/
    |- posts/
      |- YYYYMMDD-TOPIC1/   # Article 1 folder
        |- index.md         # Article 1 Markdown file
        |- xxxxx.jpg        # Image used in article 1
        |- xxxxx.png        # Image used in article 1
      |- YYYYMMDD-TOPIC2/   # Article 2 folder
        |- index.md         # Article 2 Markdown file
        |- xxxxx.jpg        # Image used in article 2
        |- xxxxx.png        # Image used in article 2
    |- privacy.md           # Site-wide fixed pages, etc.
  • Keeping each article in its own folder groups the article with its referenced images.
  • Including the date in the folder name sorts folders chronologically.
    • The URL also contains the date, making the article’s age explicit.
  • Appending the topic name to the folder name makes the subject inferrable from the URL alone.
  • Using a single folder level keeps management simple.
    • Use tags to categorize articles by genre.

Adding an Article Folder #

When starting a new article, use hugo new to scaffold the folder.

cd (BLOG top folder)
hugo new (article folder)/index.md

Example:

cd "${env:USERPROFILE}\Dropbox\blog"
hugo new posts/20240818-test/index.md

A template-based index.md is automatically created.

Writing the Article #

index.md has the following structure (TOML front matter format):

---
+++
(Front Matter section)
title = '20240818 Test'
date = 2024-08-18T19:59:42+09:00
draft = true
...
+++

(Body)

Article-specific metadata is added to the Front Matter section. By default, draft is true, so the article is treated as a draft and is not included in the public build output.

The body of the article is written in Markdown in your editor.

←→ Creating a Blog with Hugo: Background My Blog Setup (January 2025) →←