The Situation

Vuepress is simple.

Being simple is rather difficult. In the case of Vuepress, the difficulty can show up in unexpected places.

Starting with Vuepress is simple enough. Equally simple is enabling navigation on your site at multiple levels through a “sidebar” and/or a “navbar”. Specifically for the sidebar - you can enable in by adding a couple of lines in /docs/.vuepress/config.js.

module.exports = {
  //...
  themeConfig: {
    sidebar: [
      { title: "Home", children: [""] },
      {
        title: "Misc",
        children: ["more"],
      },
    ],
  },
  //...
};

The above change will create a sidebar for your site with links under Home and Misc. The title of links will be either -

• the title of the page (or)
• the first header element within the markdown files that the links point to

This is how it looks -

As you can see: the H2 headers will be links grouped below the file links.

But, what if you need to do more -

1. you want to create different sidebars for different pages. For e.g. if you are creating a site that has a bunch of different guides instead of one guide with multiple chapters. When you go to specific pages (which are represented as folders in Vuepress root folder), the navigation links have to change to point to different markdown files in a specific folder
2. you may want to continue having H2 behaviour be Vuepress default - show the links within the specific markdown files
3. you don’t want to write links to all the files by hand. Instead you want the system to automatically “see” the content to be linked

In a recent project I needed the “Admin”, “Developer” and other folders to have their own sidebars with navigation links. -

This sidebar is slightly different from Vuepress default, which seemingly assumes that all of the content is one big happy family. Vuepress by default enables links just point to the different markdown files in the document root, and to the H2 elements when the parent links are expanded.

Solutions

Let’s look at how we can customise sidebar in Vuepress.

Vuepress is after all powered by Vue - so customisation is not really a complex problem. However, I did not find this as straight forward as something like Gridsome. In Gridsome you just create a component for navigation like any sane developer and the system will exactly do what it has to - render the navbar.

Vuepress’s navbar is driven by config (and if applicable, plugins) - so this seemed not so elegant(!?) at first. But as always - all you need to solve world’s problems are good docs and some time.

Given below are three solutions that I tried to different degrees of success. The solution that worked for me is at the end because I am heartless and believe in making people scroll.

Solution 1. Use vuepress-plugin-auto-sidebar plugin

The plugin vuepress-plugin-auto-sidebar seemed to do exactly what I wanted.

To install a plugin in Vuepress, all you have to do is -

1. Install the package using npm/yarn
2. Use the plugin in config

Let’s get this going. Go to Vuepress folder and install package.

npm install --save vuepress-plugin-auto-sidebar

Include plugin in /docs/.vuepress/config.js-

