That was my life for 4 years.

I kept telling myself “it’s fine” - until I actually measured it. 2.5MB transfer, 47 network requests, and 40 seconds to load a single page on a slow connection. My plain HTML homepage? 32KB and 0.3 seconds.

This post shows you how I ditched WordPress for Hugo, a static site generator that turns markdown into blazing-fast HTML - and deployed it with GitHub Actions and nginx. No more database, no more PHP, no more 2 AM debugging sessions.

Working migration scripts and deployment pipeline: All the code you need is in this post.

Why this matters

Look, I’m not a web developer. I picked WordPress 4 years ago because it was the only CMS I knew. It worked… until it didn’t.

Here’s what I was fighting:

The technical pain:

• 2.5MB transfer and 47 network requests per page load
• 40-second load times on slow connections (yes, really)
• PHP + MariaDB + nginx stack just to serve some blog posts
• Security vulnerabilities every few months
• No version control for content

The workflow pain (and this was the real killer):

1. Write content locally in vim (because the online editor is unusable)
2. Copy-paste into WordPress and watch it mangle the formatting
3. Manually fix broken code blocks with a syntax highlighter plugin
4. Edit the generated HTML by hand
5. Cry and drink
6. Repeat this every 3 months

I accept judgment for this workflow. It’s worse than writing Confluence pages on dial-up.

And here’s the thing - my plain HTML homepage loads 32KB in 0.3 seconds on the same connection. The blog? 2.5MB and 40 seconds. That’s an 8,000% size increase for… a blog.

AWS published this architecture diagram for running WordPress at scale. It’s horrifying. Load balancers, RDS instances, ElastiCache, S3, CloudFront - all to serve markdown content.

There had to be a better way.

What we’ll build

Here’s the migration plan:

1. Export all WordPress posts to markdown
2. Set up Hugo as the static site generator
3. Customize a theme (remove all external CDN dependencies, add TOC, improve syntax highlighting)
4. Migrate content with scripts to fix broken formatting
5. Deploy with GitHub Actions and nginx
6. Secure deployment with restricted SSH access

The result? Write in markdown locally, push to Git, auto-deploy to production. No database, no PHP, no security updates, no 40-second page loads.

Let’s build it.

Part 1 - The WordPress nightmare: why I had to leave

The WordPress pain points weren’t just about performance. They were about the entire development experience.

What drove me crazy:

• No offline work - Everything happens in a web browser connected to the server
• WYSIWYG hell - No markdown support, no vim bindings, everything is mouse-driven
• Slow everything - Navigation, updates, previews all crawl
• Plugin roulette - Syntax highlighting plugins fight with each other
• No collaboration - Accepting feedback requires manual work, no pull requests
• Bot spam - Constant comment spam to clean up
• Template limitations - WordPress templates are hard to customize without breaking things

But the workflow was what finally broke me. Writing locally, copying to WordPress, watching it destroy my formatting, manually fixing HTML… this isn’t 2005.

I wanted: Write markdown in vim → push to Git → see it live. That’s it.

Part 2 - Static site generators: the mental model

Here’s the key insight: most blogs don’t need a database and server-side rendering for every page load. The content doesn’t change between requests.

How static site generators work:

1. You write content in markdown files
2. The generator reads the files and applies templates
3. It outputs plain HTML/CSS/JS
4. You serve the static files (no database, no PHP)

Why this works:

• Fast - No database queries, no PHP execution, just static files
• Secure - No login pages, no SQL injection, no PHP vulnerabilities
• Version control - Everything is text files in Git
• Portable - Works on any web server (nginx, Apache, S3, GitHub Pages)
• Offline work - Write locally, preview locally, push when ready

The workflow becomes:

1

Write markdown → Run generator → Deploy static HTML

Instead of:

1

Log into WordPress → Fight WYSIWYG → Manually fix HTML → Hope it works

There are several options: Jekyll (Ruby), Hugo (Go), Gatsby (React), 11ty (JavaScript). I chose Hugo because it’s a single binary with no dependencies, it’s fast, and it has good themes.

Part 3 - Hugo setup: getting started

Hugo is a static site generator written in Go. It’s a single binary with no dependencies. No Ruby gems, no Node modules, no Python packages. Just download and run.

Why Hugo over Jekyll or Gatsby? Simple:

• One binary - No runtime dependencies
• Fast builds - Go is compiled, not interpreted
• Good templates - Nice MIT-licensed themes available
• Simple syntax - Easy to learn even for non-web-devs

I saw it on HackerNews years ago and bookmarked it. Finally got around to using it.

Installing Hugo

Grab the latest binary for your platform from GitHub:

1
2

wget https://github.com/gohugoio/hugo/releases/download/v0.70.0/hugo_0.70.0_Linux-64bit.tar.gz
tar xvf hugo_0.70.0_Linux-64bit.tar.gz

Put it somewhere on your $PATH and you’re done. No gem install, no npm install, no dependency hell.

Creating the site

1

hugo new site vitthalmirji.com

This creates the basic structure. Now edit config.toml:

1
2
3
4

baseURL = "https://vitthalmirji.com/"
languageCode = "en-us"
title = "Vitthal Mirji"
theme = "ink-free"

