The Ultimate Hugo Guide

Welcome to the Installation Guide presented by Gethugothemes! This detailed guide will help you start your static site-building journey with Hugo Theme. Learn how easily you can install, run, customize, and update your Hugo theme!

Prerequisites

You need to fulfill some prerequisites to configure your machine, before starting the development process of your static site via Hugo.

1. Install Hugo
2. Install Go
3. Install Nodejs

Install Hugo

Install Hugo with the following command on your Terminal according to your operating system.

winget install -e --id Hugo.Hugo.Extended

hugo version

brew install hugo

hugo version

hugo version

Or

Go to the official site to Download and Install Hugo Extended.

Install Go

Install Go with the following command on your Terminal according to your operating system.

winget install -e --id GoLang.Go

go version

brew install go

go version

go version

Or

Go to the official site to Download and Install Go.

Install Nodejs

Install Nodejs with the following command on your Terminal according to your operating system.

winget install -e --id OpenJS.NodeJS.LTS

node -v

brew install node@18

node -v

node -v

Or

Go to the official site to Download and Install Nodejs.

Run Theme Locally

To set up a site using a Hugo theme in your local environment, follow the instructions below:

Get Your Theme (Premium Themes)

Unzip the downloaded file, and you will find the Main theme folder inside the themes directory, which you will be working with. As an example, let’s use bigspring-hugo theme.

📂 bigspring-hugo/ (Unzipped Folder)
   |
   ├── 📁 themes/
   |     |
   |     └── 📂 bigspring-hugo/ (Main Theme)
   |
   ├── 📄 changelog.html
   ├── 📄 documentation.html
   └── 📄 license.html

Get Your Theme (Free Themes)

Unzip the downloaded file, and the unziped folder is your main theme, which you will be working with. As an example, let’s use bigspring-light-hugo.

📂 bigspring-light-hugo-main (Unzipped Folder)

After unzipping, your folder should have a -main or -master suffix. remove the suffix from the folder name. like from bigspring-light-hugo-main to bigspring-light-hugo.

Setup Your Project

1. Run hugo new site my-project to create a new project.
2. Delete hugo.toml file from the my-project/ folder.
3. Copy the Main Theme into the my-project/themes folder. Resulting in a folder structure like my-project/themes/bigspring-hugo/ for premium themes, and my-project/themes/bigspring-light-hugo/for free themes.
4. Copy all files from the my-project/themes/bigspring-hugo/exampleSite folder into the root folder (my-project/). This action will overwrite any existing files and folders. You can delete the exampleSite folder afterwards.
5. Additionally, copy the package.json file from my-project/themes/bigspring-hugo to the root folder (my-project). If your theme doesn’t have a package.json file, you can proceed to the next step.

Run Your Project

1. Open the terminal on the my-project/ folder.
2. Run npm install to install all the dependencies. If you don’t have a package.json file, you can proceed to the next step.
3. Then, run npm run dev to serve this theme on your localhost. If you don’t have a package.json file, run hugo server instead.
4. After successfully serving the theme, you will receive a localhost address. Open this address in your browser to see the theme.

Build Your Project

After completing your development process, you can build your project for production. To build your project, run npm run dev. If you don’t have a package.json file, run hugo instead.

Now that you’ve got your theme running and understand the compiling process, let’s discuss the proper ways to edit and customize your theme. You can directly customize your template from the source file. For a better experience, open the whole theme folder with a text-editor or IDE (i.e. Visual Studio Code).

Deploy Your Project

To deploy your project, you need some prerequisites. Let’s discuss the prerequisites.

1. Git account (Ex: Github, Gitlab etc )
2. Netlify account to host files and add a custom domain

Add Project to Git

First of all, create a git repository (Ex: Github, Gitlab) and push your template to the repository. If you don’t know how to create a git repository, then follow the link: Create a git repository.

Deploy to Netlify

Go to your Netlify account and click add new site. Then choose import an existing site. Then choose your git provider to import your site. And now you can see your repository. Select it and follow the steps. BOOM! Your site is live.