module.exports = {
  // ...
  plugins: {

"vuepress-plugin-auto-sidebar": {
      titleMap: {
        "salesforce-for-students": "Salesforce for Students",
        "pd1-guide": "Platform Developer I Certification Guide",
        "admin-guide": "Admin Certification Guide",
        "why-learn-salesforce": "Why Learn Salesforce?",
        misc: "Miscellany"
      }
    },
// ...
}

This configuration will provide custom titles for the different folders and automatically pick up the files within the folder to create distinct, dynamic navigation bars.

In the ideal world, this should have been it and I should not have been sitting around to create a blog post about all the circus. But hey - ideal world is not exciting.

1. Getting started was bit of a bother. The documentation of the package is in Chinese and there are not many examples. Google translation helped to an extent
2. I could not quite figure out how autoNext and autoPrev worked. My files were not exactly sorted in the folder and sort order of the links in the sidebar was messed up
3. There were random failures. You could never say when sidebars generation failed (silently), and for the life of me, I could not figure out why. With dozens of files in different folders, I was quite frustrated with all the cut/pasting of content just to see what caused the program to fail
4. If you have a sub-folder with a README in the root, the README does not show in the navigation. This is expected as per Vuepress, but I could never say when the README appeared as a separate link and when it wouldn’t

Solution 2: Use vuepress-bar

vuepress-bar was another ready solution that seemed promising.

First, install the package.

npm i --save vuepress-bar

Next, include the plugin in /docs/.vuepress/config.js -

const getConfig = require("vuepress-bar");

module.exports = {
  themeConfig: {
    ...getConfig(`${__dirName}/..`),
  },
};

That’s it - you should have the new sidebars working. This worked more reliably than solution (1), but I could not figure out how to generate distinct sidebars for indidvidual content folders. All links appeared under one title - which was not ideal for my case.

Consider using this library if you just want a dynamic sidebar (and/or a navbar).

Solution 3: Go custom

My final solution was just doing everything myself. This was not as scary as it initially appeared - all it took was a couple of lines of code.

Get started by doing changes in /docs/.vuepress/config.js -

const fs = require("fs");
const path = require("path");

module.exports = {
  //...
  themeConfig: {
    sidebar: {
      "/why-learn-salesforce/": getSideBar(
        "why-learn-salesforce",
        "Why Salesforce?"
      ),
      "/admin-guide/": getSideBar("admin-guide", "Admin Certification Guide"),
      "/pd1-guide/": getSideBar("pd1-guide", "PD1 Certification Guide"),
      "/salesforce-for-students/": getSideBar(
        "salesforce-for-students",
        "Salesforce for Students"
      ),
    },
  },
  //...
};

function getSideBar(folder, title) {
  const extension = [".md"];

  const files = fs
    .readdirSync(path.join(`${__dirname}/../${folder}`))
    .filter(
      (item) =>
        item.toLowerCase() != "readme.md" &&
        fs.statSync(path.join(`${__dirname}/../${folder}`, item)).isFile() &&
        extension.includes(path.extname(item))
    );

  return [{ title: title, children: ["", ...files] }];
}

And voila, you have the brand new sidebar -

You can see that -

1. There’s a distinct sidebar for each folder - first level links are the files within the folder
2. Links to README and other files are consistent

Here’s a distilled-down version of my experience with Vuepress.

The Situation

I create static sites that are “real” websites. Typically the following factors in a static site generator help -

1. A cool, easy-to-customise home page
2. Themes/starter projects that make life easy
3. Plugins that can extend functionality of core software

Although I had played around Vuepress quite a bit, I always ended up choosing non-Vue technologies like Hugo, or Vue-based static site generators like Gridsome or Saber.land.

More recently however, I decided to have this long drawn out project to create a free tutorial website. With great delight and big plans, I chose Vuepress.

This is that true story.

What exactly is Vuepress?

A Vue-based static site generator, which is created by Evan Yu and supported by the Vue team. If that is not enough to get you going, there are other factors too. Read on.

Vuepress was created for documentation sites but has official themes/plugins to create a blog as well.

• Create documentation sites
• Create full-scale websites (we will get back to this point)
• Create blogs
• Create eCommerce sites
• Make sites interactive with the power of Vue

Vuepress is simple, provides a standard experience, (kind of) easy to configure and easy to get started.

Getting Started on Vuepress

Create a project folder and install Vuepress.

mkdir awedocs
cd awedocs
yarn init
yarn add -D vuepress

And then.. be prepared to act surprised - because there is nothing really there. There is little to see fresh out of the box. We need a few more steps to get there.

Open the awedocs folder in your VSCode. Create a sub directory called docs in the root folder. Then, create a file named README.md in docs folder. Enter following content in the file..

Hello world

md or markdown files will contain the content of your site. This file should be good for initial tests.

Open package.json and enter scripts to run Vuepress. Your entire file may look like below -

{
  "name": "awedocs",
  "version": "0.0.1",
  "description": "Awesome docs.",
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  },
  "main": "index.js",
  "repository": "https://github.com/techformist/awedocs",
  "author": "Prashanth Krishnamurthy",
  "license": "MIT",
  "devDependencies": {
    "vuepress": "^1.2"
  },
  "dependencies": {}
}

