Reference¶

Three of the four pages in this section are generated. Editing them by hand wastes your time: the next make docs overwrites the change, and CI fails the build in between.

Generated versus hand-written¶

Page	Source of truth	Regenerated by	Edit by hand?
API reference	Go types in `api/v1alpha1/*.go`	`make docs-api`	No — edit the Go doc comments
Helm values	`charts/authentik-operator/values.yaml`	`helm-docs`	No — edit the `# --` comments in `values.yaml`
Supported versions	`supported-versions.yaml`	`make sync-versions`	No — edit `supported-versions.yaml`
Conditions	—	—	Yes

Conditions is the exception. The condition types and reasons come from a fixed set of Go constants, but the cause and fix for each one is judgement that no generator can produce. It is maintained by hand, and a new reason added to api/v1alpha1/common_types.go needs a row added here in the same pull request.

How generation works¶

Each generated page has a body delimited by HTML comment markers:

<!-- BEGIN GENERATED: api -->
...everything here is replaced wholesale...
<!-- END GENERATED: api -->

The prose outside the markers is hand-written and preserved. The generator replaces only what lies between them, which is why the markers must not be removed — a page missing them fails generation with an explicit error rather than being silently rewritten.

The same convention is used by hack/sync-versions.py for the version table in README.md, and by hack/gen-docs.py for the pages on this site.

Regenerating everything¶

hack/gen-docs.py            # rewrite derived pages in place
hack/gen-docs.py --check    # exit non-zero if anything is stale

--check is what CI runs. It prints which page drifted and what to run, and writes nothing.

Some generators do not exist yet

hack/gen-docs.py handles the supported-versions table and the pages that mirror root-level markdown files today.

The API reference and Helm values generators are not yet wired into the Makefile — there is no docs-api target, and no target that runs helm-docs (the helm-docs target installs the binary into bin/ but does not invoke it). Those two pages currently carry an empty generated block and a note saying so.

Building this site¶

The documentation is Zensical. Configuration lives in zensical.toml at the repository root, which defines the navigation — every file listed in nav must exist or the build fails.

zensical build --clean            # output in site/
zensical build --clean --strict   # fail on warnings, including broken links
zensical serve                    # live-reloading preview

Strict mode treats a broken internal link as an error

Including links that leave docs/. A relative link to ../../SECURITY.md resolves fine on GitHub and fails the site build, because the target is not a page in the site.

Link to root-level files by absolute URL, or refer to them by path in a code span without linking.

Other references¶

Conditions — every condition type and reason, with fixes.
Troubleshooting — keyed to those reasons.
Supported versions — the authentik compatibility matrix.
Decisions — architecture decision records.

CONTRIBUTING.md in the repository root covers the development workflow and the make verify contract; Contributing summarises it.