Contributing to Ananke

Thanks for helping improve Ananke. This document describes the current contribution workflow for this repository.

• Ways to Contribute
• Release Process
• Before You Start
• Reporting Bugs and Requesting Features
• Pull Request Workflow
• Circumventing Git Hooks
• Documentation Contributions
• Attribution
• License

Ways to Contribute

• Report bugs
• Suggest enhancements
• Improve documentation
• Improve templates, styles, or assets
• Improve translations in i18n/*.toml

Release Process

The project follows a structured release workflow based on conventional commits, staging branches, and automated versioning.

For details, see RELEASES.md.

Before You Start

1. Use a compatible Hugo version (see config/_default/module.toml for the current state).
2. Install dependencies:

bash npm install

1. Run a local preview via npm run instead of just calling hugo server:

bash npm run server

This runs the documentation site from site/ using contents from docs/ with local configuration.

1. 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).

2. Make sure to install git hooks for linting and testing before you push changes:

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

Reporting Bugs and Requesting Features

• Open bugs in GitHub Issues.
• Start feature or idea discussions in GitHub Discussions.
• Include clear reproduction steps, expected behaviour, actual behaviour, and versions (hugo version, OS, browser if relevant).

Pull Request Workflow

1. Fork the repository and create a focused branch.
2. Keep the change set small and cohesive (which means, DO NOT introduce multiple changes in a single PR).
3. Update docs for all user-facing changes.
4. Run quality checks locally:

bash npm run lint:markdown

1. If your change affects behaviour, validate with Hugo locally (for example hugo or hugo server in the relevant project).
2. Open a pull request with:

• a clear summary,
• motivation/context,
• screenshots when UI/visual output changes,
• linked issues (for example: Fixes #123).

Circumventing Git Hooks

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.

Documentation Contributions

Documentation lives in multiple places:

• Main project overview: README.md
• Contributor docs: CONTRIBUTING.md
• Theme docs content: docs/

Please keep links relative where possible and remove stale references when updating pages.

Attribution

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.

License

By contributing, you agree that your contributions are provided under the repository license in LICENSE.md.