[Blog] Upgrading My Tech Blog: Hugo, Giscus, and Pagefind Integration

By See Hiong

December 26, 2023 - 3 minutes read - 427 words

In this post, I will provide updates on my transition to utilizing Hugo for my tech blog.

Setup Process

To begin, I recommend installing Chocolately, a free and open-source package manager designed for Windows.

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Proceed to install Hugo using Chocolately:

choco install hugo-extended

After installation, I opted for the Ananke theme. Upon completing your post, you can view your site at http://localhost:1313:

hugo serve

Giscus Integration

Gicus serves as a comment system powered by Github Discussions.

I created a giscus.html file under the \themes\ananke\layouts\partials folder with the following contents:

<p class="f5 b mb3">Post a comment:</p>
<script src="https://giscus.app/client.js"
    data-repo="xxxxxxxx/seehiong.github.io"
    data-repo-id="R_xxxxxxxxxx"
    data-category="General"
    data-category-id="DIC_xxxxxxxxxxxxxxxx"
    data-mapping="url"
    data-strict="0"
    data-reactions-enabled="1"
    data-emit-metadata="0"
    data-input-position="top"
    data-theme="preferred_color_scheme"
    data-lang="en"
    data-loading="lazy"
    crossorigin="anonymous"
    async>
</script>

Add the Giscus partial to the \themes\ananke\layouts_default_\single.html:

{{- .Content -}}
{{- partial "tags.html" . -}}
<div class="mt6 instapaper_ignoref">
{{ if .Site.DisqusShortname }}
{{ template "_internal/disqus.html" . }}
{{ end }}
{{ if .Site.Params.commentoEnable }}
{{- partial "commento.html" . -}}
{{ end }}
{{ if .Site.Params.giscusEnable }}
{{- partial "giscus.html" . -}}
{{ end }}
</div>
{{- partial "post-paginator.html" . -}}

In my config.toml:

[params]
  giscusEnable = true

Pagefind Installation

Pagefind is a fully static search library.

First, install Node.js on WSL.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
nvm ls
nvm install --lts

Navigate to your working Hugo directory, install and run Pagefind:

npx pagefind --site "public"

pagefind-on-hugo-site

NOTE: If you are unable to see the site bar from hugo serve, copy the public/pagefind folder to your static folder.

pagefind-static-folder

Add the following to \themes\ananke\layouts\partials\head-additions.html:

<link href="/pagefind/pagefind-ui.css" rel="stylesheet">
<script src="/pagefind/pagefind-ui.js"></script>

Next, adds these lines to \themes\ananke\layouts\partials\site-header.html:

<div style="max-width: 50%; margin: clamp(2px, 1vw, 10px) auto;">
    <div id="search"></div>
    <script>
        window.addEventListener('DOMContentLoaded', (event) => {
            new PagefindUI({ element: "#search", showSubResults: true });
        });
    </script>
</div>

Enjoy experimenting with Giscus and Pagefind on your Hugo site. I hope this information proves helpful in your endeavors!

Optional

Since I wanted to index only the main post, following pagefind indexing, these are the customizations that I made.

Add data-pagefind-body to \themes\ananke\layouts_default\single.html file:

{{ define "main" }}
  {{ $section := .Site.GetPage "section" .Section }}
  <article class="flex-l flex-wrap justify-between mw8 center ph3" data-pagefind-body>
    <header class="mt4 w-100">
  ...

Add data-pagefind-ignore to \themes\ananke\layouts\partials\summary-with-image.html file:

{{ partial "func/warn" `You are currently using 'partial "summary-with-image"' in your project templates. 
You should replace it with '.Render "summary-with-image"' as the use of this partial will be deprecated in future releases.
More info here: https://github.com/theNewDynamic/gohugo-theme-ananke/releases/tag/v2.8.1` }}
{{ $featured_image := partial "func/GetFeaturedImage.html" . }}
<article class="bb b--black-10" data-pagefind-ignore>
...

Add data-pagefind-ignore to \themes\ananke\layouts\partials\tags.html file:

<ul class="pa0" data-pagefind-ignore>
  {{ range .GetTerms "tags" }}
  ...