How to Build Hugo Website - Chase Mao's blog

Introduction

Hugo is a famous static website generator. Recently I refactor this blog website with Hugo. In this article, I will share the basic usage of Hugo and how to build a blog with it.

Hugo 101

Basic concept on Hugo is content + theme -> public static website files. So Hugo is a very suitable to generate static website like blog and product introduction.

Content

The content directory contains what will be presented in website.

home/

└── user/

├── my-site/

│ ├── content/

│ │ ├── books/

│ │ │ ├── _index.md

│ │ │ ├── book-1.md

│ │ │ └── book-2.md

│ │ └── _index.md

In this example, the website will have:

Home page website-url or website-url/index.html: the content is home/user/my-site/content/_index.md
Section page website-url/books: the content is home/user/my-site/content/books/_index.md
Detail page website-url/books/book-1 and website-url/books/book-2: the content are home/user/my-site/content/books/book-1.md and home/user/my-site/content/books/book-1.md.

Theme

Theme is how you layout the website, like formatting in Word. There are a lot of amazing themes to help you organize a wonderful website. With content filled in and a blog theme, you could generate a cool blog website so easily.

Theme is like a html file, and difference is that it use Go Template as a way to retrieve content, config, static file, and other resources. And with the resources, Hugo build a full completed static html files.

A proper analogy is that theme is a html files with blanks, and Hugo knows how to retrieve the blanks by Go Template instruction.

<!DOCTYPE html>

<html>

<head>

This is part of html of theme, it is like a normal html file, except it check if a static file exist, and decide whether to have <link rel="icon" href="/favicon.ico"> in the final html output.

Public Static Website Files

Running Hugo this simple command in your site project, will generate public directory which contains static website files. You can use the public directory to run a http server, like Nginx.

To help you understand, when end users browsing a static website, the http server is providing end users with the html files in public directory. For example, the index.html file in public directory is the home page of the website.

Build a Hugo Blog

In this part, I will share how I refactor my blog with Hugo. First download proper Hugo binary and run hugo new site site-name. Hugo will generate a new directory site-name. Under this directory, follow the 101 part, and prepare content and theme to generate public directory, here is a step by step guide.

Cotent

I put all my blog under hugo-site/cotent/article directory, so my blog article url will be like https://chasemao.com/article/run-home-website-server/.

Hugo also need metadata for each page, for example, title, date, and so on. Hugo suggest to put a extra yaml block in the beginning of each content file. But I don't like the way, so use a config to extract the metadata from file name.

frontmatter:

date:

- :filename

- :default

Put it in hugo.yaml config. You just need to format you blog file name as 2018-02-22-mypage.md. Hugo will extract the date and title from file name.

Theme

After content well prepared, I focus on the layout directory which is the template of website html file, and asset directory which stores the css files and js files for website to better format.

To simplify this part, I basically refactor my blog from React to Hugo, and I tried to keep the same layout as much as possible, so what I really do is to move the html files rendered by React into Hugo Template, and also the css files.

I have shared my theme on GitHub, you could follow the README instructions to add it into your site.

Serve Public Files

With cotent and theme prepared, just run hugo. It will generate a public directory. I used Nginx as a http server.

To run a Nginx server, first you need to install Nginx, and put following into config.

http {

server {

listen 443 ssl;

listen [::]:443 ssl;

server_name your-site.com;

ssl_certificate /path/to/server.crt;

ssl_certificate_key /path/to/server.key;

location / {

root /path/to/hugo-site/public;

index index.html;

include /etc/nginx/mime.types;

}

If you are serving as http instead of https, you need to change the listen port to 80 and remove certificate part.

Do note that you need to add include /etc/nginx/mime.types; in config to serve css and other files properly.

Summary

In the end, I would say Hugo is an awesome generator, you could build a static website so easily and there are so many well-designed theme for you to format your website. And during testing, you could run hugo server to run a daemon http server to test the website, and document is well maintained. When having any issue, don't hesitate to find the result in doc.