Creating a Blog Like CrystalLabs.io

Introduction

This article explains how to set up a blog using Hugo and the same theme, format, and features as seen on https://crystallabs.io/.

The article is also used as the theme’s Git repository README.md, in which the shortcodes will display as text when viewed through Git. That minimal visual artifact is fine.

Quick Start

As a pre-requisite, download hugo_extended from Hugo releases page. You might have to click “Show all X assets” to see hugo_extended in the list.

You can then clone the whole template website with a working default configuration and have the site running in no time:

git clone https://github.com/crystallabs/hugo-template-minima-crystallabs mysite
cd mysite

# For generating static pages, to be served by a web server:
# (Hugo server still runs permanently, to watch for changes to files)
./run.sh

# Or to run the standard Hugo server, as usual:
hugo serve

If you already have a Hugo website and only want the theme (not the whole template website), copy or make a symlink to themes/minima-crystallabs/ in this repository.

Static Site Generator

Static site generator of choice is Hugo.

It is not the best static site generator, but it is cleaner than the venerable WML and much more reasonable than Gatsby.

Hugo has the ability to serve pages directly from its built-in web server, or you can generate static pages and serve them with an external web server. Both options are shown.

Theme

After seeing Will (decuser) Senn's Blog, I found a blog theme more promising than various themes I found in the previous couple years.

That site is implemented in Jekyll, but searching for the theme named “minima” I was able to find a similar template for Hugo.

I did many changes and improvements to it.

Theme Improvements

The improvements to the “minima” theme done so far are:

• Blog homepage shows all articles, sorted in order of last modification time, most recent first

• Maximum page width was increased from 640px to 1600px

• Default font size has been increased from 16px to 18px

• Page titles (H1 tags in HTML or # tags in markdown) are centered

• Heading sizes have been adjusted for a more natural progression from large/bold to smaller/normal

• Color scheme for links has been set to a very simple one like the old Netscape default (blue for unvisited links, red for visited links)

• Similarly, links become underlined when they are hovered over with the mouse

• Links which point to external resources have the “external” icon, like on Wikipedia

• Links-related shortcodes r, R, l, and L, which mean “L” for external links and R for local references, have been added

• All links inserted in an article with shortcodes L and R get automatically listed automatically once again at the end of the page

• Simple styling for tables in HTML was added

• Page “banner” feature was added. If a page has banner: image.png in frontmatter, image.png will display as a banner below the title, in the size/ratio like on YouTube

• Inappropriate titles such as “Oops!” have been replaced with valid, formal titles like “Not Found”

• Last modification time shows on each page

• An article can belong to a series

• An article can have various tags (categories) assigned

• Series and tags have long descriptions, in addition to short names

• The /series and /tags pages have been improved

• tags and series shortcodes display a list of all tags or series

• Possibly multiple series to which an article belongs are properly listed at the end of the article

• When building the site, Hugo prints a warning for all series and tags that are not pre-configured and have a page in content/series|tags/*/_index.md

• Default robots.txt advises GPTBot not to index the pages (although the setting may be ignored GPTBot)

• Promotion for Hugo was removed

Theme To-Do

• Devise a better way for code blocks to show difference between lines of input and output. (The current model where lines to highlight are manually specified with e.g. sh {hl_lines="1-2"} is impractical)

• Improve link colors when using dark theme

• Improve content of /tags and /series pages, to include descriptions like tags and series shortcodes do

• Visually better integration of the banner feature?

Theme Customization

You can create the layouts/ directory at the same level with hugo.yaml and put your customizations there.

Serving the Website

To generate a completely static site in the directory public/, which can then be served by any web server, run:

./run.sh

(Note that hugo will remain running in foreground, to watch for changes in files and rebuild them automatically.)

Or you can run the usual Hugo server as it comes by default:

hugo serve

Nginx config

To serve the completely static website via Nginx, you could use a basic config such as:

server {
	listen 1313 default_server;
	listen [::]:1313 default_server;

	server_name _;

	root /var/www/html;

	index index.html index.htm index.nginx-debian.html;

	location / {
		try_files $uri $uri/index.html =404;
	}

	location ~ /\.ht {
		deny all;
	}
}

(The example does not show SSL setup because it is behind a proxy.)