Sun, Oct 4, 2020

Check out or comparison page other options when finding the best blogging platform

Hugo is a Static site generator written in Go. It’s main selling point is speed.

Getting started

Usual data backup warning here. I’m creating a new site, so if you have any content, make sure you have a backup!

Download and install the latest deb from https://github.com/gohugoio/hugo/releases

wget https://github.com/gohugoio/hugo/releases/download/v0.76.3/hugo_extended_0.76.3_Linux-64bit.deb
sudo dpkg -i hugo_extended_0.76.3_Linux-64bit.deb
hugo version

Create a Site

hugo new site hugo-test
cd hugo-test

Add a theme

git init .
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
cp -a themes/anake/exampleSite/* .

Create a post

hugo new posts/my-first-post.md

Start a local server

hugo server -D

At this point I have content displaying. If you had trouble getting that working, check the troubleshooting section

Folder layout

archetypes - Content templates for creating new content. You can use these to automatically fill out boilerplate stuff when you create new content.
content - The important stuff you’ll create
data - Files that are usually theme specific and allow you to customize the theme or store data that you share across pages.
layouts - Theme overrides
public - Generated, don’t worry about it
resources - Generated, don’t worry about it
static - Static files like images or pdf files.
themes - Add you themes as subdirectories, typically with the git submodule add or download the theme outside the source tree and use --themesDir

Creating content

Top level Pages go in the content folder.
Posts go in the content/<type>/ folder (I chose posts).

I organize my content by category. Each category is a folder, with the posts under the category. This allows you to have landing pages for each category called _index.md.

The content files are all split into 2 parts, the front matter and the content. The front matter is where Hugo gets parameter values to fill in the templates.

The front matter should look something like this:

---
title: "Post Title"
date: 2020-10-04T17:46:45-06:00
image: "posts/blogging/hugo-logo.svg"
draft: false
---

Markdown Syntax

Supports the standard markdown syntax as well as a list of shortcodes.

Images and other Assets

You can store images and other assets you don’t want parsed in the static folder, or as of
Referencing images requires the full path, such as posts/dir1/dir2/myImage.png. This image would be at content/posts/dir1/dir2/myImage.png.

Content Templates (Archetypes)

Hugo has an archetypes folder that allows you to have templates for creating new content. Here’s what happens when you write hugo new posts/cool-new-post.md:

Hugo will look for archetypes/posts.md
If it can’t find that it will look for archetypes/default.md

This is a great place for putting your post starter. Find a list of variables to use at https://gohugo.io/variables/page/

Customizing themes

There are 2 ways to customize a theme

fork an existing theme
use theme overrides.

Fork

Essentially you’re creating a copy of a theme and modifying it in place. You’ll need to set up your own repository to save the changes, since you can push changes to the original theme.

This is typically the route you want to go if you can’t find any themes that are even close and you want to do a bunch of modifications.

Override

If you don’t want to completely own the maintenance of the original theme you can just override parts of it. This is done by taking a file you want to change and copy it to the same folder in your directory.

For example if you want to add some javascript libraries. You can override themes/ananke/layouts/partials/head-additions.html by creating a new file layouts/partials/head-additions.html and adding your new code.

Theme syntax

Sitemap

Hugo generates the sitemap for you, so you don’t have to worry about that.

Speed

Troubleshooting

I realized that I actually need hugo-extended for most of the themes to work since they all use scss. Installed hugo-extended, theme works better now, however I’m getting an error of:

ERROR 2020/09/28 21:15:14 render of “section” failed: list.html:29:59": execute of template failed: template: _default/list.html:29:59: executing “main” at <.Site.Params.dateFormat>: invalid value; expected string

Apparently my date format is “wrong”, didn’t realize I had added a date, but OK.

Looks like you have to copy the exampleSite/config.toml to your root to really get anything working.

Hugo Review