Blog-hugo

Blog refactored.

Quickstart

scoop install main/go
scoop install main/hugo-extended
hugo mod get
# hugo --minify --gc --logLevel info
hugo --gc --logLevel info

Migration notes

This blog is migrated from Jekyll with /article/:slug/ URL pattern (allow uppercase). The migrated slugs are defined explicitly in the front matter.

GitInfo

When hosting your site in a CI/CD environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may not be accurate—it may reflect the most recent repository commit, not the commit that last modified the file.

Change Build Settings

Compress media

All files in final release should < 25 MB to make Cloudflare Pages happy.

scoop install main/ffmpeg
# https://stackoverflow.com/a/26109838
ffmpeg -i input.flac -ab 320k -map_metadata 0 -id3v2_version 3 output.mp3
# Or to Opus
ffmpeg -i input.wav -c:a libopus -b:a 160k output.opus
# https://gist.github.com/lukehedger/277d136f68b028e22bed?permalink_comment_id=4436587#gistcomment-4436587

# Deprecated HEVC codec
# ffmpeg -i input.mp4 -c:v libx265 -preset ultrafast -crf 30 -c:a aac -b:a 250k output.mp4
# Firefox: media.wmf.hevc.enabled = 1 to play.

scoop install extras/handbrake
scoop install main/handbrake-cli
# Use preset:
# VP9_720P_OrigFPS_40CQ_Faster_Opus_160_WebM for modern videos.
# VP9_720P_24FPS_50CQ_Faster_Opus_160_WebM for ancient videos.
# VP9_720P_30FPS_45CQ_Faster_Opus_160_WebM as a medium choice.
handbrakecli --preset-import-file <preset>.json --preset <preset> -i input.mp4 -o output.webm
# Or use the GUI.

Choose a good codec

Read Web video codec guide by MDN.

The codec should be generally supported by all major modern browsers (VP9) and royalty-free.

MDN suggests "A WebM container using the VP9 codec for video and the Opus codec for audio".

Cloudflare Pages enforce file size

git fetch --unshallow && hugo --gc --logLevel info && find public -type f -size +25M -print -exec rm -vf {} \;
# The maximum file size for a single Cloudflare Pages site asset is 25 MiB.
# https://developers.cloudflare.com/pages/platform/limits/
# With metrics and more info:
git fetch --unshallow && hugo --gc --logLevel debug --templateMetrics --templateMetricsHints --enableGitInfo --printI18nWarnings --printPathWarnings --printUnusedTemplates && find public -type f -size +25M -print -exec rm -vf {} \; && find public -type f -printf '%P\n' > public/filelist.txt

Template Metrics

It turns out that --minify takes the longest time, especially for XML.

Actually, the long build time is caused by very long markdown content, very long XML feed and minify.

hugo --templateMetrics --templateMetricsHints

Icons

Tabler

CMS & OAuth

netlify-cms-cloudflare-pages

CDN

This blog used to use unpkg.com, but after an outage (on 2025-03-15 UTC+8) which affected the CDN for 17 hours+, it was migrated to fastly.jsdelivr.net.

The Chinese (PRC) government's Internet censorship system blocked jsDelivr's cdn.jsdelivr.net domain without explicit legal basis or notification in 2022. This system itself is not legally recognized, lacks transparency and accountability, and severely harms Internet openness and technological development.

Currently, fastly.jsdelivr.net is not blocked in Mainland China, which seems to be a good choice.

To easily switch to jsDelivr:

Replace unpkg.com to fastly.jsdelivr.net/npm

https://unpkg.com/react-dom@16.7.0/umd/react-dom.production.min.js
https://fastly.jsdelivr.net/npm/react-dom@16.7.0/umd/react-dom.production.min.js

Update on 2025-03-25: unpkg.com is back to normal with a new architecture which is believed to be more stable. I decide to give it another chance. unpkg.com has a much shorter load time than fastly.jsdelivr.net when the cache is hit.

---

Hugo Theme Stack Starter Template

This is a quick start template for Hugo theme Stack. It uses Hugo modules feature to load the theme.

It comes with a basic theme structure and configuration. GitHub action has been set up to deploy the theme to a public GitHub page automatically. Also, there's a cron job to update the theme automatically everyday.

Get started

1. Click Use this template, and create your repository as <username>.github.io on GitHub.

2. Once the repository is created, create a GitHub codespace associated with it.

3. And voila! You're ready to go. The codespace has been configured with the latest version of Hugo extended, just run hugo server in the terminal and see your new site in action.

4. Check config folder for the configuration files. You can edit them to suit your needs. Make sure to update the baseurl property in config/_default/config.toml to your site's URL.

5. Open Settings -> Pages. Change the build branch from master to gh-pages.

6. Once you're done editing the site, just commit it and push it. GitHub action will deploy the site automatically to GitHub page asociated with the repository.

---

In case you don't want to use GitHub codespace, you can also run this template in your local machine. You need to install Git, Go and Hugo extended locally.

Update theme manually

Run:

hugo mod get -u github.com/CaiJimmy/hugo-theme-stack/v3
hugo mod tidy

This starter template has been configured with v3 version of theme. Due to the limitation of Go module, once the v4 or up version of theme is released, you need to update the theme manually. (Modifying config/module.toml file)

Deploy to another static page hostings

If you want to build this site using another static page hosting, you need to make sure they have Go installed in the machine.

Vercel

You need to overwrite build command to install manually Go:

amazon-linux-extras install golang1.11 && hugo --gc --minify

If you are using Node.js 20, you need to overwrite the install command to install manually Go:

dnf install -y golang

Make sure also to specify Hugo version in the environment variable HUGO_VERSION (Use the latest version of Hugo extended):