SysTutorials

How to Migrate WordPress to GitHub Pages with Hugo

We migrated SysTutorials — 1,346 blog posts plus 56,253 Linux man pages — from WordPress to a Hugo static site on GitHub Pages. The result: a single binary, single config, single CI job that builds in ~8 seconds (down from 12 minutes), zero URL drift, free hosting, and a completely static attack surface with no PHP, no database, and no plugin stack to maintain.

Why migrate from WordPress to a static site on GitHub Pages

Maintenance burden eliminated

Running WordPress means constant upgrades (core, plugins, themes), backups, database monitoring, PHP version management, and server patching. A static site on GitHub Pages removes all of that:

Security: the final push

Running WordPress means running a full PHP stack — and that stack has been under relentless attack. Between Q3 2025 and today, the combined vulnerability surface across WordPress core, plugins, themes, and PHP itself made the risk untenable.

The compounding risk: A WordPress site exposes PHP runtime, WordPress core (1M+ lines of PHP), 60k+ plugins/themes (frequent supply-chain compromises like Gravity Forms, WP Fastest Cache, LiteSpeed Cache), web server config, MySQL database, and the OS kernel — all simultaneously.

Recent critical examples (2024–2025):

Static sites eliminate the entire PHP+WordPress+plugin+database stack. The only remaining surface is the CDN (GitHub Pages) serving static HTML/CSS/JS — no interpreter, no database, no plugin architecture, no dynamic code execution.

Why Hugo over Jekyll

We originally ran Jekyll on GitHub Pages. Hugo won for four reasons:

  1. Build speed — ~8 seconds vs 12 minutes for 57k pages. Hugo’s parallel rendering and single-binary architecture scale linearly; Jekyll’s Ruby pipeline does not.

  2. No Ruby dependency — GitHub Pages’ Jekyll version is pinned and lags. Hugo is a single binary we control; upgrades are a one-line CI change.

  3. Module mounts — Merging the separate man-site (56k pages) into the main repo required Hugo’s [module.mounts]. Jekyll has no equivalent; we’d need artifact merging across repos.

  4. Taxonomy & permalink parity — Hugo’s [permalinks] and [taxonomies] config mirrors WordPress’s /category/slug/ and /author/slug/ exactly. Jekyll needs plugins for the same.

How to migrate: step-by-step

This is the exact process we used for SysTutorials (1,346 posts, ~56k Linux man pages).

1. Export from MariaDB/MySQL

WordPress stores everything in MySQL/MariaDB. We used a direct database dump instead of the WXR export — it gives full control over every field and avoids XML parsing issues.

# Dump the WordPress database
mysqldump -u wp_user -p wp_database > wp_dump.sql

# Or if using a managed host, use their backup tool to get a .sql file

Then extract the key tables:

2. Convert database rows to Markdown with front matter

We wrote a Python script that reads the SQL dump (via mysql-connector-python or by loading into a local MariaDB instance) and:

# Key: canonical URL becomes Hugo's url: front matter
# This guarantees zero URL drift
front_matter["url"] = front_matter["canonical"]

3. Clean the Markdown

WordPress content contains shortcodes ([gallery], [caption], etc.), inline styles, and HTML that won’t render in Hugo. Strip or convert them:

# Remove WordPress shortcodes
sed -i 's/\[caption.*\]//g' *.md
sed -i 's/\[\/caption\]//g' *.md
# Convert [gallery] to simple markdown lists
# ... custom rules per site

4. Organize content structure

content/
  posts/           # all blog posts (YYYY-MM-DD-slug.md)
  _index.md        # home page
  archive/         # year/month archives (auto-generated by Hugo)
  tools/           # static tool pages (e.g., BBCode editor)
  man/             # mounted from man-src/ (see step 7)
data/
  authors.yml      # author slug → display name
  topics.yml       # category taxonomy metadata
static/
  files/           # uploaded assets (images, PDFs)
  docs/linux/man/man.css

hugo.toml key sections:

[taxonomies]
  category = "categories"
  author = "authors"

[permalinks.term]
  categories = "/category/:slug/"
  authors = "/author/:slug/"

[frontmatter]
  lastmod = ["modified", "date"]

This mirrors WordPress’s /category/slug/ and /author/slug/ URLs exactly.

6. Preserve canonical URLs for every post

Every post must have both url: and canonical: in front matter:

---
title: "Post Title"
date: 2026-01-15
url: /my-canonical-slug/
canonical: /my-canonical-slug/
---

The url: field tells Hugo where to render the page. The canonical: field is used in <link rel="canonical"> and Open Graph tags. We derived both from the original WordPress permalink (stored in wp_postmeta by the SEO plugin).

7. Merge separate sites with module mounts

SysTutorials had a separate man-site/ Hugo instance for ~56k Linux man pages. We merged it into the main site:

[module]
  [[module.mounts]]
    source = "man-src"
    target = "content/man"

Now one hugo --minify builds everything. The man pages keep their /docs/linux/man/ URLs.

8. Sitemaps and feeds

Fix: the man sitemap index had a bug pointing to /docs/docs/sitemap-N.xml — corrected to /docs/sitemap-N.xml.

9. CI/CD: one build step

GitHub Actions workflow (.github/workflows/pages.yml):

- uses: peaceiris/actions-hugo@v3
  with:
    hugo-version: 'latest'
- run: python3 scripts/gen-man-page-length.py man-src data
- run: hugo --minify
- run: python3 scripts/gen-man-sitemap.py public/docs public/docs
- run: touch public/.nojekyll

Result: ~8 seconds vs 12 minutes previously. No Ruby, no Jekyll, no artifact merging.

Tools and configuration summary

ToolPurpose
Hugo (extended)Static site generator
Python + MariaDB connectorDB dump → Markdown conversion
GitHub ActionsCI/CD (free for public repos)
GitHub PagesHosting (free, TLS, CDN)
GitVersion control + backup

Key config files to copy/adapt:

AI-assisted migration

This entire migration was driven by OpenCode with GLM 5.3 / 5.3-Flash (via Z.AI’s coding plan). The AI handled:

Human role: strategic decisions (URL structure, taxonomy design), final review, and gh pr create.

Result: SysTutorials on GitHub Pages

The site is live at systutorials.com — this very post you’re reading is served from the Hugo + GitHub Pages stack.

To leave comments or report issues, please create a PR or report an issue at https://github.com/nv2n1/nv2n1.github.io.

← All posts