Static Site With Hugo and Org Mode

16/08/2020

Parse the Source is written in Hugo. The requirements for this blog were simple; it needs to be a static site and I need to be able to write in org mode. Static because I want to host in the simplest way possible, and org mode as that's where most of my notes are written, and the plan is to tidy up my notes I've written over the years, and make them blogs. Here's an overview of how it's set up.

Basics of Hugo

Hugo is an open-source static site generator written in Go. There are two basic commands that I use when I'm working with the site.

To get started run:

> hugo new site yoursitename

To serve the site locally run:

> hugo serve

and to build the site when you want to publish run:

> hugo

hugo new site creates all the files you need to get going

hugo serve will open up a port so you can see your site locally, automatically picking up changes in your working directory so you can see the results whilst developing or writing a post. The -D tells it to include drafts.

hugo will publish the results to a public folder, ready to be sent into the wild.

Templates

There's a huge library of hugo templates available to use, but if you want to make your own, it's pretty simple. Simply run hugo new theme followed by your theme name and a new folder with some files will be created under themes/yourthemename. Once you've done that you'll want to change the config.toml file in the root of your site directory so the theme is the theme you've created. It's worth noting here that You can do all of this using the /archetypes, /layouts and /static folder in the root of your site and there's not much difference, apart from the fact that it's probably easier to move this over, should you want to make a site with the same theme.

The layout folder is where you'll be throwing your HTML, and there's a few files that are important in there.

/index.html - This file is where you can put the HTML for your home page
/_default/single.html - Here's where you can specify what your posts should render
/_default/list.html - When you hit /posts/ or whatever you want to prefix your categories with, this is what will be run

Finally, you can override the rendering for any page by creating an HTML file with the corresponding page in the _default folder. I have one for the archive page, that simply lists off all of the pages in my site.

Partials

The first thing I needed to know was how to not repeat myself (tm). For that you'll need partials, which couldn't be simpler. Just create the markup you want in a file in /partials, then reference it with {{ partial "filename.html" }}. Here's the <head> on all of my pages:

<head>
  {{ partial "head.html" }}
</head>

Page Variables

On each page that's rendered there are some accompanying variables that you can reference with the dot operator. This is useful for things like titles, content and date published. Here's my single page, note the title, date and content parameters referenced.

<html>
    <head>
        {{ partial "head.html" }}
    </head>
    <body>
        {{ partial "header.html" }}
        <main>
            <article class="entry">
                <div class="parappa-thinboi">
                    <h1>{{ .Title }}</h1>
                    <time>{{ dateFormat "02/01/2006" .Date }}</time>
                    {{ .Content }}
                </div>
            </article>
        </main>
        {{ partial "footer" }}
    </body>
</html>

You can also extend these variables by specifying it in the front matter of the page. When you're writing in org mode, you can use the page variables in native syntax, then reference it in your templates and the value will pull through.

Site Variables

Within your template you can also access site wide variables within .Site. You can find more on the hugo docs, but my main use for it so far has been to recurse thought the .Ste.RegularPages list to display the recent articles on my home page.

{{- range first 4 .Site.RegularPages }}
<article class="item">
  <h4>{{ .Title }}</h4>
  <time>{{ dateFormat "02/01/2006" .Date }}</time>
  <div class="tags">
    {{ range first 3 (.GetTerms "tags") }}
    <a href="{{ .Permalink }}"><span>{{ .LinkTitle }}</span></a>
    {{ end }}
  </div>
  <p>{{ .Summary }}</p>
  <a href="{{ .Permalink }}" class="button">Read</a>
</article>
{{- end }}

Writing a blog Post

Content for the posts themselves go into the content folder in the root. If you want to have a page at /articles/my-first-article/ you'll want to create your org file at /content/articles/my-first-article.org. You'll want to populate a few things for the page which should be self-explanatory. Here's the page variables for this page

#+title: Static Site With Hugo and Org Mode
#+date: 2020-08-16T08:50:30+01:00
#+summary: HUGO plus org-mode. How parsethesource is made using basic hugo theming and a little bit of org
#+tags[]: hugo org-mode emacs
#+draft: true

The only thing that may be unexplained here is the draft variable. When you call hugo serve with the -D flag, it will show pages with draft set to true, otherwise it won't and this is also true for publishing.

From here you can pretty much just write org. It supports links, images, tables, headings, code listings and emphasis like bold, italics etc. all natively. Just write your org and if your css is up to scratch, it will look good.

Publish

To publish your site, call hugo. This creates all the HTML you need and puts it in a /public/ folder.

That's it! Put that HTML somewhere and you have yourself a website. Mine is hosted in S3, with cloudfront for that super thrifty experience, but more on that in a later blog post.