Start Up A New Hugo Installation
Getting a New Hugo Site with Custom Theme
Well, I have been busy working away on moving my sites away from a server to serverless. I looked at many models of serverless. They all have some sort of vendor lock in problems. At this point, I am feeling confident that I can extricate my data from whatever format I have it in and pack it into a new format. So the vendor lock in does not bother me so much. I want secure, reliable and low monthly fee. My sites are either for my business, which gets regular traffic... not much but pretty regular, or sites like this one which are virtual ghost towns. I don't need to pay for a server to be sitting ready 24-7.
Provider
I settled on AWS as the provider. It is a bit more complex, or has a higher learning curve, but I am confident I can run it cheaper. And I like the security it provides.
Static Generator
I settled on Hugo as the static site generator. It is fast, and I have a bias against the react framework. I don't know it and I don't want to learn it right now. I don't see much need for the complexity of a single page application. It seems JAMstack is simple and good for me for now, and very secure.
The Stack
I will back hugo with aws cognito, api-gateway, lambda and dynamodb. The main thing I like about dynamodb is the incredibly generous free forever tier. I have avoided going into serverless until now as the database alternatives were usually more costly than running my own rented server. With the forever free under 25GB provided by dynamo, I can reap the benefits of pay as you go low cost serverless.
The Recipe for Hugo Custom Themes
Granted off the shelf themes are much faster and convenient, I still prefer a DIY customized theme, even though my own front end work is not really great looking. But starting up a new custom theme in Hugo can be a bit tricky. Once it is going though, it is great!
The Commands:
Start up a new hugo site with the command:
hugo new site <name-of-site>
and hugo will get the skeleton of the site set up for you. cd into the directory and run the next command:
hugo new theme <name-of-your-custom-theme>
and hugo will scaffold up the new theme in the themes folder for you. Then make some new content with the command:
hugo new post.md
and inside the content folder hugo will put a new file with your name post.md. You can edit this file and add a bit of content at the bottom. Then use the next command:
hugo server
and it will generate the pages and you go to the page hugo directs you to at http://localhost:1313 and there will be a big fat nothing!
Configure it
You have to configure it to use your new theme. Edit the config.yaml file (I prefer yaml to toml, so I change it to that format. Use what you like). Put in an entry:
theme: <name-of-your-custom-theme>
and you still need to do a bit more. Go to this page[https://gohugo.io/templates/single-page-templates/] and copy the html they suggest into the
./themes/<name-of-your-custom-theme>/layouts/_default/single.html
It will look like this:
{{ define "main" }}
<section id="main">
<h1 id="title">{{ .Title }}</h1>
<div>
<article id="content">
{{ .Content }}
</article>
</div>
</section>
<aside id="meta">
<div>
<section>
<h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
<h5 id="wordcount"> {{ .WordCount }} Words </h5>
</section>
{{ with .Params.topics }}
<ul id="topics">
{{ range . }}
<li><a href="{{ "topics" | absURL}}{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
{{ end }}
{{ with .Params.tags }}
<ul id="tags">
{{ range . }}
<li> <a href="{{ "tags" | absURL }}{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
{{ end }}
</div>
<div>
{{ with .PrevInSection }}
<a class="previous" href="{{.Permalink}}"> {{.Title}}</a>
{{ end }}
{{ with .NextInSection }}
<a class="next" href="{{.Permalink}}"> {{.Title}}</a>
{{ end }}
</div>
</aside>
{{ end }}
Do the same for the list page in the same directory. It will look like this:
{{ define "main" }}
<main>
<article>
<header>
<h1>{{.Title}}</h1>
</header>
<!-- "{{.Content}}" pulls from the markdown content of the corresponding _index.md -->
{{.Content}}
</article>
<ul>
<!-- Ranges through content/posts/*.md -->
{{ range .Pages }}
<li>
<a href="{{.Permalink}}">{{.Date.Format "2006-01-02"}} | {{.Title}}</a>
</li>
{{ end }}
</ul>
</main>
{{ end }}
Do the same for the index page in one directory up.
It will look like this:
{{ define "main" }}
<main aria-role="main">
<header class="homepage-header">
<h1>{{.Title}}</h1>
{{ with .Params.subtitle }}
<span class="subtitle">{{.}}</span>
{{ end }}
</header>
<div class="homepage-content slideIn">
<!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
{{.Content}}
</div>
<div>
{{ range first 10 .Site.RegularPages }}
{{ .Render "summary"}}
{{ end }}
</div>
</main>
{{ end }}
file and then re-run:
hugo server
and go to the page. You should see your page nicely rendered.
Add Some Styling
One of the things I find so wonderful about Hugo is that the scss preprocessor is built-in. You need to access it though. cd into your new theme directory and make a new directory called assets. Inside that, make a new directory sass. You can put your sass files in there. (if you use the code below, be sure to have your main file called main.scss)
Then add some content to the partial file in your theme called 'head'. You will find it here:
./themes/<name-of-your-custom-theme>/layouts/paritals/head.html
and in there paste some code like the following:
{{ $sass := resources.Get "sass/main.scss" }}
{{ $sass := $sass | toCSS }}
{{ with $sass }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
Now you can style your content to your heart's content!
Happy coding!!