Developing

The theme is developed across two repositories.

The rule for deciding where something belongs is a single question: does somebody installing the theme need this file? If not, it belongs in the infra repository - unless it can only act from the theme repository. GitHub runs a workflow only in the repository holding it, and a git hook only fires on the checkout it sits in, so those stay put, along with the actions those workflows call.

Why the Split

For a Hugo theme the repository is the distributed artifact. Anything committed to it is downloaded by every user, so a test suite and a screenshot generator would be dead weight for every consumer.

The docs and exampleSite directory stay in the theme repository despite not being needed to run the theme to make the theme self-contained and help to quickly set up a test installation.

Setting Up

There are two setups. Pick the smaller one unless you need what the larger one adds - most contributions never do.

The Simple Setup

One repository and Hugo. Nothing else to install.

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

That serves the documentation site, built with the theme itself, so your changes show up as you save. Swap docs for exampleSite to work against the simpler starting-point site instead.

This is enough for most changes. If that is what you came to do, stop here.

The Full Setup

Add the infra repository as a sibling of the theme. This is what you need to run the test suite, regenerate the screenshots, or change the CI workflows.

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

The tooling finds the theme by looking at the RELEARN_THEME_DIR environment variable, then a sibling directory named hugo-theme-relearn, then the parent directory. The theme is never copied into the infra repository, so the tests always run against a real checkout.

To point the tooling at a checkout somewhere else:

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

Git Hooks

Optional, and independent of which setup you chose - the hooks live in the theme repository, in the .githooks root folder. Documentation for each hook is contained in each file.

The post-commit hook updates the version number on each commit, which is what makes a build from main distinguishable from a release when debugging user reports. Nothing depends on you having it.

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

Working Across Both Repositories

Only this repository triggers test runs; the infra repository triggers nothing.

A change spanning both - a theme change that alters what the tests expect - takes the same branch name in each, and the infra branch is pushed first. The single run the push here then starts sees both halves. The other way round it pairs against infra main and can pass while testing only half the change; nothing detects that, so the order is the safeguard.

A change to the suite alone - a runner refactor, a regenerated baseline - never reaches this repository, so nothing triggers. Start a run from the Actions tab and name the infra branch in infra_ref.

Each workflow is described on the page for the thing it does: the test suite and releases.