Go back to command prompt, and issue the command ..

yarn dev

.. and ta da - you have your Vuepress site up and running.

You can make a few smart observations -

1. Vuepress is minimal (at least in the beginning)
2. Vuepress comes with a default theme
3. Content and presentation layer is well isolated with the presentation layer

This means that -

1. you can get started really really quickly. Install Vuepress -> start creating documents / blog posts
2. you don’t need to learn Vue/Vuepress to use Vuepress to create a documentation site or blog

Making Vuepress your own

The site generated so far is functional but too minimal. Let’s add some jazz.

Update README.md with following content -

---
home: true
heroImage: /images/dog.jpg
heroText: Awedocs
tagline: docs. docs. docs.
actionText: Get Started →
actionLink: /more
features:
  - title: Good
    details: Know everything.
  - title: Better
    details: Know something.
  - title: Best
    details: Know nothing.

footer: MIT Licensed
---

# Hello world!

The content between --- is called frontmatter. This tells Vuepress to mete out some special treatment to the file.

Now do two things to support above content -

1. Add a file called more.md alongside README.md.

   # Morrreee
   
   This is much more information than I can handle.
   

2. Create a new folder /docs/.vuepress/images. Save a sample image and name it dog.jpg.

Stop Vuepress dev server. Start it again.

yarn dev

You have something that resembles a typical website.

The /docs/.vuepress folder will have any and all customisations for your Vuepress instance. This includes -

• Vue Components
• Navigation bars
• Additional Javascript
• Styles

Content stays in the /docs folder.

Add more UI elements

Lets add a sidebar and navbar.

Create a file called /docs/.vuepress/config.js, which will house all the configuration for Vuepress. Introduce following content in the file -

module.exports = {
  base: "/",

  title: "awedocs",
  description: "Awesome docs",

  themeConfig: {
    label: "English",
    editLinkText: "Edit this page on GitHub",
    lastUpdated: "Last Updated",
    nav: require("./nav"),
    sidebar: [
      { title: "Home", children: [""] },
      {
        title: "Misc",
        children: ["more"],
      },
    ],
    repo: "techformist/awedocs",
    editLinks: true,
  },

  plugins: {
    "@vuepress/back-to-top": {},
  },
};

Create a file called .vuepress/nav.js.

module.exports = [
  {
    text: "Let Me Google",
    link: "https://google.com",
  },
  {
    text: "About",
    items: [
      { text: "About", link: "/about" },
      { text: "Terms", link: "/terms" },
    ],
  },
];

Restart Vuepress to see this -

Build and Deploy

Once you are ready, you do a simple -

yarn build

This will create a docs/.vuepress/dist folder. Upload this folder to your host and you are done!

What could I do next?

Well, sky’s the limit. Vuepress is based off Vue and Javascript - so you can do nothing short of magic.

There are a few things that can be highlighted here -

1. Add simple Vue components and interactivity

We can include interactive components in markdown.

Create a Vue component called AddNum.vue in docs/.vuepress/components/.

<template>
  <div>
    <div>
      <label for="a">Num 1</label>
      <input id="a" v-model="a" type="number" />
    </div>
    <div>
      <label for="b">Num 2</label>
      <input id="a" type="number" v-model="b" align="right" />
    </div>

    <div style="font-weight:bold; margin-top:15px">
      <div>
        <label for="sum">Sum =</label>
        <input id="sum" type="number" :value="sum" align="right" />
      </div>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        a: 0,
        b: 0,
      };
    },
    computed: {
      sum() {
        return +this.a + +this.b;
      },
    },
  };
</script>

<style lang="css">
  input {
    text-align: center;
  }
</style>

Include this component in more.md.

# Morrreee

This is much more information than I can handle.

But, I could do a sum for you.

<AddNum/>

See the magic of adding numbers on the fly.

Create even more complex components

Let us have a Vue gallery for our glorious site.

In the root folder do an install.

yarn add vue-gallery

