This page documents how to create a new Hugo website using the UNICEF Inventory theme. You need to already understand the basics of Hugo. If you do not know about Hugo, review the Hugo documentation on getting started to learn more about the basics.

Overview 🔗

This guide assumes you will use GitHub to host the source content for your website and GitHub Pages to deploy the generated HTML built by Hugo. To create a new Hugo website with the UNICEF Inventory theme, you will need to complete the following steps:

1. Create a git repository for your project
2. Add the UNICEF Inventory theme as a git submodule
3. Configure your Hugo website
4. Create content in your website
5. Preview the website locally
6. Deploy to GitHub Pages

Create a git repository for your project 🔗

First, you need to create a new Hugo site on your workstation, initialize a local git repository, and push your local changes to a remote git repository.

To begin, you need to create a new Hugo site with the source content. Source content refers to the content files, Hugo configuration file, and other text files used to build the final HTML website. Hugo provides a handy command to bootstrap a new website and generate initial source content (hugo new site <website_name>). However, this command also creates several sub-directories and files you will not need for the UNICEF Inventory theme. Alternatively, create the following sub-directories within the website directory for your new Hugo website:

1mkdir content/ static/ themes/

Next, you need to initialize a local git repository in your Hugo website directory. Note, if you already have an existing remote git repository, you should skip this step and instead clone the remote repository locally to your workstation. To initialize a new git repository with the UNICEF Inventory theme configuration, use the following commands:

 1# Initialize a new git repository.
 2git init
 3
 4# Copy the config file from this website to use as a base for your own site. If `curl`
 5# is not installed in your $PATH, you can also manually copy the file from GitHub and
 6# add it to your Hugo website directory.
 7curl --location --output config.yaml https://raw.githubusercontent.com/unicef/inventory-hugo-theme/main/exampleSite/config.yaml
 8
 9# Create the first commit in your git repository.
10git add .
11git commit --signoff --message="Initial commit"

Finally, you need to push your local changes to a remote git repository hosted on a site like GitHub. This example guide uses GitHub for the remote git repository, but you can use any git hosting platform like GitLab, Pagure, or any other. Note that the git hosting platform you choose may have implications on the hosting (see Deploy to GitHub Pages for more information). Your git hosting platform should give you instructions on how to push local changes if it is unclear. The commands needed should look like this:

1git remote add origin git@github.com:myname/myrepo.git
2git push --set-upstream origin main

Now, your local git repository is synchronized with the remote git repository.

Add the UNICEF Inventory theme as a git submodule 🔗

The recommended way to install the UNICEF Inventory theme into your Hugo website is to add it as a git submodule. Using a git submodule provides an easier method to get changes, improvements, and bug fixes from the upstream theme in your downstream Hugo site.

While you are in your Hugo website directory, use the following commands to initialize a git submodule with the UNICEF Inventory theme:

1git submodule add --name inventory https://github.com/unicef/inventory-hugo-theme.git themes/inventory

This initializes a new git submodule with the UNICEF Inventory theme. It also creates a .gitmodules file in addition to cloning the theme repository inside of your Hugo website repository. Make sure to commit these files into your git repository.

1git submodule update --init

Alternatively, you can download the UNICEF Inventory theme as a .zip file file and extract it in the themes directory. However, this is not recommended as you will be responsible for manually updating changes, improvements, and bug fixes introduced in the upstream UNICEF Inventory theme.

Configure your Hugo website 🔗

The easiest way to configure your Hugo website is to copy the example site config.yaml and modify it to fit your needs. See the Features category for more guidance on configuring different components of the UNICEF Inventory theme.

Create content in your website 🔗

Next, you need to create source content in your Hugo website. The UNICEF Inventory theme supports Markdown and AsciiDoc as source content markup languages. Create a new page either by manually creating files in content/ or using this shortcut command:

1hugo new my-category/_index.en.md
2hugo new my-category/hello-world.en.md

Edit these files by adding front-matter and content into the files. The front-matter for this page is shown below as an example:

1---
2title: Create a new Hugo site
3description: Learn how to create a new Hugo site using the UNICEF Inventory theme.
4tags: ["forking", "git", "new site"]
5downloadBtn: true
6# search keywords
7keywords: ["fork", "forking", "install", "installation", "launch"]
8
9---

Preview the website locally 🔗

Now, you can preview your Hugo website locally from your own workstation before pushing your changes to the remote git repository. Build the Hugo website and preview the changes with the following command:

1hugo serve

Click the URL from the console output to view a local preview of the website.

Deploy to GitHub Pages 🔗

See Hugo documentation on deploying your Hugo website to GitHub Pages. You will need a continuous integration (C.I.) pipeline to help you deploy changes to a hosting service provided by your git hosting platform.

The UNICEF Open Source Inventory uses Circle CI to build its changes, validate the HTML, and deploy to GitHub Pages. Find the Circle CI configuration file and deployment script here.