A Single-Page Portfolio (using Beautiful Hugo theme)

Courses

Author

Sangeetha Nandakumar

Download Materials

Hugo builds websites by reading files from a computer and turning them into web pages. Content is written in Markdown files, extra information is stored in front matter, and themes and configuration files control how the site looks.

Here we will see:

how Hugo is used locally
how a single-page homepage is created
how themes control the appearance of the site

Section 1: Initial Setup

Background

Hugo needs a project structure and a theme before it can display content. Without a theme, Hugo has no templates to turn Markdown files into web pages. This section covers the essential setup steps that must happen before creating any content.

This section covers creating a new Hugo site, learning how the local server works, installing a theme using Hugo Modules, and configuring basic theme settings.

At the end of this section, the portfolio will look something like this:

Exercises

Code	Description
`hugo new site <n>`	Create a new Hugo site with the specified name
`cd <directory>`	Navigate into a directory
`hugo server -D`	Start the Hugo development server (includes draft content)
`hugo server`	Start the Hugo development server (does not include draft content)
`Ctrl+C`	Stop the running server
`hugo mod init <module-path>`	Initialize Hugo Modules for the project
`hugo mod get <module-path>`	Download and add a Hugo module (like a theme)

Hugo is a tool that builds websites from files on a computer. Content is written in simple text files, and Hugo converts them into web pages.

When creating a new Hugo site, it sets up a folder structure with all the necessary directories. This structure tells Hugo where to find content, themes, and configuration settings.

Example Create a new Hugo site called my-portfolio. In the file explorer, you should see directories like archetypes, assets, content, data, i18n, layouts, static, and themes, along with a hugo.toml file.

hugo new site my-portfolio
cd my-portfolio

Hugo includes a web server that runs on a computer. This server lets browsers display the website before publishing it online. The server watches files, and when a change is saved, it automatically rebuilds the site and refreshes the browser.

Exercise: Start the Hugo development server and view the site in a browser. What do you see?

Solution

hugo server -D

Exerise: Stop and restart the server

Solution

# Press Ctrl + C, then
hugo server -D

A Hugo theme is a collection of templates, stylesheets, and assets that control how a site looks. Without a theme, Hugo cannot display content because it has no templates to render it.

Hugo Modules is the modern way to add themes to a site. Instead of downloading theme files into the project, the theme is declared as a dependency. Hugo then downloads and manages it.

In this subsection, you will practice adding different themes to see how Hugo Modules works and how different themes change the site’s appearance.

Example Initialize Hugo Modules for the project, then add the Ananke theme. Replace yourusername with any name (it doesn’t need to be a real GitHub username for local development).

hugo mod init github.com/yourusername/my-portfolio
hugo mod get github.com/theNewDynamic/gohugo-theme-ananke/v2

After running these commands, look at the go.mod file that was created in the project root. This file tracks the Hugo modules (themes and other dependencies) used by the project.

Exercise: Add the Hugo Coder theme (github.com/luizdepra/hugo-coder)

Solution

hugo mod get github.com/luizdepra/hugo-coder

Exercise: Add the Beautiful Hugo theme (github.com/halogenica/beautifulhugo). We will be using this theme for the rest of the exercises.

Solution

hugo mod get github.com/halogenica/beautifulhugo

After adding a theme, Hugo must be told to use it. With Hugo Modules, the theme is imported in the configuration file using the module import syntax. The configuration file is where Hugo looks for site-wide settings.

Example Import the Ananke theme in hugo.toml and look at your website.

Solution

[module]
[[module.imports]]
path = "github.com/theNewDynamic/gohugo-theme-ananke/v2"

Exercise: Change the theme to Coder

Solution

[module]
[[module.imports]]
path = "github.com/luizdepra/hugo-coder"

Exercise: Change the theme to Beautifulhugo

Solution

[module]
[[module.imports]]
path = "github.com/halogenica/beautifulhugo"

Section 2: Creating Homepage

Background

Now that the site has a working theme, content can be created that will actually display. For a single-page portfolio, only one content file called _index.md is needed. This file becomes the homepage.

Exercises

This section shows how to create the homepage file, add paragraph content, and configure front matter settings. The focus is on writing simple paragraph text without using headings, lists, or links.

Code	Description
`hugo new <filename>`	Create a new content file with default front matter
`+++` or `---`	Delimiters that mark the start and end of front matter
`draft: true`	Front matter setting that marks content as a draft
`draft: false`	Front matter setting that marks content as published
`title: "text"`	Front matter setting for the page title

Example: In a new terminal, navigate to my-portfolio and create the homepage file

hugo new _index.md

With the homepage file created, paragraph content can now be added that will display in the browser. Content is written below the front matter (after the second +++ line).

For this workshop, focus on writing simple paragraphs. No headings, lists, or links are needed. Just plain paragraph text.

Exercise: Add a self-introduction paragraph and check the browser.

Solution

+++
date = '2026-01-12T19:03:27+01:00'
draft = false
title = ''
+++

I am a researcher working on interesting problems in data science and machine learning. This is my portfolio website where I share information about my work and projects.

Exercise: Change the paragraph text and verify the browser automatically updates with your new text.

Solution

I am a computational biologist specializing in genomic data analysis. My research focuses on developing machine learning methods to understand gene regulation patterns.

Currently, I am working on integrating multi-omics data to predict disease outcomes. My work combines statistical modeling with deep learning approaches to extract meaningful biological insights from complex datasets.

Front matter is a block of information at the top of the content file. It sits between two lines of three dashes (+++). Hugo reads this information to understand how to handle the page.

Exercise: Without changing draft setting to true, run hugo server without the D option.

Solution

hugo server

Exercise: Change draft to true, run hugo server without the D option.

Solution

+++
date = '2026-01-12T19:03:27+01:00'
draft = false
title = ''
+++

hugo server

Section 3: Customizing Portfolio

Background

The portfolio now has content and structure. This section covers customization options that make the portfolio more professional and personalized. This includes configuring theme-specific settings and exploring different theme options.

Exercises

Beautiful Hugo theme provides configuration options to customize how the site looks and behaves. These settings are added to the hugo.toml file under a [params] section. Each theme has its own set of parameters. By modifying these parameters, you can change colors, fonts, layout options, and other visual elements.

TOML Syntax	Description
`[params]`	Section in config file for theme parameters
`key = "value"`	Setting a parameter with a string value
`key = true`	Setting a boolean parameter
`[[module.imports]]`	Importing a Hugo module (theme)

Example Add a [params] section to hugo.toml with a subtitle parameter.

[params]
subtitle = "Researcher and Data Scientist"

Exercise: Change the subtitle to something that describes your work or interests.

Solution

subtitle = "Computational Biologist | Machine Learning Researcher"

Example Add your name to the [params.author].

[params.author]
name = "Your Name"

Exercise: Add social media links by including github = "yourusername" and linkedin = "yourusername".

Solution

github = "janesmith"
linkedin = "jane-smith-bio"

Exercise: Add an email contact by including email = "your.email@example.com"

Solution

email = "jane.smith@university.edu"

Note about theme parameters:

Each Hugo theme has its own unique set of parameters for author information and other settings. Always refer to the theme documentation to see what parameters are available. For Beautiful Hugo, see: https://github.com/halogenica/beautifulhugo

Exploring More Themes and Features

Hugo has hundreds of themes available with different designs and features at https://themes.gohugo.io/. When finding a theme, follow its installation instructions and refer to its documentation for configuration options. Different themes may require different configuration parameters and have different features.