Thanks for helping improve Ananke. This document describes the current contribution workflow for this repository.
i18n/*.tomlThe project follows a structured release workflow based on conventional commits, staging branches, and automated versioning.
For details, see Branch Strategy. Publish a stable theme release from main before publishing the matching documentation. The documentation production build resolves the latest stable theme without changing its checked-in dependency files; preview builds can select an unreleased ref. Follow the release and publication order, and confirm the resolved theme version in the documentation build log.
config/_default/module.toml for the current state).npm install
npm run instead of just calling hugo server:npm run dev
This runs the sibling documentation/ site with the local Ananke working tree. Keep both repositories next to each other, install the documentation dependencies, and use Node.js 22.18 or later. The calling repository stays on its branch: main selects the companion's main, development selects development, and other named branches select the same local branch in the companion when it exists. Otherwise, they select development. The launcher prints both branches and any switch it makes, and stops if the companion needs switching but has uncommitted or untracked changes (excluding scratch/). Stop the server before selecting another branch pair. You can run the same command from either repository; see the documentation development guide.
Follow the coding style and format commit messages as described in the conventional commits specification (for example: docs: add troubleshooting section or fix: correct hero image path).
Make sure to install git hooks for linting and testing before you push changes:
npm run prepare
This command is run automatically after npm install but you can run it manually to set up hooks in an existing clone or update changed hooks. It uses simple-git-hooks to install a commit hook that runs lint-staged for markdown files, which in turn runs linting tasks on staged files.
hugo version, OS, browser if relevant).flowchart LR
feature["feature/*, fix/*, docs/*, refactor/*"] --> development
development --> main
main --> development
This repository uses a linear, rebase-based branch model. Long-lived branches MUST stay connected to main, and merge commits MUST NOT be introduced.
| Branch | Purpose | Release role | Write policy | Merge |
|---|---|---|---|---|
main |
Stable source of truth | releases | Protected. Only receives reviewed PRs from development. |
Rebase |
development |
Active development | pre-releases | Feature, fix, chore, and documentation PRs target this branch. | Squash |
Use short-lived branches for regular work:
feat/<topic>fix/<topic>docs/<topic>chore/<topic>refactor/<topic>After a successful rebase between those branches, push with lease:
git push --force-with-lease
Run the relevant theme test commands for each change and register changed parameters or shortcodes in tests/catalog.yaml. npm test uses the Node test runner and feature mini-sites; browser, static, visual, and Lighthouse checks have separate commands. The coverage gate checks registration and test paths, not complete behavioural coverage.
Follow the manual testing guide after relevant UI changes and for release candidates. Record the tested commit, environment, scope, and findings in the pull request or release record. Initial screenshot approval establishes a starting point; changed screenshots and relevant accessibility behaviour need fresh review.
npm run lint:markdown
hugo or hugo server in the relevant project).Fixes #123).To prevent git commit and git push from running hooks you can use the --no-verify flag:
git commit --no-verify -m "docs: update README"
git push --no-verify origin my-feature-branch
This should be used sparingly and only when you have a good reason to bypass checks. If you find yourself needing to use --no-verify frequently, please consider improving the hooks or contributing fixes to reduce false positives.
The theme documentation lives in a separate repository at gohugo-ananke/documentation.
Please keep links relative where possible and remove stale references when updating pages.
If you want to receive attribution for your contribution please follow the contribution guidelines to add yourself to the list of contributors in the Ananke theme documentation. A permanently open issue to add your contribution can be found at the documentation repository. Read the initial message to understand how to add yourself to the list of contributors.
By contributing, you agree that your contributions are provided under the repository license in LICENSE.md.