How I migrated to Minimal-Mistakes
This site ran on Jekyll’s default Minima theme for three years. It worked, but 150 posts in one long date-ordered list made it hard to find anything. Over a weekend I moved it to Minimal Mistakes, sorted every post into topics, kept every old link working, and set it up so each push also publishes a copy to www.highserv.com on my VeeroTech hosting.
This is the whole process, in the order I’d do it again.
The Plan
- Snapshot the existing site so rollback is one command.
- Get a local Jekyll build that matches GitHub Pages exactly.
- Do the migration on a branch, previewed locally, while the live site stays untouched.
- Merge when it looks right.
- Add automatic publishing to a second host.
1. Snapshot the Current Site
Before touching anything, freeze the current state three ways: a tag, a branch, and a downloadable release.
cd ~/dev/pspowell.github.io
git pull
git tag -a minima-final-2026-11-14 -m "Site as-is before Minimal Mistakes"
git push origin minima-final-2026-11-14
git branch archive/minima && git push origin archive/minima
Then on GitHub: Releases → Draft a new release, choose the tag, give it a title, and Publish release. GitHub attaches a zip of the whole site automatically, which makes a handy offline copy.
If anything ever goes badly wrong:
git checkout main && git reset --hard origin/archive/minima && git push --force
2. A Local Build That Matches GitHub Pages
I build on Windows 11 under WSL2. The full setup is in Installing Jekyll on WSL. The two things that matter most:
- Use GitHub’s Ruby version and the
github-pagesgem, not a globalgem install jekyll. GitHub Pages runs Jekyll 3.10 on Ruby 3.3; a global install gives you Jekyll 4 and builds that don’t match. Current versions are listed at pages.github.com/versions. - Keep the repo in the Linux filesystem (
~/dev), not under/mnt/c. Builds are much faster and live reload actually notices your edits.
My Gemfile is just:
source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins
gem "webrick" # needed by `jekyll serve` on Ruby 3.x
My old Gemfile.lock pinned Jekyll 4 from years ago and conflicted with github-pages, so I deleted it and let bundle install generate a fresh one.
3. Work on a Branch, Preview Side by Side
GitHub Pages builds only main, so I did all the theme work on a minimal-mistakes branch. To preview it without disturbing my normal working folder, I gave the branch its own folder with a git worktree, and added two shortcuts to ~/.bashrc:
MM_MAIN="$HOME/dev/pspowell.github.io"
MM_DIR="$HOME/dev/pspowell.github.io-mm"
MM_BRANCH="minimal-mistakes"
# mpull: create/update the branch's preview folder
mpull() {
git -C "$MM_MAIN" fetch origin "$MM_BRANCH" || return
if [ ! -d "$MM_DIR" ]; then
if [ "$(git -C "$MM_MAIN" branch --show-current)" = "$MM_BRANCH" ]; then
git -C "$MM_MAIN" checkout main || return
fi
if git -C "$MM_MAIN" show-ref --verify --quiet "refs/heads/$MM_BRANCH"; then
git -C "$MM_MAIN" worktree add "$MM_DIR" "$MM_BRANCH" || return
else
git -C "$MM_MAIN" worktree add --track -b "$MM_BRANCH" "$MM_DIR" "origin/$MM_BRANCH" || return
fi
fi
cd "$MM_DIR" || return
git pull --ff-only origin "$MM_BRANCH" || return
bundle config set --local path "$MM_MAIN/vendor/bundle" # share installed gems
bundle check >/dev/null 2>&1 || bundle install
}
# mserve: preview the branch on port 4001
mserve() {
cd "$MM_DIR" 2>/dev/null || { echo "Run mpull first."; return 1; }
(sleep 8 && explorer.exe http://localhost:4001) &
bundle exec jekyll serve --livereload --port 4001 --livereload-port 35730 "$@"
}
With that, the live version runs on localhost:4000 and the new theme on localhost:4001, side by side.
4. Configure Minimal Mistakes
Minimal Mistakes works on GitHub Pages as a remote theme, so there’s nothing to install. The key parts of my _config.yml:
remote_theme: "mmistakes/minimal-mistakes@4.28.1" # pinned so theme updates can't break the site
minimal_mistakes_skin: "default"
search: true
breadcrumbs: false # post breadcrumbs link to /YYYY/ pages that don't exist
plugins:
- jekyll-remote-theme
- jekyll-paginate
- jekyll-sitemap
- jekyll-gist
- jekyll-feed
- jekyll-include-cache
- jekyll-redirect-from
paginate: 10
paginate_path: /page:num/
category_archive:
type: liquid
path: /categories/
tag_archive:
type: liquid
path: /tags/
defaults:
- scope:
path: ""
type: posts
values:
layout: single
author_profile: true
read_time: true
share: true
related: true
toc: true
toc_sticky: true
toc_label: "On this page"
I also filled in the author: block (name, photo, bio, links), which becomes the sidebar on every post.
Pin the theme version. @4.28.1 means an upstream change can’t break the site overnight. Bump it on purpose when you want new features.
5. Sort the Posts into Topics
The biggest improvement was organizing 146 posts into nine topics:
| Topic | What’s in it |
|---|---|
| Windows & PC Help | Fixing, imaging, upgrading Windows |
| Coding & Automation | PowerShell, Python, Docker, Excel, Jekyll |
| AI & Chat Tools | ChatGPT, Claude, Gemini |
| Money & Retirement | Social Security, Medicare, taxes, investing |
| Kitchen & Recipes | Breads, barbecue, cocktails |
| Home, Shop & DIY | Woodworking, welding, tractors |
| Health & Safety | Health, privacy, rights |
| Local Interest | Champaign County topics |
| Life & Leisure | Careers, games, sports, hobbies |
Each post gets exactly one category in its front matter:
categories: ["Home, Shop & DIY"]
Each topic also gets its own page in _pages/, using the theme’s category layout:
---
title: "Home, Shop & DIY"
layout: category
permalink: /categories/home-shop-diy/
taxonomy: "Home, Shop & DIY"
entries_layout: list
---
Then there’s an all-topics page (layout: categories, permalink /categories/), a tags page, a posts-by-year page, and a search page. The top menu lives in _data/navigation.yml.
The home page (index.html, which must be HTML for pagination to work) uses layout: home with a feature_row of nine topic tiles, each with a Browse button, followed by the ten most recent posts.
6. Keep Every Old Link Working
This was the part most worth getting right. Jekyll’s default URL pattern puts a post’s categories in its address:
/:categories/:year/:month/:day/:title.html
Most of my posts had no categories, so their URLs were just /2025/11/23/.... A few older ones had categories like tech or recipes, giving /tech/2023/11/23/.... If I had added the new categories under the default pattern, every post’s URL would have changed.
The fix:
-
Drop categories from the URL pattern. Posts that never had categories keep exactly the same address.
permalink: /:year/:month/:day/:title:output_ext -
Redirect the posts that did have categories. For those 19 posts, add their old address with the
jekyll-redirect-fromplugin, which GitHub Pages supports:redirect_from: - "/tech/2023/11/23/Activate-Windows-God-Mode.html" -
Pin the time zone. A post dated late in the evening Eastern time falls on the next day in UTC, which is what GitHub builds in. Setting
timezone: Etc/UTCmakes local builds produce the same dates, and the same URLs, as GitHub.
Check your old URLs against the live site before you merge. A post’s URL date comes from its front-matter date:, not the filename, and time zones can shift it by a day. I confirmed each redirect target against the live site.
7. Clean Up the Front Matter
A few things that worked in Minima break or look wrong in Minimal Mistakes:
- Remove
layout: postandlayout: page. Minimal Mistakes has neither layout, so those posts render without styling. With thedefaults:block above, posts don’t need alayout:line at all. - Don’t repeat the title as a
#heading. The theme already shows the title, so a body that starts with# Same Titledisplays it twice. I removed those. - Add an
excerpt:. Post lists show the excerpt, and the default is the first paragraph. For posts that open with a heading or a code block, that’s useless, so I added a one- or two-sentenceexcerpt:to each post. - Fix leftovers such as
**inside titles.
With 146 posts, I scripted these edits rather than doing them by hand, then reviewed the diff before committing.
8. Merge and Go Live
After previewing with mserve, merging is a normal pull request:
- On GitHub, click Compare & pull request for the branch (or Pull requests → New pull request with base
mainand compareminimal-mistakes). - Click Create pull request, then Merge pull request, then Confirm merge.
- Watch Actions (or Deployments → github-pages) for the build to go green, about 1–2 minutes.
- Press Ctrl+F5 on the live site, because browsers and the CDN cache the old pages for a few minutes.
9. Auto-Publish a Copy to My Own Host
I also wanted the same site at www.highserv.com, hosted on VeeroTech (cPanel, LiteSpeed). Instead of uploading by hand, a GitHub Actions workflow builds the site with that domain’s settings and syncs it over SSH every time main changes. GitHub Pages keeps building separately, as before.
Domain-specific build settings
A second config file overrides only the URL, so canonical links, the sitemap and redirects point to the right domain:
# _config.highserv.yml
url: "https://www.highserv.com"
It’s used by building with --config _config.yml,_config.highserv.yml, and listed under exclude: in _config.yml so it isn’t published.
An .htaccess (added to include: in _config.yml, since Jekyll skips dotfiles) handles the server side:
ErrorDocument 404 /404.html
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{REQUEST_URI} !^/\.well-known/
RewriteCond %{HTTPS} off [OR]
RewriteCond %{HTTP_HOST} !^www\. [NC]
RewriteRule ^ https://www.highserv.com%{REQUEST_URI} [L,R=301]
</IfModule>
The .well-known exception keeps cPanel’s free SSL certificates renewing. GitHub Pages ignores the file.
A deploy-only SSH key
Use a key just for GitHub, never your personal one. In WSL:
ssh-keygen -t ed25519 -f ~/.ssh/highserv_deploy -N "" -C "github-actions-highserv"
cat ~/.ssh/highserv_deploy.pub
In cPanel, go to SSH Access → Manage SSH Keys → Import Key, paste the public key, then Manage → Authorize. Then capture the server’s host key so the workflow can verify it’s talking to the right machine:
ssh-keyscan -p PORT your.server.name
Secrets and a safety switch
In the repo, under Settings → Secrets and variables → Actions:
| Secrets tab | Value |
|---|---|
HIGHSERV_SSH_KEY |
the private key (cat ~/.ssh/highserv_deploy) |
HIGHSERV_KNOWN_HOSTS |
the ssh-keyscan output |
HIGHSERV_HOST |
server name |
HIGHSERV_PORT |
SSH port |
HIGHSERV_USER |
cPanel username |
On the Variables tab, HIGHSERV_LIVE controls whether the workflow really uploads. Anything other than true, or no variable at all, means dry run: the workflow shows what it would change and uploads nothing.
The workflow
.github/workflows/deploy-highserv.yml:
name: Deploy to highserv.com
on:
push:
branches: [main]
workflow_dispatch:
inputs:
dry_run:
description: "Dry run (show changes, upload nothing)"
type: boolean
default: true
concurrency:
group: deploy-highserv
cancel-in-progress: false
permissions:
contents: read
jobs:
deploy:
runs-on: ubuntu-24.04
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- uses: ruby/setup-ruby@v1
with:
ruby-version: "3.3"
bundler-cache: true
- name: Build for www.highserv.com
env:
JEKYLL_ENV: production
run: bundle exec jekyll build --config _config.yml,_config.highserv.yml
- name: Set up SSH key
env:
SSH_KEY: ${{ secrets.HIGHSERV_SSH_KEY }}
KNOWN_HOSTS: ${{ secrets.HIGHSERV_KNOWN_HOSTS }}
run: |
install -m 700 -d ~/.ssh
printf '%s\n' "$SSH_KEY" > ~/.ssh/highserv
chmod 600 ~/.ssh/highserv
printf '%s\n' "$KNOWN_HOSTS" > ~/.ssh/known_hosts
- name: Sync to server
env:
HOST: ${{ secrets.HIGHSERV_HOST }}
PORT: ${{ secrets.HIGHSERV_PORT }}
USER: ${{ secrets.HIGHSERV_USER }}
LIVE: ${{ vars.HIGHSERV_LIVE }}
MANUAL_DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
run: |
DRY="--dry-run"
if [ "$LIVE" = "true" ] && [ "$MANUAL_DRY_RUN" != "true" ]; then DRY=""; fi
echo "Mode: ${DRY:-LIVE UPLOAD}"
rsync -az --delete --itemize-changes $DRY \
--exclude '.well-known' --exclude 'cgi-bin' \
-e "ssh -i ~/.ssh/highserv -p $PORT -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes" \
_site/ "$USER@$HOST:public_html/"
- name: Remove SSH key
if: always()
run: rm -f ~/.ssh/highserv
Two details that matter:
- Pin the runner.
ubuntu-latestmoved to a release wheresetup-rubydidn’t have Ruby 3.3.x yet, so the build failed at the Ruby step.ubuntu-24.04withruby-version: "3.3"is stable. --deletemakespublic_htmlan exact copy of the site. Anything else in that folder gets removed. Run a dry run first and read every*deletingline in the log. Anything you want to keep (other scripts, an FTP account’s folder, server config files) gets its own--exclude.
Going live
- Push the workflow. The first run is a dry run. Open Actions → Deploy to highserv.com → Sync to server and review the changes.
- Add
--excludeentries until the dry run shows 0 deletions of anything you care about. - Back up
public_htmlfrom the server:ssh highserv 'tar czf ~/public_html-backup-$(date +%F).tgz public_html' - Create the variable
HIGHSERV_LIVE=true. - Actions → Deploy to highserv.com → Run workflow, untick Dry run, and run it.
From then on, every push updates both sites within a couple of minutes.
10. Rules for Future Posts
To keep new posts consistent, I added a CLAUDE.md to the repo root (and to exclude: so it isn’t published). It records the conventions: filename format, front matter with exactly one of the nine categories, no layout: line, no repeated title heading, and the settings that must not change because URLs depend on them (permalink, timezone, category names). It’s written for my AI assistant, but it’s just as useful as a checklist for me.
A new post now looks like this:
---
title: "Post Title"
date: 2026-11-15 16:00:00 -0500
categories: ["Coding & Automation"]
tags: [jekyll, github-pages]
excerpt: "One or two sentences for post lists and search results."
---
Intro paragraph...
## First Section
Checklist
- Tag, branch and release snapshot of the old site
- Local build with the
github-pagesgem and GitHub’s Ruby version - Theme work on a branch, previewed with a worktree
remote_themepinned to a version- One category per post, with category pages and navigation
permalinkwithout:categories, plusredirect_fromfor posts whose URLs changedtimezone: Etc/UTCso local and GitHub dates agreelayout: post/layout: pageremoved; excerpts added- Old URLs spot-checked on the live site after merging
- Second host: separate config, deploy-only key, secrets, dry run, excludes, then live