SysTutorials

Migrating from WordPress to GitHub Pages: A Practical Guide

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.

WordPress ecosystem vulnerabilities (Q3 2025 – present)

ComponentVulnerabilityImpact
Wordfence (free firewall)Q3 2025 RCE series1M+ sites affected
GutenKit / Hunk CompanionBundled plugin flawArbitrary file upload, admin takeover
Post SMTPCVE‑2025‑11833Unauthenticated mail relay
Alone themeCVE‑2025‑5394Stored XSS on every page
Gravity FormsSupply-chain compromiseCredit-card skimmer in forms
Fluent FormsCVE‑2025‑9260RCE via contact form
WP Fastest CacheCVE‑2025‑42853Unauthenticated file deletion → RCE
LiteSpeed CacheCVE‑2025‑38117Unauthenticated privilege escalation
Elementor ProCVE‑2025‑34972Broken access control → RCE
Ultimate MemberCVE‑2025‑33113Auth bypass → admin account creation

PHP runtime vulnerabilities (2024–2025)

VersionCVETypeWhy it matters for WordPress
PHP 8.3CVE‑2024‑4577CGI argument injection → RCEAffects any PHP-FPM/Apache mod_php setup; WordPress runs on PHP
PHP 8.2/8.3CVE‑2024‑5586php_filter parse error → info leak / DoSInput validation bypass
PHP 8.1–8.3CVE‑2024‑11236phar deserialization → RCEPhar:// wrapper abuse in file uploads
PHP 8.0–8.3CVE‑2024‑8925mbstring heap overflowMultibyte string handling in WP core
PHP 8.2CVE‑2024‑38551openssl private key leakTLS key exposure on shared hosting

Linux kernel & infrastructure (2024–2025)

ComponentCVEImpact
Linux kernelCVE‑2024‑1086netfilter use-after-free → local privilege escalation
Linux kernelCVE‑2024‑26581nftables verification bypass → root
OpenSSHCVE‑2024‑6387regreSSHion — unauthenticated RCE as root
systemdCVE‑2024‑2961resolved DNS parsing → RCE
glibcCVE‑2024‑2961iconv heap overflow → RCE

The compounding risk

A WordPress site exposes all of the above simultaneously:

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.

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.

5. 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).

6. 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.

7. Sitemaps and feeds

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

8. 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.


This post documents the migration that landed in PR #62. The blog post itself was added in PR #66.

← All posts