Hugo is useful when a website has repeated page structures and content that benefits from a consistent publishing process. You write content, define templates, and build a collection of files for your web host. Understanding those separate stages makes the project easier to troubleshoot: a content problem, a template problem, and a deployment problem need different fixes.
This walkthrough describes a small article site built from an empty project folder. The template paths use the layout organization introduced in Hugo 0.146. If you maintain an older project, check its version and existing conventions before changing paths. The goal is a modest working foundation that you can expand after completing a reliable first release.
1. Establish the project and its build environment
Install a Hugo version suitable for the project and record the output of hugo version. If you later adopt a theme, check whether it needs a particular Hugo edition, version, or additional tools. Keeping those requirements explicit prevents a project from working only on the original author's computer.
Create a project folder with content, layouts, and static directories, plus a hugo.toml configuration file. For this minimal example, set a site title and a base URL. Use the real production address before release, including its protocol and trailing slash.
baseURL = 'https://example.org/'
title = 'Field Notes'Keep a short README beside the configuration. Record the Hugo version, preview command, build command, and intended output folder. Initialize version control when available. You now have a place for authoring, presentation, assets, and project decisions, even though the site still needs content and templates before it becomes useful.
2. Create a content file with deliberate metadata
Add content/posts/first-guide.md. Front matter at the beginning of the file carries metadata; the remaining Markdown supplies the body. Start with a title, date, description, and draft status. Use dates that reflect your editorial record, and write the description as a useful summary of the particular page.
---
title: "A first publishing checklist"
date: 2025-07-16
description: "A repeatable process for reviewing a small release."
draft: true
---
## Prepare the content
Review the title, links, images, and final instructions.Keep the sample draft until you have reviewed the complete page. Hugo normally excludes draft content from a production build, while the draft preview flag lets you inspect it locally. A draft setting is part of the authoring workflow; it is not an access-control system for files you choose to publish.
Agree on an editorial checklist for these fields before inviting another contributor. For example, require the title to describe the actual lesson, the description to stand alone, and the date to follow one documented convention. Keep optional fields optional in the template too. An article without a subtitle should still produce a complete, well-spaced page, without a blank heading or an unexplained gap.
As you add articles, keep required fields consistent. A description that exists in front matter still needs a template that uses it. Validate both the content record and the resulting document.
3. Give the site shared page templates
Create a base template for the document shell, a single template for articles, and a list template for collections. Hugo's template types documentation describes these roles and how named blocks connect a base template to the templates that use it.
Place this compact shell in layouts/baseof.html. It establishes the document language, title, viewport, and main content region. Add shared navigation and styles after the basic pages render.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{{ .Title }}</title>
</head>
<body><main>{{ block "main" . }}{{ end }}</main></body>
</html>In layouts/single.html, define the article content block:
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ end }}In layouts/list.html, define a collection view:
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
<ul>{{ range .Pages }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}</ul>
{{ end }}This intentionally small design exposes the relationship between content and output. Once it works, add styling and page-specific details without losing that clear structure.
4. Shape routes and collections around readers
Inspect the generated home and posts pages before adding many articles. Decide what the homepage should introduce and whether its primary list should lead to sections or individual articles. A dedicated home template can provide that editorial choice as the site grows. The generic list above is a starting point, not a final content strategy.
Add a section introduction where it helps explain what readers will find. Keep slugs descriptive and stable. When a published path changes, plan a redirect on the host and update the links you control. Renaming a source file deserves the same review as changing a visible navigation destination.
Keep classification useful
Choose a small set of meaningful topics before creating taxonomies. Test empty and small collections, and decide how archives should behave. The Hugo static website builder overview discusses the fit between structured content and shared templates. A collection should help a reader choose their next page, rather than exist only because a generator can produce it.
5. Organize assets and shared presentation
For this small project, place directly served files in static, using descriptive paths such as static/images/publishing-checklist.webp. Hugo copies files from that directory into the published output. As the project becomes more sophisticated, page resources and asset processing can support other arrangements; adopt them when they solve a concrete requirement.
Keep references consistent with the deployment location. A site published at a domain root and one published under a subdirectory need careful URL handling. Test the actual configured base path, and use Hugo's appropriate URL and resource functions as you extend the templates. Avoid assuming that every absolute-root reference suits every deployment.
Build a small shared stylesheet for typography, layout, links, and focus states. Test a long heading, a wide code example, and a missing optional image. The accessible HTML and CSS guide provides a practical sequence for checking those patterns before they spread through the article archive.
6. Preview drafts and inspect representative pages
Run hugo server -D from the project folder and open the local address shown in the terminal. The flag includes drafts for review. Read the first article in its actual layout, then navigate through the homepage and section listing. Correct missing titles, unclear links, and layout problems while the project is still small.
Review more than one ideal page. Add a second article with a long title and a third with a table or code sample. Resize the browser, use the keyboard, and confirm that the content remains readable without depending on decorative effects. Inspect the console and terminal for warnings relevant to the pages you changed.
When an article is ready, set its draft status to false. Then check it in a build that uses production settings. Preview and release are separate checks because a development server can include content or behavior that you do not intend to publish.
7. Build and inspect the actual release artifact
Run hugo to generate the production site. The default destination is public. That directory contains the files to deliver, while your content and templates remain the source used to reproduce them. Avoid editing generated HTML as the normal maintenance workflow, because the next build can replace those changes.
Create release output from a clean build destination so obsolete files cannot quietly survive from an earlier version. Inspect the resulting folder and serve it as static files. Load a nested article directly, follow its assets and navigation, and verify that unpublished drafts are absent. Check the production titles, descriptions, and expected routes.
A successful command establishes that the build completed; it does not prove that the release contains the intended content. Compare the output against your page inventory. The static website launch checklist provides a useful final review of links, assets, and publishing details.
Keep a short release record that identifies the source revision, build date, and pages intentionally changed. If an old article remains in the output after its source was removed, stop and resolve the discrepancy before deployment. This record also makes a later content question easier to answer: you can identify which approved source produced the public files and repeat the same build when necessary.
8. Deploy the files and preserve a repeatable process
Configure the host to publish the generated output directory. If the host builds from source, specify the recorded Hugo version, command, and destination. If you upload files, keep the upload process tied to the exact artifact you reviewed. Build completion and deployment completion should be distinguishable in your release notes.
After publishing, verify the public homepage, a deep article URL, and an asset from another directory. Confirm the host's missing-page behavior and any required redirects. Preserve the previous working artifact or a documented way to recreate it, so a correction does not depend on improvisation.
For the next article, repeat the same cycle: write structured content, preview, approve, build, inspect, and release. Improve the templates when a recurring need appears. Hugo becomes easier to maintain when every stage has a clear input, a clear output, and a small set of checks that match the website you actually operate.