Create /docs/.vuepress/Galleria.vue.

<template>
  <!-- code from https://www.npmjs.com/package/vue-gallery -->
  <div class="padme">
    <gallery :images="images" :index="index" @close="index = null"></gallery>
    <div
      class="image"
      v-for="(image, imageIndex) in images"
      :key="imageIndex"
      @click="index = imageIndex"
      :style="{
        backgroundImage: 'url(' + image + ')',
        width: '300px',
        height: '200px'
      }"
    ></div>
  </div>
</template>

<script>
  import VueGallery from "vue-gallery";

  export default {
    data: function () {
      return {
        images: [
          "https://dummyimage.com/800/ffffff/000000",
          "https://dummyimage.com/1600/ffffff/000000",
          "https://dummyimage.com/1280/000000/ffffff",
          "https://dummyimage.com/400/000000/ffffff",
        ],
        index: null,
      };
    },

    components: {
      gallery: VueGallery,
    },
  };
</script>

<style scoped>
  .image {
    float: clear;
    background-size: cover;
    background-repeat: no-repeat;
    background-position: center center;
    border: 1px solid #ebebeb;
    margin: 5px;
  }

  .padme {
    padding-top: 2.5em;
    padding-bottom: 2.5em;
  }
</style>

Include this component in our more.md.

# Morrreee

This is much more information than I can handle.

## Sum

But, I could do a sum for you.

<AddNum/>

## Gallery

Or, I could show a gallery. Click on the image to view full screen.

<Galleria/>

You have a fully functioning gallery!

Note that we did not add this component anywhere other than creating a vue file, nor did we use the component.

3. Use a Vue plugin

Since Vuepress has Vue behind the scenes, we could hop on to the same magic train for our own nefarious schemes.

Do yet another install.

yarn add vue-typed-js

Create a new Vue file - /docs/.vuepress/components/.

<template>
  <div>
    <vue-typed-js
      :strings="[
        'once',
        'twice',
        'thrice',
        'four times',
        'five times',
        'infinity'
      ]"
      :loop="true"
    >
      <h4 style="color:red">Going.. <span class="typing"></span></h4>
    </vue-typed-js>
  </div>
</template>

Again, add this new component to our more.md.

# Morrreee

This is much more information than I can handle.

## Sum

But, I could do a sum for you.

<AddNum/>

## Gallery

Or, I could show a gallery. Click on the image to view full screen.

<Galleria/>

## Typing Ahoy

I could even show this cool type simulator.

<TypeAhoy/>

You now have some typing magic :)

Custom themes and plugins

So far you have seen themes provided by default in Vuepress. You can extend the theme or use a theme developed by third parties.

Similarly, you can develop custom functionality using plugins. Vuepress provides a number of core-team and community maintained plugins that do everything from enabling a blog on your site to creating a sitemap, creating diagrams using MermaidJS, or displaying your content as a presentation.

See themes and plugins listed on Vuepress.tools.

That was easy. Time to go crazy?

Well, it depends. Vuepress has its positives and not-so-positives.

For starters -

1. Vuepress is easy to get started with. It’s out-of-box theme is great and anyone can get started in no time
2. Provides a great user experience (similar to a single page app)
3. It is easy to understand for non-techies. Provides a good isolation b/w content creation and presentation layers
4. Has the full power of Vue behind it - you can provide super interactivity using Vue components and plugins
5. Theming is quite strong
6. It has some good plugins. You can also roll out your own plugin quite easily

On the other hand..

1. Is not as flexible as more developer-friendly solutions like Gridsome. Yes, this is opinionated and YMMV
2. I struggled a bit to implement adhoc taxonomies
3. With dependency on Webpack, it does not lend itself well for lot of content
4. It has a big initial payload, which is increasingly viewed as something that we live with (but wanted to mention it anyway)

Starting a documentation site and using a couple of plugins was easy enough, but my experience customising Vuepress was not that great (again, this is a ‘me’ experience). I found Gridsome or Saber.land easier to understand and customise to my heart’s content.

