Building a Modern Website with Hugo: A Complete Beginner’s Guide

Introduction to Hugo

Hugo is a powerful static site generator built with the Go programming language. It transforms your templates and content into a blazing-fast static website, perfect for blogs, portfolios, and documentation. Unlike content management systems like WordPress that rely on databases, Hugo builds complete HTML pages that you can host anywhere, often for free. The latest versions of Hugo, such as v0.152.2, require at least Windows 10 or Windows Server 2016 .

Installing Hugo on Windows

You have several straightforward options for installing Hugo on Windows. For most users, a package manager is the easiest method.

Method 1: Using a Package Manager (Recommended)

Choose one of these free, open-source package managers for a simple installation of the extended edition of Hugo, which includes advanced features like image processing .

• Chocolatey: Open a command prompt as administrator and run: choco install hugo-extended
• Scoop: Run: scoop install hugo-extended
• Winget: Run: winget install Hugo.Hugo.Extended

Method 2: Manual Installation with Prebuilt Binaries

If you prefer not to use a package manager:

1. Visit the Official releases page on GitHub .
2. Scroll to the “Assets” section and download the archive for the Windows version of the extended edition.
3. Extract the archive and move the single executable file to a dedicated folder (e.g., C:\Hugo\bin).
4. Add this folder to your system’s PATHenvironment variable so you can run hugofrom any command prompt.

Verifying Your Installation

To confirm the installatio is installed correctly, open a new command prompt and type:

hugo version

You should see output displaying the version number, confirming the installation is complete.

Creating Your First Hugo Site

Follow these steps to create and preview your new website locally.

1. Generate the Site Structure: Navigate to where you want to store your projects and run the following command. This creates a new folder with all the necessary directories and files.

hugo new site my_awesome_site

2. Start the Local Server: Navigate into your new site’s directory and start the Hugo development server.

cd my_awesome_site
hugo serve

3. View Your Site: Open your web browser and go to http://localhost:1313. You will see a blank page, which is normal until you add a theme and content. This server will automatically reload the page as you make changes to your files.

Working with Themes

Themes control the visual design and layout of your project. The DoIt theme you referenced is a great choice. Here’s how to install it:

1. Inside your site’s folder (e.g., my_awesome_site), run this command in your terminal to clone the theme into the correct directory:

git clone https://github.com/HEIGE-PCloud/DoIt.git themes/DoIt

If you don’t have Git, you can download the theme from its GitHub repository and manually place it in the themes folder.

2. Basic Configuration: Edit the config.tomlfile in your site’s root directory. Set the theme and add basic configuration. Here is a minimal example:

baseURL = "https://yourfuturedomain.com/"
languageCode = "en"
title = "My New Hugo Site"
theme = "DoIt"

For detailed instructions, always refer to your chosen theme’s official documentation.

Creating and Managing Content

Your First Post

To create a new blog post, use the following command in your terminal:

hugo new posts/my-first-post.md

This creates a new Markdown file in the content /posts/directory. By default, new posts are saved as drafts. To publish them, you can either remove the line draft: true from the top of the file or start your server with the –buildDrafts flag: hugo serve –buildDrafts.

Organizing Your Content

Hugo uses a simple directory structure to organize your content, which directly reflects your site’s URL structure .

• Blog Posts: Store these in the content/posts/directory (e.g., content/posts/my-first-post.md).
• Standalone Pages: Store pages like “About” or “Contact” directly in the content folder (e.g., content/about.md).
• Sections: You can create sections (like a blog or portfolio) by creating subdirectories within the content folder. Each section can have its own _index.mdfile for a landing page .

Advanced Tips and Best Practices

Local Development

For the best experience while writing and designing, use the following command to start your server. It includes live preview and ensures you can see draft content.

hugo serve --disableFastRender --buildDrafts

Image and Resource Management

Hugo offers several ways to handle images :

• Page Bundles: Place images in a folder alongside your post’s Markdown file for easy, page-specific organization.
• Static Directory: Store site-wide assets like logos, stylesheets, and global images in the staticdirectory.
• Assets Directory: Use the assetsdirectory for files that  processing pipelines can optimize.