That’s it for basic setup. Now we need content and a theme.

Local testing

Hugo has a built-in dev server with auto-reload:

1

hugo server -D

This starts a local server on localhost:1313. Every time you save a file, the browser refreshes automatically. No build step, no manual refresh.

The -D flag includes drafts. Super useful for previewing work-in-progress posts.

Part 4 - Migrating WordPress content

Now comes the fun part: getting all those old WordPress posts out.

Exporting WordPress posts to markdown

I need to export all old blog posts to markdown. There’s a great little tool by lonekorean on GitHub that does exactly this.

First, export your WordPress content (Tools → Export in WordPress admin). You’ll get an XML file.

Then run the converter:

1
2
3
4

git clone https://github.com/lonekorean/wordpress-export-to-markdown
cd wordpress-export-to-markdown
npm install
node index.js

It’ll prompt you for the WordPress XML file and output directory. The tool generates markdown files with front matter.

Hugo has other migration tools available, but since I’d customized WordPress heavily, this one worked best for me. Your mileage may vary.

After that, copy the generated files to Hugo’s content/posts/ directory.

The problems with exported content

Due to my “interesting” WordPress configuration, the exported posts needed help:

• GitHub Gists not rendered
• Internal syntax formatting caused everything to be escaped with \, breaking code
• Headlines missing
• Tags missing
• Descriptions missing

Yeah, it was a mess.

Part 5 - Theme customization

We also need a theme. Hugo’s default is… minimal.

My requirements:

• No external CDNs - No googleapis, no Google Analytics, no trackers
• Simple interface - Clean, without hiding information
• Fast on slow connections - Remember those 40-second WordPress pages?

I chose hugo-ink by knadh, but customized it heavily. This became a fork called ink-free .

What I changed

Removed privacy invasions:

• All references to Google’s font CDN (fonts are now local)
• Analytics code (even if it was toggled off)

Fixed usability issues:

• Tags display inline instead of as a list
• Syntax highlighting background changed (was grey on grey - unreadable)
• Added a back button to all posts
• Added TOC (table of contents) controlled by a variable
• Added word count, tags, and read time to post previews

Added random footer messages: This was the fun part. Hugo’s templating language (based on Go) lets you pipe commands. I wanted random silly messages at the end of posts:

1
2
3
4
5
6
7

<div class="back">
  {{ if isset .Site.Params "footers" }}
    {{ if ne .Type "page" }}
      Next time, we'll talk about <i>"{{ range .Site.Params.footers | shuffle | first 1 }}{{ . }}"</i>{{ end }}
    {{ end }}
  {{ end }}
</div>

This picks a random message from config.toml and displays it. Messages like “What Tiger King can teach us about x86 Assembly” or “Why Spark’s lazy evaluation is basically procrastination with a PhD”.

Most theme changes were simple HTML and CSS. Even as someone who’s not a web dev, Hugo’s templates are straightforward:

1
2
3
4
5
6
7
8

.tag-li {
  display:inline !important;
}

.back {
  padding-top: 1em;
  font-size: 1em;
}

The result:

Check out the theme here: ink-free on GitHub

Part 6 - Fixing exported content with scripts

Remember those export problems? Time to fix them.

The WordPress exporter gave me markdown files, but they were broken:

• GitHub Gists embedded as <script> tags (Hugo needs shortcodes)
• Code blocks escaped with \ everywhere
• Missing metadata

Fixing GitHub Gists

WordPress had this:

1

<script src="https://gist.github.com/vim89/8dcc79ab16daf5fcdda3df1a4ccc183a.js"></script>

Hugo needs this:

1

{{< gist vim89 8dcc79ab16daf5fcdda3df1a4ccc183a >}}

Doing this by hand for dozens of posts? No thanks. Let’s script it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

grep "gist.github.com" *.md | while read -r line ; do
  guser=$(echo "${line}" | cut -d'/' -f4)
  gist=$(echo "${line}" | cut -d'/' -f5 | sed -E 's/(\.js).+//g')
  repl="{{/* gist "${guser}" "${gist}" */>}}"

  # Get line number
  ln=$(grep -n "$line" *.md | cut -d : -f 1)

  # Replace
  echo "Replace line $ln with ${repl}"
  sed -Ei "$ln s#.*#${repl}#g" *.md
done

This finds all Gist URLs, extracts the username and Gist ID, and replaces them with Hugo shortcodes. Saved me hours of manual editing.

VS Code shortcuts for Hugo syntax

I added keyboard shortcuts in VS Code to quickly insert Hugo’s syntax highlighter blocks. In keybindings.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

[
  {
    "key": "ctrl+1",
    "command": "editor.action.insertSnippet",
    "when": "editorTextFocus",
    "args": {
      "snippet": "{< highlight bash \"linenos=table\" >}"
    }
  },
  {
    "key": "ctrl+2",
    "command": "editor.action.insertSnippet",
    "when": "editorTextFocus",
    "args": {
      "snippet": "{< / highlight >}"
    }
  }
]

Now Ctrl+1 opens a syntax block, Ctrl+2 closes it. Small productivity win.

Preserving URLs (SEO matters)

I don’t want to break existing links. People have bookmarked posts, shared them, indexed them in search engines.

