ADR-028: Documentation published to GitHub Pages

Category: development Provenance: human

Decision

Publish all project documentation to GitHub Pages at https://vriesdemichael.github.io/keycloak-operator/ using MkDocs with Material theme.

Rationale

GitHub Pages provides free, reliable hosting for project documentation. MkDocs with Material theme provides professional appearance and good UX (search, navigation, mobile support). Versioned documentation matches versioned releases. Users can access documentation without cloning repository. GitHub Pages SSL and CDN provide fast, secure access globally. Integrated with CI/CD for automatic publishing.

Agent Instructions

Maintain documentation in docs/ directory using Markdown. Build documentation with MkDocs. Documentation is automatically published to GitHub Pages on pushes to main branch. Keep documentation in sync with code changes - update docs when adding features.

Rejected Alternatives

Documentation only in README.md

Single file doesn't scale for complex project. No proper navigation or search.

Wiki or separate documentation site

Harder to keep in sync with code. Wiki doesn't support versioning or CI/CD publishing.