Setting Up Hugo on Netlify

First we'll need to install hugo. You need to install the single binary using the package manager you prefer. In mac OS you can install it using Homebrew with the following command:

brew install hugo

You can check the version with hugo version, at the time I'm writing this post the latest version available is 0.48.

Now we need to generate an new empty site so we'll use the command hugo new site myblog. Once the command finished you'll have a new folder called myblog

The structure of the new folder should be:

├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

For now we have to pay attention to only one file config.toml this file contains the configuration of the new site. We can define stuff like the title of the blog, menus structure, theme parameters, etc.

The contents of config.toml should be like this:

baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"

We have to change baseURL to / to avoid error with broken links(we'll see these possible errors later). So the result config.toml will be:

baseURL = "/"
languageCode = "en-us"
title = "My New Hugo Site"

Now we have to install a theme. There are many awesome themes available for Hugo. You can check and pick one in Hugo themes.

For this example we'll use Beautiful Hugo

We have 2 options to include the theme in the new site:

• Clone the theme repository and add it to our folder. This will copy all the files inside our folder.
• Use git sub modules to create a reference to the theme repository. This way we don't need to copy all the files.

We'll use the second option this time.

First we need to initialize a git repository inside our myblog folder using the following command git init. Now we have a git repository created.

Now we have to run the following commands to add the theme:

cd themes
git submodule add https://github.com/halogenica/beautifulhugo.git
cd ..

This will clone the theme repository and add it to our repository as a submodule. We can see that now we have a beautifulhugo folder inside themes folder and also there is a new file in the root of myblog called .gitmodules with the following content:

[submodule "themes/beautifulhugo"]
	path = themes/beautifulhugo
	url = https://github.com/halogenica/beautifulhugo.git

Now we have to tell hugo we want to use this theme in the new site, we'll do this adding the following lines to the config.toml file:

theme = "beautifulhugo"

To see the new site running before publish it we'll use the embedded development server. We run it with hugo server -D -p 9000.

After that we'll an output similar to this:

                   | EN
+------------------+----+
  Pages            |  7
  Paginator pages  |  0
  Non-page files   |  0
  Static files     | 33
  Processed images |  0
  Aliases          |  1
  Sitemaps         |  1
  Cleaned          |  0

Total in 46 ms
Watching for changes in /Users/erick/Code/hugo/myblog/{content,data,layouts,static,themes}
Watching for config changes in /Users/erick/Code/hugo/myblog/config.toml
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:9000/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Now we can open the browser and enter http://localhost:9000 and we'll see the new site with the chosen theme.

The server is watching for changes to be compiled so we leave it running.

At this point we don't have any content to show up so let's create some.

Hugo by default can render Markdown and Org-mode files. For this example we'll create a new post using markdown format.

Run hugo new post/hello-world.md to create a new file called hello-world.md in content/post/, Hugo will create a new file with the following content:

---
title: "Hello World"
date: 2018-09-22T15:05:47-05:00
draft: true
---

These lines are used by Hugo to show details about the content in the result file.

Let's add the lines below to hello-world.md

# This is a heading with level 1

## This is a heading with level 2

This is a paragraph

This is some python code

This is a list:

- item 1
- item 2

Now if we go to the browser we'll see the home page with a summary of the content of hello-world.md

By default Hugo show a list of the posts created in content/post in the homepage. Now we can enter to the post to see the full content.

Once we finished with the post it's necessary remove draft: true from hello-world.md file otherwise the file won't show up when we publish the site.