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…
> 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
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:
> 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
> 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
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.
> sudo chown root:wheel /usr/local
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
1 2 3 4 5 6 7 8 9
> brew update Already up-to-date. > brew doctor ... Warning: An outdated version (184.108.40.206) 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
> brew install git
And now, I’m finally back to attempting to install Hugo again.
> 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
Suffice it to say, I verifying the Python version installed and installed Pygments.
> 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 updatemore often
- Homebrew permissions issues - resolved in more recent versions
- An older git install - install/update git using Homebrew
- Python/pip permissions issues -
sudoshortcut 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:
> hugo new about.md > vi content/about.md
Next I created a new page and added dummy content:
> 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.
> 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
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
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. 😉