5 Mins Hugo 04 - Getting Started

This is the 4th part of the "5 Mins Hugo" tutorial series I am doing on YouTube. 

JAMstack JoymonOnline.in using Hugo - Part 03 - Current and proposed architecture & CI/CD system

The third part of the Hugo tutorial is also a theory. Here I am explaining the current architecture of my site https://joymononline.in and how it will look like in the proposed JAMstack based site using Hugo. Below is the video.

The main points discussed are

• Current and proposed arch of JoymonOnline
• The problem with dynamic content in JAMstack.
• How to bring dynamic content into the site during compile-time and build the static site
• How to detect dynamic content changes and recompile the static site.
• How CI/CD work at the end using Zapier and GitHub Actions

The major shift in JAMstack is the technique of building a static website from changing contents and recompiling the site to include those future changes in the content.

[Video] Hugo date formatting bug - Oh it was a bad assumption

Mistakes are with humans. Most of those maybe because of ignorance, lack of experience, and there are many other reasons. But programmers make mistakes because of one more category called lack of reading documentation. They just try it and builds assumptions. When things are not getting working they think there is a bug. It could have occurred because of simple assumptions made without reading the documentation.

This is a story of such a mistake.

I got obsessed with Hugo especially with its templating. The templating is easy to learn and there are a lot of examples on the internet. If we take an example of date formatting, we can easily get help saying we can use "2006-Jan-2" as a format string to format the date. If we are from the traditional formatting world of  "YYYY-MMM-DD" we feel this format is innovative and assumes that the year 2006 is just a year. Hugo is intelligent enough to understand any year in the format string.

With that ASSUMPTION if we give "2020-Jan-2' things will not work and start thinking as an error in Hugo. I went one more step ahead and did a video on the workaround saying use 2006 only. Below it is embedded.

Later publishing the video and when I get a chance I read the Hugo code as well as documentation. That opened my eyes. The documentation about the same is below.

https://gohugo.io/functions/format/#gos-layout-string

The above works for 'Date' data type only. To format string use the function .dateFormat .The root goes to the Go programming language that has this specific date to format dates.

Moral of the story is never goes with assumptions especially before deciding something is not working as expected.

JAMstack JoymonOnline.in using Hugo - Part 01 Introduction

Introduction

Following the post about "Static Site Generator a.k.a JAMstack for JoymonOnline.in..", started portion the AngularJS based site to 3 different leading JAMstack technologies. First I planned Gatsby. But after going in-depth, it feels to me like a regular React web application than a template-based static site generator. So decided to port to the second technology in the list which is Hugo. 

After starting Hugo by overcoming the big learning curve, I became a fan of Hugo. Especially it is fast processing. That leads me to a series of tutorials on Hugo about my web personal site conversion. It will not be a Hugo tutorial that covers all the aspects of Hugo, instead, the aim is to help people overcome the learning curve and focus is on its web site building capabilities than blogging or documentation building capabilities.

Organization

Most of the tutorials about Hugo are an hour long. The minimum I found is 20 mins. Everywhere including this post is talking about the big learning curve of Hugo. The hour-long tutorials second that opinion and people may think its not something for them to work on. If the size of the tutorial is 5 min, it may be more approachable to the masses through the learning curve is not changing.

So I am experimenting with 5 Mins Hugo. It is not the hard rule, I am expecting 5-8 mins for each video. Without further due below is the first video tutorial in the series.

Part 01 - Introducing the series

Part 02 - This is introduction to Hugo features, pros and cons

Static Site Generator aka JAMstack for JoymonOnline.in personal portfolio web site

No. Not really it is going to be JAM Stack as per my view. JAM Stack has a Static Site Generator but when Static Site Generator alone is not JAM Stack application. In JAM Stack application there will be JavaScript running at the browser to interact with data provided by APIs.

JavaScript+APIs+Static Site Generator = JAM Stack Application