Hugo needs to generate the same URLs WordPress used. In config.toml:

1
2

[permalinks]
  posts = "/:year/:month/:title"

This matches WordPress’s default permalink structure. No 301 redirects needed.

Verifying the migration

How do I know all URLs match? I wrote a quick Go script to compare RSS feeds - WordPress’s export vs Hugo’s generated feed:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

package main

import (
  "os"
  "fmt"
  "github.com/mmcdole/gofeed"
)

func mapToUrl(feed *gofeed.Feed) map[string]string {
  output := map[string]string{}
  for _, post := range feed.Items {
    output[post.Link] = post.Title
  }
  return output
}

func readFeed(path string) *gofeed.Feed {
  fp := gofeed.NewParser()
  file, _ := os.Open(path)
  defer file.Close()
  feed, _ := fp.Parse(file)
  return feed
}

func compareUrls(local, remote map[string]string) bool {
  allFound := true
  for k, _ := range local {
    if title, ok := remote[k]; ok {
      fmt.Printf("✓ Found %s\n", title)
    } else {
      fmt.Printf("✗ Missing: %s\n", k)
      allFound = false
    }
  }
  return allFound
}

func main() {
  remoteFeed := readFeed("./wordpress.xml")
  localFeed := readFeed("../public/index.xml")

  remote := mapToUrl(remoteFeed)
  local := mapToUrl(localFeed)

  fmt.Println("All URLs match:", compareUrls(local, remote))
}

Running this found a couple of posts with mismatched URLs:

1
2

✗ Missing: https://vitthalmirji.com/blog/2020/02/how-a-broken-memory-module-hid-in-plain-sight/
✗ Missing: https://vitthalmirji.com/blog/2019/12/tensorflow-on-edge-building-a-smart-security-camera/

Fixed those manually. (Psst, don’t check the Git commits.)

There were more adjustments - re-embedding videos, fixing image paths - but this covered the bulk of it. I’ll spare you the tedious details.

Part 7 - Deployment with GitHub Actions

Now for the fun part - automated deployment.

The goal: Every git push to master should automatically build and deploy the site to my nginx server. No manual steps, no FTP clients, no SSH sessions.

I could use GitHub Pages, but I want to keep everything on my own server. Plus, I’m already running nginx and Docker there.

The deployment flow:

1. Git push triggers GitHub Actions
2. Checkout code (including theme submodule)
3. Download Hugo binary
4. Build static HTML/CSS/JS
5. Deploy via SCP to server (in a restricted chroot jail for security)
6. Optional: Trigger any server-side updates (Docker container refreshes, etc.)

For CI/CD, I have two free options: Travis CI or GitHub Actions. I chose GitHub Actions to avoid yet another external service. Everything stays within GitHub.

Creating the workflow

Create .github/workflows/workflow.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

name: build, test, audit & deploy vitthalmirji.com site

on:
  push:
    branches: [ master, main ]
  pull_request:
    branches: [ master, main ]
  workflow_dispatch:

jobs:
  build-test-audit-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 📥 Checkout code with submodules
        uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: ⚙️ Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.148.1'
          extended: true

      - name: ✅ Validate taxonomies via taxlimits.yaml
        continue-on-error: true
        run: |
          valid_terms=$(yq e '.tags + .categories + .series' data/taxlimits.yaml | sed 's/- //g')
          find content -name "*.md" | while read -r md; do
            for term in $(grep -E '^(tags|categories|series):' -A3 "$md" | sed -n 's/- //p'); do
              if ! grep -qx "$term" <<< "$valid_terms"; then
                echo "❌ Invalid taxonomy term '$term' in $md"
                exit 1
              fi
            done
          done

      - name: 🏗️ Build Hugo site
        run: hugo --gc --minify

      - name: 🚦 Run Lighthouse audits
        uses: treosh/lighthouse-ci-action@v12
        continue-on-error: true
        with:
          urls: 'https://vitthalmirji.com'
          uploadArtifacts: true

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Pa11y CLI
        run: npm install -g pa11y-ci

      - name: Cache Node.js dependencies
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      - name: ♿ Run accessibility checks (Pa11y)
        run: PUPPETEER_EXECUTABLE_PATH=$(which chromium-browser || which chromium || true) \
          npx pa11y-ci --chrome-launcher-flags="--no-sandbox" --config .github/workflows/.pa11yci.json
        continue-on-error: true
    
      - name: 📦 Upload to GitHub Pages (gh-pages)
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.PERSONAL_TOKEN }}
          publish_dir: ./public
          external_repository: vim89/vim89

      - name: 📤 Deploy to InfinityFree via FTP
        uses: SamKirkland/FTP-Deploy-Action@v4.3.5
        with:
          server: ${{ secrets.FTP_HOST }}
          username: ${{ secrets.FTP_USERNAME }}
          password: ${{ secrets.FTP_PASSWORD }}
          local-dir: ./public/
          server-dir: /htdocs/
          dangerous-clean-slate: false

Note on SCP Actions: I tried using pre-configured SCP Actions from the GitHub marketplace. They either didn’t support key passphrases or had terrible debug logs. After fighting “Exit code 1” errors despite successful connections (verified in syslog and auth.log), I gave up and wrote the bash deployment myself. If you know what causes that error, let me know!

