Embed example manifests inline via shortcode (#960) by jonasz-lasut · Pull Request #1086 · crossplane/docs

jonasz-lasut · 2026-04-28T10:33:09Z

Replaces the inconsistent mix of save-and-apply YAML, kubectl heredocs, and duplicated manifest files with a single mechanism: example manifests live as real .yaml files under
content//manifests/.yaml, embedded into prose by a new {{< manifest >}} shortcode and simultaneously published as fetchable URLs at https://docs.crossplane.io/<ver>/manifests/... so readers can run kubectl apply -f <url> directly.

I see room for improvement in the future by moving Function manifests to a separate directory and use the shared functions in all docs across all versions as this way we'll be able to update Function versions in one place only.

Fixes #960

Changes:

Adds a Hugo module mount in config.yaml that re-exposes content/<ver>/manifests/**.yaml under static/, so each manifest publishes verbatim at its natural URL.
Adds themes/geekboot/layouts/shortcodes/manifest.html. Required arg path= names the manifest relative to the calling page's version. The shortcode auto-derives the version segment from .Page.File.Path so authors never type version strings. Optional args: apply="false" suppresses the kubectl block; command= overrides the default verb (kubectl apply -f); label= wraps the rendered YAML in <div label="..."> so existing {{< hover label="..." >}} annotations keep working. Hostname is based on base URL so preview deploys still emit usable kubectl URLs.

netlify · 2026-04-28T10:33:18Z

✅ Deploy Preview for crossplane ready!

Name	Link
🔨 Latest commit	`e3aec85`
🔍 Latest deploy log	https://app.netlify.com/projects/crossplane/deploys/6a02be6bf455df0008930f24
😎 Deploy Preview	https://deploy-preview-1086--crossplane.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 91 (🔴 down 2 from production) Accessibility: 90 (🔴 down 2 from production) Best Practices: 92 (no change from production) SEO: 100 (no change from production) PWA: 70 (no change from production) View the detailed breakdown and full score reports

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

tr0njavolta · 2026-05-11T19:07:40Z

Thanks for the contribution @jonasz-lasut! I was able to review and test:

Core functionality
- kubectl apply -f works
- kubectl edit -f works
- kubectl apply --dry-run=client passes for all manifests across all versions
- Missing manifest file returns build error.
Shortcode combinations
- {{< manifest >}} inside {{< tabs >}} works
- {{< manifest >}} inside {{< expand >}} works
- apply="false" inside {{< hint >}} works
- {{< hover >}} on manifests works

Couple things I noticed:

Hover targeting a manifest inside a tab doesn't render the line highlighting but isn't a blocking error.
Local hugo build absURL produces //localhost/1313/.... Doesn't affect production but breaks copy-paste testing during doc authoring. Manually updating to http://localhost/1313/... works.

I created a PR to your forked branch to add usage information to the docs code styling guide.. Once that's accepted or edited, we'll be good to approve and merge 🚀

tr0njavolta

Requesting a usage guide for the shortcode in https://docs.crossplane.io/contribute/code-style-guide/. Created a PR here

jonasz-lasut · 2026-05-11T19:23:44Z

Really appreciate the review @tr0njavolta
I've merged the PR that you've opened against my fork without changes, thank you for finding time to test all functionalities.

I'll take a look at fixing hover inside a tab and localhost baseUrl in the follow-up PR sometime next week :)

jonasz-lasut · 2026-05-11T19:27:57Z

Looks like your commit was missing a signoff, I've invited you as a collaborator on my fork so you should be able to push directly to the branch

Replaces the inconsistent mix of save-and-apply YAML, kubectl heredocs, and duplicated manifest files with a single mechanism: example manifests live as real .yaml files Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Signed-off-by: Jonasz Łasut-Balcerzak <jonasz.lasut@gmail.com> Signed-off-by: Rae Sharp <resharp20@gmail.com>

Signed-off-by: Rae Sharp <resharp20@gmail.com>

jbw976

thank you so much for taking this on @jonasz-lasut, i think it's a lot easier/quicker to walk through the interactive guides now than the previous approach of copying the content to a file each time. This is very appreciated!! 🙇

I added two small comments of things I noticed, none of them are explicitly blocking - I'll add my approval on as well and we can merge tomorrow either way 😁

jbw976 · 2026-05-11T22:42:02Z

+
+{{- $highlightOpts := "linenos=table,linenostart=1" -}}
+
+<div class="gdoc-manifest">


one funny thing i noticed is that the manifest code blocks now seem to use a blue/green color for their line numbers, when before they were a grey color. Is something in the logic here affecting that? Compare the line number colors on these two:

Current: https://docs.crossplane.io/v2.2/guides/change-logs/#configure-permissions

NEW: https://deploy-preview-1086--crossplane.netlify.app/v2.2/guides/change-logs/#configure-permissions

The horizontal grey bar is also missing. Part of the development loop was diffing between the newly generated content and the source page and the agent missed that.
I'll have a look today what may be the root cause

ah good eye, yes the gray border bar is missing too! hopefully we can find the root cause without too much trouble 🙏

Line numbers were using table instead of inline styling and because of that the CSS was not applied. Fortunately that was a oneliner

jbw976 · 2026-05-11T22:43:55Z

+
+{{< manifest path="code-style-guide/provider.yaml" apply="false" >}}
+
+### `generateName`


is it also worth mentioning the manifest-url function in this contributing guide page? i see it used quite a lot on some pages like https://deploy-preview-1086--crossplane.netlify.app/v2.2/get-started/get-started-with-composition/

Thanks for calling this out - added a mention in the contributing guide.

Signed-off-by: Rae Sharp <resharp20@gmail.com> Vale exception Signed-off-by: Rae Sharp <resharp20@gmail.com> Fix language and mismatched backticks Signed-off-by: Rae Sharp <resharp20@gmail.com>

…e instead of inline) and thus not using correct CSS Signed-off-by: Jonasz Łasut-Balcerzak <jonaszlasut@proton.me>

jbw976 · 2026-05-12T17:00:52Z

awesome, it looks like all the feedback is incorporated now, let's merge!! great work @jonasz-lasut and @tr0njavolta!!! 🎉

jonasz-lasut force-pushed the inline-manifests-squashed branch 3 times, most recently from 2c1b789 to 522ac0a Compare April 28, 2026 10:57

jonasz-lasut closed this Apr 28, 2026

jonasz-lasut reopened this Apr 28, 2026

jonasz-lasut force-pushed the inline-manifests-squashed branch 2 times, most recently from 2ac5d78 to d365ad9 Compare April 28, 2026 11:41

jonasz-lasut marked this pull request as ready for review April 28, 2026 11:42

jonasz-lasut force-pushed the inline-manifests-squashed branch from d365ad9 to 9db2446 Compare April 28, 2026 11:43

jonasz-lasut mentioned this pull request Apr 28, 2026

Load example manifests and embed them inline #960

Closed

tr0njavolta self-requested a review May 11, 2026 19:12

tr0njavolta requested changes May 11, 2026

View reviewed changes

tr0njavolta force-pushed the inline-manifests-squashed branch from 6f11719 to 809144d Compare May 11, 2026 19:49

tr0njavolta self-requested a review May 11, 2026 19:50

tr0njavolta approved these changes May 11, 2026

View reviewed changes

tr0njavolta self-requested a review May 11, 2026 19:52

Adds style guide examples

c549185

Signed-off-by: Rae Sharp <resharp20@gmail.com>

jbw976 approved these changes May 11, 2026

View reviewed changes

Add manifest-url information

dd2ebb5

Signed-off-by: Rae Sharp <resharp20@gmail.com> Vale exception Signed-off-by: Rae Sharp <resharp20@gmail.com> Fix language and mismatched backticks Signed-off-by: Rae Sharp <resharp20@gmail.com>

tr0njavolta force-pushed the inline-manifests-squashed branch from ba449a9 to dd2ebb5 Compare May 12, 2026 01:53

Fix manifest tables being generated with incorrect line numbers (tabl…

e3aec85

…e instead of inline) and thus not using correct CSS Signed-off-by: Jonasz Łasut-Balcerzak <jonaszlasut@proton.me>

jbw976 merged commit 274fcf1 into crossplane:master May 12, 2026
7 checks passed

jonasz-lasut deleted the inline-manifests-squashed branch May 12, 2026 17:24


		{{- $highlightOpts := "linenos=table,linenostart=1" -}}

		<div class="gdoc-manifest">


		{{< manifest path="code-style-guide/provider.yaml" apply="false" >}}

		### `generateName`

Conversation

jonasz-lasut commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

✅ Deploy Preview for crossplane ready!

Uh oh!

tr0njavolta commented May 11, 2026

Uh oh!

tr0njavolta left a comment

Choose a reason for hiding this comment

Uh oh!

jonasz-lasut commented May 11, 2026

Uh oh!

jonasz-lasut commented May 11, 2026

Uh oh!

jbw976 left a comment

Choose a reason for hiding this comment

Uh oh!

jbw976 May 11, 2026

Choose a reason for hiding this comment

Uh oh!

jonasz-lasut May 12, 2026

Choose a reason for hiding this comment

Uh oh!

jbw976 May 12, 2026

Choose a reason for hiding this comment

Uh oh!

jonasz-lasut May 12, 2026

Choose a reason for hiding this comment

Uh oh!

jbw976 May 11, 2026

Choose a reason for hiding this comment

Uh oh!

tr0njavolta May 12, 2026

Choose a reason for hiding this comment

Uh oh!

jbw976 commented May 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jonasz-lasut commented Apr 28, 2026 •

edited

Loading

netlify Bot commented Apr 28, 2026 •

edited

Loading