Quick Start: How To Use Hugo

Create a new site

Create a directory for sites created by Hugo

mkdir hugo-sitescd hugo-sites

Create a new sites

hugo new site hello-worldcd hello-worldls# outputarchetypes  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:00draft: true---# My HeaderThis 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 wellhugo server -D# outputStarted building sites ...Built site for language en:1 of 1 draft rendered0 future content0 expired content1 regular pages created8 other pages created0 non-page files copied0 paginator pages created0 tags created0 categories createdtotal in 3 msWatching for changes in /code/hugo-sites/hello-world/{data,content,layouts,static}Serving pages from memoryWeb 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 HeaderThis 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-worldsudo 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-worldsudo 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/.