Part 8 - Security: locking down deployment

Here’s the problem: GitHub Actions needs SSH access to deploy files. But giving full SSH access to an automated system? That’s a security nightmare.

The solution: Create a restricted user that can only upload files via SCP. No shell, no commands, no lateral movement.

Setting up rssh (restricted shell)

rssh is a restricted shell that only allows SCP/SFTP. No bash, no command execution.

Create the deployment user:

1
2

useradd -m -d /home/github github
passwd github

Lock down permissions:

1
2
3
4
5
6
7
8
9

# Make home directory owned by root (prevents user from writing there)
sudo chown -R root:github /home/github

# Only allow writes to .ssh for key management
sudo chown github:github /home/github/.ssh

# Give write access only to the deployment target directory
sudo mkdir -p /var/www/vitthalmirji.com
sudo chown github:github /var/www/vitthalmirji.com

Compile and install rssh:

1
2
3
4
5
6
7

wget http://prdownloads.sourceforge.net/rssh/rssh-2.3.4.tar.gz
tar -xvf rssh-2.3.4.tar.gz
cd rssh-2.3.4

./configure
make
sudo make install

Configure rssh:

Edit /usr/local/etc/rssh.conf:

1

user = "github:022:00001:/var/www/vitthalmirji.com"

This configuration means:

• username: github (the restricted user)
• umask: 022 (files created with rw-r–r– permissions)
• access bits: 00001 (rsync=0, rdist=0, cvs=0, sftp=0, scp=1)
  • Only SCP is allowed
• chroot path: /var/www/vitthalmirji.com (user can’t access anything outside this directory)

See the rssh.conf man page for details.

Setting up chroot is complex. You need to copy required libraries and binaries into the chroot directory. Read the CHROOT file in the rssh source directory carefully. This is a multi-step process that varies by distribution.

Update SSH configuration:

Edit /etc/ssh/sshd_config:

1
2

# Ensure github user is allowed
AllowUsers your-user github

Consider creating separate groups for rssh and regular ssh users if you’re doing this on a multi-user system.

Restart SSH:

1

service sshd restart

Set user shell to rssh:

1

usermod -s /usr/bin/rssh github

Now the github user can only SCP files to the deployment directory. They can’t:

• Run shell commands
• Access other parts of the filesystem
• SSH in for interactive sessions

Generate SSH keys:

For GitHub Actions, generate keys in PEM format (the Ubuntu runner image uses an older OpenSSH version):

1

ssh-keygen -m PEM -t rsa -b 4096 -f github_deploy_key

Add the public key to /home/github/.ssh/authorized_keys, then add the private key as a GitHub secret.

The result

Well, if you’re reading this, judge for yourself!

Performance improvements:

• Before (WordPress): 2.5MB transfer, 47 requests, 40 seconds on slow connections
• After (Hugo): ~500KB transfer (mostly images), minimal JS/CSS, instant load

It’s not as flashy as the WordPress template. But it’s fast, it works, and I can actually write without fighting an editor.

The workflow now:

1. Write markdown in vim (offline)
2. git push
3. GitHub Actions builds and deploys automatically
4. Live in seconds

No database, no PHP, no manual HTML editing, no fighting with plugins.

Conclusion

I’m pretty happy with this change. For my sanity, if nothing else.

Look, I don’t get a ton of traffic here (I don’t run analytics, so I don’t actually know). But blogging is fun. Every time I write something, I learn something - whether it’s complex ML theory or, like today, getting back into web dev and deployment automation.

This new setup lets me blog more. I spend time writing code and posts, not fighting WordPress. Faster load times mean less frustration for readers. Version-controlled markdown means no more lock-in - anyone can contribute via pull requests.

If you’re thinking about migrating away from WordPress, or starting a blog, give Hugo (or any static site generator) a try. The workflow is so much cleaner than fighting a WYSIWYG editor.

And if you want to use GitHub + Hugo + nginx, hopefully this post helps.

TL;DR

• Migrated from WordPress (40s page loads, horrible editor) to Hugo static site generator
• Hugo: Single Go binary, markdown input, blazing-fast static HTML output
• Exported WordPress posts to markdown with wordpress-export-to-markdown tool
• Fixed broken content with bash/Go scripts (Gists, permalinks, metadata)
• Customized hugo-ink theme: removed CDN dependencies, added TOC, fixed syntax highlighting
• Automated deployment with GitHub Actions: push to Git → auto-build → deploy via SCP
• Secured deployment with rssh (restricted shell): GitHub Actions can only SCP files, no shell access
• Result: 500KB pages that load instantly, markdown workflow in vim, version control, collaborative via PRs

In 2020, I wrote about leaving WordPress because I was tired of fighting editors, plugins, PHP, databases, and 40-second page loads.

Hugo fixed the first pain: write Markdown, build static HTML, deploy it somewhere boring.

This is the sequel to Goodbye, WordPress: hello Hugo + nginx with fast builds and sane deploys today .

It covers the setup I would build today, when I would use it, and how this site grew into CI/CD, search, validation, generated data, and a small Cloudflare backend.

Note