That said, I will probably use Vuetify for all the documentation sites going forward since it is quite simple and fast to get started with.

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 -

1. Create a summary page on the site
2. Include counts in the manually maintained writing/editorial calendar (and bring some automation to that side of the world while at it)
3. 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 -

1. Quickly check the categories / tags and select relevant combination for a new post
2. Keep an eye on the counts and refocus on things that I have to write more about
3. 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;">Description</td>
        <td style="text-align:center;font-weight: bold;">Value</td>
      </tr>
    </thead>
    <tbody>
      <tr><td>Pages</td><td>{{ $pageCount }}</td></tr>
      <tr><td>Posts</td><td>{{ $postCount }}</td></tr>
      <tr><td>Post by Categories</td>
        <td>
          {{ range $name, $taxonomy := .Site.Taxonomies.categories }}
            <a href="/categories/{{ $name | urlize }}">{{ $name | humanize }} ({{ $taxonomy.Count }})</a>
            &nbsp;
          {{end}}
        </td>
      </tr>
      <tr><td>Post by Tags</td>
        <td>
          {{ range $name, $taxonomy := .Site.Taxonomies.tags }}
            <a href="/tags/{{ $name | urlize }}">#{{ $name | humanize }} ({{ $taxonomy.Count }})</a>
            &nbsp;
          {{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 <your site>/summary.

Have fun.

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) -

<!-- layouts\_default\rss.xml -->
{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\" ?>" | safeHTML }}
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>{{ if eq  .Title  .Site.Title }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}{{ end }}</title>
    <link>{{ .Permalink }}</link>
    <description>Recent content {{ if ne  .Title  .Site.Title }}{{ with .Title }}in {{.}} {{ end }}{{ end }}on {{ .Site.Title }}</description>
    <generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }}
    <language>{{.}}</language>{{end}}{{ with .Site.Author.email }}
    <managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }}
    <webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
    <copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }}
    <lastBuildDate>{{ .Date.Format "2006-01-02" | safeHTML }}</lastBuildDate>{{ end }}
    {{ with .OutputFormats.Get "RSS" }}
        {{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
    {{ end }}



    {{- range first 10 (where .Site.RegularPages "Type" "not in" "pages" ) -}}
    <item>
      <title>{{ .Title }}</title>
      <link>{{ .Permalink }}</link>
      <pubDate>{{ .Date.Format "2006-01-02" | safeHTML }}</pubDate>
      {{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
      <guid>{{ .Permalink }}</guid>
      <description>{{ .Content | html }}</description>
    </item>
    {{ end }}
  </channel>
</rss>

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

.. except for two crucial differences -

1. Include full content in RSS feed

   <description>{{ .Content | html }}</description>
   

2. 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" ) -}}
   

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 <root>/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 SW in footer

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;
                                }
                            );
                    }
                )
        );

    }
);

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 -

1. I had been trying to make my workflow even more seamless
2. 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.

1. Go to your Hugo site root directory
2. 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)
3. Install husky, lint-staged, and prettier packages -

     npm install husky lint-staged prettier
   

4. 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.

So, what will happen when Vue is combined with static sites?

Awesome Gridsome - that’s what.

Gridsome describes itself as a Vue-powered site generator. Use Vue to design your site on top of Gridsome framework, and write your content in markdown, and generate complete HTML pages for your content that is complete in all respects.

The awesomeness includes -

• Use the ever-developing theme framework of Gridsome to quickly incorporate design elements
• Connect to other data sources like Wordpress, Contentful or any other headless CMS. The content is pulled in at the time of site generation (and you could use GraphQL!)
• Your sites appear to be faster - navigation is similar to a SPA
• Once generated, host your sites anywhere - they are just static files. You can leverage the speed of GitHub pages, or use GitLab, host on Netlify for free, or just use a CDN. Anything’s possible.
• Your sites will also work offline - thanks to the built-in PWA features

