Hugo on Techformist

Simple Site Summary in Hugo

Mon, 25 Nov 2019 18:30:00 +0000

Here’s a simple way to organize your taxonomies and have a bird’s eye view of the number of posts per category/tag in Hugo.

The Problem

As techformist.com grew, I became more and more disorganised in maintaining taxonomies. I had some interesting situations -

a “static-site” category coexist with “static sites” category
confusion b/w why I chose a few terms to be tags rather than categories in their own right
the recurring need to “rethink taxonomy structure” depending on the flavour of the month and time of the day

This often required me to go back and change a few taxonomy terms, or to reorganize site structure in order to provide better visibility to chosen topics.

I also developed this habit of referring back to the older topics with a site search / VSCode search just to copy/paste tags and categories from an older post.

This was frustrating.

The Solution

There were couple of simple solution options -

Create a summary page on the site
Include counts in the manually maintained writing/editorial calendar (and bring some automation to that side of the world while at it)
Analyse sitemap to get a nice summary and maintain that analysis somewhere

In the end, I felt it would be easier to create a quick summary page on the site and refer back to it, rather than over-engineer a solution.

So, I created this summary page with just a few lines of code for layout.

I can now -

Quickly check the categories / tags and select relevant combination for a new post
Keep an eye on the counts and refocus on things that I have to write more about
Satisfy my ego by showing the post counts and by hiding away more useful statistics such as the usefulness & longevity of the content

How to implement this in your own Hugo site?

Create a file called “summary.html” in your layouts folder.


{{ partial "header" . }} 

{{ partial "header/header" . }}

{{/*-- post count */}}
{{ $posts := (where .Site.RegularPages "Section" "==" "posts") }}
{{ $postCount := len $posts }}

{{/*-- page count */}}
{{ $pages := (where .Site.RegularPages "Section" "==" "page") }}
{{ $pageCount := len $pages }}


<div style="overflow: auto;">
  <table>
    <thead>
      <tr>
        <td style="text-align:center;font-weight: bold;width: 10em;">Descriptiontd>
        <td style="text-align:center;font-weight: bold;">Valuetd>
      tr>
    thead>
    <tbody>
      <tr><td>Pagestd><td>{{ $pageCount }}td>tr>
      <tr><td>Poststd><td>{{ $postCount }}td>tr>
      <tr><td>Post by Categoriestd>
        <td>
          {{ range $name, $taxonomy := .Site.Taxonomies.categories }}
            <a href="/categories/{{ $name | urlize }}">{{ $name | humanize }} ({{ $taxonomy.Count }})a>
             
          {{end}}
        td>
      tr>
      <tr><td>Post by Tagstd>
        <td>
          {{ range $name, $taxonomy := .Site.Taxonomies.tags }}
            <a href="/tags/{{ $name | urlize }}">#{{ $name | humanize }} ({{ $taxonomy.Count }})a>
             
          {{end}}
        td>
      tr>
    tbody>
  table>

{{ partial "footer" . }}

As you can see, I am no where near an expert on Hugo. Or, even basic styling in HTML :)

Next, create a content page in pages folder. This is to better organize structure in the future.

---
title: Summary of Posts
url: summary
type: page
layout: summary
date: 2020-02-20 20:20:20
comments: false
---

This is a summary of the site that lists categories, tags and what not alongside the number of posts. Not quite useful for anyone other than the publishers.

Navigate to /summary.

Have fun.

Include full content in site feed in Hugo

Thu, 17 Oct 2019 06:30:00 +0000

Include all content of your posts in your site feed when using Hugo static site generator.

By default Hugo will include only summary in your website feed (e.g. in /index.xml). Your theme may already provide a way to provide full content instead of just the summary. If it doesn’t, you can make those simple changes yourself.

Create a new file rss.xml in layouts\_default\ folder in your site root directory. Include following content (as of v0.58) -


