I’m new to building websites and even newer to using Hugo. Here I’ll document a few of the issues I ran into during set up.

What am I using?

The whole reason I was put onto Hugo was because of an emacs library ox-hugo. Ox-hugo allows for me to export org files directly to markdown for use by Hugo with all the proper formatting. With that in mind, the first issue I ran into was getting posts to export to the correct location.

Where do the exports go?

Since I am doing all my writing in org the export path is set at the top of the file. The two lines required are

#+HUGO_BASE_DIR: ../
#+HUGO_SECTION: ./science-posts/

The base directory is wherever the config.yaml (or .toml) is located. Since my org-files are held in a subdirectory we tell ox-hugo that the base directory is one tunnel up. The section tells ox-hugo where within the /​contents/ folder the file should be exported to. In this case the post is under the /​science-posts/ directory.

Date formatting

This one is fairly straight forward. In the front matter the format for the date should be yyyy-mm-ddTHH:mm:ss-TZ. So at the time of writing this post it will read 2022-03-12T15:33:00-5:00. That said typing out the data by hand has caused export issues where the timestamp is changed during export. I haven’t been able to track down the issue but an easy fix is to use the Org timestamp (by default this is ‘C-c .'). All that is to say my export date looks like this.

:EXPORT_DATE: <2022-03-12 Sat>

By default Hugo opens links in the same tab as the website, which is annoying when you want to check a link without fully leaving the website. To fix this a new file is made called ./layouts/_default/_markup/render-link.html (note that most of this path didn’t exist with the theme I’m using). I want have both html and pdf links open in a new page so the file looks like this

<a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}
   {{ if strings.HasPrefix .Destination "http"}} target="_blank"{{ end }}
   {{if strings.HasSuffix .Destination ".pdf"}} target="_blank"{{end}}
   >{{ .Text | safeURL }}</a>

The original solution for this was found here . I have about 15 minutes experience with html templates and the Go language, but here is the basic way to use the template. Line 1 grabs the link string and assigns it to .Destination for processing. The next two lines are if statements to check if this is a link that should open in a new tab. Go has a ‘strings’ class which is documented well here , using this the appropriate part of the string is checked to see if it matches the “.pdf” or “html” in this case. So to add new file types to this all that is needed is an extra line in the form of

{{ if <string.function> .Destination "<string>" }}

toml vs yaml

By default when ox-hugo exports, it exports in the yaml format. However, by default my theme (and maybe Hugo in general) looks for the toml format. The solution is a single line appended to the config.toml.

metaDataFormat = "yaml"

Deploying on Netlify

As of writing, this website is hosted on Netlify, which when first trying to build gave some error about postcss. Turns out the Sam template doesn’t come with a properties.json file and this issue only appears when building on Netlify because locally it uses compiled css from the resources folder. The solution is to add a new file called “properties.json” in the website’s root directory. The code to get the Sam theme working is

{
  "dependencies": {
    "postcss-cli": "8.3.1",
    "postcss": "8.2.9",
    "autoprefixer": "10.2.5"
  }
}

Some things I still want to change

  1. Depending on your screen size, you may have noticed that wide code blocks have a scroll bar. However, this scroll bar is not in the right color scheme for the website, so I’d like to fix that. I’m guessing this will require some learning on how the theme is written

  2. Change font styles within a page. This is mostly so I can format my publications in a more standard academic font (i.e. times new roman). As is, I find the citations difficult to read. This too will require knowledge on how the templates are built

  3. I’d like to add a navigation bar to posts so it’s easy to skip between sections. This will particularly useful later when writing recipes with more than a few steps.

    For now I have a functional website, so these changes will either be appended to this or added to a new post, depending on how complicated they are.