Hugo – Static webpage framework

This is Eddie Tonkoi back to tell you about a new project, this time an element of our burgeoning publishing empire.

My wife, Jern Tonkoi, has fallen in love with, and dedicated herself towards, writing creative fiction. She is passionate about it and loves writing, bringing characters to life, and letting those characters explore the worlds she creates. I am creative, but not in that way, and by happy circumstance, we complement one another very well, in that I have the passion to support Jern and I have the technical skills to take on all the not-writing-a-novel aspects of the venture, such as editing, publishing, and marketing.

This is a publishing empire I’m building, taking a cue from Jill from the Northwoods there, so I’m not here to tell you about it all. But I am here to tell you about one small component, and then I’ll be back to tell you about another. Essentially, how I’m using my Mac in a thousand different ways to support Jern.

Today, I’m going to cover a project that sprang up out of nowhere, consumed 5 days of my life, and taught me new knowledge and skills along the way.

As is best, it started with a problem to be solved, so let’s start there.

Problem to be solved

Our indie-author website was managed by Kit, which was great for building and maintaining an email list. However, I realized that it wasn’t searchable by ChatGPT, which could limit discovery. To take control and optimize for search, I decided to switch to a static website built with Hugo, hosted on Cloudflare Pages, and deployed via GitHub.

In just four days, my new website was up and running. In this post, I’ll share my journey and the decisions I made along the way.

jerntonkoi.com Showing Header and Two Book Series

What is Hugo?

Found at gohugo.io/…, Hugo positions itself as, “The world’s fastest framework for building websites”.

That sounds perfect for me, but what is it? Well, the next paragraph on the website conveniently tells us, “Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.”

Even more perfect. So, it is a tool for making static websites. Back in the day, I made my own websites by opening a text editor and typing in the HTML. There was nothing fancy, no fancy JavaScript, no dynamic insertion of fancy content, just a simple text file with quick and simple rendering as a web page. In my mind, that’s what a static website is. Something pure, something simple, something easy for me to understand and own. Not necessarily better than a rich, dynamic website, but what I wanted.

Hugo is a tool that lets the user create templates for pages, so I have a “book page” template, and have a markdown file with the content I want for a specific book, and Hugo reads all these files and spits out a directory of HTML files with everything blended together. This allows me to create a complex page once and reuse it across multiple books, saving both time and effort.

How Hugo Works

VSCode with the Website Markdown Loaded

Hugo starts with a layout, which in my case gave me a decent website all by itself.

At the heart of the layout are templates for types of pages, such as an individual book page or a book series page. These templates also include partials, which are reusable pieces of HTML that can be used across multiple pages.

For example, I might want to display a book cover with a white border and a caption underneath on both book and series pages. Instead of duplicating this code across both templates, I create a “book cover” partial with the desired formatting. Then, I can simply include this partial in both templates using the simple code, {{ partial “book-cover.html” . }}.

This means that if I ever want to change the book cover format, I only need to update the single partial file – and the change will be reflected everywhere it’s used.

In essence, this is the beauty of Hugo: creating reusable templates and partials that make it easy to maintain and update my website.

Content

To make content, we can rely on the fact Hugo has a fixed structure, determined by the layout I chose at the start. I have a template for a book page, and I also have a folder called “content”. Inside that is a folder called “books”. Hugo assumes that everything inside the “books” folder is a book, and will create webpages for anything in here.

So, one subfolder in “books” is called “murder-in-treggan-bay”, and that has just 3 files: index.md, cover.jpg, extra-1.jpg.

With just those 3 files, Hugo will take the contents of index.md, it will take the book template and any partials it references, and use these to create my “Murder in Treggan Bay” book page. It will put a nice book cover image on the page, and lower down it puts the extra image. All according to the template.

index.md

The main file, index.md, can be as simple or as complex as you want.

Mine is quite long, and gives all the information presented on the page from title to isbn to reviews to FAQ to the blurb. Here’s a snippet:

title: "Murder in Treggan Bay" summary: "A Devon Coast Mystery" date: "2025-10-11" series: "Treggan Bay Mysteries" series_id: "treggan-bay-mysteries" series_order: 1 publisher: "Tonkoi Books" wordCount: 62000 tagline: "He came to sell a cottage, not count alibis."

So, this file is never actually present on the final webpage, but it is used in Hugo’s computations to create the “Murder in Treggan Bay” page. Apparently, Hugo can handle this metadata in a number of formats, but this is what I used.

Answer Engine Optimization and SEO

