Creating a Blog with Hugo: Background

Introduction

I have been writing this blog since June 2020 using a static site generator called Hugo. It has been five years and I have only posted about 20 articles — something I am not proud of.

Better late than never, I am writing down the background and current setup of yamk blog.

Having used several web diary (blog) applications — tDiary, Movable Type, and WordPress — the biggest pain point was always the same: application servers that depend on languages like Ruby or PHP are extremely difficult to recover when a public server breaks down. The deep dependency chains between OS distributions, bundled libraries, web server versions, and language versions made every component update and long-term maintenance a struggle.

My blog “yamk Diary,” which I had been writing for years on tDiary, and its later WordPress successor, were both completely lost when my home server failed — with no way to recover them.

Yes, an engineer should take backups. Fair point. But backup infrastructure takes more time and money than most people expect, and the backup destination itself can fail just as easily. It is genuinely difficult to set all that up as a hobby project.

At some point I came across an article about a category of CMS (Content Management System) called “static site generators,” and immediately realized that this approach could solve most of my problems.

What Is a Static File Generator?

Features and Advantages

• Articles are written as text files.
  • The Markdown (.md) format, widely used in technical documentation, is the most common choice.
  • Markdown has dialects, but the basic syntax is nearly identical across them, keeping migration costs low when switching systems.
• A full build is performed from the tree of text files, generating a static website consisting of HTML/CSS/JS files.
  • With no server-side application, the blog site can be extremely lightweight.
  • With no application, there are no vulnerabilities beyond the web server itself (Apache, nginx, etc.).
• The source content before building can be treated as source code, making it a natural fit for version control systems like git.
• No database — just a source code tree, making it compatible with file sync services like Dropbox and trivially easy to back up.
  • Even if the public server breaks, recovery is straightforward as long as the files are in Dropbox or a git repository.

Weaknesses

Being “static” introduces the following limitations, which must be supplemented with external tools as needed:

• No search
  • With no blog application, there is no built-in search function.
• No comments, replies, or reactions
  • Comment systems are breeding grounds for spam and vulnerability attacks. WordPress in particular was quite exhausting — more mental energy went into fighting spam comments than actually writing posts.
    • Serious spam protection is usually a paid service.
  • It is possible to add comment functionality via third-party services, but free plans often have integration limitations or require commenters to register for the service. I decided to accept this and treat the blog as a personal notes repository.
• No GUI
  • Writing in plain text means you cannot see formatted output in real time.
    • Some text editor extensions and system-level features can partially compensate for this.
  • Embedding inline images is cumbersome.
    • You need to place the image file (.jpg/.png/.webp) and specify the file path and placement in text. It is nowhere near as effortless as drag-and-drop in a web GUI.
• Limitations of the Markdown format itself
  • Tables are not part of standard Markdown.
    • Multiple dialects exist, but there seems to be no widely agreed-upon, readable way to express complex structures like tables in plain text.
    • Tables are handled differently by each static site generator, which can become a hurdle during migration.

Comparing and Choosing a Static File Generator

Before switching this blog, I evaluated the most popular static file generator options.

Even though the final output is a “static site,” a build tool is still required to generate the site from source files. I weighted ease of build environment setup heavily.

Being web-oriented tools, JavaScript-based options dominate, and Gatsby and NEXT.js reportedly hold the top market share.

I initially considered them, but I lacked the basic JavaScript/TypeScript knowledge, and Node.js has a poor reputation for frequent major version updates (breaking backward compatibility within just a few years) and vulnerability management — so I ruled them out.

Jekyll, written in Ruby, seemed likely to cause the same headaches as tDiary — being at the mercy of Ruby’s language churn. I have had multiple experiences where updating Python or Ruby for security patches broke add-on modules, so these languages left a bad impression.

Hugo’s defining characteristic is that a single compiled hugo.exe file is all you need. Go is used only as the compiler, and pre-compiled binaries for Windows, macOS, and Linux are distributed. When using Hugo, you never need to think about Go at all.

There are zero dependent libraries or files. Upgrading is as simple as replacing hugo.exe — the ultimate in portability.

A Closer Look at Hugo

Hugo clicked for me personally, so I looked into its features more deeply.

• No dependency on scripting languages
  • No need to worry about scripting language versions or environments
• Open source only — not a freemium product
  • I have seen several services suddenly switch to a paid model, so the reassurance matters
• Well-maintained documentation
  • English only, but usage guides and development documentation are actively maintained
• Active development community
  • One to two updates are released every month, with prompt security responses
  • Over 74,000 ★ on GitHub (as of 2024/8/12)
• Themes can be swapped to change the site design
  • The official theme site hosts nearly 1,000 contributed themes
• A reasonable amount of Japanese documentation
  • Tech blog platforms Qiita, Zenn, and note (Japanese) all have many articles on building and reviewing Hugo setups

Conclusion and Plan

Based on the above research, I decided to write this blog using Hugo. (That decision was made four years ago.)

The plan is as follows:

• Install Hugo on a Windows PC
• Use Microsoft Visual Studio Code (VSCode, free) with Hugo add-ons to write and manage articles
• Create and manage the entire Hugo build tree in a Dropbox (free plan) synced folder for backup
• Use GitHub (free plan) to version-manage the entire Hugo folder tree
• Publish the blog through Netlify (free plan), a hosting service
• Adopt a workflow where committing to GitHub automatically deploys and publishes to Netlify
• Use Google Site Search for search functionality
• Use Google Analytics to track page views

With all of the above, the entire workflow — writing, backing up, publishing, and local storage — is achieved using only free tools and services.

The specific environment setup will be covered in the next article.