Mat's Mind Dump

A static blog built with Hugo and the PaperMod theme, deployed to GitHub Pages. Comments are powered by Giscus (GitHub Discussions). Originally migrated from WordPress.

Live site: https://matfacer.com/

---

Prerequisites

Tool	Version	Install
Hugo (extended)	0.155.3 (CI pin; ≥ 0.120 works locally)	brew install hugo (macOS)
Git	any	Required for theme submodule

After cloning, initialise the PaperMod theme submodule:

git submodule update --init --recursive

---

Local preview

./preview.sh
# or: hugo server -D --source site

Open http://localhost:1313. The -D flag includes draft posts.

Draft posts have draft = true in their frontmatter. They are visible locally with -D but excluded from production builds. To publish a draft, change draft = true → draft = false.

---

Writing a new post

hugo new posts/my-post-title --source site

This creates site/content/posts/my-post-title/index.md from the archetype in site/archetypes/posts/, pre-filled with title, date, empty tags, and draft = true. Write the post, fill in description (used for search-engine and social-share previews), set draft = false, then commit and push — the site deploys automatically.

Images live next to the post (e.g. site/content/posts/my-post-title/images/) and are referenced relatively: ![alt](images/foo.png).

---

Giscus comments setup

1. Enable Discussions: repo Settings → Features → Discussions.
2. Install the Giscus GitHub App and grant it access to your repo.
3. Visit https://giscus.app, enter your repo name, and copy the generated values.
4. Paste repo, repoId, category, and categoryId into the [params.giscus] block in site/hugo.toml.

Seed comments from WordPress (optional)

If migrating from WordPress, run migrate_comments.py to import comments as GitHub Discussion replies:

uv run --with requests migrate_comments.py \
  --xml <your-wordpress-export.xml> \
  --repo mathieson/blog \
  --category Announcements \
  --base-path blog \
  --token <your-github-pat>

A GitHub personal access token with repo and discussions:write scopes is required. Create one at https://github.com/settings/tokens.

---

Deploy to GitHub Pages

Deployment is fully automated via GitHub Actions (.github/workflows/deploy.yml). Every push to main triggers a build-and-deploy pipeline:

1. Checks out the repo (including the PaperMod submodule)
2. Installs Hugo extended
3. Runs hugo --source site
4. Publishes the output to GitHub Pages

One-time GitHub setup

Before the workflow can deploy, configure Pages in your repo:

1. Go to repo Settings → Pages
2. Under Build and deployment → Source, select GitHub Actions

After that, every push to main will deploy automatically. The live URL appears in the Actions run log and on the Pages settings page.