One of my goals in this migration was visibility for tools like ChatGPT, so that if someone asked ChatGPT to recommend a great character-first mystery set in Devon, ChatGPT (and other AIs) would know where to send them. That means making the site easy for ChatGPT to read and understand, and that means something called Answer Engine Optimization (AEO). But what is AEO, you ask? Simply put, AEO is the practice of optimising your website to rank higher in search engine results pages for specific questions or answers. This is different from traditional Search Engine Optimization (SEO), which focuses on ranking for generic keywords and phrases. It’s also fully supported by the search engines and bots, and is not spammy.

In my case, I wanted to optimize my website for AEO because my wife was writing a series of books that were all part of a larger mystery series. I wanted my website to appear at the top of the search results when someone searched for questions like “What is the first book in the Treggan Bay Mysteries series?” or “Who is the author of Murder in Treggan Bay?” I don’t want the response to that question to be a link to our website; I want the response to be the answer and a link to our website.

As I delved deeper into AEO, I quickly realized that it was closely related to traditional SEO. In fact, many of the same techniques used for SEO also apply to AEO. For example, using relevant keywords in your website’s content, optimizing your meta tags, and creating high-quality, unique content are all important for both SEO and AEO.

However, AEO requires a slightly different approach. For instance, I needed to focus on creating content that was specifically designed to answer common questions related to my books. This meant writing detailed summaries, FAQs, and other types of content that were designed to provide value to my readers.

Let’s pause there, because it is quite wonderful. Optimising my website for search is the same as optimising my website for people. How charming.

Deployment

When I’m ready to deploy my Hugo website, I use a simple command that synchronizes my local changes with my GitHub repository and updates Cloudflare Pages. This streamlined process involves:

1. Building my website in production mode using Hugo: hugo --environment production --gc --minify --cleanDestinationDir

This command tells Hugo to build my website in production mode, which means it will optimize the build for deployment. The --gc flag removes unnecessary files, --minify minifies CSS and JavaScript files, and --cleanDestinationDir ensures a clean output directory.

1. Staging and committing the changes using Git: git add -A and git commit -m "Production build: update for Cloudflare Pages"

This command stages all changes in my Git repository (git add -A) and commits them with a meaningful commit message (git commit -m). The commit message describes the changes made in this commit.

1. Pushing the changes to my GitHub repository: git push

This command sends the committed changes to my remote GitHub repository, making them available for Cloudflare Pages to fetch and deploy.

I’ve found that Cloudflare’s GitHub integration makes it incredibly easy to automate the deployment process for my Hugo website. To get started, I simply signed in to my GitHub account from within my Cloudflare account and authorized the connection. Then, I selected the repository that contains my Hugo website, and Cloudflare took care of the rest.

From that point on, Cloudflare uses a system it refers to as workers to set up a webhook in my GitHub repository, which listens for changes such as new commits or updates. Whenever changes are detected, the webhook triggers a deployment to Cloudflare Pages. Cloudflare automatically pulls the updated code from my GitHub repository and updates my website, ensuring that it’s always up-to-date and reflecting the latest changes.

Problems I Encountered

It took me about 2.5 days to create the entire website, for the series and the books, since I had all the information in my database. I’m using TapForms, by the way, which let me create a script that outputs the contents of index.md for each book.

I then spent another 2.5 days trying desperately to get the SEO and AEO part working. I eventually got to a decent place, good enough to leave and come back to later on, but that was surprisingly hard. In a nutshell, Google and others look for specially encoded information in a page, and I was struggling to get it just right so that Google was happy. More on that another time if I ever really solve it.

In the End

Five days after starting, what did we gain?

• We have a pretty new website that is ours (i.e., I control it) at jerntonkoi.com and has room to expand beyond just mailing lists. Glorious.
• I learned a new tool, which is always fun.
• We’re saving some money by eliminating GreenGeeks (nothing against them, mind; we just don’t need it now).
• The website is (at least in part) being presented nicely to Google.
• We have over 150 unique visitors a day. I’ve no idea about the old site, but this feels good to me.
• ChatGPT still cannot search the site.

Oh.

It turns out, ChatGPT still cannot search the site because, well ChatGPT cannot search the web. Things you learn, eh? But, GPTBot can search it, GoogleBot can search it, and it seems like this is in fact how things work. The bots index the web, the engines read the index.

Whether or not the old site was perfectly capable really, I’ll never know.

If you are interested in knowing more you can find me and all the other lovely NosillaCastaways at podfeet.com/slack. If you are curious about what I did, please ask me, Eddie Tonkoi, and if you are curious about how to do website management properly, there are plenty of others there far more knowledgeable in it than me, so come and join the friendly community.

And if you’re interested in having a good read from an indie author, come along to jerntonkoi.com, and have a look at all of the books we have available on our website.