I’ve tried to learn Hugo a few different ways, and finally found one that works for me, and I hope will work well for anyone.
This guide and the accompanying repository should help anyone switching from either Jekyll to Hugo, or Hugo to Jekyll.
I’ve got two branches of the same exact website except one is run by Jekyll and one is run by Hugo!!
That’s pretty neat, if you ask me!
I also show examples of the differences between the two, where and how I made changes.
Why
-
mmistakes/hpstr-jekyll-theme
is archived, and you can no longer submit issues or pull-requests. - Hugo has a lot of support from the development community, and is growing quickly in features and popularity.
- It can be really hard finding working jekyll themes.
- There are a lot of awesome Hugo themes that generally seem to be operational.
- I know of some indieweb themes.
-
/themes/
directory allows for easy testing and switching between new themes.
HPSTR Jekyll vs Hugo
I’m looking through different releases of Hugo to see which will run HPSTR, since its an old theme and won’t run in the newest version. If you have a newer suggestion, feel free to shout out. I will also find out what the options are.
Releases
- mmistakes/hpstr-jekyll-theme
- dldx/hpstr-hugo-theme
It turns out that each version was released at the same time, and that they were built together from the very beginning!
The nice thing about hpstr-hugo-theme
is that its not archived, and if you want to open any issues or pull-requests, that can be done.
Interestingly, but nice to see, there are currently 0 open pull request or issues in the themes repository.
Root Directories
Which Version of Hugo Should I Run?
Scrolling back through the hugo releases when the HPSTR theme was in active development, I come across:
0.16.0 June 6th 2016
Hugo 0.16 is our best and biggest release ever. The Hugo community has outdone itself with continued performance improvements, beautiful themes for all types of sites from project sites to documentation to blogs to portfolios, and increased stability.
.deb packages for Debian, Ubuntu, etc.
Hugo has become part of the official Debian and Ubuntu repositories since January 2016!
That’s a nice note to find, since I’m an Ubuntu user.
v0.17 - October 2016
There are numerous options for different platforms, and this version of Hugo was released in October, one month after the final release of HPSTR.
Hugo is going global with our 0.17 release. […] Adding additional languages to your website is simple and straightforward.
Hugo continues its trend of each release being faster than the last.
Apparently it’s fast enough that people began using hugo’s webserver in production, around this time.
New in 0.17: Available as Snap package
Thanks to the contribution #2443 and guidance from @dholbach, Hugo is now available as a Snap package! (Snaps are a new kind of universal Linux packages.) Check it out at https://uappexplorer.com/app/hugo.hugo-authors
Download links for Hugo v0.17
Now that I have Hugo working, lets see how far I can go in Hugo versions.
v0.30.1 - Oct 16, 2017
Hugo 0.30 is the Race Car Edition. Hugo is already very very fast, but much wants more. So we added Fast Render Mode. It is hard to explain, so start the Hugo development server with hugo server and start editing. Live reloads just got so much faster! The “how and what” is discussed at length in other places, but the short version is that we now re-render only the parts of the site that you are working on.
This is a big release, so I’m going to look ahead for the closest bug-fixes, but avoid any feature releases.
v0.31.1 - Nov 27, 2017
So.. there’s another big release after this, at the start of 2018, but I think I’ll stick with this one. It’s a year after HPSTR completed its development. I think we’ll be good here, and I want to get to know Hugo better before changing things up too much.
The next major change introduces page bundles. I wouldn’t be surprised if it has a problem with this theme.
Test Install
Once it’s installed, type I hugo version
and read:
perfect!!
Clone the Hugo Theme.
With some pre-requisites out of the way, lets jump in at the first step in the theme setup:
- Theme Setup - HPSTR Hugo
$ mkdir newProject
$ cd newProject
$ mkdir themes
$ cd themes
$ git clone https://github.com/dldx/hpstr-hugo-theme.git hpstr
and you will see hpster
located in: /web-work/themes/hpstr
.
Example Site
Once you have the newProject/themes/hpstr
you’ll find the folder exampleSite
in the hpstr
directory.
Just Copy the contents of exampleSite
to the root of newProject
, and test to see if it will run.
$ hugo
It should print something like this:
Started building sites ...
Built site for language en:
0 draft content
0 future content
0 expired content
10 pages created
0 non-page files copied
15 paginator pages created
9 tags created
0 categories created
total in 100 ms
Unless you get that print-out, don’t bother changing your whole sites configuration just yet.
Make sure you placed the contents of exampleSite
into the root of your project directory, and that your directories are structured properly.
If you did everything right and it still won’t build, then I would shop around to different releases in that same time period to see if I could get one to work.
Just to be sure! I’ll test the server, also, and see that I get a website.
$ hugo server
Started building sites ...
Built site for language en:
0 draft content
0 future content
0 expired content
10 pages created
0 non-page files copied
15 paginator pages created
9 tags created
0 categories created
total in 61 ms
Watching for changes in /newProject/ {data,content,static,themes}
Yay!!!
Directory Structure HPSTR Jekyll vs Hugo
mmistakes.github.io/hpstr-jekyll-theme/theme-setup/
hpstr-hugo-theme/theme-setup
In with the new.
Now, it’s simply moving over the content, and swapping out some frontmatter, and configuration formating.
Content
Posts are stored in the content directory. By default, only content in the
content/posts
will show up in theAll Posts
section, however, you can link to other sections manually. For example, if you create a post atgallery/photo1.md
, your post will appear both under the home page and under /gallery.
In Hugo-HPSTR-Theme, it’s all about your directory structure.
You’ll notice that your root directory mirrors the themes directory structure, because the theme always keeps a backup file of everything necessary to function.
archetypes/
I entered some tags and categories:
web-work/themes/hpstr/archetypes/default.md
+++
Description = ""
Tags = ["resources", "web-work"]
Categories = ["howto", "tools"]
menu = "main"
+++
data/
From YAML to TOML
In the theme
directory is a navigation.yml file, and even awhole exampleSite
that we can copy over to our root data directory and customize.
Be sure to change title:
to title =
and so forth.
[[links]]
title = "Webwork.tools"
url = "/webwork.tools/"
[[links]]
title = "Services"
url = "/services/"
[[links]]
title = "Mostly Free SEO Tools"
url = "/seo-tools/"
[[links]]
title = "GitHub Pages Starter Pack"
url = "/github-pages-starter-pack/"
[[links]]
title = "Practical Public Key Crypto"
url = "/practical-public-key-crypto/"
[[links]]
title = "IndieWeb"
url = "http://infominer.id/indieweb/"
[[links]]
title = "InfoMine"
url = "http://infominer.id/"
Frontmatter
The main differences:
- using
type
rather thanlayout
- using the frontmatter variable
date
to signify publication date, rather than hardcoding it into the title.
HPSTR-Jekyll
---
layout: post
title: "Sample Code Post"
description: "Examples and code for various HPSTR functions."
tags: [samples, code, snippets]
comments: true
link: http://mademistakes.com
image:
thumb: /images/pgp-og.png
feature: pgp-banner.png
background: triangular.png
modified: 2019-05-30T13:15:59-23:00
permalink: /sample-code/
---
HPSTR-Hugo
---
type: post
title: Sample Post
description: "Just about everything you'll need to style in the theme: headings, paragraphs, blockquotes, tables, code blocks, and more."
date: 2011-03-10
tags: [sample post]
image:
feature: /images//images/abstract-3.jpg
credit: dargadgetz
creditlink: http://www.dargadgetz.com/ios-7-abstract-wallpaper-pack-for-iphone-5-and-ipod-touch-retina/
---
config.toml
Now we are getting places! Next step is to copy the config.toml
from the root of our example site into the root of our repository.
This is the final stretch, and we should be good to go
baseurl = "https://infominer.id/web-work"
languageCode = "en-gb"
title = "Webwork.tools: Independent Web-Work and Skyscraper Publishing."
theme = "hpstr"
pluralizelisttitles = false
PygmentsCodeFences = true
Paginate = 5
disqusShortname = "hpstrhugo"
publishdir = "docs"
enableEmoji = true
[params]
subtitle = "Digital Tools for a Digital Transformation."
[params.author]
name = "⧉ Infominer"
avatar = "/images/info-id.png"
bio = "Full-Time Crypto-Curation and Histories ⧉ #Bitcoin #Blockchain #DecentralizedID ⧉ Research, Publishing, #WebWork #Indieweb ⧉"
github = "infominer33/web-work"
[params.image]
feature = "/images/web-work-tools.png"
- Configuring Hugo
publishdir = "docs"
By setting this in our config.toml, we will be able to ask github pages to publish from the docs folder.
Redirects
One thing that’s important to note, if you are switching from Jekyll HPSTR to HPSTR Hugo with me. HPSTR Hugo makes all your posts live in the /posts/
directory.
If you used to let your blog live at the root of the site, like me, then add aliases, which are how Hugo does redirects.
- Content Manegement - Aliases
aliases:
- /title-goes-here/
- /other-title-too/
One last thing!
It seems like you need to type hugo
to publish to the docs directory, because hugo server
doesn’t do both, it only does the webserving.. I don’t really understand, but that seems to be the case.
Use a linebreak before each list!
Twitter Cards
This part, I can’t figure out.
I don’t understand why .Title
is not .title
.
I’m pretty sure I need to add
but I didn’t have success with that yet.
{{ with .Site.Params.owner.twitter }}{{ end }}
{{ if isset ($.Scratch.Get "Params") "image" }}
{{ $imageparams := index ($.Scratch.Get "Params") "image" }}
{{ with $imageparams.thumb }}
{{ else }}
{{ end }}
{{ end }}
I also added these lines to my config.toml
[twitter]
card = "summary_image_large"
site = "@infominer33"
title = "Webwork.tools: Independent Web-Work and Skyscraper Publishing."
description = "Resources for Independent Webworkers: Web-Publishing, SEO, Static Site Generators, Ubuntu, Research Driven Content."
image = "/images/web-work-tools.png"
I think some of those are supurfulous but it doesn’t matter if I use extra, as long as I get all the right values in.
Reach out in the Comments
If they ever figure out. If you have any questions, or if anything is unclear!!
I’ll get web-mentions and the like soon!
Test Branches
Even if I change this web-site to a different theme or SSG, I made a branch to save this build forever :D and anyone confused can browse them.
- https://github.com/infominer33/web-work/tree/test-hugo
- https://github.com/infominer33/web-work/tree/hpster-jekyll
Check Back In
I’ll be updating this post a lot as I learn new things about Hugo, until the resources branch off into their own post.
Resources
- web.archive.org - Installing Hugo v0.17
- web.archive.org - Using Hugo v0.17
- Creating a Test Branch and Merging changes back to Master
- Goodbye Jekyll - Hello Hugo
Other Hugo Themes
- https://github.com/EmielH/tale-hugo
Over the Rainbow
- Blogging with Org-Mode and Hugo