Hugo QuickStart

I’m using hugo installed with brew on a Mac:

brew install hugo

hugo version
Hugo Static Site Generator v0.59.1/extended darwin/amd64 BuildDate: unknown

Create site

First, we’ll create the site and install a theme

``` bash 
hugo new site mikeski-blog
cd mikeski-blog
git clone https://github.com/avianto/hugo-kiera themes/kiera
```

Most themes have an exampleSite directory, so we need to copy the config.toml from there to our main config.

cp themes/kiera/exampleSite/config.toml .

Next, we need to edit the config file that we just copied. Update baseurl, theme, themesDir. There are lots of other things you can customize, but this is all that is needed for local development. Here is a diff of what I did to get mine working:

diff themes/kiera/exampleSite/config.toml config.toml

1c1
< baseurl = "https://www.example.org/"
---
> baseurl = "http://localhost:1313"
5,6c5,6
< theme = "hugo-kiera"
< themesDir = "../.."
---
> theme = "kiera"
> themesDir = "themes"

Adding content

Understaing front-matter

One important concept we must understand about Hugo is front-matter.

** front-matter is, quite simply, metadata used by Hugo about each file in your site**. Each post, static page, and special index.md and _index.md can (and should) contain front-matter

There will be a number of places we reference front-matter while building our blog, so it pays to understand a little more about it. We can find the Hugo official reference on front-matter here: https://gohugo.io/content-management/front-matter/

Adding our first content direcotry

Now, we’ll create a category called sites and set Hugo up to list posts that are inside this category.

 mkdir -p content/development/web

We need to create an index file called _index.md to tell Hugo that we want the posts in the directory to be displayed as a list. To do this, we create a special file called _index.md in content/development/web/_index.md and add some front matter like this:

---
title: Web
menu: main
weight: 10
---

The title is how our theme displays this item in the menu, the menu item is which menu it belongs to and the weight sets the ordering in the menu.

Adding a post to our new content directory

Then, we can create a post in development/web by running: hugo new development/web/hugo.md

Edit hugo.md to add some markdown content, launch Hugo in dev mode and you can preview your site at http://localhost:1313

hugo server -D

While the dev server is running, we will see the automatic reloads happen whenever a file changes. We should see output similar to this when the server is running:

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

Total in 13 ms
Watching for changes in /Users/mike/code/public/mikeski-blog/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /Users/mike/code/public/mikeski-blog/config.yml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Change detected, rebuilding site.
2019-11-13 09:14:35.397 -0500
Source changed "/Users/mike/code/public/mikeski-blog/content/development/sites/hugo.md": WRITE
Total in 5 ms

We can edit that file and see it appear on the site.

Conclusion

In this article we saw how to install hugo and setup a basic site. We also saw how to preview it locally.