A Newbies Guide to the Galaxy - Part 2

SERIES January 28, 2023 18:48 by Jesper Nielsen • 18 minutes to read

Updated: April 11, 2023

Building my blog

This is not a guide, it is merely a collection of blog-ramblings, a collection of things I found to be useful while building this website from the ground up, a to-do list, and a list of things I want to accomplish in my quest building this blog and over time become a blogger.

I have not been posting many posts since I initially created the first version of this blog. I have kept this blog unannounced, and it has been living a kind of secret life. In many ways, this blog is defining who I am and what I do daily, I love the technical part of all this. I always been more of techie than a writer and found I was spending a lot of time building, tuning, and customizing various sites, and the whole thing kind of stranded halfway through, becoming too complicated as ambitions was outrunning skills - it was time for a change.

I have always been a serious person, with a well proven procrastination issue and often too preoccupied with other things and I had a halfhearted go to get a blog going in the past. I have been talking about ‘my blog’ for years, I had several domain names, several ideas and pretty much all of them never got airborne - This time, I changed my approach and put a focused effort and time into starting this blog, started planning and blocking time for the task, and at the same time fulfill some goals on my bucket list.

I wanted to put effort and time into having a blog, and at the same time fulfill multiple goals on my bucket list.

I started out with a WordPress platform, hosted in Azure, and I leaned a ton, however I also realized WordPress didn’t “turn me on” and there were several things that did not match my ambitions and way of work. Particularly, the sheer scale of security issues, a myriad of third-party add-ons and the whole ecosystem around WordPress seems to me like one big mess. And then, there is the multitude of things WordPress sites do, things I simply didn’t need - all I wanted was a blog, not add-ons nightmare and web-shop forms and things that were secondary to the simple objective of just creating a blog - not to mention the cost for hosting a WordPress site in Azure, didn’t fit well with my goals.

I wanted to simplify the whole thing, I wanted to be able to tweak the visuals, create my own theme, be able to edit and add posts offline, and still wanted to run the site in Azure for as low a cost as possible - I realized I wanted to ‘go static.

There are many static site generators available to choose from, all of which serve their purpose well.

Advantages of going static:

  • Work on the content while being offline.
  • Have the content in version control.
  • Compose elements in a highly flexible layout and structuring.
  • Enable hand-crafted pages and multiple output formats.
  • Decrease lead time for changes to an absolute minimum.
  • Greatly reduce complexity of operations.

Challenges when going static:

  • No dynamic content: Personalization of content, e.g., adjusting content with a recommendation engine, requires using external services (including authentication).
  • No user interaction: Integrating comments, Feedback forms, etc. again must be handled client-side by integrating 3rd-party services.
  • No administration UI: If you prefer graphical user interfaces when doing things like media ‘uploads’, editing and previews, static websites might not be you.

I meet Hugo

Hugo  is a general-purpose website framework. Technically speaking, Hugo is a static site generator  . Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website’s end users and an ideal writing experience for website authors.

Hugo is for people like me, preferring to write in a text editor over a browser, is for you who want to hand code our own website without worrying about setting up complicated runtimes, dependencies, and databases.

Hugo is, what I unknowingly have been looking for. What you are looking at here, is the all-new site, with an all-home-grown design on a new platform. I have kept the content, however I rewritten some of the old posts too, and over the past few months I have literally rebuilt everything from the ground up. Over that time, I have had to learn quite a few new tricks, some of which was completely new, and others needed de-rusting, and everything you are seeing here has been put together with love, and passion for playing, building, and leaning.

Feedback

I would love to hear your feedback, particularly anything constructive around things I can refine, clarify, fix or otherwise make better, it has been a huge effort, and whilst I am very happy with the result, you are the reader who have to look at it so your opinions is valuable to me - unfortunately adding a comment system to a static website is in my backlog, but please feel free to reach out on Twitter or push me an e-mail, see the contact page for further information.

The plan

For me, it was extremely important to define the purpose of building this website, and a while a plan was brewing, I started to put purpose on paper. Previously I did not spend much time thinking about the purpose, or the reason if you like, or formulating the purpose of having a blog, by doing so the puzzle somehow started to show and the goals became more measurable. Having a purpose gives me opportunity to adjust as I learn new skills, as new ideas develop. At the same time, it gives me the opportunity to come back and adjust and remind me self about my goals.

Why

  1. Ensure I stay curious and keep learning new skills.
  2. Use for references as I must spare my keystrokes  and time.
  3. Make people aware of me, and my ideas and skills, and hopefully expose me to future speaking opportunities.

