Hugo Basics

What is Hugo?

Hugo is a popular open-source static site generators. It takes your content written in Markdown format, applies templates, and generates a static HTML website. It is written in Go and has great performance.

Comment: I have used other static site generators before, including Gatsby and Docusaurus. I prefer Hugo because it is very easy to use, and good for lightweight websites.

Get Started

Install Hugo and run the following command to verify you have installed Hugo:

hugo version

Here is the official quick start tutorial.

To create an empty website, run:

hugo new site YourAwesomeWebsite

To create a new Hugo site with YAML format:

hugo new site YourAwesomeWebsite --format yaml

Use Templates

Do not reinvent the wheel, there are many Hugo themes online. Go through the popular ones and choose the one that works best for you.

Comment: for me, I use the template that is minimal, has dark theme support, and LaTex support.

Once you decide the right theme, run the following commands:

git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo "theme = 'ananke'" >> hugo.toml

In the above example, we use the ananke theme. We clone the theme with git submodule.

It is very important to set the theme name in the config file: hugo.toml.

Comment: in my case, I use the popular PaperMod theme and it recommends to use the YAML format, and therefore the configuration file for my website is hugo.yaml. There’s an online yaml to toml converter.

Putting things together (for PaperMod theme):

hugo new site blogs --format yaml
cd blogs
git init
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

Git Submodule

Since I work on different devices, I need to clone the repo there as well. To git clone the repo, including its submodules, run:

git clone --recurse-submodules git://github.com/foo/bar.git

If the repo is already cloned, run:

git submodule update --init --recursive

Override Theme Template

Since this is an advanced topic, I will briefly touch the point here. There is a layouts directory and you can add your new template there.

For example, I want to use my own footer style, I can copy the original footer HTML from ./themes/PaperMod/layouts/partials/footer.html and paste the content in the ./layouts/partials/footer.html and customize it.

<website>
|-content
  |-blogs
|-layouts
  |-partials
    |-footer.html # copied from /themes/PaperMode/layouts/partials/footer.html

Create New Content

Run the following command:

hugo new content [path] [flags]

In my case, hugo new content content/posts/myFirstBlog.md.

You can find the documentation on the hugo new content here.

You may wonder why we want to run the command instead of creating a new markdown file directly. The reason is that, this command can create frontmatter automatically using the template defined in the archetypes/default.md.

View Site Locally

You can start Hugo’s development server to view the site locally:

hugo serve -D

Deploy Website

You can use your preferred cloud provider; I use Azure in my case. This section of the tutorial will be specific to Azure.

Here are the steps for hosting Hugo websites in Azure:

  1. Create Azure resources

  2. Create resource

    • Configure deployment details
    • Grant the Azure resource permission to access GitHub.
    • Select the target organization/repository/branch of the source code

  3. Configure build details

    • Select Hugo from the build presets drop-down menu
    • Set app_location to /
    • Set output_location to public

Here are some useful links:

GitHub Workflow

Once you created the Azure resource and granted it the permission to edit your GitHub repository, a GitHub workflow file will be generated under /github/workflows.

In the builddeploy step, you will need to set the HUGO_VERSION environment variable:

env:
  HUGO_VERSION: 0.137.1

This is how the final builddeploy step will look like:

- name: Build And Deploy
  id: builddeploy
  uses: Azure/static-web-apps-deploy@v1
  with:
    azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_POLITE_BUSH_0A91F4A1E }}
    repo_token: ${{ secrets.GITHUB_TOKEN }}
    action: "upload"
    app_location: "/"
    api_location: ""
    output_location: "public"
  env:
    HUGO_VERSION: 0.137.1

Custom Domain

This is how to set up a customer domain for the static website.

CNAME

First, let’s set up a CNAME record. I can go to the domain name provider and add a CNAME record there. This is the how the record looks like:

CNAME | techblog.huijinghuang.com | *.azurestaticapp.net

Comment: you can find the url from the azure resource overview page. Do not include the https protocol in the value of the DNS record.

In the meanwhile, in azure, you go to the settings > Custom domains. You can choose Custom domain on other DNS, and then enter techblog.huijinghuang.com.

TXT

Then, let’s set up a TXT record so that Azure knows you own the website. In Azure, you can choose TXT and then generate code. This may take a while. In the domain name provider, you can enter the code generated in Azure to the answer section. BTW, you will need to use @ as the host for the TXT record. In this way, Azure knows you own the root of the domain.

Update BaseURL

Last but not least, don’t forget to update the baseURL in the hugo.[toml/yaml] configuration file!

Enjoy your personal website 🎊