[Iheanacho-ai]

What

Adds an Omni Helm Chart reference page, generated from the chart README in siderolabs/omni, and a tool to regenerate it. Closes #333.

Why

The chart docs only existed as a README on GitHub, so readers had to leave the docs site to find install steps and values. As agreed in #333, the README stays the source of truth, and the docs site gets a generated copy that can be refreshed with one command.

Change

• New tool tools/omni-helm-chart-gen (Go, with tests and a Dockerfile). It fetches the chart README from the latest Omni release tag, or a pinned ref, and converts it to MDX:
  • GitHub alerts become Mintlify callouts.
  • Bare autolinks become Markdown links.
  • Relative values.yaml links point to GitHub.
  • The title, badges, homepage line and Maintainers section are dropped.
• New workflow build-omni-helm-chart-gen.yaml publishes the tool's image to ghcr.io.
• Makefile: adds generate-omni-helm-chart-reference (container) and -local, both taking OMNI_HELM_CHART_REF=<tag> to pin a version. Both are included in generate-omni-reference and generate-omni-reference-local.
• New page public/omni/reference/helm-chart.mdx, added to the Omni Reference nav, with docs.json regenerated.
• Repointed three GitHub README links to the new page, using relative links: one in run-omni-on-k8s.mdx and two in enable-workload-proxy.mdx.
• Bumped version variables in public/snippets/custom-variables.mdx: omni_release to v1.12.2, and omni_helm_chart_release to 2.12.2. The chart variable was 2.5.10, which installed Omni v1.5.10.

Testing

• Ran:
  • go test (13 tests)
  • make code-review (golangci-lint, tests, hadolint, checkmake)
  • both generate targets
  • make broken-links, validate-docs-nav, style-check-changed, check-frontmatter-changed, docs.json
• Where: local checkout, local Mintlify preview, and the tool image built locally.
• By: Claude Code (agent), reviewed by me.
• Result:
  • All checks pass. The style check reports 0 errors; the 7 warnings on the new page come from the upstream README's wording.
  • The container and local targets produce identical output.
  • The source README matches the README in the published chart 2.12.2 (helm show readme).
  • The page renders in preview, with all callouts, both tables and the anchors working.
  • The values table covers every chart setting outside config. The chart marks the 26 config.* keys it omits # @ignored, and those are documented on the Omni Configuration reference page.
  • In preview, Run Omni on Kubernetes shows --version 2.12.2, and Run Omni Air-gapped shows v1.12.2.
• Filled from outside the page: the chart has moved from deploy/helm/v2/omni, the path in the issue, to deploy/helm/omni.
• Follow-up: the container target needs the image, which is published after merge. Until then, use -local or make build-omni-helm-chart-gen-container.

[github-actions]

📋 Automated documentation review

An automated pass runs on documentation changes in every PR. The items below are suggestions to consider — advisory, not a merge gate.

Reviewed commit b1cf966 · 🔴 0 critical · 🟡 4 warning(s) · ⚪ 2 notice(s)

• 🟡 public/omni/reference/helm-chart.mdx:40 — Helm install/upgrade examples pin chart 2.7.2 while the page documents chart v1.12.2 values
  • Why: The page is generated from the v1.12.2 chart README and lists 1.12.x defaults, but the install and upgrade commands use --version 2.7.2, which by the page's own mapping installs Omni v1.7.2. The command works, so readers silently get an Omni several minor versions older than the values documented here.
  • Fix: helm install omni oci://ghcr.io/siderolabs/charts/omni --version 2.12.2 -n omni --create-namespace -f values.yaml
• 🟡 public/omni/reference/helm-chart.mdx:138 — Link points at the legacy omni.siderolabs.com/docs/how-to-guides path, which has no redirect
  • Why: The page it links to now lives in this repo at public/omni/cluster-management/expose-a-workload-via-service-proxy.mdx, and the only redirect in common.yaml covers /omni/cluster-management/expose-an-http-service-from-a-cluster, not the /docs/how-to-guides/ path, so the link very likely 404s. I could not fetch the live site to confirm since WebFetch is limited to GitHub.
  • Fix: For details on exposing services, see Expose a Workload via Service Proxy.
• 🟡 public/omni/reference/helm-chart.mdx:1 — New page is not listed in omni.yaml or docs.json, so the new cross-links will 404
  • Why: The Reference group in omni.yaml uses an explicit pages list rather than folder scanning and does not include helm-chart.mdx, and public/docs.json has no helm-chart entry, so the page is unpublished and the links added in run-omni-on-k8s.mdx and enable-workload-proxy.mdx break; the nav and docs.json CI checks would also fail. Disregard if the PR already updates those files, which were not shown to me.
  • Fix: Add - "helm-chart.mdx" to the Reference group pages in omni.yaml and run make docs.json, committing the regenerated public/docs.json
• 🟡 public/omni/reference/helm-chart.mdx:6 — Header comment names a make target that does not exist
  • Why: The Makefile has generate-omni-cli-reference, generate-omni-config-reference and generate-omni-image-factory-reference but no generate-omni-helm-chart-reference, so a contributor following the regeneration instruction gets 'No rule to make target'.
  • Fix: Add a generate-omni-helm-chart-reference target to the Makefile (and to the generate-omni-reference aggregate), or reference the command that actually regenerates this page

Notices, and the reviewer's full report, are in the run's doc-accuracy-report artifact.

[github-actions]

📋 Automated documentation review

⚠️ The reviewer did not finish on commit c94ce15 (it timed out or errored) — see the workflow run log. This run did not produce a result; any findings from an earlier run on this PR still stand.

[Iheanacho-ai]

/m