{{ printf "" | safeHTML }}
 version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  
    </span>{{ if eq  .Title  .Site.Title }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}{{ end }}<span class="nt">
    {{ .Permalink }}
    Recent content {{ if ne  .Title  .Site.Title }}{{ with .Title }}in {{.}} {{ end }}{{ end }}on {{ .Site.Title }}
    Hugo -- gohugo.io{{ with .Site.LanguageCode }}
    {{.}}{{end}}{{ with .Site.Author.email }}
    {{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}{{end}}{{ with .Site.Author.email }}
    {{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}{{end}}{{ with .Site.Copyright }}
    {{.}}{{end}}{{ if not .Date.IsZero }}
    {{ .Date.Format "2006-01-02" | safeHTML }}{{ end }}
    {{ with .OutputFormats.Get "RSS" }}
        {{ printf " href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
    {{ end }}



    {{- range first 10 (where .Site.RegularPages "Type" "not in" "pages" ) -}}
    
      </span>{{ .Title }}<span class="nt">
      {{ .Permalink }}
      {{ .Date.Format "2006-01-02" | safeHTML }}
      {{ with .Site.Author.email }}{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}{{end}}
      {{ .Permalink }}
      {{ .Content | html }}
    
    {{ end }}

The content of the file is almost same as the embedded rss.xml used in Hugo.

.. except for two crucial differences -

Include full content in RSS feed
```
{{ .Content | html }}
```
Fetch only 10 articles in the feed. You can get this 10 from the site config as well.
```
{{- range first 10 (where .Site.RegularPages "Type" "not in" "pages" ) -}}
```

Add PWA to your Hugo site

Wed, 11 Sep 2019 06:30:00 +0000

Adding PWA to your Hugo static site is quite easy.

What is PWA and why should I add it?

Progressive web applications (PWA) are a nice way to give your websites an “app makeover”. Using PWAs your sites are perceived to load faster, are available offline, and in general improve user experience.

PWAs are supported by all web browsers. Using PWAs on single page applications have shown remarkable improvement in site speed and have provided us the ability to continuing to serve static content even when the connectivity is down.

Back to Hugo - although I can see incremental gains, nothing jumped out to make up for a compelling case for PWA. The sites generated by Hugo are static - pages are already generated and waiting to be loaded. Depending on the theme, you may already be seeing the best load times that your site can achieve. So, YMMV.

How do I add PWA to Hugo?

At a minimum a PWA needs a manifest and service worker. We will use a offline-first cache strategy to enable PWA.

Create your icons

PWAs are available offline and can be installed on the phone. This requires icons of different sizes for your website. Just pluck your logo, remove the text if necessary and generate icons of all popular sizes. You can use a service like Favicomatic to make that a one-click process.

Create manifest

Create a new file called manifest.json in your /static folder and add content similar to below

{
  "name": "Techformist",
  "short_name": "techformist",
  "icons": [
    {
      "src": "/appicons/favicon-128.png",
      "sizes": "128x128",
      "type": "image/png"
    },
    {
      "src": "/appicons/apple-touch-icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png"
    },
    {
      "src": "/appicons/apple-touch-icon-152x152.png",
      "sizes": "152x152",
      "type": "image/png"
    },
    {
      "src": "/appicons/favicon-196x196.png",
      "sizes": "196x196",
      "type": "image/png"
    },
    {
      "src": "/appicons/splash.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "start_url": "/",
  "display": "standalone",
  "orientation": "portrait",
  "background_color": "#FFFFFF",
  "theme_color": "#FFFFFF"
}

Create service worker

Create a new javascript file sw.js in /static. This script does all the heavy lifting like maintaining cache and enabling your site to be treated like an app.

I just copied the code from the sample service worker script available at [https://github.com/wildhaber/offline-first-sw].

Modify the file and choose to make some or all files available offline - I typically include CSS, common Javascript files and images. See the end of this article for the file used by this blog.

Include manifest in `head`

Include a link to your manifest in your header.

I use Minimo theme and included the following line in /layouts/partials/head/extra.html. Note that I am not over-writing the file in the theme folder, but overriding it using my own version (as is typical to Hugo themes).

<link rel="manifest" href="/manifest.json">

Include the service worker JS file reference in your footer. For some strange reason, I chose to be different and included that in my sidebar.html.

<script>
  if('serviceWorker' in navigator) {
      navigator.serviceWorker
          .register('/sw.js', { scope: '/' })
          .then(function(registration) {
              //console.log('Service Worker Registered');
          });

      navigator.serviceWorker
          .ready
          .then(function(registration) {
              //console.log('Service Worker Ready');
          });
  }
script>

See the Results

That is it. Your site automagically is a PWA now.

Check out Chrome developer tools -

A site or an app?

Go to Application tab.

You should see details provided in your manifest including the different icons. You will also see the different offline files you specified in the Cache Storage section.

Lighthouse scores

Go to Audit tab and do a Lighthouse audit for your site.

Mobile Lighthouse score for home page -

Lighthouse score for an article -

Rejoice.

Conclusion

Adding and setting up PWA to Hugo is trivial. But, I did not clearly make out any significant advantages of enabling PWA on my blog - given that I am not after providing a read-offline feature.

Post Script

sw.js code

const CACHE_VERSION = 1;

const BASE_CACHE_FILES = [
    '/css/custom.css',
    '/js/custom.js',
    '/search/index.json',
    '/manifest.json',
    '/favicon.png',
    '/images/logo.png',
    '/techformist-logo-no-text.png',
    '/assets/css/main.6a060eb7.css',
    '/assets/js/main.67d669ac.js',
    '/assets/js/sidebar.9ea42a6e.js',
    '/assets/js/fuse_search.1ada4bca.js',
];

const OFFLINE_CACHE_FILES = [
    '/images/logo.png',
    '/techformist-logo-no-text.png',
    '/assets/css/main.6a060eb7.css',
    '/assets/js/main.67d669ac.js',
    '/assets/js/sidebar.9ea42a6e.js',
    '/assets/js/fuse_search.1ada4bca.js',
];

const NOT_FOUND_CACHE_FILES = [
    
    '/404.html',
];

const OFFLINE_PAGE = '/offline/index.html';
const NOT_FOUND_PAGE = '/404.html';

const CACHE_VERSIONS = {
    assets: 'assets-v' + CACHE_VERSION,
    content: 'content-v' + CACHE_VERSION,
    offline: 'offline-v' + CACHE_VERSION,
    notFound: '404-v' + CACHE_VERSION,
};

// Define MAX_TTL's in SECONDS for specific file extensions
const MAX_TTL = {
    '/': 3600,
    html: 3600,
    json: 86400,
    js: 86400,
    css: 86400,
};

const CACHE_BLACKLIST = [
    (str) => {
       return !str.startsWith('http://localhost') ;
    },
];

const SUPPORTED_METHODS = [
    'GET',
];

/**
 * isBlackListed
 * @param {string} url
 * @returns {boolean}
 */
function isBlacklisted(url) {
    return (CACHE_BLACKLIST.length > 0) ? !CACHE_BLACKLIST.filter((rule) => {
        if(typeof rule === 'function') {
            return !rule(url);
        } else {
            return false;
        }
    }).length : false
}

/**
 * getFileExtension
 * @param {string} url
 * @returns {string}
 */
function getFileExtension(url) {
    let extension = url.split('.').reverse()[0].split('?')[0];
    return (extension.endsWith('/')) ? '/' : extension;
}

/**
 * getTTL
 * @param {string} url
 */
function getTTL(url) {
    if (typeof url === 'string') {
        let extension = getFileExtension(url);
        if (typeof MAX_TTL[extension] === 'number') {
            return MAX_TTL[extension];
        } else {
            return null;
        }
    } else {
        return null;
    }
}

/**
 * installServiceWorker
 * @returns {Promise}
 */
function installServiceWorker() {
    return Promise.all(
        [
            caches.open(CACHE_VERSIONS.assets)
                .then(
                    (cache) => {
                        return cache.addAll(BASE_CACHE_FILES);
                    }
                ),
            caches.open(CACHE_VERSIONS.offline)
                .then(
                    (cache) => {
                        return cache.addAll(OFFLINE_CACHE_FILES);
                    }
                ),
            caches.open(CACHE_VERSIONS.notFound)
                .then(
                    (cache) => {
                        return cache.addAll(NOT_FOUND_CACHE_FILES);
                    }
                )
        ]
    );
}

/**
 * cleanupLegacyCache
 * @returns {Promise}
 */
function cleanupLegacyCache() {

    let currentCaches = Object.keys(CACHE_VERSIONS)
        .map(
            (key) => {
                return CACHE_VERSIONS[key];
            }
        );

    return new Promise(
        (resolve, reject) => {

            caches.keys()
                .then(
                    (keys) => {
                        return legacyKeys = keys.filter(
                            (key) => {
                                return !~currentCaches.indexOf(key);
                            }
                        );
                    }
                )
                .then(
                    (legacy) => {
                        if (legacy.length) {
                            Promise.all(
                                legacy.map(
                                    (legacyKey) => {
                                        return caches.delete(legacyKey)
                                    }
                                )
                            )
                                .then(
                                    () => {
                                        resolve()
                                    }
                                )
                                .catch(
                                    (err) => {
                                        reject(err);
                                    }
                                );
                        } else {
                            resolve();
                        }
                    }
                )
                .catch(
                    () => {
                        reject();
                    }
                );

        }
    );
}


self.addEventListener(
    'install', event => {
        event.waitUntil(installServiceWorker());
    }
);

// The activate handler takes care of cleaning up old caches.
self.addEventListener(
    'activate', event => {
        event.waitUntil(
            Promise.all(
                [
                    cleanupLegacyCache(),
                ]
            )
                .catch(
                    (err) => {
                        event.skipWaiting();
                    }
                )
        );
    }
);

self.addEventListener(
    'fetch', event => {

        event.respondWith(
            caches.open(CACHE_VERSIONS.content)
                .then(
                    (cache) => {

                        return cache.match(event.request)
                            .then(
                                (response) => {

                                    if (response) {

                                        let headers = response.headers.entries();
                                        let date = null;

                                        for (let pair of headers) {
                                            if (pair[0] === 'date') {
                                                date = new Date(pair[1]);
                                            }
                                        }

                                        if (date) {
                                            let age = parseInt((new Date().getTime() - date.getTime()) / 1000);
                                            let ttl = getTTL(event.request.url);

                                            if (ttl && age > ttl) {

                                                return new Promise(
                                                    (resolve) => {

                                                        return fetch(event.request)
                                                            .then(
                                                                (updatedResponse) => {
                                                                    if (updatedResponse) {
                                                                        cache.put(event.request, updatedResponse.clone());
                                                                        resolve(updatedResponse);
                                                                    } else {
                                                                        resolve(response)
                                                                    }
                                                                }
                                                            )
                                                            .catch(
                                                                () => {
                                                                    resolve(response);
                                                                }
                                                            );

                                                    }
                                                )
                                                    .catch(
                                                        (err) => {
                                                            return response;
                                                        }
                                                    );
                                            } else {
                                                return response;
                                            }

                                        } else {
                                            return response;
                                        }

                                    } else {
                                        return null;
                                    }
                                }
                            )
                            .then(
                                (response) => {
                                    if (response) {
                                        return response;
                                    } else {
                                        return fetch(event.request) 
                                            .then(
                                                (response) => {

                                                    if(response.status < 400) {
                                                        if (~SUPPORTED_METHODS.indexOf(event.request.method) && !isBlacklisted(event.request.url)) {
                                                            cache.put(event.request, response.clone());
                                                        }
                                                        return response;
                                                    } 
                                                    else {
                                                        return caches.open(CACHE_VERSIONS.notFound).then((cache) => {
                                                            return cache.match(NOT_FOUND_PAGE);
                                                        })
                                                    }
                                                }
                                            )
                                            .then((response) => {
                                                if(response) {
                                                    return response;
                                                }
                                            })
                                            .catch(
                                                () => {

                                                    return caches.open(CACHE_VERSIONS.offline)
                                                        .then(
                                                            (offlineCache) => {
                                                                return offlineCache.match(OFFLINE_PAGE)
                                                            }
                                                        )

                                                }
                                            )
                                        
                                    }
                                }
                            )
                            .catch(
                                (error) => {
                                    console.error('  Error in fetch handler:', error);
                                    throw error;
                                }
                            );
                    }
                )
        );

    }
);

Format Hugo markdown and code

Fri, 09 Aug 2019 06:30:00 +0000

Format your markdown using prettier and you are off to the races.

Hugo static site generator keeps everything simple. I just love the power of typing in something in markdown, and seeing the finished HTML pages and blog formatted to specs (in no time, I might add).

I use VSCode for writing markdown text. This works out beautifully - I can save markdown files and prettier kicks in to format everything - the markdown within those files and the code within markdown.

Why use VSCode?

I keep markdown and code typing similar - no brain-freeze. And, the formatting is a huge bonus as you see below.

What I type -

###   Header 3
 Hello World
```js
  if (true){
console.log("hello world")
}
  ```

What the content gets automatically formatted to -

### Header 3

Hello World

```js
if (true) {
  console.log("hello world");
}
```

You may see that -

### line has extra spaces removed
a blank line has been added between header and content
another blank line added between content and the beginning of code block
the js block has been changed to -
- format if statement as a code-block
- semicolons at logical end

If you have been typing in markdown, you would have recognized how valuable adding blank line can be. While it is easier for prettier, markdown does not “see” what you meant and format the entire block of content in an altogether different way.

Another crucial advantage for me - I can type in code-blocks within markdown and let it automatically format. I also get to know any silly mistakes (e.g. a bracket not closed) since Prettier parser will not format the code.

The Alternative

If VSCode is working so well with a couple of extensions, why change that? Two reasons -

I had been trying to make my workflow even more seamless
VSCode gobbles up a lot of memory. I want to minimise stuff I do on VSCode other than main-stream programming. Obviously all those windows are going to be open all the time, which is a big problem

I wanted to retain VSCode’s fantastic formatting support, and I can do that in just a couple of steps - thanks to Hugo.

Go to your Hugo site root directory
If your theme does not use any kind of packages today - do npm init. (in other words, ignore this step if you already have package.json in your Hugo site root directory)
Install husky, lint-staged, and prettier packages -
```
  npm install husky lint-staged prettier
```

Change your package.json to-

{
  "scripts": {
    "precommit": "lint-staged"
  },
  "lint-staged": {
    "*.md": ["prettier --parser markdown --write", "git add"]
  }
}

We parse markdown file with lint-staged and use prettier to format files. husky enables us to prevent accidental commits before running pre-commit hook.

That’s it - now you can see your files nicely formatted no matter which editor you use.

Web Inspector to design static sites

Wed, 06 Feb 2019 15:30:00 +0000

Chrome and Firefox web inspectors are my new best friends in my quest to develop static sites. I never took the time to appreciate the complete power of web inspection - until I actually started changing the design of this very site.

I have been redesigning techformist.com website on Hugo. The plan is to migrate from Jekyll and design a simpler site that can easily showcase what I have to offer (ahem..).

While there are excellent ways to develop Go templates on my own, I always appreciate the opportunity to stand on the shoulders of giants. I selected the Minimo theme for the purpose and started customizing CSS alongside a few changes in the layouts and templates.

It was then and only then I could completely and deeply commit myself to the inspectors.

You see - all of my ‘professional’ web development life has been spent using UI standards and libraries like Materialize, Bulma and Bootstrap. These offer a million ways of personalizing stuff but, at the same time, stay abstract from targeting CSS changes for specific, individual elements / ids / classes.

This changed when I started personalizing fonts, colours, borders et. al. on a static site theme like Minimo that did not use these standards. I had to start identifying the individual tags, ids and elements in the CSS path so that they can be over-ridden in custom.css file provided by the theme.

While this seemed trivial from my experience with other themes, Minimo had a slightly different approach and had an arguably better hierarchical structure in CSS. (Actually, the theme used SCSS that I did not bother to override, I chose the easier path.)

After about 10 minutes of wrangling with elements, I was seriously contemplating on switching to another generator altogether. It was then I started using the web inspector in the way it was supposed to be used.

Click, find CSS path and use the path in custom.css to override the style. This was so efficient and easy.

In a span of 4-6 hours over 2 days I had done multiple iterations of the site including a few template/layout changes. What you see may be that, or may be a few more changes. The point is - such changes to styles on a SSG is much much more simplified if you use web inspector.

But wait - that is not my final advice. If I would redo anything, I would probably use a starter theme based on Bulma or Tailwind and start customizing from that baseline. I believe that will be an easier, more intuitive customization option than the “start from scratch” approach.

Copy/paste Datatable Issues in Hugo

Fri, 26 Oct 2018 15:38:00 +0000

It is interesting how the minor things eat away a lot of your time. Especially if you happen to be like me, one of the greater idiots on a planet full of idiots.

One of the days, I had to create website really fast to demonstrate to a potential customer. I abandoned my dear old friend Jekyll since - well, I had to create something in Hugo.

There was a requirement to show a data list (phone numbers and some related information) on one of the pages.

|Phone | Active|
|+91 1029292122 | Y|
|+91 1298329929 | Y|
|+91 1192389292 | Y|

Easy enough.

But, this data had to be changed by the end user - who is not super computer-savvy) and does not want to mess around with templates or md files.

There is Hugo feature called Data Driven Content to help in those situations.

So this..

Step 1:

Create CSV file in the static (static/csv) under my root folder.

Step 2:

Create a new partial in Layouts.

<section id="basic-content">
  <div class="container">
    <script>
      $(document).ready(function() {
        $("#csvnum").dataTable();
      });
    script>

    <table
      id="csvnum"
      class="table table-striped table-bordered"
      style="width:100%"
    >
      <thead>
        <tr>
          <th>Phoneth>
          <th>Activeth>
        tr>
      thead>
      <tbody>
        {{ $url := "static/csv/phone_active.csv" }} {{ $sep := "," }} {{ range
        $i, $r := getCSV $sep $url }}
        <tr>
          <td>{{ index $r 0 }}td>
          <td>{{ index $r 1 }}td>
        tr>
        {{ end }}
      tbody>
    table>
  div>
section>

So far so good. Except, the outcome isn’t anything but what I expect.

I get following errors depending on whether I refresh the browser during an even second or an odd second.

TypeError: c is undefined

TypeError: col is undefined

I don’t claim to be an expert on JS, but did a fair bit of debugging here. My interim thoughts were focused on investigating how $(document).ready was called even though the data was not ready yet. I assumed this was the sole reason since the static table was getting rendered but the data from file wasn’t. What other reason could there be?

It turns out there are many valid reasons for the problem. And, I should not blame the collective wisdom of Javascript at every second error.

Excel and some formatting issues had introduced a third phantom column in the CSV. For good or for worse (mostly the latter), this did not show up in Excel, or in Notepad.

Datatable was all weird since defines two columns while has three.

The debugging of this problem should have ideally taken less than five minutes, and there I was exploring why the data table would not work after two hours of reading email, debugging stuff, checking Feedly, and so forth.