Build a Manual with Hugo #1: From Install to Your First Doc

When you start building documentation in earnest, you almost always run into the same problem: where do you put the documentation that a single README can’t handle anymore? Notion makes public sharing and version control awkward, and a blog tool just lists posts in chronological order, which is inconvenient as a reference. So many teams move to treating docs like code — Docs as Code. You write in Markdown, manage it with Git, and ship it as a static site.

This series covers the first step of that move: building a documentation site with a static site generator. The tool is Hugo. It’s a single binary built in Go, so installation is lightweight, and builds finish in around a second even at hundreds of pages. For the theme, we use Hextra, which is purpose-built for documentation.

This series, Build a Manual with Hugo, runs in six parts.

• #1: From Install to Your First Doc ← this post
• #2: Sidebar and Search — Shaping the Information Architecture
• #3: Writing Content — Code Blocks, Mermaid, Callouts
• #4: Deploying to Cloudflare Pages and Connecting a Domain
• #5: Multilingual Content and Versioning
• #6: Maintenance — Search Index, Accessibility, Documentation Culture

This post walks through, hands-on, what Hugo requires as prerequisites and how to create a new site, attach Hextra, and serve your first doc locally.

Three Prerequisites #

A Hugo documentation site requires three tools installed up front.

1. Hugo Extended — Hugo comes in two editions, standard and Extended. Modern themes including Hextra use built-in asset processing, so you must install Extended.
2. Go — Hextra is distributed as a Hugo Module. You need Go to download and update the theme.
3. Git — Hugo Modules use Git internally, and since you’ll manage your docs with Git anyway, you set it up alongside.

Installing Hugo #

The commands per operating system are as follows.

# macOS (Homebrew)
brew install hugo go git

# Windows (winget)
winget install Hugo.Hugo.Extended GoLang.Go Git.Git

# Linux (e.g. on Debian/Ubuntu the distro package is often outdated,
# so installing the official release binary is recommended)
sudo apt install golang-go git
# For Hugo Extended, download and install hugo_extended_*.deb from the GitHub releases

After installing, check the version. The output must include extended.

hugo version
# confirm the extended marker, like hugo v0.xxx.x+extended ...
go version

If you don’t see extended, the standard edition is installed; reinstall with Extended so you don’t get stuck at the next step.

Creating a New Site #

Generate an empty site. We’ll specify the config file format as YAML, which is easy to read.

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

In the generated folder, initialize Hugo Modules. The path at the end is where you’ll later host this repository. It doesn’t have to be exact right now, and that won’t affect how things work.

hugo mod init github.com/your-account/my-docs

Wiring Up the Hextra Theme #

Open the config file hugo.yaml and set it up to import Hextra as a module.

# hugo.yaml
baseURL: "https://example.com/"
title: Product Manual
languageCode: ko

module:
  imports:
    - path: github.com/imfing/hextra

Then download the theme module.

hugo mod get github.com/imfing/hextra

Unlike the old approach of copying the theme in as a Git submodule, the module approach lets you bump the version up or down with a single command, which keeps management clean.

Serving Your First Doc #

Now create a single doc. First, content/_index.md, which becomes the front page.

---
title: Product Manual
---

This is our team's official documentation. Pick an item from the sidebar on the left.

Next, add one actual doc.

hugo new content docs/getting-started.md

Open the generated file and fill in the body.

---
title: Getting Started
---

## Installation

Install with the following command.

```bash
npm install our-product
```

Finally, start the local server. To include draft docs as well, add the -D option.

hugo server -D

Open http://localhost:1313 in your browser and the doc you just made appears in Hextra’s default layout, complete with the sidebar. Edit and save a file and the screen refreshes automatically.

Understanding the Folder Structure #

In the structure built so far, the one place you need to know right now is content.

my-docs/
├─ hugo.yaml        # site config
├─ content/         # doc bodies (you only need to fill this in)
│  ├─ _index.md     # front page
│  └─ docs/
│     └─ getting-started.md
├─ static/          # files served as-is, such as images
└─ go.mod           # module list (records the Hextra dependency)

Growing your docs comes down to adding more Markdown files under content. The folder structure becomes the sidebar hierarchy directly. This is the biggest difference from a blog tool, and it’s the main subject of the next post.

Wrapping Up #

In this post we installed Hugo Extended and Go, attached Hextra to a new site, and served our first doc locally. It’s still just the basic skeleton, but we confirmed the flow where a single Markdown file becomes a searchable documentation page right away.

The next post covers sidebar configuration and search. It’s the stage where you design the information architecture so readers don’t get lost even as the docs grow to dozens of pages.