My First Post

After a discussion with a passionate co-worker about the merits of various static site generation options and seeing an example of Hugo combined with what seemed like attractive code blocks, I decided to give it a try.

When I did I took some notes on the process. Naturally, when it came time to write a first post to try it out I took the barely formatted notes in Evernote and converted them into this post. I’ve added additional comments to those notes - both to make them more useful and to play with some of my ideas on what I want this to look like and feel like.

In the end, my hope is that this begins the process of building up a record of my technical wanderings and learning along the way. My own attempt to “blog more [and] tweet less”. I think it will be a while before I settle on my decisions regarding some good technical blogging advice and in that regard I will be learning somewhat publicly. Asuming I actually post this publicly. ;)

On to the technical goodness of my first exposure to Hugo…

Installing Hugo

I started by (primarily) referencing the “Installation” section of Hugo’s Getting Started page. Because I’m on a Mac, I used Homebrew to install Hugo.

1

> brew install hugo

When I invoked Homebrew, I saw a note that the Homebrew version of Hugo apparently thinks that macOS 10.12 is a pre-release version… concerning as this has been out for most of a year as of this writing. It also showed me some error which I failed to capture in my notes.

Dependency Issues - Homebrew Edition

Digging into those error messages it looked like I had some Homebrew issues. Later, I would realize that the fact that Homebrew was out-of-date was the reason for the strage warning about macOS 10.12 as a pre-release version.

As it had been a while since I went down this particular rabbit hole, I turned to the Homebrew site’s Troubleshooting page. There I was reminded of the “run brew update twice, then run brew doctor” routine to address common issues.

Running the following gave an error:

1
2

> brew update
Error: /usr/local must be writable!

Oh right… permission errors installing software packages…

I’ll talk about that more in a future post.

Running the following addresses the /usr/local error:

1

> sudo chown -R $(whoami) /usr/local

With that out of the way, I went back to brew update and got a new error:

1
2
3
4
5
6

> brew update
/usr/local/Library/Homebrew/cmd/update.sh: line 13: /usr/local/Library/ENV/scm/git: No such file or directory
/usr/local/Library/Homebrew/cmd/update.sh: line 13: /usr/local/Library/ENV/scm/git: No such file or directory
/usr/local/Library/Homebrew/cmd/update.sh: line 13: /usr/local/Library/ENV/scm/git: No such file or directory
/usr/local/Library/Homebrew/cmd/update.sh: line 13: /usr/local/Library/ENV/scm/git: No such file or directory
/usr/local/Library/Homebrew/cmd/update.sh: line 13: /usr/local/Library/ENV/scm/git: No such file or directory

Strange errors, but the Homebrew instructions did say to run brew update twice so…

1
2
3
4
5
6

> brew update 
==> Migrating HOMEBREW_REPOSITORY (please wait)...
==> Migrated HOMEBREW_REPOSITORY to /usr/local/Homebrew!
Homebrew no longer needs to have ownership of /usr/local. If you wish you can
return /usr/local to its default ownership with:
  sudo chown root:wheel /usr/local

Happy to know I can return my permisisons to something closer to stock settings, I followed the instructions given in that last command.

1

> sudo chown root:wheel /usr/local

Since running brew update is the thing you do until it tells you all is well, I ran that again and moved on to an appointment with brew doctor.

1
2
3
4
5
6
7
8
9

> brew update
Already up-to-date.
> brew doctor
...
Warning: An outdated version (1.8.1.2) of Git was detected in your PATH.
Git 1.8.5 or newer is required to perform checkouts over HTTPS from GitHub and
to support the 'git -C <path>' option.
Please upgrade:
    brew install git

I already have git on this machine but I continued to follow Homebrew’s instructions:

1

> brew install git

And now, I’m finally back to attempting to install Hugo again.

1

> brew install hugo

It worked. Next, I verified Hugo is on the path and which version was installed.

1
2
3
4
5
6

> which hugo
/usr/local/bin/hugo
> ls -l $( which hugo )
lrwxr-xr-x  1 josh  admin  30 Aug  5 06:44 /usr/local/bin/hugo -> ../Cellar/hugo/0.25.1/bin/hugo
> hugo version
Hugo Static Site Generator v0.25.1 darwin/amd64 BuildDate: 2017-08-05T06:44:24-05:00

Earlier I mentioned that I would talk about permissions issues I ran into in a future post - well, I hit a similar snag installing Pygments and will talk about that too.

Suffice it to say, I verifying the Python version installed and installed Pygments.

1
2

> pip install Pygments
Successfully installed Pygments-2.2.0

A Return to Daylight - Installing a New Hugo Site

In summary, I ran into the following issues before I was able to successfully install Hugo:

• Homebrew being out of date - run brew update more often
• Homebrew permissions issues - resolved in more recent versions
• An older git install - install/update git using Homebrew
• Python/pip permissions issues - sudo shortcut works but isn’t the best choice

With those out of the way, I was able to move on to get a site running using the Hugo quick start as a reference.

1
2
3

> pwd
/Users/josh/Documents/Code
> hugo new site hugo-quickstart

I also installed the Beautiful Hugo theme after looking for ones that looked clean and had what I thought were nice code block styling.

1
2
3
4

> cd hugo-quickstart
> git init
> git submodule add https://github.com/halogenica/beautifulhugo.git themes/beautifulhugo
> echo ‘theme = “beautifulhugo”’ >> config.toml

NOTE: I removed the extra ‘ around the new config.toml line. Also needed to add an additional newline to the end of the file.

Creating a new About page and added dummy content:

1
2

> hugo new about.md
> vi content/about.md

Next I created a new page and added dummy content:

1
2

> hugo new posts/2017-08-my-first-post.md
> vi content/posts/2017-08-my-first-post.md

Then I started up the Hugo server with drafts enabled to see what I have so far.

1

> hugo server -D

I navigated to http://localhost:1313/ to see my site. So far so good.

Next, I updated the config.toml to include the navigation as mentioned in the Netlify Victor Hugo Guide with some variations of my own based on other references.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

[[menu.main]]
    name = "Home"
    url = "/"
    weight = 0
[[menu.main]]
    name = "About"
    url = "pages/about"
    weight = 5
[[menu.main]]
    name = "Posts"
    url = "posts/"
    weight = 10
[[menu.main]]
    name = "Tags"
    url = "tags"
    weight = 15

Update: Later I found that the theme I had chosen prefers pages and posts to be stored in page/ and post/ respectively. If you don’t you will find that the formatting isn’t working quite right as I cover in this post.

I added the following line to my config.toml to allow server side syntax highlighting.

1

pygmentsUseClasses = true

NOTE: Somehow I misspelled this line as pygmentUseClassses = true the first time around - see the missing “s” in “pygments”? - and was very confused. A few styling issues crept in as a result including some keywords were displayed very close to the background color. When I fixed the spelling here I also noticed that a strange artifact at the corners of the code boxes was also removed.

I verified the changes took. For now I’m holding off on publishing this site to GitHub / Netlify until I better understand how I want to make this all work. But a good start for a random early morning. 😉