What

  1. Build and learn to run a blog in Microsoft Azure and go as far for as little cost as possible.
  2. Learn to run and optimize a website using Cloudflare  free-tier services.
  3. Create and build my own content, themes and visuals based on proven technologies.

How

  1. By adding content regularly.
  2. Sharing knowledge about the topics I care about and work with daily.
  3. Aim to have around 2,500 words per post - if post require more than 2,500 words, I will consider writing multiple posts - or series.

Getting started

Part of my plan was to ensure basic knowledge to get started, baselining my ambitions with skills, and ensure I stay focused. I started out doing hours of research, after all basis knowledge should be expected.

And then, after days of internet searches, quite a bit of trial and error and more research I found some really good resource - for a start I can recommend these:

Get going

While preliminary configuration of a Hugo site using Azure Static Websites is fairly simple, I quickly found myself searching all over the internet for configurations options, and I didn’t have any previously Go-lang experience; I somehow needed a game plan.

If you, like me, want to Build your first static site with Azure Static Web Apps  from a code repository, there is a few prerequisites to be aware of:

  • You need a GitHub account.
  • You need an Azure subscription/account.
  • You need to install Git 
  • You need an editor, I prefer to use Visual Studio Code  .

Furthermore, I am exploring, the Front Matter CMS  extension for Visual Studio Code.

Hugo core configuration

Creating a Hugo site is simple, just follow the guide  , it will help you through the first steps to get you started:

  • Create a site.
  • Add content.
  • Configure the site.
  • Publish the site.

Now the fun begins, and to get you going, I highly recommending start digging the Hugo Documentation  , and if you need further inspiration, explorer the Hugo External Learning Resources  .

Managing content

Hugo Content Management  is rather powerful, and Hugo’s content types are a way to organize your content into sections. For example, you can have a blog section with posts of type blog, or a project section with pages of type project.

Table of Contents

Hugo can automatically parse Markdown content and create a Table of Contents  you can use in your templates.

The built-in TableOfContents variables outputs a <nav id="TableOfContents"> element with a child <ul>, whose child <li> elements begin with appropriate HTML headings.

The table of Content on this page, is created using the built-in TableOfContents element, showing Header 2 and Header 3 (default) only.

Related content

Hugo uses a set of factors to identify a page’s related content, based on Front Matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo’s default Related Content configuration  settings.

The table of Related Content in the side panel on this page, is created using the built-in related content functionality.

Since I started rebuilding this site using Hugo, I have been looking for a way to add a list of featured posts.

For bloggers and digital marketing and content writers, it is valuable to list related posts, featured content or content in a series. While I have configured Related Content functionality, I am still exploring a way to add Featured Posts functionality - Stay tuned for further updates!

Get to the next level

To push your Hugo web skills to the next level, you might want to deep dive into other topics:

  • How to migrate your existing website to Hugo.
  • How to customize your theme and layout with Hugo templates.
  • How to use Hugo’s features such as short codes, taxonomies, menus, and more.
  • How to deploy your Hugo website to various platforms such as GitHub Pages, Netlify, and more.

In my world Hugo is the right choice for a technical blog, I like the developer type approach using Visual Studio Code, Git and writing content using Markdown. Some people might just think I am off the rails, and it is pure stupidity to use Markdown for writing posts, and it’s perfectly understandable. However, Markdown, and the Git-centric workflow for publishing my posts to Azure Static Web sites, the source code and versioning by using Git for publishing a post, I think it is awesome, and is related to a lot of other things I work with on a regular basis.

The process for writing a new post is:

  • Write a post using Markdown.
  • Take some days to review the post in the preview environment, make some improvements and when I am happy change it from draft.
  • Commit my changes to GitHub.
  • The updated content is automatically posted to Azure using GitHub Action - which is automatically created when settings up an Azure Static Web App.

I wanted to push my skills to, and the list below is the list of topics I want to understand, features I want to add but don’t yet understand how to do so, and other things I have had to learn, and other blog ramblings and things, I as a newbie, have learned about the galaxy.

Topics, features, and other things

Front Matter

Front matter  is a list of information that describes the content, or the meta data of a post. The Front Matter would be information like the title of the post, the date that the post was created or edited, the author of the post etc.

For me, Front Matter seem to evolve and change as I learn and get deeper into Hugo content management, below is the current Front Matter for this page.

slug: ""
title: A newbies Guide to the galaxy, part 2
description: ""
summary: ""
image: img/hero.jpg
images:
  - img/hero.jpg
