fix(docs): update stale policy type API reference links

[Suhani95]

Related issue

Fixes #2047

Proposed Changes

This PR updates stale API reference links in the policy type documentation.

The affected pages were linking to old hardcoded release-1.14 / policies.kyverno.io/v1alpha1 API references while the examples and documentation use the stable policies.kyverno.io/v1 API.

Updated the following files:

• src/content/docs/docs/policy-types/validating-policy.mdx
• src/content/docs/docs/policy-types/mutating-policy.mdx
• src/content/docs/docs/policy-types/image-validating-policy.mdx

The stale external links were replaced with the centralized internal CRD reference route:

/docs/crds/

Direct release-1.18 deep links were also tested, but the generated anchors did not reliably resolve to distinct policy-specific sections. To avoid replacing stale links with misleading or unstable deep links, this PR uses /docs/crds/ as the stable API reference entry point.

Testing

Verified stale references are removed:

grep -RniE "release-1\.14|policies\.kyverno\.io/v1alpha1|policies\.kyverno\.io%2fv1alpha1" src/content/docs/docs/policy-types/

Result: no matches.

Verified updated references:

grep -Rni "/docs/crds/" src/content/docs/docs/policy-types/

Build verification:

npm run build

Build passed successfully.

Manual verification performed for:

• /docs/policy-types/validating-policy/
• /docs/policy-types/mutating-policy/
• /docs/policy-types/image-validating-policy/

Confirmed all API Reference links now resolve to /docs/crds/.

Checklist

• I have read the contributing guidelines.
• I have inspected the website preview for accuracy.
• I have signed off my commits.

[onasser1]

We need the API specification, why did you remove it?

[Suhani95]

I replaced the stale release-1.14 / v1alpha1 links with /docs/crds/ since the original references no longer matched the stable policies.kyverno.io/v1 examples.

I also tested release-1.18 HTMLPreview links, but the generated anchors were not resolving reliably during testing.

[onasser1]

How can we access the following link: https://htmlpreview.github.io/?https://github.com/kyverno/kyverno/blob/release-1.14/docs/user/crd/index.html#policies.kyverno.io/v1alpha1.ImageValidatingPolicy after your changes?
can you get me the link from the deploy artifacts?

[Suhani95]

After this change, the API reference is reached via /docs/crds/, which links to the generated CRD reference through the "The complete Kyverno CRD reference can be viewed here" link.

[onasser1]

I'd make it more clear, I want to see the image validating policy crd such as in this link: https://htmlpreview.github.io/?https://github.com/kyverno/kyverno/blob/release-1.14/docs/user/crd/index.html#policies.kyverno.io/v1alpha1.ImageValidatingPolicy

After this change, the API reference is reached via /docs/crds/, which links to the generated CRD reference through the "The complete Kyverno CRD reference can be viewed here" link.

The complete Kyverno CRD reference is refering to this: https://htmlpreview.github.io/?https://github.com/kyverno/kyverno/blob/main/docs/user/crd/index.html

Which I can't find reference to ImageValidating Policy for example.
At least for me I use it, I'm not sure if there is a way to include them but referring to a link that does not include vpol, gpol, ivpol and mpol I think is not the correct way

@lucchmielowski is there a way to include them in that crd specification?

[Suhani95]

Thanks for clarifying. I see your point now. My goal was to fix the stale release-1.14 / v1alpha1 references, but you're right that /docs/crds/ doesn't provide the policy-specific CRD definitions that the original links pointed to.

I'll revisit the approach and update the PR to preserve direct access to those API references while fixing the version mismatch.