If you want to add a custom domain, then go to Settings > Domain Management and add your custom domain.

Know Your Theme

Before you start customizing your theme, you should know the theme file structure. The main file structure is the same for every theme. Let’s discuss the file structure.

File Structure

📂 my-project/ (Root Directory)
   |
   ├── 📁 assets/
   |     ├── 📁 scss/
   |     ├── 📁 js/
   |     └── 📁 images/
   |
   ├── 📁 config/
   |     └── 📁 _default/
   |           ├── 📄 params.toml
   |           ├── 📄 menus.toml
   |           └── 📄 module.toml
   |
   ├── 📁 content/
   |     └── 📁 english/
   |           ├── 📁 pages/
   |           └── 📄 _index.md
   |
   ├── 📁 data/ (optional)
   ├── 📁 i18n/ (optional)
   |     └── 📄 en.yaml
   |
   ├── 📁 static/ (optional)
   |     └── 📄 static files
   |
   ├── 📁 themes/
   |     └── 📁 bigspring-hugo/ (bigspring-hugo is an example)
   |           ├── 📁 assets/
   |           └── 📁 layouts/
   |
   ├── 📁 scripts/ (optional)
   ├── 📄 hugo.toml (or config.toml)
   ├── 📄 package.json (optional)
   └── 📄 other files

If the list above sounds like a foreign language to you, that’s okay! Let’s break it down:

1. assets: This folder contains theme scss/css, js, and images files. In some cases, images could be in the static folder.

2. config: This folder contains all the configuration files for your site. params.toml file is for your site parameters. menus.toml file is for your site menus. module.toml file is for your site modules. If you didn’t find any config folder in your theme, then you can find all the parameters in the config.toml file.

3. content: This folder contains all the content for your site. you can create, duplicate, or delete a page from this folder. If you have a multilingual theme, then your content folder shold have languages folder first (i.e. english, french etc).

4. data: This folder mainly contains global data. this is an optional folder, your theme may not have this folder.

5. i18n: This folder is only available with a multilingual theme, that’s because this folder contains the multiple language translations for your site.

6. static: This folder has all the static files like images, videos, or other files that don’t need to compile.

7. themes: This folder contains your themes layouts, and assets folder for your pages.

8. scripts: This folder contains node scripts that helps to structure your project, clear modules cache, and other things. This is an optional folder, your theme may not have this folder.

9. hugo.toml: This is the main configuration file for your site. You can configure your site from this file. If you don’t have this file, then you can find all the parameters in the config.toml file.

10. package.json: This file contains all the node dependencies for your site. This is an optional file, your theme may not have this file.

What are the source, compiled, and static files?

These terms are can mean different things in different contexts, but for the purposes of a Hugo Theme:

• Source files are files that are meant to be processed by a theme’s build tools.

• Compiled files are generated as a result of running a compiling process (also called a “build process”) on the source files.

• Static files are ones that aren’t processed or generated.

Site Configuration

You have a hugo.toml or config.toml file in the root folder (my-project). Which gives you the ability to configure your site. You also could have a folder called config in the root folder. This folder contains the params.toml file. This file is for your site parameters. You can change your site parameters from this file. Let’s discuss the configuration file.

Default Configuration

Default configuration stays in the hugo.toml or config.toml file.

1. baseURL field for your website URL / domain. Add your site URL here. Remember, you need to add a trailing slash at the end of the URL.
2. languageCode defines your global site language. For more information, see Official Hugo Docs.
3. title is for the main title of your website.
4. theme sets up the used theme. If your theme is located in my-project/themes/theme-name folder, then the value for this parameter is theme-name.
5. summaryLength decides how many words are in excerpts of your posts when they are displayed as a preview. The default summaryLength is 70 words.
6. paginate set the number of posts shown on blog overview pages. If you have more than this amount of posts, pagination will be visible to navigate the next set of posts.
7. disqusShortname add your Disqus shortname to enable comments on the blog section. To install Disqus please follow this tutorial.
8. googleAnalytics add your Google Analytics ID to enable analytics on all pages. # example: UA-123-45. For more info, read the article. If you want another third-party analytics, you can contact us for custom service.
9. timeZone is the default time zone for time stamps. Use any valid TZ database name. see this for a list of valid time zones.
10. disableLanguages field is for disabling languages. If you don’t want to show one or multiple languages, then you can add the language name here. It will disable those languages from your site. For example, disableLanguages = ["fr"] will disable the french language from your site.

