I had a really positive experience posting a question to the Hugo forum today, and getting kind responses from strangers. (The internet can be so nice! Surpise!)

1. The Problem

Hugo styles not showing up on Github Pages, though it loads locally – issue seems not due to baseURL: The absolute paths created with the baseURL are making requests from the root of the path, and omitting the subdirectory /digitalgarden. How do I reconfigure my site so that it is making requests to the correct absolute path?

I’ve never used Hugo before, so in the wee hours of last night, when I suddenly decided I wanted to have a Digital Garden for my SFPC class, I found myself stumbling on some basics, like file directory structures, template variable syntax, and configuration files.

Hugo is the static site generator I’m using to build this blog.

My styles were not loading due to this repository being hosted as a “project” under a random github repo, and not at the root URL (kaizengrowth.github.io). I couldn’t properly deploy my site with an Action on Github Pages. The styles and scripts were not showing up. I combed through various posts on the Hugo forum and verified that I was correctly setting the baseURL property in my config.toml file to:

baseURL = "https://kaizengrowth.github.io/digitalgarden/"

However, the deployed build was unable to find the the CSS and JS files in the /static folder. What confused me was that it seemed like the images were loading, which were sitting in the same folder.


2. The Ask

I was very hesitant and shy about posting on the forums where I had been looking for solutions, thinking my question was probably an extremely dumb one. (It is, tbh! I think they probably get a dumb question much like this one every few days or so.) But as they say, dumb questions help other dumb people…I mean novices :)…so…after scratching my head for a few hours, I finally relented and posted.

Within five minutes of submitting my post, a kind @davidsneighbor on the forum responded efficiently with a working solution: just change the filepaths manually in /layouts.

Duh!?! Why didn’t I think of just directly hard-coding the absolute URL paths?

I had been hoping to solve this issue through some kind of property in the configuration file, to maintain ease of editing in case I change my deployment. I am actually still wondering if there is a setting I can add to config.toml that points static assets to to a project directory. (I couldn’t find the answer to this in the Hugo documentation.) It turns out, having read quite a few other forum posts on this topic across different websites, that this is actually no trivial task in Hugo. However, @davidsneighbor’s approach effectively solves the problem, and my website now looks styled!

Hooray! 😊


3. The Solution

[Update: Using the absURL function]

Guidance from kind contributor @Irkcode who took the time to give me more clarification on how to use the absURL function in Hugo:

I don’t need to assign a site variable to reference the baseURL in the configuration file. I can simply add absURL to the path string like so:

<link rel=“stylesheet” href={{ absURL "css/styles1.css" }} />

Another method would be to use a loop in my head.html partial in this way:

{ with $myBase := absURL "" }}
    <link rel="stylesheet" href="{{ $myBase }}css/styles2.css" />
    <link rel="stylesheet" href="{{ $myBase }}css/other2.css" />
{{ end }}

Thanks so much, @Irkcode, for generously giving your time to make sure I understood the guidance from @davidsneighbor!


[Older Implementation: misinterpretation of how to use absURL, assigning it to a site variable]

Site Variables in Hugo

A better approach than hard coding the absolute file path every time it’s been used, as @davidsneighbor pointed out, would be to assign a {{ absURL }} variable to the baseURL site variable config.toml so that the full path can be more quickly and thoroughly modified across the codebase if I need to deploy the site elsewhere in the future.

Here’s how that would be done:

  1. Reference the baseURL in a variable inside the pages where I’m calling the absolute URL path and assign it to the value of .Site.BaseURL:

    {{ $absURL := .Site.BaseURL }}
<link rel="stylesheet" href="{{ $absURL }}/css/styles.css">

  2. Make these changes in the head.html and script.html partials inside of /layouts/partials.

In addition to these changes, another user, @jmooring, suggested consolidating my config.toml and hugo.toml files, and eliminating my theme.toml file, which is superfluous. @Arif also suggested using hugo.toml, the newer convention rather than config.toml.

I followed this guidance.


4. The Joy!

Voila! I’ve got a styled site! 🌸 Happy first day with Hugo.

I’m just getting to know how this static site generator works. It seems to perform a lot faster than Jekyll, with similar directory structure and build processes. GitHub Pages defaults to Jekyll, but my user experience with Hugo is much much better! For one thing, the developer community is awesome! I hope to be able to contribute to the Forum in the future, to help other users with issues I’ve finangled through.

Happily deploying this new Digital Garden for collecting things I’ve learned, read, and created. You can read about the ethos and history of digital gardens on this site.

Thank you, kind Internet Denizens and Neighors of the Hugo Forums, for your help.

My faith in humanity has been restored.