Developin'

Th' theme be developed across two repositories.

Repository	Contents
hugo-theme-relearn	Th' theme itself, an' th' workflows, release act'ns an' git hooks that act on it.
hugo-theme-relearn-infra	Th' test suite an' th' tool'n that drives it. Noth'n here be shipped t' users.

Th' rule fer decid'n whar' someth'n belongs be a single quest'n: does somebody install'n th' theme need this file? If not, it belongs 'n th' infra repository - unless it can only act from th' theme repository. GitHub runs a workflow only 'n th' repository hold'n it, an' a git hook only fires on th' checkout it sits 'n, so those stay put, along wit' th' act'ns those workflows call.

Whar' t' report

Open issues 'n th' theme repository, even when they concern th' tests or th' tool'n.

Issues, milestones an' releases be all tracked there, an' a release be cut from a milestone 'n that repository. A second tracker would split that history apart.

Why th' Split

For a Cap'n Hugo theme th' repository be th' distributed artifact. Anyth'n committed t' it be downloaded by every user, so a test suite an' a screenshot generator would be dead weight fer every consumer.

Th' docs an' exampleSite directory stay 'n th' theme repository despite not be'n needed t' run th' theme t' make th' theme self-contained an' help t' quickly set up a test installat'n.

Sett'n Up

There be two setups. Pick th' smaller one unless ye need what th' larger one adds - most contribut'ns never do.

Th' Simple Setup

One repository an' Cap'n Hugo. Noth'n else t' install.

git clone https://github.com/McShelby/hugo-theme-relearn.git
cd hugo-theme-relearn/docs
hugo server

That serves th' documentat'n ship, built wit' th' theme itself, so yer changes show up as ye save. Swap docs fer exampleSite t' work against th' simpler starting-point ship instead.

This be enough fer most changes. If that be what ye came t' do, stop here.

Avast

Ye cannot run th' test suite 'n this setup, so yer change gets verified by CI rather than by ye. Take th' second setup if ye want th' answer before push'n.

Th' Full Setup

Add th' infra repository as a sibl'n o' th' theme. This be what ye need t' run th' test suite, regenerate th' screenshots, or change th' CI workflows.

hugo-theme-relearn/
hugo-theme-relearn-infra/

cd hugo-theme-relearn-infra
npm ci
npm test

Th' tool'n finds th' theme by look'n at th' RELEARN_THEME_DIR environment vari'ble, then a sibl'n directory named hugo-theme-relearn, then th' parent directory. Th' theme be never copied into th' infra repository, so th' tests always run against a real checkout.

T' point th' tool'n at a checkout somewhere else:

RELEARN_THEME_DIR=/path/to/hugo-theme-relearn npm test

Git Hooks

Optional, an' independent o' which setup ye chose - th' hooks live 'n th' theme repository, 'n th' .githooks root folder. Documentat'n fer each hook be contained 'n each file.

Th' post-commit hook updates th' version number on each commit, which be what makes a build from main distinguish'ble from a release when debugg'n user reports. Noth'n depends on ye hav'n it.

#!/bin/sh
python3 .githooks/post-commit.py

Work'n Across Both Repositories

Only this repository triggers test runs; th' infra repository triggers noth'n.

A change spann'n both - a theme change that alters what th' tests expect - takes th' same branch name 'n each, an' th' infra branch be pushed first. Th' single run th' push here then starts sees both halves. Th' other way round it pairs against infra main an' can pass while test'n only half th' change; noth'n detects that, so th' order be th' safeguard.

A change t' th' suite alone - a runner refactor, a regenerated baseline - never reaches this repository, so noth'n triggers. Start a run from th' Act'ns tab an' name th' infra branch 'n infra_ref.

Each workflow be described on th' plank fer th' th'n it does: th' test suite an' releases.