Add opt-in serialization variants to code_sample by TineoC · Pull Request #58042 · kubernetes/website

TineoC · 2026-10-13T15:02:42Z

Description

Lets code_sample show a sample in more than one format, as tabs. Opt-in per sample:

{{% code_sample file="pods/simple-pod.yaml" variants="kyaml" %}}

The extra file is read from content/<lang>/examples-kyaml/. Without variants, nothing changes. No page uses it yet.

Split from the original version of this PR, per review:

Show a sample in several formats (this PR)
Generate the KYAML files: Add tooling to generate KYAML example variants #59129
Use KYAML on pages: follow-up

Test: Hugo shortcodes (new section), Pods (renders as before).

Issue

Part of #57030 (KEP-5295). Relates to #59129.

This PR was written in part with the assistance of generative AI.

/sig docs
/language en

netlify · 2026-10-13T15:05:27Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`a792b06`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/6af27d0037bd93dff659f780
😎 Deploy Preview	https://deploy-preview-58042--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

TineoC · 2026-10-13T17:45:56Z

TineoC · 2026-10-13T17:51:59Z

From 10-13-2026 SIG Docs meeting:

This feature don't have to be part of a particular milestone because KYAML is already on main.

Notes to @TineoC: This pr should target main instead of dev-1.38

cc. @lmktfy @katcosgrove

TineoC · 2026-10-15T14:46:10Z

/remove-area blog
/remove-area localization
/remove-language ko
/remove-language zh
/remove-language fr
/remove-language de
/remove-language pt
/remove-language ru
/remove-language pl
/remove-language uk
/remove-language fa

lmktfy

Thanks for this. Sorry it's been a while waiting on reviews.

Overall, I think we can split this more.

changes to make it possible to have multiple serializations of the same code (or manifest) sample
changes to make it easier to work with KYAML

actually using KYAML in some pages
(and personally, I like the idea that we verify it works, then split off the commit for this into its own separate / follow-up PR)

lmktfy · 2026-11-07T10:54:48Z

+`scripts/README.md` covers the rest: why the conventional YAML stays canonical,
+which manifests get no KYAML rendering, and how localizations opt in.


This reads like AI. Consider rewording it?

lmktfy · 2026-11-07T10:55:13Z

+Returns the objects a manifest describes, as JSON, one entry per document in it.
+Comparing that instead of the text is how two renderings of one manifest are
+checked against each other: a dialect changes the spelling, so only the decoded
+objects are comparable.
+
+Expects a dict with:
+  key       a name unique to this manifest and dialect, for the temporary
+            resource; derive it from the path actually read, so that two
+            languages holding the same manifest name do not share one resource
+  content   the manifest text
+
+Each document goes through a .yaml-named resource because transform.Unmarshal
+guesses a bare string's format and KYAML's leading brace reads as JSON; jsonify
+then orders the keys, leaving only meaning to compare.


What's the purpose of this partial? I don't quite get it.

lmktfy · 2026-11-07T10:55:42Z

@@ -0,0 +1,24 @@
+{{- /*
+Renders one example manifest.


Suggested change

Renders one example manifest.

Renders one example code sample (usually a manifest).

lmktfy · 2026-11-07T10:56:00Z

Docsy provides a similar shortcode; are we drifting further from it?

lmktfy · 2026-11-07T10:56:23Z

+{{/* The dialects an example can be offered in besides the conventional YAML it
+     is written as, from params.codeSampleDialects in hugo.toml. Configuring one
+     and generating for it are separate: nothing here changes a page until a
+     generator has left renderings in content/<lang>/examples-<name>. */}}


Don't imply or assume that a code sample defaults to YAML.

lmktfy · 2026-11-07T10:57:13Z

+{{/* The tabs are the site's own, from layouts/partials/tabs.html, so a dialect
+     chosen here is remembered the way every other tab choice on the site is:
+     the persistence key is the dialect's name, so picking one picks it for every
+     other example and the choice survives to the next page. Without JavaScript
+     the first tab, conventional YAML, is the one shown. */}}


Don't imply or assume that a code sample defaults to YAML.

Also, we should try to align more with Docsy where we can.

lmktfy · 2026-11-07T10:57:18Z

+     the persistence key is the dialect's name, so picking one picks it for every
+     other example and the choice survives to the next page. Without JavaScript
+     the first tab, conventional YAML, is the one shown. */}}
+{{ $tabs := slice (dict "label" "YAML" "persist" "yaml" "content" (partial "code-sample-pane.html" $yamlPane)) }}


