Starting a Blog - Part 2: Customization

Fri, Aug 9, 2019

blog
hugo

This is the second part of my blog feature on setting up a blog using Hugo and Netlify. In part 1, I discussed installing Hugo and the Hyde theme and adding an initial post. We then used the hugo server command to create a live version of the website to view locally. This post will discuss various means on how to customize the appearance of the generated blog.

Modifying the theme - Parameters

Themes are only starting points and it is unlikely the default settings for a theme will match your desired appearance. As such, the next step in creating my blog was to do some tweaking of the standard Hyde theme.

One common way of making changes is through parameters stored within the site config file (config.toml by default, though you can also have .yaml or .json variants). Each theme might have different parameters that are used for formatting and creating web pages. The following shows the config I use:

baseURL = "/"
languageCode = "en-us"
title = "jbowen.dev"
theme = "hyde"

## Site Settings
[params]
  # Descriptive text shown in sidebar beneath title
  description = "Thoughts and musings"

  # Hyde theme specific setting
  themeColor = "theme-base-0d"

## Main Menu
[[menu.main]]
    name = "Posts"
    weight = 100
    identifier = "posts"
    url = "/posts/"
[[menu.main]]
    name = "About"
    identifier = "about"
    weight = 200
    url = "/about/"

And here is an example of the changed blog:

Modifying the theme - Overriding CSS

Of course, only so a small portion of the theme can be customized via the config file. Hyde, like many of the Hugo themes, makes use of CSS for defining the styling and presentation of the web pages Hugo generates. While it is possible to modify the CSS files in the Hyde theme folder (themes/hyde/static/css/) doing so would introduce local changes to our copy of the remote repository for Hyde. If we wish to later update Hyde to any remote changes we will need to handle reconciling these local and remote changes.

A better way of making local changes is to utilize Hugo’s built-in path resolution feature. When determining a path to a file from the URL, Hugo will look in a few different directories in a defined order until it finds a match. For instance, the URL https://<hostname>/image.png will cause Hugo to look for static/image.png in the root directory. If it does not find it, Hugo will then look for the same static/image.png within the active theme’s directory.

Hyde stores its CSS files in themes/hyde/static/css/ which means if we place an identically named file in the static/css directory of the site root, Hugo will use our new file as a replacement for the original.

One item I did not care for in the default Hyde theme was the title font and size. These are defined as part of the hyde.css file under the class sidebar-about:

.sidebar-about h1 {
  color: #fff;
  margin-top: 0;
  font-family: "Abril Fatface", serif;
  font-size: 3.25rem;
}

We will want to change the font-family and font-size parameters. We do this first by copying the entire existing file to static/css/hyde.css in the root directory:

jbowen@maranello:~/blog/jbowen.dev$ mkdir -p static/css
jbowen@maranello:~/blog/jbowen.dev$ cp themes/hyde/static/css/hyde.css static/css
jbowen@maranello:~/blog/jbowen.dev$ git add static/css/hyde.css
jbowen@maranello:~/blog/jbowen.dev$ git commit -m "Add override for theme hyde.css"
[master 687a3d9] Add override for theme hyde.css
 1 file changed, 250 insertions(+)
 create mode 100644 static/css/hyde.css

As shown above, we also perform a git add and git commit of the unmodified, copied file. This will allow us to see any changes we make to this override file relative to the version we copied.

Now we can modify the file by changing the above lines to:

.sidebar-about h1 {
  color: #fff;
  margin-top: 0;
  font-family: sans-serif;
  font-size: 2.75rem;
}

then perform the necessary git commands:

jbowen@maranello:~/blog/jbowen.dev$ git add static/css/hyde.css
jbowen@maranello:~/blog/jbowen.dev$ git diff HEAD
diff --git a/static/css/hyde.css b/static/css/hyde.css
index 1ddbdda..254f482 100644
--- a/static/css/hyde.css
+++ b/static/css/hyde.css
@@ -79,8 +79,8 @@ html {
 .sidebar-about h1 {
   color: #fff;
   margin-top: 0;
-  font-family: "Abril Fatface", serif;
-  font-size: 3.25rem;
+  font-family: sans-serif;
+  font-size: 2.7rem;
 }

 /* Sidebar nav */
jbowen@maranello:~/blog/jbowen.dev$ git commit -m "Change title font and size"
[master eb58512] Change title font and size
 1 file changed, 2 insertions(+), 2 deletions(-)

If we have hugo server running in another terminal, we should be able to see the change take effect in our web browser. One thing to note, I have found that sometimes the browser (Chromium in my case) might cache CSS files so it will require a force-reload of the page for the changes to take effect.

Modifying Theme - Overriding Layouts

Above we showed how to override the CSS file used by the Hyde theme by copying the original file from the theme directory into an identically named directory in the blog root directory. The same approach can be taken with layouts.

Layouts are the core templates used by Hugo when generating a web site. They determine the actual HTML that is created for a given page.

In our case I wish to add an avatar photo to the sidebar. The sidebar is generated based on the layout file at themes/hyde/layouts/partials/sidebar.html. Our first step to modifying this file is to once again copy the file into an identically directory and then commit to git to preserve the original content.

jbowen@maranello:~/blog/jbowen.dev$ mkdir -p layouts/partials
jbowen@maranello:~/blog/jbowen.dev$ cp themes/hyde/layouts/partials/sidebar.html layouts/partials/
jbowen@maranello:~/blog/jbowen.dev$ git add layouts/partials/sidebar.html

Next we add the following to the newly copied file:

{{ with .Site.Params.authorimage }}
  <div class="author-image">
    <img src="{{ $.Site.Params.authorimage }}" alt="Author Image" class="author-image">
  </div>
{{end}}

The above templating logic will add the <div> block containing an image only if the parameter authorimage is set in the configuration.

Next we copy our image file to /static/images/avatar.jpg so that Hugo can access it at /images/avatar.jpg.

Following this, we add the following to our config.toml file within the [params] section:

# Avatar for sidebar
authorImage = "/images/avatar.jpg"

Finally we need to amend the hyde.css file with the appropriate settings for the author image to appear in a circular frame:

.author-image {
  border-radius: 50%;
  height: 200px;
  width: 200px;
  display: block;
  margin-left: auto;
  margin-right: auto;
}

This concludes part 2 of my write-up on starting my blog. In part 3, we will investigate what it takes to actually deploy our web site to a Netlify web server.

Starting a Blog - Part 3: Deploying

Starting a Blog - Part 1: Hugo