This article has two parts. Part 1 is the simple version: Hugo, GitHub Actions, GitHub Pages, and a short backend summary for when static HTML is no longer enough. Part 2 is the grown-up version: how this site grew into validation, search, generated data, CI/CD, and a small Cloudflare backend. This is not a “copy my entire repo” article. That would be the wrong lesson.

Why I am writing part 2

The original article was about escape velocity. WordPress was solving a problem I no longer had.

I did not need a database query to render a blog post. I did not need a plugin ecosystem to paste a code block. I definitely did not need an admin dashboard that made writing feel like data entry with extra sadness.

I wanted this:

• write locally,
• preview locally,
• keep content in Git,
• push once,
• let automation publish the site.

Hugo gave me that. Six years later, the better lesson is:

A static site can stay simple for a long time if you keep runtime behaviour at the edges.

Hugo owns content and pages. GitHub Actions owns repeatable builds. GitHub Pages owns static hosting. Cloudflare Workers owns the few API paths that need secrets, state, or webhooks.

No one piece is magical. The setup works because each piece has a boring job.

Part 1 - The simple version: Hugo + GitHub Pages first

Let’s separate the two stories clearly.

Start here before copying any mature personal-site setup:

• Hugo for content and static rendering,
• GitHub Actions for repeatable CI/CD,
• GitHub Pages for static hosting,
• a tiny backend summary only for cases where static HTML stops being honest.

For a blog, portfolio, docs site, project site, or technical writing home, this may be the whole setup. No Worker. No D1. No scheduled data pipeline. No cleverness tax.

Why Hugo still makes sense

Hugo turns content, templates, data files, assets, and config into static output: HTML, CSS, JavaScript, RSS, sitemap, and custom formats.

The important bit is not that Hugo is written in Go. The important bit is the publishing model.

1

Content + templates + data -> static files -> CDN/static host

That model removes noise:

• no production database for ordinary posts,
• no admin login to protect,
• no runtime rendering for the same article again and again,
• no plugin update treadmill just to keep a blog online.

For engineers, the workflow also feels natural. Markdown is diffable. Frontmatter is clear. Page bundles keep assets near the article. Pull requests can review prose, diagrams, and metadata like code.

That is the real win. Not “static sites are cool”. Static sites are boring. Boring is the point.

What a wider check changes about the when

I checked wider usage before writing this: personal sites, docs, portfolios, static blogs, Git-backed publishing, and small business sites. The useful pattern was not “Hugo is best”. It was this:

That is why the WHEN section matters more than the setup commands. Most bad design starts when we choose a tool because it can do something, not because the problem needs it.

When Hugo + GitHub CI/CD + GitHub Pages is the right choice

Use this stack when your site is mostly content and your publishing flow matters more than runtime features.

The key condition: Markdown and Git must be acceptable. For a developer, Hugo feels freeing. For a non-technical editor who wants a visual CMS, bare Hugo may feel like homework.

When not to use this stack

This is where people over-sell static sites. Hugo is not an app framework. GitHub Pages is not an app platform. GitHub Actions is not a database.

You can stretch the stack, but at some point you are just hiding an app inside a build pipeline.

The failure mode is not “this is impossible”. You can add JavaScript, APIs, CMSs, webhooks, scheduled jobs, and serverless functions. The problem starts when the mental model stops being static, but the setup still pretends it is.

If you are building an app, build an app. If you are building content, start static.

How the simple version works

This is the version I would recommend to someone starting today.

flowchart LR
    A["Write Markdown<br/>in site/content"] --> B["Push to GitHub"]
    B --> C["GitHub Actions"]
    C --> D["Hugo build"]
    D --> E["Optional Pagefind<br/>search index"]
    E --> F["GitHub Pages"]
    F --> G["Custom domain"]

    style A fill:#e1f5ff,stroke:#0066cc,color:#000
    style B fill:#fff4e1,stroke:#cc8800,color:#000
    style C fill:#f0e1ff,stroke:#8800cc,color:#000
    style D fill:#f0e1ff,stroke:#8800cc,color:#000
    style E fill:#fff4e1,stroke:#cc8800,color:#000
    style F fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style G fill:#e1ffe1,stroke:#2d7a2d,color:#000

The flow:

1. Hugo source lives in the repo.
2. Articles live as Markdown page bundles.
3. GitHub Actions runs the build.
4. Hugo writes static output.
5. Optional search/indexing runs after the build.
6. GitHub Pages serves the generated files.

That is enough for a serious personal site.

The minimal repository can be as small as this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

my-site/
├── site/
│   ├── content/
│   │   └── posts/
│   ├── layouts/
│   ├── static/
│   ├── themes/
│   └── hugo.toml
├── .github/
│   └── workflows/
│       └── deploy.yml
└── README.md

You do not need a monorepo, five workflows, or a backend on day one. You need one working path from Markdown to the live site.

DIY path: from zero to GitHub Pages

If you are starting fresh or moving from another host, use this path. I am assuming you already have:

• a GitHub account,
• Git installed,
• Hugo installed,
• a domain name if you want a custom domain.

No domain yet? Use https://<username>.github.io/<repo>/ first. Get the site live before touching DNS.

Step 1 - Create the repository

