My new personal website: setup and customization

At the end of summer 2023, I decided to create a new personal website to showcase my work and share my thoughts. I’m conscious I won’t be very consistent in updating it, so I wanted to keep it simple and easy to maintain. Static site generators are perfect for this purpose, and after a brief search I selected Hugo, together with the Wowchemy Academic theme as the one to use.

However, in the subsequent months, I applied a bunch of customizations to add some features I liked, and I’m still working on it. I want to remember how I did it, so I’m writing them down here. This post is a living document where I keep track of all the changes I applied.

Side ToC in posts

This is now (as I’m writing is Sept ‘24 and the Wowchemy is now called Hugo Blox) a feature active by default. But this website still uses the old Wowchemy theme, in which the feature was not working out of the box, at least in my case. I started from this post by Chen Xing, then I experimented a little bit, since at first his solution wasn’t working for me, probably due to a different version of the theme (mine should be v5.5, ~Sept 2023). In the end, this is the solution it worked from me.

1. Redefine single.html

I created the file <website root>/layouts/_default/single.html (which overwrites the original one from the theme) with the following content:

{{- define "main" -}}
{{ if .Params.toc }}
<div class="container-fluid docs">
    <div class="row flex-xl-nowrap">
      <div class="d-none d-xl-block col-xl-2 docs-toc">
        <ul class="nav toc-top">
          <li><a href="#" id="back_to_top" class="docs-toc-title">{{ i18n "on_this_page" }}</a></li>
        </ul>
        {{ .TableOfContents }}
      </div>
      <main class="col-12 col-md-0 col-xl-10 py-md-3 pl-md-5 docs-content" role="main">
{{ end }}
        <article class="article">
            {{ partial "page_header" . }}
            <div class="article-container">
              <div class="article-style">
                {{ .Content }}
              </div>
              {{ partial "page_footer" . }}
            </div>
        </article>
  {{ if .Params.toc }}
      </main>
    </div>
  </div>
  {{ end }}
{{- end -}}

2. Add settings in config.yaml

In <website root>/config/_default/config.yaml I found the markup key in the “Advanced” section and added the following sub keys:

markup:
  tableOfContents:
    startLevel: 2
    endLevel: 4

3. Activate ToC in each post

Fiinally, if you want the ToC to be actually shown, you have to add the following line in the front matter of each post you want it to appear:

toc: true

4. Customize ToC style

For now I’m satisfied with the default style, but if I want to change it I can do it by adding some CSS in the assets/css/custom.css file. The only modification I made is to make the ToC a little bit more compact reducing the line height:

#TableOfContents li a {
  line-height: 23px
}

Show both date and lastmod in posts header

By default, the Wowchemy theme shows the date of a post (or other page) in the page metadata. But whenever a lastmod date is present in the front matter, is is shown in place of the original one. I wanted to retain both of them shown in a format like:

Aug 21, 2023 · Last updated on Sep 11, 2024

I found a solution in this old issue on github. As usual I had to modify it slightly to make it work on my specific version of the template.

First I cloned the original Wowchemy page_metadata.html partial from the Wowchemy repository, and I placed it in <website root>/layouts/partials/page_metadata.html. Then I modified a single line in the file. In the following you can see the output of the diff command between the original file and the modified one:

--- page_metadata_original.html	2024-09-12 09:51:39.141821816 +0200
+++ page_metadata.html	2024-09-12 09:47:43.503390586 +0200
@@ -20,7 +20,7 @@
       {{ $date = $page.Date | time.Format (site.Params.publications.date_format | default "January, 2006") }}
     {{ else }}
       {{ if ne $page.Params.Lastmod $page.Params.Date }}
-          {{ i18n "last_updated" }}
+        {{ $page.Date.Format site.Params.locale.date_format }} · {{ i18n "last_updated" }}
       {{ end }}
     {{ end }}
     {{ $date }}

That’s it! You can see the result at the top of this post.

Enable comments in posts

I’m conscious that I’m not reaching masses of people here 🤣, but still I liked the idea of enabling comments in my posts. Discarded all the options that require money spending and/or the give away of your personal data, I finally selected Giscus as commenting engine.

The installation was quite straightforward, and I mostly followed the procedure well explained by Yury Zhauniarovich, amended with modifications explained by Nick Ballou.

You can see the comments in action at the bottom of the page.

Enable map in contact page

For some reason, even if the feature should have been already included in my version of the theme, the map in the contact page was not working. In the end, I opted to inject directly the iframe code in the contact.html file, as advised by this post.

First I cloned the original Wowchemy contact.html partial (the link points to the specific version used in my theme) from the Wowchemy repository, and I placed it in <website root>/layouts/partials/blocks/contact.html. Then I modified the file to include the iframe code for OpenStreetMap:

--- contact_original.html	2024-09-12 18:24:02.158160786 +0200
+++ contact.html	2024-09-12 18:15:02.128967142 +0200
@@ -154,7 +154,7 @@
 
   </ul>
 
-  {{ if and site.Params.features.map.provider $data.coordinates.latitude }}
+  <!-- {{ if and site.Params.features.map.provider $data.coordinates.latitude }}
   <div class="d-none">
     <input id="map-provider" value="{{ lower site.Params.features.map.provider }}">
     <input id="map-lat" value="{{ $data.coordinates.latitude }}">
@@ -164,6 +164,20 @@
     <input id="map-api-key" value="{{ site.Params.features.map.api_key }}">
   </div>
   <div id="map"></div>
-  {{ end }}
+  {{ end }} -->
+  
+  <div class="col-xs-12 col-sm-8 col-md-9" style="padding:0">
+    <div class="map_canvas">
+      <iframe width="133%" height="400" frameborder="0" scrolling="no" marginheight="0" marginwidth="0" src="https://www.openstreetmap.org/export/embed.html?bbox=9.1544796%2C45.49995998%2C9.1594796%2C45.5029998&amp;layer=mapnik&amp;marker=45.5015998%2C9.1542000,623"></iframe>
+    </div>
+      <style>
+        .map_canvas {
+          overflow:hidden;
+          background:none!important;
+          height:400px;
+          width:133%;
+        }
+      </style>
+  </div>
 
 </div>