How to plan your Hugo site with multiple pages: A beginner's introduction

Introduction

Creating a Hugo site from scratch with multiple pages can feel overwhelming at first, but with a clear plan and understanding of its structure, it becomes much easier. This guide is designed to help beginners get started with Hugo, plan their site, and manage multiple pages effectively.

Before Jumping In

Make sure you have followed the getting started guide from Hugo. This guide is not a replacement for the official documentation or guide for a basic hello world page. It is a step-by-step guide to help you plan your site and manage multiple pages effectively.

What I Found Complex After "Getting Started"

When I started with Hugo, the most challenging part was understanding how to organize content and manage pages effectively. Here’s what I learned:

Plan Your Site Structure

Before you start adding content, take a moment to plan how your site will be organized. A well-structured site is easier to maintain and expand. Here’s a simple plan:

  • Content Folder: This is where your individual pages will go. Each file represents a page on your site. like post 1, post 2, etc.,
  • Layouts Folder: This folder contains templates that define how your pages are rendered. The entry point of your site's dynamic representation. This is the place where we plan how we are going to maintain or chunk our one HTML document into smaller units with the help of partials and the baseof file.
    • Partials: These are reusable components like headers, footers, and scripts or the individual units from the whole HTML document. The individual units of our one page can be maintained and managed with ease.
    • Default Layouts: Use _default/baseof.html as the base template to combine partials into a full HTML document. The split individual partials are directly used here to combine them to represent a whole HTML document.
  • Static Folder: This is for static files like CSS, images, or JavaScript that don’t require processing, like in any other web application.
  • Resources Folder: Use this for dynamic assets like SCSS or images that need processing.
Note: Hugo will not serve your site like PHP, ASP.NET Core, or any other server-side language. It will just generate static files, and you can use any server to serve the static files. Each individual page will be a generated static HTML document. The advantage of using Hugo is that you can handle page-specific matters without setting layouts and common HTML elements everywhere. Kind of master page child page while building not in running state.
Sample File Structure

Here’s a minimal file structure to get started:

.
├── content/
│   ├── _index.html
│   ├── about.md
│   └── contact.md
├── layouts/
│   ├── _default/
│   │   └── baseof.html
│   └── partials/
│       ├── footer.html
│       ├── head.html
│       ├── header.html
│       └── scripts.html
└── static/
    ├── css/
    │   └── site.css
    └── images/
        └── icon.jpg
1. Content Folder

The content folder is where all your site’s pages are stored. Each file in this folder corresponds to a page on your site. For example:

  • about.md: Represents the "About" page.
  • contact.md: Represents the "Contact" page.

You can organize the content folder into subdirectories for better management. For example:

.
└── content/
    ├── blog/
    │   ├── post1.md
    │   └── post2.md
    └── projects/
        ├── project1.md
        └── project2.md

In this structure:

  • blog/post1.md will be accessible at /blog/post1/.
  • projects/project1.md will be accessible at /projects/project1/.

Each file in the content folder should have front matter at the top, which defines metadata for the page. For example:

title: "About Me"
description: "Learn more about me."
date: 2023-10-01
2. Layouts Folder

The layouts folder defines how your content is displayed. It contains templates that Hugo uses to render your pages. Here’s a breakdown:

  • _default/baseof.html: This is the base template that acts as the skeleton for all pages. It typically includes the <head> section, header, footer, and placeholders for content.
  • Partials: These are reusable components that can be included in other templates. For example:
    • partials/head.html: Contains the <head> section with metadata and styles.
    • partials/header.html: Contains the navigation menu.
    • partials/footer.html: Contains the footer section.
  • Page-Specific Layouts: You can create custom layouts for specific types of pages. For example:
    • layouts/blog/single.html: Defines how individual blog posts are displayed.
    • layouts/projects/list.html: Defines how a list of projects is displayed.

Hugo automatically selects the appropriate layout based on the content type and file structure.

3. Public Folder

This is the final output of the Hugo site. You can see the files which were generated using the content and layouts. Each one file represents a full HTML document.

Tips for Managing Multiple Pages

  1. Use Front Matter: Add metadata to each page using front matter. For example:
    title: "About Me"
description: "Learn more about me."
date: 2023-10-01

    This metadata can be accessed in templates to dynamically render content. For example, in your head.html partial:

    <head>
...
<title>{{ .Params.title }}</title>
...</head>
  2. Navigation: Create a navigation menu in a partial (e.g., partials/header.html) and include it in baseof.html:
    <nav>
  <ul>
    <li><a href="{{ "/" | relURL }}">Home</a></li>
    <li><a href="{{ "about" | relURL }}">About</a></li>
    <li><a href="{{ "contact" | relURL }}">Contact</a></li>
  </ul>
</nav>
  3. Use Taxonomies: For blogs or categorized content, define taxonomies like tags or categories in config.toml:
    ---
[taxonomies]
tag = "tags"
category = "categories"

Dynamic vs Static Content

Understanding the difference between dynamic and static content is crucial:

  • Static Content: Files in the static folder are served as-is. Use this for assets like images or CSS.
  • Dynamic Content: Use the resources folder for assets that need processing, such as SCSS or resized images. For example:
    {{ $style := resources.Get "scss/main.scss" | toCSS }}
<link rel="stylesheet" href="{{ $style.RelPermalink }}">

Final Thoughts

This guide is designed to help beginners get started with Hugo. As you explore, you’ll discover more features to enhance your site. The key is to start simple, plan your structure, and build incrementally. Remember, this is just the beginning. Happy building!

Thank you…

Written On: July 25th, 2023