stharrold.github.io

Source for Data Science Demos, a blog built with Pelican and deployed to GitHub Pages by GitHub Actions.

Quick start

Requirements: uv (Python 3.12+). All dependencies are pinned in pyproject.toml and uv.lock.

uv sync                                         # install Pelican, plugins, Pagefind, dev tools
uv run pre-commit install                       # once: ruff and file checks on commit
uv run pelican --settings pelicanconf.py        # build the dev site into output/ (drafts included, no analytics)
uv run python -m pagefind --site output         # build the search index (rerun after each build)
uv run pelican --listen                         # serve output/ at http://localhost:8000
uv run pytest                                   # build the publish site in a temp dir and check it

uv run pelican --settings pelicanconf.py --autoreload --listen rebuilds on every change, but each rebuild deletes output/pagefind/, so search only works after rerunning Pagefind. Stop it with Ctrl-C; killing only the parent process leaves its file watcher running.

Branches and deployment

Branch	Purpose
src_master	Production source. Every push builds, tests, and deploys the site (.github/workflows/pages.yml).
src_develop	Integration branch; pushes run the same checks without deploying.
src_feature_*	Feature branches off src_develop (git-flow); merged with --no-ff.
(tag) legacy-ghp-import-master	The former master branch, which held the built site (via ghp-import) until 2026-10-06.

To release: merge src_feature_* into src_develop, then src_develop into src_master, and push. The workflow runs ruff, pytest, pelican --settings publishconf.py --fatal warnings, and Pagefind, then deploys output/. GitHub Pages must be set to Settings > Pages > Source: GitHub Actions. output/ is generated and not tracked.

To verify a deploy, wait for the run (gh run watch <id>; find it with gh run list --workflow pages.yml --json databaseId,headSha), then check the live site with a cache-busting query, e.g. curl -s "https://stharrold.github.io/?v=$(date +%s)". For visual changes, compare before/after screenshots of a local dev build served with python3 -m http.server before merging to src_master.

Automation:

• .github/workflows/links.yml logs internal and external link status every Monday (and on manual dispatch) against a fresh build: a job summary plus a link-report JSON artifact kept 90 days. It is report-only (never fails, files no issues); alerting belongs to whatever reads the log. Dead links in the frozen 2015-2016 posts are left as is. GitHub disables scheduled workflows in public repos after 60 days without repository activity, so the log can stop silently on a quiet blog; re-enable with gh workflow enable links.yml (see #67).
• Dependabot (.github/dependabot.yml) opens weekly grouped PRs for GitHub Actions and Python packages against src_develop; security fixes target src_master, so review them as deploys. Actions are pinned to commit SHAs.
• Vendored theme files and the MathJax CDN version are not covered by Dependabot; see themes/README.md.

pelicanconf.py holds the site settings; publishconf.py extends it for production (absolute URLs, feeds, GA4, no drafts).

Writing posts

Posts are Markdown files in content/ with a metadata header (Title, Date, Modified, Category, Tags, Slug, Summary, optional Related_posts and Alias for old URLs). Pages go in content/pages/. Notebooks, notebook HTML exports, and images go in content/static/<slug>/ and are linked with {static}/static/<slug>/....

• Drafts: Status: draft renders only in dev builds (output/drafts/). Static files are copied regardless of status, so add a draft's static/<slug> folder to STATIC_EXCLUDES in publishconf.py, and remove it when the post is published.
• Math: $...$ inline and $$...$$ display (as its own paragraph); rendered by MathJax 4. Prices such as $20 are left alone.
• Old posts: posts last updated 5+ years before the build year show an "out of date" notice (OUTDATED_AFTER_YEARS).
• Before pushing: run uv run pytest. Deploys stop on any Pelican warning (for example a broken {filename}/{static} link) or failed test. The tests derive what to expect from content/, so new and newly published posts need no test changes; publishing a draft that has a STATIC_EXCLUDES entry fails with a message saying which entry to remove.

This is the beginning of the README. Read the rest at the original. Read the full README ↗