Default Parameters

Mostly all the parameters are in the params.toml file. But if you don’t have a params.toml file, then you can find all the parameters in the config.toml file.

1. favicon is for your website favicon. Place your favicon in the assets/images folder and put the path here.
2. logo is for your website logo. Place your logo in the assets/images folder and put the path here.
3. logo_width defines the width of the logo in pixels. It doesn’t work with .svg file.
4. logo_height defines the height of the logo in pixels. It doesn’t work with .svg file.
5. logo_text will only appear if the logo parameter is missing.
6. logo_webp coverts your logo to webp format. Default value is true. It doesn’t work with .svg file.
7. mainSections defines the section names that you want to show on your website. It’s an array, so you can add more sections to show. For more information, see Official docs.
8. contact_form_action is for activate your contact form. As Hugo generates a static site, so you need to activate this form by a third-party service. You can use any of them Airform, formspree, or Formsubmit. Go to any of the sites that you preferred, and get your form action from there. Then, paste it here. If you use Airform, your form action will be like this: https://airform.io/your@email.com.
9. copyright is for copyright text at the bottom of the page.
10. preloader is for your website preloader, which means it will show up until your website loads properly in the background. You can enable or disable preloader by setting the value of enable as true or false. If you want to put any image, logo, or animation as your preloader, give the file location in the preloader =, ex: preloader = images/preloader.gif. If you don’t want any logo or image, leave the preloader field empty. So it will show just a white screen when every component is loading.
11. navigation_button is for main navigation button, you can enable or disable it.
12. contact_info has some filed (like phone, email, and address) to show your contact information in the footer and contact page.
13. metadata is for your website SEO. It has fields like (keywords, description, author, image). You can change those as per your requirements.

Contact and Subscription Form

Our many users want to know how to set up a contact form, or how to set up a subscription form. So we make a step to differentiate the contact and subscription form guide.

• contact_form_action is for activate contact form. Give your form action here, it works with formspree. Go to this site, and create an account by click on signup button. Then give contact form action, it will looks like this contact_form_action = "https://formspree.io/your.name@email.com/". Now verify your email address by click varify button in the mail you got in your inbox. When someone sent you the first email from this contact form, you will get an email in your inbox, it will ask to activate the form. Click on this button to activate your form. Now it’s done. You will get every email that someone sends you via this contact form.

• [params.subscription] is for user subscription database. We used mailchimp service for our theme development. Replace your own subscription form action URL in mailchimp_form_action field, and your form name in mailchimp_form_name field. You can get your action URL and form a name from here (after login or signup).

Google Map

Google Maps is one of those items that the user asks frequently. So we have also differentiated that from regular parameter setup. It starts with [params.map].

• enable = true is a default value for map. But if you don’t need the map, then change the value to false.

• gmap_api needs to be replaced with your own API. You can get your google map API key from here.

• map_latitude and map_longitude field is for your google map location. you can find this location from here.

• map_marker is for your map pointer, you can set your own map pointer that you want to show. Just maintain the pointer size with the provided one.

• You can change your map style also. For this, pick a style from here, copy the styling code, and replace it with static/plugins/google-map/gmap.js files provided styling code. You can also tweak some map configuration from this file, like zoom, controllers, pointer size, etc..

Navigation

Navigation is a list of links to other pages. It is rendered in the header/footer of the page. you can find the menus.toml file in the config/_default directory. If your theme doesn’t have a menus.toml file, then you can find all the parameters in the config.toml file.

Main Navigation

Every theme has the main navigation to navigate all the pages. Main navigation loop starts with [[main]] heading. If your theme does not have a menus.toml file, then the navigation loop starts with [[menu.main]] heading. Let’s discuss the main navigation loop.