Create an empty GitHub repository. Skip the GitHub UI README if you plan to push a local Hugo site into it; that avoids one early merge.

Locally:

1
2
3

mkdir my-site
cd my-site
git init

Result: my-site is your source repo. Git tracks Hugo files and workflows. CI will create public/, so do not commit it.

Step 2 - Create the Hugo site

You can keep Hugo at the repository root. I prefer site/ because it leaves room for scripts, workflows, or backend code later:

1
2

hugo new site site
cd site

Result: Hugo creates the site under site/. Future scripts or backend code can live beside it.

Step 3 - Add a theme

Use one theme. Keep it boring first.

Example with a theme submodule:

1

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git site/themes/ananke

Then set it in site/hugo.toml:

1
2
3
4

baseURL = "https://<username>.github.io/<repo>/"
languageCode = "en-us"
title = "My site"
theme = "ananke"

• The theme gives Hugo templates and styling.
• baseURL must match the deployed URL.
• If you later use a custom domain, update baseURL to that domain.

Tip

If your repository is named <username>.github.io, your default URL is usually https://<username>.github.io/. If it is a project repository, the default URL is usually https://<username>.github.io/<repo>/. This matters for baseURL.

Step 4 - Create a first post

1

hugo new posts/hello-hugo/index.md

Edit the generated file:

1
2
3
4
5

---
title: "Hello Hugo"
date: 2026-09-21T09:00:00Z
draft: false
---

Then add a few paragraphs below the frontmatter.

• index.md creates a page bundle.
• Page bundles make it easy to keep images and article files together later.
• draft: false means the post can appear in production builds.

Step 5 - Test locally

1

hugo server -D

Open the local URL Hugo prints, usually http://localhost:1313/.

• hugo server starts a local preview server.
• -D includes drafts while previewing.
• If the site does not work locally, do not debug GitHub Actions yet. Fix local first.

Step 6 - Ignore generated output

From the repository root, create .gitignore:

site/public/
site/resources/_gen/
.hugo_build.lock

• public/ is generated output.
• GitHub Actions will rebuild it.
• You commit source, not build artifacts.

Step 7 - Add the GitHub Actions workflow

Create .github/workflows/deploy.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

name: Deploy Hugo site

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: "0.165.0"
          extended: true

      - name: Build
        working-directory: site
        run: hugo --minify --gc --cleanDestinationDir

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: site/public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Result: the workflow checks out the repo, builds site/public, uploads the Pages files, and deploys them.

Step 8 - Enable GitHub Pages

In the GitHub repository:

1. Go to Settings.
2. Open Pages.
3. Under source, choose GitHub Actions.
4. Push to main.
5. Open the Actions tab and watch the workflow.

If the workflow passes, your site should be live at the Pages URL.

Step 9 - Add a custom domain

If you own a domain, configure it after the default GitHub Pages URL works.

At a high level:

1. Add the custom domain in GitHub Pages settings.
2. Configure DNS at your domain provider.
3. Wait for DNS to settle.
4. Enable HTTPS in GitHub Pages.
5. Update baseURL in site/hugo.toml.

Result: GitHub Pages serves the same files through your domain. Hugo uses baseURL for canonical links, RSS, social preview URLs, and absolute links.

What this looks like in my repo

The DIY path above is the beginner version. My repo is the grown-up version, so do not copy it blindly. These snippets are trimmed from the real source, with account names, personal workflows, and secrets removed.

At the root, scripts delegate into the Hugo site workspace:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "private": true,
  "packageManager": "pnpm@9.15.0",
  "engines": {
    "node": ">=20"
  },
  "workspaces": [
    "site",
    "workers",
    "packages/*"
  ],
  "scripts": {
    "dev": "pnpm --filter site run dev",
    "build": "pnpm --filter site run build",
    "test": "pnpm --filter site run test",
    "build:hugo": "pnpm --filter site run build:hugo",
    "build:search": "pnpm --filter site run build:search"
  }
}

• The root repo only coordinates commands.
• Hugo still lives under site/.
• A beginner can ignore the workspace and run Hugo directly inside site/.
• Once the repo grows, root scripts keep commands predictable.

Inside site/package.json, the actual build is still boring:

1
2
3
4
5
6
7
8
9

{
  "scripts": {
    "dev": "hugo server -D",
    "build": "pnpm run og:generate && hugo --minify --gc --cleanDestinationDir && pnpm exec pagefind --site public",
    "build:hugo": "pnpm run og:generate && hugo --minify --gc --cleanDestinationDir",
    "build:search": "pnpm exec pagefind --site public",
    "test": "./tests/sanity/html-validation.test.sh"
  }
}

• dev is still the normal Hugo local server.
• build:hugo renders the static site.
• build adds two earned extras: generated OG images and Pagefind search.
• test runs a small sanity check after rendering.

The real hugo.toml has more settings now, but the important part is this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

baseURL = "https://example.com/"
title = "Example site"
theme = "ink-free"
enableRobotsTXT = true
enableGitInfo = true

[frontmatter]
  lastmod = ["lastmod", ":git", "date", "publishDate"]
  date = ["date", "publishDate", "lastmod"]

[permalinks]
  posts = "/:year/:month/:title"