author: Jesper Nielsen
date: 2023-01-28T18:48:00+02:00
lastmod: ""
keywords:
  - blog
  - guide
  - hugo
categories:
  - Building my blog
  - What I use
  - Hugo
tags:
  - blog
  - hugo
  - ramblings
draft: false
series: []

Robots.txt

The Robots.txt  is a text file webmasters often creates to instruct web robots and search engine robots how to crawl pages on their website. The robots.txt file is part of the robot’s exclusion protocol (REP), a group of web standards that regulate how robots crawl the web, access and index content, and serve that content up to users.

Hugo can generate a customized robots.txt in the same way as any other template. Maintaining Robots.txt is almost automatically in Hugo, if you want to know more, read about Hugo Robots.txt  file by clicking the link.

This is the robots.txt in use on my site - placed in /layouts/robots.txt folder structure.

# {{ .Site.Title }}
# {{ now | time.Format (.Site.Params.format.dateformat | default "January 2, 2006") }}

User-agent: *
{{ if hugo.IsProduction -}}
Allow: /

Sitemap: {{ "/sitemap.xml" | absURL }}
{{ else -}}
Disallow: /
{{ end -}}

Security.txt

The Security.txt  files have been implemented by Google, Facebook, GitHub, the UK government, and many other organizations. In addition, the UK’s Ministry of Justice, the Cybersecurity, and Infrastructure Security Agency (US), the French government, the Italian government, the Dutch government, and the Australian Cyber Security Centre endorse the use of security.txt files.

Security.txt is as described a text file named security.txt, usually under the .well-known directory of your website. I have not found a way for Hugo to maintain the Security.txt file, and I will revisit this at a later time - You can check out my Secuity.txt file by clicking the link.

Humans TXT

The humans.txt  is an initiative for knowing the people behind a website. It’s a text file that contains information about the people who have contributed to building the website, and I think it is an awesome idea and want to support the initiative.

I haven’t found a way for Hugo to maintain the humans.txt file, and I will revisit this at a later time - You can check out my humans.txt file by clicking the link.

Hugo theme

Over the time I have been doing the blog ramblings, I have spent way too much time, money and resources looking for the perfect theme. I had a clear idea what I wanted, and especially what I did not want, especially free themes offering upgrading to pro versions would cause me to drop a theme, and the effort to make the theme look just close to the samples, I often found near impossible.

I decided to set out on a journey, building my own Hugo Theme. I was inspired by the WiX Toolset  webpage.

I wanted a sticky header, a hero images following the section, page and/or post. I wanted to build the theme using the newest Bootstrap  framework, adding as little custom stylesheets, as little js-scripts and other extras, with no interest or purpose to me, as possible. One component I wanted to implement, is Font Awesome  , as I like the extra visual and options it adds to a site.

The theme you are looking at now, is built bottom up, based on the Bootstrap 5.2  examples and I am really happy about the result. I leaned a ton building this theme, it has given me a deeper insight on the whole Hugo + Bootstrap sphere.

There is always more to learn, and while Bootstrap 5.3 is in the making, I am looking forward to the new possibilities, and options - even though, I am close to have learned everything yet.

  • Upgrade to Bootstrap 5.3.
  • Get to know Bootstrap even further.
  • Keep tuning and optimizing content and visuals.
  • Add dark/light theme using Bootstrap Color modes  .

Hugo 404 error page

I needed to add and to create a custom 404 page for my Hugo website, and there is plenty examples how to do so.

I wanted it to be a single page template for my 404-error page, without header, footer etc. After a bit of research and a lot of trial and errors, I have created a 404-error page based on the Bootstrap examples. If you want to see the final result try visit my 404.html page.

A static website with a dynamic search function seems impossible. However, Hugo provides an option to embeddable scripts from Google or other search engines for static websites.

Hugo allows you to provide a a custom search function by indexing your content files directly, and I will revisit this at a later time and explorer the options for adding a search function.

Hugo and comments

A static website with a dynamic comments function seems tricky. The good news is Hugo ships with an internal Disqus template  , but this is not the only commenting system that will work with a Hugo website, and I will revisit this later and explorer the options for adding comments functionality.

Google analytics

Google Analytics  is a web analytics service offered by Google that tracks and reports website traffic. It can help you measure your traffic as well as track your Flash, video, and social networking sites and applications. Despite I have chosen to use Cloudflare as DNS service, and some information might already be available to me, I have chosen to explorer Google Analytics as well - I might change this decision in the future :)