I spent some quality time evaluating Gridsome for this very blog, but postponed the decision due to ’logistical’ reasons (and because I am a bit lazy). Typically though, you can use Netlify to host your sites, have your content on GitHub, and forget about everything else. Netlify will build your sites and host for free.

Alternatives

Static sites in Javascript

There is no beating the fact that Gatsby is the most popular static site generator in the Javascript world - by a huge margin. The starter sites/themes, community help and plugins are really good.

However, when it comes to Vue, the options come down to Gridsome and Vuepress. Vuepress can be used for general purpose websites and blogs, but that is not its official purpose. Vuepress serves documentation really well. Being the official product, Vuepress may receive more love for generic sites, but that is far away in the future.

Nuxt and Next can do many more things than just generate static sites, but those are a couple of powerful options if you want to use them anyway. Sapper (Svelte ++ ) is also in this territory.

While I do acknowledge 11ty, Hexo et. al. - the more modern frameworks like Gridsome are a class apart IMO.

Other SSGs

Hugo is my favourite SSG at this time - it is dead simple, Go template language is fairly easy to understand, and has quite a few themes that you can get started with.

Jekyll is ancient but active. I would advise against Jekyll unless you are comfortable with Ruby. Don’t get me wrong - you can use Jekyll and its various themes (even customize them using the templating features), but sooner or later you would want to do something that is not possible within the templates themselves. The advantage with Jekyll is the ability to create Jekyll sites on GitHub and GitHub pages can compile pages without any additional build setup.

For a full list of other SSGs, go over to https://www.staticgen.com/.

• No one uses it
• It is prone to spam
• No one uses it (yes, this is repeated)

However, my personal opinions do not always align with client expectations. So it follows that I create these forms on a static site with resigned indignation.

Contact form is not quite a native feature of static sites. However, there are more than few solutions to this problem.

Use contact form from a third party site

Use the form provided by the email marketing provider, or use a service like Formspree. You just need to use some Javascript or use a simple URL to embed the form in the site.

For example, Formspree just requires you to include following content -

<form action="https://formspree.io/email@domain.tld" method="POST">
  <input type="text" name="name" />
  <input type="email" name="_replyto" />
  <input type="submit" value="Send" />
</form>

User-entered data is maintained and processed by the service provider. You as a developer do not have anything additional to do here.

On the flip side, the features provided by the form provider may not quite match client expectations. The low-tier plans or free plans may be a tad too limited for the client tastes (but without the option to bump up the tiers).

Link to a third party existing site from the client

Use an external site that is already owned by client organization in order to provide the contact form. This has the added advantage of centralizing contact information from multiple sources, and forcing the same tried-and-tested procedure to process contact requests.

Or, build (/ consume) a small API in existing enterprise applications (like Zoho) to feed in the contact information.

These third party sites, however, are not always an option that is readily available (or within budget).

Use Netlify Forms if you are hosted on Netlify

The simplest solution of them all is to use Netlify forms. All you need to do is include the netlify tag in the forms.

<form name="contact" method="POST" data-netlify="true">
  <p>
    <label>Your Email: <input type="email" name="email" /></label>
  </p>
</form>

Any user entered data will be redirected to Netlify and the data is available to internal users through the Netlify admin function. You also have the option to send this data to external systems without fuss if you are on a non-free tier.

But.. contact forms?

I often see potential customers calling up the customer-facing team rather than use contact forms in the case of smaller industries in my clientele. However, I need to do a better test one of these days rather than relying on my intellect that is far too superior for my own good.

Where we stand today?

Wordpress really brought web sites to the masses. Instead of writing obscure code using HTML / Javascript, using Blogspot, or using third party site builders, Wordpress and its ecosystem allowed all humans with basic computer skills to whip up a site within no time.

Wordpress is a content management system (“CMS”), and a good CMS at that.

Wordpress has improved over time, and it can do much much more than what it could do even 2 years back. But it is still old school.