There are many places in the theme where the above local resource references can be used, such as links, images, imageshortcode, musicshortcode and some params in the front matter.

Front Matter

• title: the title for the content.
• subtitle:  the subtitle for the content.
• date: the datetime assigned to this page, which is usually fetched from the date field in front matter, but this behavior is configurable in the site configuration.
• lastmod: the datetime at which the content was last modified.
• draft: if true, the content will not be rendered unless the –buildDrafts/-D flag is passed to the hugo command.
• authors:  the list of authors for the content.
• description: the description for the content.
• license: the special lisence for this content.
• images: page images for Open Graph and Twitter Cards.
• tags: the tags for the content.
• categories: the categories for the content.
• series:  the series for the content.
• series_weight:  define the position of the post in the series.
• seriesNavigation:  whether to enable series navigation.
• featuredImage: the featured image for the content.
• featuredImagePreview: the featured image for the content preview in the home page.
• hiddenFromHomePage: if true, the content will not be shown in the home page.
• hiddenFromSearch:  if true, the content will not be shown in the search results.
• twemoji:  if true, the content will enable the twemoji.
• lightgallery: if true, images in the content will be shown as the gallery.
• ruby:  if true, the content will enable the ruby extended syntax.
• fraction:  if true, the content will enable the fraction extended syntax.
• fontawesome:  if true, the content will enable the Font Awesome extended syntax.
• linkToMarkdown: if true, the footer of the content will be shown the link to the original Markdown file.
• linkToSource:  if false, turn off the view source link in the footer. You can set it to the link to the source file of the post. Use the magic variable {path} to specify the relative path of the post, for example, the {path} for this post is posts/theme-documentation-content/index.en.md.
• linkToEdit:  if false, turn off the edit this page link in the footer. You can set it to the link to edit the page. Use the magic variable {path} to specify the relative path of the post, for example, the {path} for this post is posts/theme-documentation-content/index.en.md.
• linkToReport:  if false, turn off the report issue link in the footer. You can set it to the link to report issues about the page. Use the magic variables: {path} to specify the relative path of the post, for example, the {path} for this post is posts/theme-documentation-content/index.en.md, {title} to specify the title of the post, for example, the {title} for this post is Theme Documentation – Content and {url} to specify the url of the post, for example, the {url} for this post is https://hugodoit.pages.dev/theme-documentation-content/.
• rssFullText:  if true, the full text content will be shown in RSS.
• pageStyle:  adjust the page layout style, “normal” or “wide”.
• license:  set the license info (HTML format is supported).
• toc:  the same as the params.page.toc.
• code:  the same as the params.page.code.
• table:  the same as the params.page.table.
• math:  the same as the params.page.math.
• mapbox:  the same as the params.page.mapbox.
• share: the same as the params.page.share.
• comment:  the same as the params.page.comment.
• library:  the same as the params.page.library.
• seo:  the same as the params.page.seo.
• outdatedArticleReminder:  the same as the params.page.outdatedArticleReminder.
• sponsor:  the same as the params.sponsor.

Migrating from WordPress

If you are moving an existing site from WordPress to Hugo, the community has developed several tools to make the process easier. The official Hugo documentation lists tools like the “wordpress-to-hugo-exporter” plugin, which can convert your posts, pages, and metadata into the Markdown format Hugo uses . Some users have also reported excellent results with third-party tools like “wordpress-export-to-markdown” for a more streamlined conversion that handles images and link formatting .

Conclusion

Using a static site generator like Hugo provides a fast, modern, and efficient workflow for building websites. By following this guide, you’ve learned the core steps: from installation and site creation to working with themes and managing your content. The shift from a database-driven system like WordPress might seem different at first, but the benefits in speed, security, and simplicity are significant.

The best way to learn is by doing. Start with a simple site, experiment with the commands, and consult the excellent official Hugo documentation as you explore more advanced features.

I’m still learning Hugo and its features in order to get the most out of it, so for now, you can check out these resources to fully understand how to build a Hugo website.

This tutorial has covered the majority of how to use the DoIt theme, which is used on my website. You might also want to look at  these tests for more detailed examples on various cases.