[outputs]
  home = ["html", "rss"]
  taxonomy = ["html", "rss"]
  term = ["html", "rss"]

[params]
  mainSections = ["posts"]
  enablePagefind = true
  images = ["/images/default-og.png"]

• baseURL is the production URL.
• enableGitInfo lets Hugo use Git history for last-modified dates.
• permalinks preserves stable post URLs.
• outputs keeps HTML and RSS explicit.
• params.images gives Open Graph/social cards a default image.

The production workflow is also the simple workflow with extra checks added:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

name: build, test, audit & deploy site

on:
  push:
    branches: [ master ]
    paths:
      - 'site/content/**'
      - 'site/data/**'
      - 'site/themes/**'
      - 'site/static/**'
      - 'site/assets/**'
      - 'site/layouts/**'
      - 'site/hugo.toml'
      - '.github/workflows/**'
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          submodules: recursive

      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: "0.165.0"
          extended: true

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build Hugo site
        working-directory: site
        run: hugo --gc --minify --cleanDestinationDir

      - name: Run sanity tests
        run: pnpm --filter site run test

      - name: Build search index
        working-directory: site
        run: npx -y pagefind --site public

      - name: Publish static output
        uses: peaceiris/actions-gh-pages@v4
        with:
          publish_dir: ./site/public

• The trigger is scoped to site-related files.
• The workflow checks out the theme submodule.
• Hugo builds site/public.
• Sanity tests run before publishing.
• Pagefind indexes the rendered site.
• The publishing step uploads only static output.

The point is the shape, not my exact deploy target.

Build order, CI/CD, and hosting

Start with the parts that shorten the path from writing to publishing.

GitHub Actions should do one clean build: checkout, install Hugo, build site/public, publish generated output. Local machines lie; CI starts from scratch.

GitHub Pages should only serve built files:

1
2

GitHub Actions builds.
GitHub Pages serves.

For a new site, use the official Pages Actions flow. Move to a gh-pages branch or separate hosting repo only when source and published output must live separately.

For a custom domain: configure DNS, add the domain in Pages settings, enable HTTPS, then update baseURL. If baseURL is wrong, RSS, canonical URLs, social preview images, and absolute links quietly break.

When a backend becomes necessary

Most blogs do not need a backend. Add one only when a feature crosses the static-site boundary:

Cloudflare Workers fit when you want a small API near a static site without managing a server. Workers give you routes, serverless functions, D1 for small SQL state, R2 for object storage, and secrets outside the static build.

The rule I like:

