diff --git a/content/en/docs/contribute/style/style-guide.md b/content/en/docs/contribute/style/style-guide.md index 30865c49e8ef3..1cade55ee0c27 100644 --- a/content/en/docs/contribute/style/style-guide.md +++ b/content/en/docs/contribute/style/style-guide.md @@ -380,6 +380,47 @@ The output is: {{< kat-button >}} +### Downloadable code blocks + +Use {{}} to make code samples (manifests) downloadable. + + A way to include code in your topic is to create a new, complete sample file (or group of sample files) and then reference the sample from your topic. Use this method to include sample YAML files when the sample is generic and reusable, and you want the reader to try it out themselves. + +```none +{{}} +``` + +The output is: + +{{< codenew file="application/deployment.yaml" >}} + +Here is an example page containing that shortcode: + +https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/ + +When adding a new standalone sample file, such as a YAML file, place the code in one of the `/examples/` subdirectories where `` is the language for the topic. In your topic file, use the codenew shortcode: + +```none +{{/my-example-yaml>" */>}} +``` + +where `` is the path to the file to include, relative to the +`examples` directory. The following Hugo shortcode references a YAML +file located at `/content/en/examples/pods/storage/gce-volume.yaml`. + +```none +{{}} +``` + +Typically, code samples do not change, however natural-language comments can be translated. +For example: https://github.com/kubernetes/website/blob/master/content/ko/examples/application/deployment.yaml is the `ko` version for https://github.com/kubernetes/website/blob/master/content/en/examples/application/deployment.yaml + +You may also tell the reader about how to run the code after downloading the file by mentioning relevant commands like + +```none +kubectl apply -f /path/to/ +``` + ## Common Shortcode Issues ### Ordered Lists