Hugo ships with an internal templates supporting Google Analytics  , and to get started using Google Analytics, you need to obtain a Google Analytics Property ID and configure your website accordingly.

Open Graph

Open Graph  is a protocol that allows web pages to become graph objects with rich metadata that can be used by social media platforms. It helps to control how web content looks when shared online.

Hugo ships with an internal template for the Open Graph  protocol, and Hugo’s Open Graph template is configured using a mix of configuration variables and front-matter on individual pages.

Twitter Cards

A Twitter card is a feature that allows you to display rich media content such as images, videos, or summaries when you tweet a link to a website. There are different types of Twitter Cards  depending on your purpose.

Hugo ships with an internal template for Twitter Cards  .

To use Twitter cards, some markup code to your webpage is required, and Hugo supports Twitter cards with an internal template  . In short You can configure Twitter cards by setting some variables in your site’s config file and your page’s front matter settings.

Optimizing and improving my website

Website optimization is a task close to me and where I find a lot of pride to make it right, and as I am building this website from scratch, following and monitor the progress and follow recommendations seems obvious.

Optimizing and performance will help increase site traffic and visitor returns.

Unlike search engine optimization (SEO), optimizing the hidden gems of your website prioritizes visitors’ experience, and ultimately will help to improve the website speed, mobile friendliness, accessibility, and search engine ranking.

Make your web pages fast on all devices

PageSpeed Insights  (PSI) reports on the user experience of a page on both mobile and desktop devices, and provides suggestions on how a page may be improved.

Pingdom Website Speed Test  because nobody likes a slow website. The test is designed to help make your site faster by identifying what about a webpage is fast, slow, too big, and so on and is using more than 70 global polling locations to test and verify your website.

The Pingdom Website list improvements for page performance, and I currently have a performance grade of B (90) and a load time around 650 milliseconds.

I have been investigating the requirements and how to add “expires headers”, and so far I “resolved” this requirement, by adding "Cache-Control": "public, max-age=604800, immutable" to the staticwebapp.config.json configuration file – see below . I will keep scratching this to find the perfect max-age.

I am actively investigating the options for compressing components with gzip and exploring how to make fewer HTTP requests – stay tuned.

HTML Validator

The HTML Validator  checks the markup validity of Web documents in HTML, XHTML, SMIL, MathML, etc.

If you wish to validate specific content such as RSS/Atom feeds or CSS stylesheets, MobileOK content, or to find broken links, there are other validators and tools available.

The service was created by the W3C, which is an international community that develops open standards for the web. Visit the HTML Validator  website for further information.

CSS Validator

The CSS Validation Service  is a tool that can check the correctness (validity) of W3.CSS1, which is a modern CSS framework for faster and better responsive web pages.

The service was created by the W3C, which is an international community that develops open standards for the web. Visit the CSS Validation Service  website for further information.

Security Headers

Security headers is kind of mythical to me, however I am aiming to get a top score on Security headers  . The HTTP response headers that this site analyses provide huge levels of protection, and it is important that sites deploy them.

The service provides an easy mechanism to validate them, and further information on how to deploy missing headers.

Configure Azure Static Web Apps 

Configure HTTP security response headers for Azure Static Web Apps 

staticwebapp.config.json

{
    "globalHeaders": {
        "Cache-Control": "public, max-age=604800, immutable",
        "content-security-policy": "frame-ancestors 'self'; upgrade-insecure-requests",
        "Permissions-Policy": "autoplay=()",
        "Referrer-Policy": "no-referrer",
        "X-Content-Type-Options": "nosniff",
        "X-Frame-Options": "SAMEORIGIN",
        "X-Permitted-Cross-Domain-Policies": "none"
    },
    "responseOverrides": {
        "400": {
            "rewrite": "/400.html"
        },
        "401": {
            "statusCode": 302,
            "redirect": "/login.html"
        },
        "403": {
            "rewrite": "/403.html"
        },
        "404": {
            "rewrite": "/404.html"
        }
    }
}

Security Headers Result

Security Headers Result
Security Headers Result

Qualys SSL Labs

Qualys SSL Labs  is a non-commercial research initiative that offers free online tools and resources to test and improve the security of SSL web servers.

To get a top score on their SSL Server Test, I validate I have configured my site correctly and is following the Best Practices for SSL deployment.

Test your own site and go for a top score on the Qualys SSL Labs SSL Server Test  website.

Qualys SSL Labs Result

Qualys SSL Labs Result
Qualys SSL Labs Result

… and more is likely to surface as I ramble along.

–Jesper