Normal Menu

[[main]]
name = "About"
url = "about/"
weight = 1

• name is for menu item name/text.
• URL is for the page URL. To set about page URL here, type about/. You can also use an external URL by putting the URL in this attribute. ex: url = "https://gethugothemes.com/"
• weight is for your navigation sorting. The smaller number weight will show first. You can switch menu items by changing the weight value.

Dropdown Menu

[[main]]
weight = 4
name = "Dropdown"
hasChildren = true

  [[main]]
  parent = "Dropdown"
  name = "Dropdown Item"
  url = "https://gethugothemes.com/"
  weight = 1

• For dropdown menu, you need to add another attribute called hasChildren = true. And remove URL. Then repeat the [[main]] loop, and put the parent = attribute in the dropdown menu item. Parent name should be the same as the dropdown item name. Also, update name and URL attributes.

Footer Navigation

Footer navigation also follows the same rule that uses main navigation. But footer navigation does not support the dropdown menu.

Content Management

All the pages for your website can be found in the content folder. If your theme supports multiple languages, then there will be a separate folder for each language, such as english for English, french for French, and so on.

Each page is written in Markdown format. If you are unfamiliar with Markdown syntax, you can learn more about it here. Additionally, every Markdown page includes front matter, which is the metadata for that page. To learn more about front matter, refer to this resource.

Homepage

The homepage for each language can be found in the respective language folder within the content directory. The homepage is represented by the _index.md file, and you can update its content from there.

Regular Pages

The regular pages, such as About, Contact or Privacy are located within the root or pages folder in each language folder within the content directory. You can add or modify your regular pages from there.

To create a new page, you can duplicate an existing page and update the content accordingly. For example, if you want to create a new page called “Terms and Conditions,” you can duplicate the privacy.md file and rename it to terms-conditions.md. Then, you can update the content in the new file.

List and Single Pages

The Hugo site consists of two types of pages: list pages and single pages. A list page serves as a landing page for single pages. For example, a “Blog” page would be a list page, while individual blog posts would be single pages.

To illustrate, in the content/english/blog folder, you will find the _index.md file, which represents the list page for the blog. Additionally, you can create separate Markdown files for each blog post within the same folder as single pages.

To create a new blog post, you can duplicate an existing blog post and update the content accordingly. For example, if you want to create a new blog post called “My First Post,” you can duplicate the post.md file and rename it to my-first-post.md. Then, you can update the content in the new file.

CMS Integration

If you want to use a CMS to manage your content, you can see the Official Hugo Documentation for more information.

Or you can take our Custom Service for CMS integration support.

Modules & Plugins

Modules and Plugins gives you the ability to add extra functionality to your site.

Modules

You can find all modules here - Gethugothemes Hugo Module. To use a Module, follow the README.md file attached with each module.

You can find modules.toml file in the config/_default directory. This file contains all the modules used in this project.

Example:

[[imports]]
path = "github.com/gethugothemes/hugo-modules/images"

CSS plugins

To add a CSS plugin, you need to add a loop like this in your hugo.toml or config.toml file.

[[params.plugins.css]]
link = "https://cdn.examplesite.com/your-plugin.css"
attributes = "your-attributes" # optional field

JS plugins

To add a JS plugin, you need to add a loop like this in your hugo.toml or config.toml file.

[[params.plugins.js]]
link = "https://cdn.examplesite.com/your-plugin.js"
attributes = "your-attributes" # optional field

Theme update

We often update our theme, fix bugs, and improve quality. When someone reports a bug, we fixed it as soon as possible, and make an update. We have mentioned every changelog in themes changelog file, so a user can understand what do we improve or fix.

Update Manually

You can manually update the theme if you have the ability to work with the source file. For this, please check our changelog, and identify what we have changed. Then copy only this file from the updated version of the theme and replace it with your project.

Update Whole Theme

If you don’t have any idea what we have changed in the theme, then you can replace the whole theme in your my-project/themes folder. But before replacing the theme, please make sure you have a backup of your project.