Keep the site static. Put runtime behaviour behind /api/*.

That gives you a clean boundary.

How to add a backend without ruining the static site

The backend should not take over the site. For this site, the production shape is:

flowchart TD
    A["Reader requests page"] --> B["GitHub Pages<br/>static Hugo output"]
    A --> C["/api/* request"]
    C --> D["Cloudflare Worker"]
    D --> E["D1<br/>small SQL state"]
    D --> F["R2<br/>object/archive storage"]
    D --> G["External services<br/>email, gateway, verification"]

    style A fill:#e1f5ff,stroke:#0066cc,color:#000
    style B fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style C fill:#fff4e1,stroke:#cc8800,color:#000
    style D fill:#f0e1ff,stroke:#8800cc,color:#000
    style E fill:#e1f5ff,stroke:#0066cc,color:#000
    style F fill:#e1f5ff,stroke:#0066cc,color:#000
    style G fill:#ffe1e1,stroke:#cc0000,color:#000

The static site and API deploy separately:

• Hugo can build without backend secrets.
• The backend can deploy without rebuilding every article.
• /api/* has its own health checks and tests.
• Cloudflare secrets stay in Cloudflare.
• GitHub Pages remains a static host, not a confused application runtime.

The current backend uses TypeScript, Hono, Effect, Cloudflare Workers, D1, and R2. The libraries matter less than the split:

1
2
3
4

Static content -> Hugo + GitHub Pages
Dynamic edge   -> Cloudflare Worker under /api/*
Stored state   -> D1/R2, only where needed
Secrets        -> Worker/GitHub/Cloudflare secret stores, never Hugo content

That split is also how payment-style flows stay sane:

1
2
3
4

Static page      -> shows content, buttons, and client-safe metadata
Worker endpoint  -> validates request, talks to provider, handles webhooks
D1/R2            -> stores only the state the site actually needs
Secrets          -> stay in Cloudflare, never in Hugo, Markdown, or browser JS

I would not start here. I would start static and add this only when the first real runtime need appears.

Part 2 - The grown-up version: what this site became

Now for the grown-up version. Do not copy this on day one. This is what appears after repeated pain becomes visible: search, validation, social previews, generated data, and a few runtime APIs.

What this site grew into

The current site is still static at the core, but the build and support work around it are more serious:

• Hugo site under site/
• theme as a submodule,
• site-level layout overrides,
• custom render hooks for links, tables, blockquotes, and Mermaid,
• shortcodes for article formatting and site features,
• content validation for frontmatter quality,
• Open Graph image generation,
• Pagefind static search,
• RSS, sitemap, llms.txt, and SEO partials,
• GitHub Actions for deploy, validation, accessibility, Lighthouse, backups, and generated data,
• TypeScript tooling for generated data workflows,
• Cloudflare Worker backend for runtime API paths,
• payment/webhook-style flows kept behind the Worker boundary,
• D1 and R2 for small stored backend state,
• docs and playbooks to keep decisions out of my head.

The current shape looks like this:

flowchart TD
    A["Markdown articles<br/>site/content"] --> B["GitHub repository"]
    B --> C["GitHub Actions<br/>site deploy"]
    C --> D["OG image sync"]
    D --> E["Hugo build"]
    E --> F["Pagefind index"]
    F --> G["GitHub Pages"]

    H["Scheduled/generated data"] --> I["YAML/JSON snapshots<br/>site/data"]
    I --> E

    J["Cloudflare Worker"] --> K["/api/*"]
    K --> L["D1"]
    K --> M["R2"]
    K --> N["External services"]

    O["Docs and playbooks"] --> B

    style A fill:#e1f5ff,stroke:#0066cc,color:#000
    style B fill:#fff4e1,stroke:#cc8800,color:#000
    style C fill:#f0e1ff,stroke:#8800cc,color:#000
    style D fill:#f0e1ff,stroke:#8800cc,color:#000
    style E fill:#f0e1ff,stroke:#8800cc,color:#000
    style F fill:#fff4e1,stroke:#cc8800,color:#000
    style G fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style H fill:#e1f5ff,stroke:#0066cc,color:#000
    style I fill:#e1f5ff,stroke:#0066cc,color:#000
    style J fill:#f0e1ff,stroke:#8800cc,color:#000
    style K fill:#fff4e1,stroke:#cc8800,color:#000
    style L fill:#e1f5ff,stroke:#0066cc,color:#000
    style M fill:#e1f5ff,stroke:#0066cc,color:#000
    style N fill:#ffe1e1,stroke:#cc0000,color:#000
    style O fill:#e1ffe1,stroke:#2d7a2d,color:#000

This came from repeated pain:

• I needed better social previews, so OG automation appeared.
• I needed search without a server, so Pagefind fit.
• I needed consistent article metadata, so validation became useful.
• I needed generated public data, so scheduled workflows wrote Hugo data files.
• I needed runtime API behaviour, so Cloudflare Workers took /api/*.
• I needed to remember how all this works, so docs became part of the system.

That is the healthy order: pain first, automation second.

What I would do again

If I rebuilt this site today, I would keep these:

The underrated part is validation. Hosting gets attention, but long-running sites quietly collect broken metadata: missing authors, long descriptions, uneven tags, bad image fields, broken slugs. A boring validator catches that early.

What I would delay

I would delay almost everything else.

Automation feels productive. Sometimes it is. Sometimes it is just a neat way to avoid writing the next article. The best stack keeps the writing path short.

The decision rule I use now

Here is the decision tree:

flowchart TD
    A["Do you mostly publish content?"] -->|Yes| B["Use Hugo"]
    A -->|No| C["Build an app"]

    B --> D["Can editors work with Git/Markdown?"]
    D -->|Yes| E["Use GitHub Actions + GitHub Pages"]
    D -->|No| F["Add a Git-backed CMS or choose a CMS"]

    E --> G["Need secrets, forms, payments, or webhooks?"]
    G -->|No| H["Stay fully static"]
    G -->|Yes| I["Add backend under /api/*"]

    I --> J["Keep static and dynamic deploys separate"]

    style A fill:#fff4e1,stroke:#cc8800,color:#000
    style B fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style C fill:#ffe1e1,stroke:#cc0000,color:#000
    style D fill:#fff4e1,stroke:#cc8800,color:#000
    style E fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style F fill:#fff4e1,stroke:#cc8800,color:#000
    style G fill:#fff4e1,stroke:#cc8800,color:#000
    style H fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style I fill:#f0e1ff,stroke:#8800cc,color:#000
    style J fill:#e1f5ff,stroke:#0066cc,color:#000

That is the practical answer:

Use the static model while the problem is static. Add runtime pieces only where static stops being honest.

References

• Hugo official site - Hugo positioning, features, community, speed, asset pipeline, and use cases.
• Hugo: Host on GitHub Pages - Official deployment guidance for Hugo and GitHub Pages.
• GitHub Pages publishing source docs - GitHub Pages publishing model and GitHub Actions support.
• Cloudflare Developer Docs - Workers, static assets, D1, R2, and serverless primitives.
• Building a personal website with Hugo and GitHub Pages - Practical example with similar needs: fast, low maintenance, Markdown, version control, automated deploy, low cost.
• Hugo Discourse - Community forum and recurring discussions around Hugo usage, hosting, themes, and maintenance.
• r/gohugo - Practical questions and trade-offs around Hugo’s fit for static blogs, docs, portfolios, CMS workflows, and runtime limits.

TL;DR

• Hugo is a strong fit when the site is mostly content.
• GitHub Actions makes builds repeatable.
• GitHub Pages is enough for static hosting.
• Add search, validation, OG images, and generated data only when the site needs them.
• Add a backend only for secrets, state, forms, payments, webhooks, or runtime APIs.
• Keep runtime behaviour behind /api/*.
• Start static. Evolve only after the pain is real.