But it is not the view of the JAMStack.org. It defines JAM Stack as follows

Fast and secure sites and apps delivered by pre-rendering files and serving them directly from a CDN, removing the requirement to manage or run web servers.

They don't need to use APIs to be called JAMStack site. Below are the quotes from the web site.

Pre-rendered sites can be enhanced with JavaScript and the growing capabilities of browsers and services available via APIs.

You may have already seen or worked on a Jamstack site! They do not have to include all attributes of JavaScript, APIs, and Markup. They might be built using sites built by hand, or with Jekyll, Hugo, Nuxt, Next, Gatsby, or another static site generator...

The main point is the site is pre-rendered and kept as static files and deliver through CDN. That being said, my view is not important. The industry recognize any static site as JAM Stack application regardless they use client-side JavaScript initiated APIs to interact with data or external services.

Welcome to my experiments with JAM Stack.

One of my previous posts was about "Why I am still with Blogger than going behind static site generators" (hereafter SSGs). There I mentioned why the SSGs are not good for blogs from my perspective. Still in the same opinion but when I considered my personal web site https://joymononline.in I feel that can be a candidate for SSGs aka JAMStack.

The current state of JoymonOnline.in site

Though it started as ASP.Net application, said bye to server-side code execution in 2017 itself. Now it is an AngularJS application served from GitHub pages. Some APIs are invoked from browser-side JavaScript to get list of projects from GitHub and recent blog posts from Blogger.

Problems

Keeping updatable contents

The home page has a section called What's new. When I added this area, my idea was to make it live as possible as twitter. But it is difficult to update frequently. I tried storing the content in Evernote, and later tried to keep in GitHub itself and dealt with its API limits. Later I decided to keep it with the HTML itself thinking I will modify it and the CI/CD will push automatically when I get full code coverage. But still, it was difficult keeping it up to date.

Client-side API calls

As I mentioned above, we may hit with API limits as every consumer has to call the API from their browser. The GitHub API throttle by the client IP address if there is no API key. The people from a company often access the internet from a single outbound IP address. It gets throttled very quickly.

Sometimes they may not have access to certain API endpoints. For example, some companies may block access to Blogger and GitHub to make sure their employees are not publishing the company code and proprietary code/algorithms. Don't laugh it happened. They access my web site but not able to see some contents.

Testing efforts

When we code any application using any technology such an AngularJS in this case, we need to test our code. Though it is not a banking application, I will feel I need to test my personal web site before publishing. As everybody agrees, it is difficult and not practical to manually test. So started automated tests. Researched different frameworks for unit and integration tests. 

Things were good until the million-dollar question triggered in my mind. Am I getting 100% code coverage? The integration tests often fail due to timing, when I just rerun it works!! May be my poor scripting skills. Overall its trouble maintaining our own code.

Technology upgrade

There are many things such as upgrading technology. Now AngularJS is getting out of support and converting to Angular is like writing from scratch.

The JAM Stack JoymonOnline.in

I don't think all the problems will be solved if I use JAM Stack for https://joymononline.in. But its an experiment to see how it takes to convert an AngularJS application to JAM Stack. I never used SSGs extensively for any of my projects. Of course, the GitHub documentation uses SSG internally. The DotNet.Helpers library uses DocFx to generate its API reference and documentation. It is SSG. But still not aware of the capabilities of JAM Stack technologies. So it would be learning to me as well on JAM Stack

Plan

The plan is very simple to convert my site joymononline.in into 3 leading SSGs. Below are the SSGs I am planning

1. Gatsby
2. Hugo
3. Jekyll

Below are the things considered

• No look and feel changes.
• All existing pages and adding one more page to show my YouTube videos.
• If possible no API calls from the client-side. Everything to be generated at the server. Includes GitHub projects, recent blog posts, etc...

References

https://dzone.com/articles/static-site-generators-overview-gatsby-vs-hugo-vs