The other CMS’s like Drupal or Joomla did not make it to the public consciousness. They solved problems for a different type of audience - and their efficacy at doing that in a rapidly changing world is called into question.

Meanwhile, there are site builders like Squarespace, Wix et. al. that started as “website builders”, but have been attaching CMS to their names. Nothing wrong, technically. They help users to manage content, may not be at the same level as their revered ancestors - and that’s ok.

There’s a new breed of headless CMS’es. These just refer to software systems that may or may not have UI of their own. But they do provide an efficient way to manage content. You can consume and present that content using your favourite frontend tool.

And, then - there are static sites. Sites that cut off the middleman in preparing content for the audience, instead (almost) everything is pre-compiled and ready-to-serve. But at the same time, do not take on the responsibility of role-based access or dynamic content.

Where’s the problem?

So, if everyone and everything has its place in the universe, how is anything a problem with this land?

The situation in CMS today is diverse -

1. Proprietary tech that can lock you down - this applies not only to Wix but also to digital publishing platforms like Medium
2. Surprising range of functions. Any application with a semblance of a role and a way of presenting data to an audience calls itself a CMS
3. Old school tech that relies on slow DB operations and unwarranted complexities, hybrid approaches with no standards and newer way of doing things that most likely do not stand the test of time

I feel individuals and even organizations do not carefully evaluate the path they want to take here. The main issue is not the CMS itself, but the definition of CMS.

CMS’s traditionally include -

• A way to create and manage digital content incl. text, images and videos
• A collaboration system where multiple people can come together to create artefacts

Today, you can create sites at a click of a button and have advanced functionality enabled in a couple of more clicks. These sites may manage plenty of content without even calling itself a CMS accomplish many many more things that a traditional CMS may not do.

Many of the modern CMS’s may also mix content and presentation at any time before the actual presentation. Think static sites. CMS may also not have a presentation layer at all!

• StrapiJS (a headless CMS) is a back-end application for any and all data. It happens to have a good ACL too
• Static sites and hybrid sites pre-cook content + presentation

I believe that CMS is dead, and the new breed should be called something else.

CoMaS, may be - that is easier to pronounce. Or just may be calling them for what they are - site builders, back-end applications (BaaS / BPaaS, anyone?), static sites and the like.

Although this very much looks like some two people’s effort to rebrand ‘customer relationship management’ into ‘customer experience’ - this is equally challenging times for all technologies that want to get contained in a box.

Where are we headed?

A fairly quick conclusion to the pointless rant - the future is ‘hybrid’. Combine static site generation with the power of dynamic content to produce hybrid solutions that handle anything thrown at them.

1. Use static site generation technologies for static content. Prep content so that presentation can be faster
2. Use APIs to provide options to use any front-end tools
3. Fall back on DBs (relational or otherwise) to enable dynamic behaviour - may it be role-based access, collaboration tools or for digital publishing

I would love to believe Wordpress will evolve to do all this and much more. Many plugins already provide a quick way to setup static content, and all it needs is to be a couple of notches higher.

But, I am betting big on an altogether new player to take the lead on this one. The question is whether any of the existing players take that role to create an open platform by foregoing the short-term monetization option.

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.

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>Phone</th>
          <th>Active</th>
        </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

OR

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 <th> defines two columns while <td> 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.

• download Ruby
• download Jekyll
• play around with platform capabilities - focus on Liquid
• see how themes are created

However, I realised mid-way that select themes offer a good way for anyone to get started.

• Just copy themes to your own repository
• Edit content
• Go-live on github.io

This information is available to anyone who is remotely interested, but the conversation on such sites were not as prevalent as they should be.

So, I created a free book to introduce Jekyll platform to non-programmers and beginners. The book “Level-up your Websites using Jekyll” will take you through the process of creating a website quickly (and for free) by using themes.

Go through the book on GitHub.

Upvote on ProductHunt if you find it interesting enough!