Contributing

Help improve KubeClaw and its documentation.

1: Development Setup
2: Code of Conduct

Read the contribution guidelines, development setup, and project conventions.

Documentation is built with Hugo and the pinned Docsy theme. Use ./scripts/serve-docs.sh for a local preview and ./scripts/build-docs.sh to produce the deployable site.

1 - Development Setup

Local development workflow for infrastructure changes and the documentation site.

Getting started

Follow the Dev Container guide to set up your development environment. The aibox Dev Container includes OpenTofu, Ansible, cloudflared, Hugo, Node.js, Kubernetes clients, and AI assistants.

Documentation development

Preview the documentation site locally:

./scripts/serve-docs.sh
# Open http://localhost:1313

When using a remote Dev Container environment, forward port 1313 from your editor to view the preview.

Build the site:

./scripts/build-docs.sh

The build uses Hugo’s strict template and content validation. The first run installs the pinned Docsy asset dependencies locally and initializes the pinned Docsy theme submodule when needed.

Infrastructure development

If you have a Hetzner Cloud account and want to test infrastructure changes:

cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your API token

tofu init
tofu plan    # Preview changes
tofu apply   # Apply changes

Project conventions

See How to Contribute for code conventions and the contribution workflow.

Deploy documentation

To deploy the documentation to GitHub Pages:

./scripts/deploy-docs.sh

This is the standard documentation deployment. It builds the Hugo site locally and pushes the generated public/ directory to the root of the gh-pages branch. GitHub Pages must be configured to serve gh-pages from /; no GitHub Actions workflow is required or used.

The build and deployment scripts create an empty .nojekyll marker in the generated site and at the branch root, so GitHub Pages always serves the prebuilt output directly instead of processing it with Jekyll.

The same script can publish an archived documentation snapshot under a version path. For example:

DOCS_VERSION=v0.1 ./scripts/deploy-docs.sh

Add the corresponding entry to params.versions in hugo.yaml when a release is ready. The versioned build is published below the matching version path and uses that path as its canonical base URL.

2 - Code of Conduct

The behavioural standard this project holds contributors to.

This project follows the Contributor Covenant v2.1.

Please read the full text at the link above. In summary: be respectful, be constructive, and create a welcoming environment for everyone.

Reporting

If you experience or witness unacceptable behavior, please contact the project maintainer at bnaard@gmx.net.