Getting Started on HCD

Understanding Hugo

Sat, 15 Aug 2026 04:09:57 +0800

Hugo is a static site generator (SSG) written in Go. Because it builds static sites, you don't need to worry about server overhead or maintenance. Hugo has many strengths. Speed is just one of them. Flexible configuration, scalability, extensibility, and out-of-the-box readiness are among its other advantages.

Installing Hugo and Its Toolchain

Sat, 15 Aug 2026 04:09:57 +0800

This page explains how to install Hugo on each operating system and set up the environment variable (PATH) it needs to run.

Hugo Editions

Hugo ships in three editions.

Creating a Site

Mon, 01 Jan 0001 00:00:00 +0000

This page explains how to create a new site with Hugo and start the local development server.

Create a Project

hugo new project my-site --format yaml
cd my-site

hugo new project creates the basic directory structure. At this point, the site has no theme or content yet.

Content Authoring

Mon, 01 Jan 0001 00:00:00 +0000

This page covers the Markdown, front matter, and shortcode syntax you'll use when writing content.

Content Structure

A content directory looks like this:

content
├── _index.md # 1. Home page
├── docs
│ ├── _index.md # 2. List page
│ ├── p1.md # 3-1. Post page: filename only
│ ├── p2 # 3-2. Post page: using index.md
│ │ ├── foo.jpg
│ │ └── index.md
│ └── bar # Nested list
│ ├── _index.md # List page for the nested section
│ ├── post-1.md
│ └── post-2.md
└── tags
 ├── _index.md # 4. List page for tags
 └── my-tag.md # Tag page

The home page is the _index.md at the top level
Every other _index.md with a leading underscore is a list page
A post page can use either a filename.md or a filename/index.md, cannot have child pages
A tag's _index.md is likewise a list page

Both p1.md and p2/index.md can create a standalone post, but only the latter can hold its own page resources, such as images or videos. You should default to the post-name/index.md form to keep your project structure consistent, except in two cases:

Basic Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Hugo's configuration file has hundreds of possible settings, which is bound to overwhelm beginners. This page's purpose is to highlight the settings in hugo.yaml that matter most, so you don't get lost in the sheer volume of options.

URLs and Routing

Mon, 01 Jan 0001 00:00:00 +0000

This page explains how Hugo determines the URL for each page. Get URL management right from the start. Broken links damage a site more than almost anything else, so plan your approach early.

Deploying Your Site

Mon, 01 Jan 0001 00:00:00 +0000

To deploy your site to the public internet, Hugo's official documentation provides an extensive walkthrough. See the official documentation.

If you're a beginner without a clear idea of where to start, hugo-community-docs recommend the GitHub Pages option, since it lets you complete everything on a single platform.