For this file, you can use make helm-doc-generate to generate instead of manual edit.

Thanks @MonkeyCanCode, I did not know it was automatically copied. But I see that there are already merged changes that diverge helm.md from helm/polaris/readme.md - markup for blockquotes was changed in #2656.
Also, there is a problem with rendering badges in the original page header when hosted on the apache.org:

Apparently apache.org content security policy does not allow embedding images from external hosts:

Refused to load the image 'https://img.shields.io/badge/Version-1.2.0--incubating--SNAPSHOT-informational?style=flat-square' because it violates the following Content Security Policy directive: "default-src 'self' data: blob: 'unsafe-inline' 'unsafe-eval' https://www.apachecon.com/ https://www.communityovercode.org/ https://*.apache.org/ https://apache.org/ https://*.scarf.sh/". Note that 'img-src' was not explicitly set, so 'default-src' is used as a fallback.

It was my motivation to remove the header from page version for the site.

As a sidenote, we have other pages on the site that are copies from getting-started docs (e.g. Keycloak setup page, Telemetry setup page), but they are not copied automatically. It would be good to have some unified approach for such cases.

Yes. That is correct. If u run local, it will all show up. Either we will need to update the policy or have a better way to handle these. Manually edit those can be fairly tedious. @flyrain

Agreed with @MonkeyCanCode to rely on automation. Can we also add a post-process step to make helm-doc-generate, e.g., generate helm.md automatically with minor adjustments (strip badges, convert blockquotes)?

I would love to see this automated, but unfortunately the two pages are different, especially the warning box style.

I think we would need two different templates.

FWIW, I think this needs to be addressed separately, in a follow-up PR.

I agree it is a good idea to converge helm.md back with helm chart readme and sync them automatically.
I see that we can go back from Hugo shortcodes to github-style blockqoutes for alert blocks - I made it work locally, but it requires updating Hugo version. It may bring additional concerns (full site testing etc.), so I would make it a separate PR as @adutra suggested.

Explicitly pulling isn't needed, Helm will pull images automatically if imagePullPolicy: IfNotPresent or Always is configured in the chart (which it is by default for most charts). All we need here is:

Otherwise, Helm will automatically pull released images during installation.

This isn't for Helm, but for the kubelet inside Minikube. The kubelet can only download images if they are publicly available.

If the image is from a private registry, or only present locally in the host machine (e.g. because you built a custom apache/polaris:latest image from sources and you want to use it), then this instruction is necessary.

All in all, I think it's fine to leave the instructions.

Thanks for the clarification, that makes sense. Good point about the kubelet behavior inside Minikube. I agree it’s fine to keep the minikube image pull instructions for users running with private or locally built images.

That said, I still think it’d be clearer to separate the doc into two sections, one for the standard “Helm install from the official repo” path, and another “advanced / from source” section for developers. This way, most users can follow the simple flow without extra steps, while contributors still have the detailed Minikube setup if needed. More details are in this comment, #2939 (review).

Thanks @flyrain for your comments. I agree that clear separation of "user" and "dev" flows is a good thing - I remember there was even an initiative to clearly split all of Polaris documentation that way.
Regarding this particular document, there is a couple of things to consider:

• flows would be largely duplicating each other (we will need to download helm chart anyway to install persistent backend and create test setup for resources using helm/polaris/ci/fixtures)
• current helm.md document is generated from helm/chart/readme.md, which assumes that helm chart was downloaded or github repo was cloned, so it kinda implies being "advanced" by default. I was specifically asked to keep the documents synced: Docs: update Helm Chart page to show usage without cloning Polaris github repo #2939 (comment)

So maybe it makes sense to create a separate document for a standard path and add a link to advanced path to it, wdyt?

Thanks for the reply. I think it's more reasonable to put them in one place. Even helm chart was downloaded or github repo was cloned, user don't need or want to rebuild docker image, etc. In fact, helm chart can be downloaded separately without other Polaris source code, users won't be able to build the docker image in that case.

I have updates the doc with two separate flows as you suggested, @flyrain.
helm.md still has some manual changes after being generated from helm/polaris/readme.md.gotmpl due to blockquotes not properly rendered in Hugo - I will fix it in a follow up PR

nit: I do not mind installing yamllint, but I could not find references to it from the examples... Why does it need to be installed?

It is not used directly in our samples, but It is required by ct lint

thx!