Hugo is a fast and flexible static site generator that makes it easy to create blogs, portfolios, and documentation sites.
This tutorial walks you through the essential steps: creating a site, adding content, building your own theme, working with templates, using front matter, and integrating local data files.

1. Creating a New Hugo Site

Start by creating the site skeleton:

1hugo new site quickstart
2cd quickstart

Initialize Git:

1git init

Add the Ananke starter theme:

1git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

Enable the theme:

1echo "theme = 'ananke'" >> hugo.toml

Start the development server:

1hugo server --buildDrafts

2. Adding New Content

Create your first blog post:

1hugo new content content/posts/my-first-post.md

3. Creating Your Own Theme

Generate a new theme named basic inside the themes directory:

1hugo new theme basic

Enable the theme in hugo.toml:

1theme = 'basic'

Add CSS and JS files

themes/basic/static/css/main.css
themes/basic/static/js/main.js

In hugo.toml:

1[[menus.main]]
2name = 'Contact'
3pageRef = '/contact'
4weight = 40

5. Customizing the Header

Replace the default header by editing:

themes/basic/layouts/_default/baseof.html

Example:

1<h1>{{ site.Title }}</h1>
2<nav>
3    <a href="/">Home</a>
4    <a href="/about">About</a>
5    <a href="/resume">Résumé</a>
6    <a href="/contact">Contact</a>
7</nav>

Correct usage:

1<head>
2  <meta name="description" content="{{ index .Site.Params "description" }}">
3  <meta name="author" content="{{ index .Site.Params "author" }}">
4  {{ partial "head.html" . }}
5</head>

6. Creating an Archetype

Create:

archetypes/projects.md

Add:

 1+++
 2date = '{{ .Date }}'
 3title = '{{ replace .Name "-" " " | title }}'
 4draft = false
 5+++
 6
 7![alt](//via.placeholder.com/640x150)
 8
 9Description...
10
11### Tech used
12
13* item  
14* item  
15* item

Create a new project:

1hugo new projects/awesomeco.md

7. Creating a List Layout

Create:

layouts/section.html

Add:

 1{{ define "main" }}
 2  <h1>{{ .Title }}</h1>
 3  {{ .Content }}
 4  {{ range .Pages }}
 5    <section>
 6      <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
 7      {{ .Summary }}
 8    </section>
 9  {{ end }}
10{{ end }}

8. Adding Site Parameters

In hugo.toml:

1[params]
2  author = 'Lance Armstrong'
3  description = 'My Portfolio site'

9. Using Front Matter Data in Templates

Modify the archetype:

themes/basic/archetypes/projects.md

 1+++
 2date = '{{ .Date }}'
 3title = '{{ replace .Name "-" " " | title }}'
 4draft = false
 5image = '//via.placeholder.com/640x150'
 6alt_text = '{{ replace .Name "-" " " | title }} screenshot'
 7summary = 'Summary of the {{ replace .Name "-" " " | title }} project'
 8tech_used = [
 9  "Javascript",
10  "HTML",
11  "CSS"
12]
13+++
14
15Description of the {{ replace .Name "-" " " | title }} project

Update the project layout:

themes/basic/layouts/projects/single.html

 1{{ define "main" }}
 2  <h1>{{ .Title }}</h1>
 3
 4  {{ $dateMachine := .Date | time.Format "2006-01-02T15:04:05-07:00" }}
 5  {{ $dateHuman := .Date | time.Format ":date_long" }}
 6  <time datetime="{{ $dateMachine }}">{{ $dateHuman }}</time>
 7
 8  {{ .Content }}
 9
10  <img alt="{{ .Params.alt_text }}" src="{{ .Params.image }}">
11
12  <h3>Tech used</h3>
13  <ul>
14    {{ range .Params.tech_used }}
15      <li>{{ . }}</li>
16    {{ end }}
17  </ul>
18
19  {{ partial "terms.html" (dict "taxonomy" "tags" "page" .) }}
20{{ end }}

10. Using Local Data Files

Create data/socialmedia.json:

 1{
 2  "accounts": [
 3    {
 4      "name": "twitter",
 5      "url": "https://twitter.com/bphogan"
 6    },
 7    {
 8      "name": "linkedin",
 9      "url": "https://linkedin.com/bphogan"
10    }
11  ]
12}

Create a contact layout:

themes/basic/layouts/contact.html

 1{{ define "main" }}
 2<h2>{{ .Title }}</h2>
 3{{ .Content }}
 4
 5<h3>
 6  <ul>
 7    {{ range .Site.Data.socialmedia.accounts }}
 8    <li>
 9      <a href="{{ .url }}">{{ .name }}</a>
10    </li>
11    {{ end }}
12  </ul>
13</h3>
14{{ end }}

Create content/contact.md:

1+++
2date = '2025-12-04T16:07:11+01:00'
3draft = false
4title = 'Contact'
5layout = 'contact'
6+++

Conclusion

With this foundation, you now know how to:

Create a Hugo site\
Add content\
Build a custom theme\
Customize layouts and partials\
Use archetypes\
Integrate front matter data\
Use local data files for reusable structured content

Getting Started With Hugo