Skip to content

README.md

Latest commit

 

History

History
77 lines (50 loc) · 2.7 KB

README.md

File metadata and controls

77 lines (50 loc) · 2.7 KB

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://mathieson.github.io/blog/

Prerequisites

Tool Version Install
Hugo (extended) ≥ 0.120 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.

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