Hugo Basics
Apr 18, 2017 11:19 · 954 words · 5 minutes read
Installation
Hugo is a flexible static site generator written in the go programming language. Getting and installing Hugo is easy — see this page for full details. To install on my NanoPi Neo Air, I just grabbed the latest armhf version from the Hugo releases site and using dpkg:
$ wget https://github.com/spf13/hugo/releases/download/v0.19/hugo_0.19_armhf.deb
$ sudo dpkg -i hugo_0.19_armhf.deb
If all went well, we should be able check our hugo version:
$ hugo version
Hugo Static Site Generator v0.19 linux/arm BuildDate: 2017-02-27T06:38:35-06:00
Making a first website
To make a new website with hugo called mysite we can do:
$ hugo new site mysite
Congratulations! Your new Hugo site is created in /home/jandrew/hugo_example/mysite.
Just a few more steps and you're ready to go:
1. Download a theme into the same-named folder.
Choose a theme from https://themes.gohugo.io/, or
create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".
Visit https://gohugo.io/ for quickstart guide and full documentation.
You can cd into the mysite directory and see the initial stucture:
$ cd mysite/
$ ls -F
archetypes/ config.toml content/ data/ layouts/ static/ themes/
Now, before anything else, we need to get a theme (there is no default) — there are many available at the hugo themes site. Let’s try the sp-minimal theme for this example:
$ cd themes
$ git clone https://github.com/eueung/hugo-sp-minimal.git sp-minimal
$ cd ..
To save time for your first exploration of Hugo in general, and this theme in particular, we will make use of the example site included within the theme. We’ll copy the example site’s config.toml to our site’s root directory, and also copy the contents of the example site’s content/ and static/ directories into our own site’s directories of the same names:
$ cp themes/sp-minimal/exampleSite/config.toml ./
$ cp -r themes/sp-minimal/exampleSite/content/* content/
$ cp -r themes/sp-minimal/exampleSite/static/* static/
To generate the site we just use the hugo command in our mysite/ directory:
$ hugo
Started building sites ...
WARNING: Page's Now is deprecated and will be removed in a future release. Use now (the template func).
Built site for language en:
0 draft content
0 future content
0 expired content
4 regular pages created
12 other pages created
0 non-page files copied
10 paginator pages created
6 tags created
2 categories created
total in 176 ms
This creates the generated site under the public/ folder:
$ ls -F
archetypes/ config.toml content/ data/ layouts/ public/ static/ themes/
$ ls -F public/
404.html categories/ css/ img/ index.html index.xml js/ page/ post/ sitemap.xml tags/
You’ll notice we got a warning about a deprecated Now function — let’s address that right now. We don’t have any templates in our layouts/ directory, so the ones from the current theme are being used. Let’s search for the deprecated function there:
$ grep -r Now themes/sp-minimal/layouts/
themes/sp-minimal/layouts/partials/footer.html: © {{.Now.Format "2006"}}
Only one occurence, so it won’t take much to fix. But instead of editing the file directly, we’ll copy it to our layouts/ directory. We make a corresponding partials/ subdirectory and and copy the file there:
$ mkdir layouts/partials
$ cp themes/sp-minimal/layouts/partials/footer.html layouts/partials/
Now we’ll edit this copy and change this line:
© {{.Now.Format "2006"}}
to this:
© {{now.Format "2006"}}
One other thing we should edit sooner rather than later is the baseURL parameter found in the config.toml file. Change it to something that makes sense for where you intend to publish your site, or just make it an empty string for our testing purposes.
Viewing our site
The hugo application has a built-in server we can use to serve our site:
$ hugo server
Started building sites ...
Built site for language en:
0 draft content
0 future content
0 expired content
4 regular pages created
12 other pages created
0 non-page files copied
10 paginator pages created
6 tags created
2 categories created
total in 167 ms
Watching for changes in /home/jandrew/hugo_example/mysite/{data,content,layouts,static,themes}
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
If you point your browser to http://localhost:1313/ you should see the example site. However, in my case I am doing all this on a headless server on my local network, so localhost isn’t going to work for me. That’s OK, because we can give the server a baseURL to use, and bind it to 0.0.0.0 so it is not just listening to localhost for connections:
$ hugo server --bind 0.0.0.0 -b "http://nanopiair:1313/"
Started building sites ...
Built site for language en:
0 draft content
0 future content
0 expired content
4 regular pages created
12 other pages created
0 non-page files copied
10 paginator pages created
6 tags created
2 categories created
total in 168 ms
Watching for changes in /home/jandrew/hugo_example/mysite/{data,content,layouts,static,themes}
Serving pages from memory
Web Server is available at http://nanopiair:1313/ (bind address 0.0.0.0)
Press Ctrl+C to stop
Now I can point the browser on my chromebook to port 1313 on my nanopiair, and see the following in my browser:
The SP-Minimal theme example site.
A first post
The example site has a few example posts, and you can find the source of those posts in the content/post directory. To create a new post we can use the following:
$ hugo new post/first_post.md
/home/jandrew/hugo_example/mysite/content/post/first_post.md created
This generates a new markdown file for us with some minimal metadata included (defined in the archetypes directory) which appears as:
+++
date = "2017-04-18T10:41:43-05:00"
title = "first_post"
+++
You can edit this file, using markdown, then regenerate and view your site with your new content.
This is just a very basic introduction to getting started with hugo. Visit the hugo docs for much more detail on configuring and using hugo.
__END__