Quick Start: How To Use Hugo

July 25, 2017
Basic command, configuration, setup, testing and deployment

Create a new site

Create a directory for sites created by Hugo

mkdir hugo-sites
cd hugo-sites

Create a new sites

hugo new site hello-world
cd hello-world
ls
# output
archetypes  config.toml  content  data  layouts  static  themes

Install Hugo Themes

Hugo does not come with a default theme, thus it will only show a blank page if no theme in installed.

The easiest way to install themes is to install and use git.

sudo apt-get use git

Visit Hugo Themes to find a list of Hugo Themes

I would recommend to start with Ananke as the default recommendation in the official documentation (not necessary a beautiful one, nor bug free).

git clone https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

Configure the site

Edit config.toml to configure title and theme

baseURL = "http://example.org/"
languageCode = "en-us"
title = "Hello World Site"
theme = "ananke"

Create a page

Create your first post

hugo new posts/my-first-post.md

Edit the markdown post at /content/post/my-first-post.md

---
title: "My First Post"
date: 2017-07-25T13:34:45+08:00
draft: true
---
# My Header
This is my content

{{< highlight python >}}
  if hello = True:
    print "World"
{{< /highlight >}}

Preview the site during development

Launch a Hugo webserver to preview the website during development.

# -D to make sure draft pages are rendered as well
hugo server -D
# output
Started building sites ...
Built site for language en:
1 of 1 draft rendered
0 future content
0 expired content
1 regular pages created
8 other pages created
0 non-page files copied
0 paginator pages created
0 tags created
0 categories created
total in 3 ms
Watching for changes in /code/hugo-sites/hello-world/{data,content,layouts,static}
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Preview the website at http://localhost:1313/

Hugo preview site

Hugo preview page

The hugo webserver support LiveReload, thus any changes made to the config and markdown shall be refreshed on the browser immediately.

Sometimes the browser might fail to render the page properly (e.g. theme changed), where you might need to force the browser to refresh (e.g. Ctrl-F5 on Chrome)

Ananke Theme issues

You might have notice the post is displayed without a date, this issue is related to the Ananke theme.

Deployment

Remove draft status from the post

hugo undraft content/posts/my-first-post.md

Or edit the post directly

---
title: "My First Post"
date: 2017-07-25T13:34:45+08:00
---
# My Header
This is my content

{{< highlight python >}}
  if hello = True:
    print "World"
{{< /highlight >}}

Edit baseUrl in config.toml

# make sure url end with backslash
baseURL = "http://www.hello-world.test/"
languageCode = "en-us"
title = "Hello World Site"
theme = "ananke"

Use the following command to generate files for deployment in the public directory

hugo
# output

Test deployed site using nginx on local machine

Assuming you already has nginx installed (How to install nginx on Ubuntu)

cd /etc/nginx/sites-available/
sudo cp default hello-world
sudo vi hello-world

Edit nginx config file of hello-world to point to public directory and setup server_name.

server {
  listen 80;
  root /hugo-sites/hello-world/public;
  index index.html;
  server_name www.hello-world.test;
  location / {
    try_files $uri $uri/ /index.html;
  }
}

Enable nginx config and edit Ubuntu’s host file.

cd ../sites-enabled/
sudo ln -s ../sites-available/hello-world hello-world

sudo vi /etc/hosts

Edit Ubuntu’s host file

127.0.0.1       www.hello-world.test

Restart nginx

sudo service nginx restart

Preview the deployed site at http://www.hello-world.test/.

References

This work is licensed under a
Creative Commons Attribution-NonCommercial 4.0 International License.