3 Quick Lessons for Hugo Beginners
I first heard about static website generators (aka SSGs) a few years ago. The idea of a far more secure alternative than running a PHP (or…
I first heard about static website generators (aka SSGs) a few years back. The idea of a far more secure alternative than running a PHP (or Ruby) content management system that you could even host on S3 seemed interesting and appealing. More recently, I’ve been looking at options generating and hosting project documentation with Gitlab Pages, but until this weekend I’d never taken any of them for a spin. Until now!
Why Hugo?
Although the project touts performance, the initial reason that drew my attention was I that really wanted to avoid dealing with dynamic language dependency complexity. Given I’m not a real developer, I’ve had too many bad experiences fighting with Python or Ruby or Node.js and I’ve gotten spoiled by Hashicorp tools that distribute a single binaries and I like that convention and I knew there was a good chance that would be the case with anything in Golang. No NPM, PyPi, or RubyGem hell please!
Hugo releases don’t disappoint in this respect. I downloaded the smallish binary and ran on my Dell ChromeBook and it just worked. I first stumbled across Pylenin YouTube video (I love his energy and Python content) and then dug into the quick start.
Lesson 1: Learn the Hugo CLI well, especially for local development.
Definitely take the time to learn the command-line options available. I’ve only scratched the surface so far. Given I’m doing development Linux VM on my ChromeBook I couldn’t connect localhost, so I had to change interface other that loopback, which the default for the server mode.hugo --debug -D server -b http://100.115.92.201 --bind 0.0.0.0
The baseURL on the command-line will override what is in the config.toml which is good to know because if was worried that it would point to my Gitlab Pages site.mdfranz@penguin:~/gitlab/hugodocs/src/hellohugo$ cat config.toml
baseURL = "https://mdfranz.gitlab.io/hugodocs/"
languageCode = "en-us"
title = "HugoDocs: First Attempt at Hugo on Gitlab Pages"
themesdir = "themes"
theme = "book"
publishdir = "publish"
I’m a debug-level zealot with most tools because I want to see what they are doing behind the scenes and hugo met my expectations for lots of output, even when things worked!INFO 2019/10/26 20:15:53 No translation bundle found for default language "en"
INFO 2019/10/26 20:15:53 Translation func for language en not found, use default.
INFO 2019/10/26 20:15:53 i18n not initialized; if you need string translations, check that you have a bundle in /i18n that matches the site la
nguage or the default language.
DEBUG 2019/10/26 20:15:53 Add template file: name "404.html", baseTemplatePath "", path "404.html"
DEBUG 2019/10/26 20:15:53 Add template file: name "docs/list.html", baseTemplatePath "docs/baseof.html", path "docs/list.html"
INFO 2019/10/26 20:15:53 Using config file:
Building sites … INFO 2019/10/26 20:15:53 syncing static files to /
DEBUG 2019/10/26 20:15:53 creating alias: /posts/page/1/index.html redirecting to http://100.115.92.201:1313/posts/
DEBUG 2019/10/26 20:15:53 Render XML for "sitemap" to "/sitemap.xml"SNIP...| EN
+------------------+----+
Pages | 52
Paginator pages | 0
Non-page files | 0
Static files | 14
Processed images | 0
Aliases | 1
Sitemaps | 1
Cleaned | 0Total in 625 ms
Watching for changes in /home/mdfranz/gitlab/hugodocs/src/hellohugo/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /home/mdfranz/gitlab/hugodocs/src/hellohugo/config.toml
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://100.115.92.201:1313/ (bind address 0.0.0.0)
Press Ctrl+C to stop
NOTE: Get the extended release because it is likely your theme will need it.
Lesson 2: Start simple (really simple) with Gitlab publishing.
Although there are examples and good documentation on how to publish on Gitlab in a fully automated way, don’t start out there. Really. You don’t need CI out of the gate despite what those DevOps fanatics will tell you. I first got my Gitlab Pages site up and running with a single HTML file. I actually still don’t have it publishing using a Gitlab runner. I’m still generating the static content locally. Not only did I run into enough problems with the config file and CLI(and many other things) but sometimes publishes take up to 7–8 minutes to complete. I can guarantee until you become fluent (and especially while you are testing a variety of themes) you will screw it up and you need the ability for fast feedback that only local development can satisfy. Maybe
Lesson 3: Gradually increase the level of your theme Complexity
Another appeal of hugo is a large number of themes to choose from. I focused on documentation and there are some pretty amazing examples such as the site used by Linode. Believe it or not I built the whole Linode documentation site on my ChromeBook and it actually worked. Well sort of!
It did bring my laptop to its knees though, but it is a great example of what a fully fledged support site can look like. Syna and Dot also look nice but I wasn’t able to get these working yet, but I eventually do want the search capabilities to provide Wiki-like functionality.
To get familiar with publishing processes, I started with Ananke in the Quick Start and then began experimenting with other themes before settling upon Book for my MVP. I found this theme to be unobtrusive both rendered on the screen as well as the filesystem layout to focus on content while having decent markup and structure. Once I master this I’ll probably move on to one of the more complex things but this is a good start!mdfranz@penguin:~/gitlab/hugodocs/src/hellohugo/content$ ls -alR | head -30
.:
total 4
drwxr-xr-x 1 mdfranz mdfranz 44 Oct 26 16:27 .
drwxr-xr-x 1 mdfranz mdfranz 184 Oct 26 16:32 ..
drwxr-xr-x 1 mdfranz mdfranz 52 Oct 26 15:47 docs
-rw-r--r-- 1 mdfranz mdfranz 183 Oct 26 16:27 _index.md
drwxr-xr-x 1 mdfranz mdfranz 16 Oct 26 16:24 menu
drwxr-xr-x 1 mdfranz mdfranz 158 Oct 26 15:42 posts./docs:
total 0
drwxr-xr-x 1 mdfranz mdfranz 52 Oct 26 15:47 .
drwxr-xr-x 1 mdfranz mdfranz 44 Oct 26 16:27 ..
drwxr-xr-x 1 mdfranz mdfranz 94 Oct 26 15:42 example
drwxr-xr-x 1 mdfranz mdfranz 142 Oct 26 15:47 longcodes
drwxr-xr-x 1 mdfranz mdfranz 142 Oct 26 15:42 shortcodes./docs/example:
total 12
drwxr-xr-x 1 mdfranz mdfranz 94 Oct 26 15:42 .
drwxr-xr-x 1 mdfranz mdfranz 52 Oct 26 15:47 ..
drwxr-xr-x 1 mdfranz mdfranz 24 Oct 26 15:42 2nd
-rw-r--r-- 1 mdfranz mdfranz 1737 Oct 26 15:42 hidden.md
-rw-r--r-- 1 mdfranz mdfranz 2786 Oct 26 15:42 _index.md
-rw-r--r-- 1 mdfranz mdfranz 1443 Oct 26 15:42 search.md
drwxr-xr-x 1 mdfranz mdfranz 68 Oct 26 15:42 table-of-contents
