Embed example manifests inline via shortcode (#960)

config.yaml

@@ -78,6 +78,10 @@ module:
     target: data/crds/
     includeFiles:
       - "**/api/**.yaml"
+  - source: content
+    target: static
+    includeFiles:
+      - "**/manifests/**.yaml"
 
 # Give Hugo access to environmental variables matching a given regex.
 # These give Hugo access to Netlify data to generate proper URLs

content/contribute/code-style-guide.md

@@ -211,3 +211,74 @@ aws_secret_access_key = $@<aws_secret_key>$@
 ```
 {{</* /editCode */>}}
 ````
+
+## Manifest shortcode
+
+The `manifest` shortcode embeds a YAML manifest inline and generates a `kubectl apply -f` command pointing to the published URL.
+
+Store manifests under `content/<version>/manifests/<page-path>/<file>.yaml`
+based on the referencing page location.
+
+For example, a page at `content/<version>/guides/change-logs.md` references
+`content/<version>/manifests/guides/change-logs/<file>.yaml` with
+`path="guides/change-logs/<file>.yaml"`.
+
+```markdown
+{{</* manifest path="code-style-guide/provider.yaml" */>}}
+```
+This renders as:
+
+{{< manifest path="code-style-guide/provider.yaml" >}}
+
+### Remove `apply` command
+
+Use `apply="false"` to render the YAML without the `kubectl apply -f` block.
+
+```markdown
+{{</* manifest path="code-style-guide/provider.yaml" apply="false" */>}}
+```
+
+{{< manifest path="code-style-guide/provider.yaml" apply="false" >}}
+
+### `generateName`
+
+Use `command="kubectl create -f"` for manifests that use `generateName`. `kubectl apply` doesn't support `generateName`.
+
+```markdown
+{{</* manifest path="code-style-guide/bucket.yaml" command="kubectl create -f" */>}}
+```
+
+{{< manifest path="code-style-guide/bucket.yaml" command="kubectl create -f" >}}
+
+### Line highlighting
+
+Use `label=` to enable dynamic line highlighting with the `hover` shortcode.
+
+```markdown
+Apply the {{</* hover label="provider" line="2" */>}}Provider{{</* /hover */>}} resource.
+
+{{</* manifest path="code-style-guide/provider.yaml" label="provider" */>}}
+```
+
+Apply the {{< hover label="provider" line="2" >}}Provider{{< /hover >}} resource.
+
+{{< manifest path="code-style-guide/provider.yaml" label="provider" >}}
+
+### Interact with manifests
+
+Use the `manifest-url` shortcode to interact with manifests applied to the cluster.
+
+```shell
+kubectl <command> -f {{</* manifest-url path="code-style-guide/provider.yaml" */>}}
+```
+You can use `get`, `describe`, `edit`, `delete` and other supported commands to perform the action on the live resource matching the manifest:
+
+```shell
+kubectl <command> -f {{< manifest-url path="code-style-guide/provider.yaml" >}}
+```
+
+{{< hint "note" >}}
+Refer to the
+[`kubectl`](https://kubernetes.io/docs/reference/kubectl/generated/) command
+reference for more information for supported commands and flags.
+{{< /hint >}}

content/contribute/manifests/code-style-guide/bucket.yaml

@@ -0,0 +1,8 @@
+apiVersion: s3.aws.m.upbound.io/v1beta1
+kind: Bucket
+metadata:
+  namespace: default
+  generateName: crossplane-bucket-
+spec:
+  forProvider:
+    region: us-east-2

content/contribute/manifests/code-style-guide/provider.yaml

@@ -0,0 +1,6 @@
+apiVersion: pkg.crossplane.io/v1
+kind: Provider
+metadata:
+  name: crossplane-contrib-provider-aws-s3
+spec:
+  package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v2.0.0