Don't imply or assume that a code sample defaults to YAML. However, it's OK to have a special kind of code_sample that does have a list of variant serializations. Or other approaches, so long as we aren't disallowing plain-JSON code samples, etc.

lmktfy · 2026-11-07T10:58:21Z

+     "tabindex" "0"
+     "tabs" $tabs) }}
+{{ else }}
+{{ partial "code-sample-pane.html" $yamlPane }}


Don't imply or assume that a code sample defaults to YAML.

lmktfy · 2026-11-07T10:58:38Z

Docsy provides a similar shortcode; are we drifting further from it?

lmktfy · 2026-11-07T10:59:14Z

+
+This script renders selected example manifests a second time as
+[KYAML](https://kubernetes.io/docs/reference/encodings/kyaml/), so the
+`code_sample` shortcode can show them in either dialect.


Don't imply or assume that a code sample defaults to YAML. A minor rewording is all that's needed here.

lmktfy · 2026-11-07T11:02:05Z

I don't think this should be placed in scripts.

Signed-off-by: Christopher Tineo <christophertineo02@gmail.com>

kubernetes-prow · 2026-11-10T02:10:31Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign dipesh-rawat for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS
content/en/docs/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

TineoC · 2026-11-10T02:14:11Z

I did the split.

https://github.com/kubernetes/website/pull/58042/changes#diff-299817675e7f7c5e1721b159d971f7c08dea8caf3e3cd1b637afdd695fe8ad02R344 They can opt in by passing a variant.

cc. @lmktfy

TineoC · 2026-11-10T02:19:31Z

the solution is kyaml-specific (specially if you see #59129). Do you think might be worth making this extensible for future variants?

kubernetes-prow Bot added this to the 1.38 milestone Oct 13, 2026

kubernetes-prow Bot requested review from dipesh-rawat and nate-double-u October 13, 2026 15:02

kubernetes-prow Bot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Oct 13, 2026

TineoC mentioned this pull request Oct 13, 2026

Serve example manifests in KYAML and YAML #56971

Closed

TineoC force-pushed the kyaml/dual-render-silent branch from e8022db to ca3c1f6 Compare October 15, 2026 14:39

TineoC changed the base branch from dev-1.38 to main October 15, 2026 14:39

kubernetes-prow Bot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. language/pt Issues or PRs related to Portuguese language labels Oct 15, 2026

TineoC marked this pull request as ready for review October 15, 2026 14:39

kubernetes-prow Bot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Oct 15, 2026

kubernetes-prow Bot requested a review from divya-mohan0209 October 15, 2026 14:40

lmktfy reviewed Oct 15, 2026

View reviewed changes

Comment thread content/en/docs/contribute/style/write-new-topic.md Resolved

lmktfy reviewed Nov 7, 2026

View reviewed changes

Comment thread scripts/kyaml_examples.txt Outdated

lmktfy Nov 7, 2026

Copy link
Copy Markdown

Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this should be placed in scripts.

add kyaml support

a792b06

Signed-off-by: Christopher Tineo <christophertineo02@gmail.com>

TineoC force-pushed the kyaml/dual-render-silent branch from ca3c1f6 to a792b06 Compare November 10, 2026 02:10

TineoC mentioned this pull request Nov 10, 2026

Add tooling to generate KYAML example variants #59129

Open

kubernetes-prow Bot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Nov 10, 2026

TineoC changed the title ~~Serve example manifests in KYAML and YAML~~ Add opt-in serialization variants to code_sample Nov 10, 2026

		`scripts/README.md` covers the rest: why the conventional YAML stays canonical,
		which manifests get no KYAML rendering, and how localizations opt in.

	Renders one example manifest.
	Renders one example code sample (usually a manifest).

Conversation

TineoC commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issue

Uh oh!

netlify Bot commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull request preview available for checking

Uh oh!

TineoC commented Oct 13, 2026

Uh oh!

TineoC commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TineoC commented Oct 15, 2026

Uh oh!

Uh oh!

lmktfy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kubernetes-prow Bot commented Nov 10, 2026

Uh oh!

TineoC commented Nov 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TineoC commented Nov 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

TineoC commented Oct 13, 2026 •

edited

Loading

netlify Bot commented Oct 13, 2026 •

edited

Loading

TineoC commented Oct 13, 2026 •

edited

Loading

TineoC commented Nov 10, 2026 •

edited

Loading

TineoC commented Nov 10, 2026 •

edited

Loading