Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add codenew shortcode to style guide #18245

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions content/en/docs/contribute/style/style-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -380,6 +380,47 @@ The output is:

{{< kat-button >}}

### Downloadable code blocks

Use {{</* codenew */>}} 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
{{</* codenew file="application/deployment.yaml" */>}}
```

anshprat marked this conversation as resolved.
Show resolved Hide resolved
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 `<LANG>/examples/` subdirectories where `<LANG>` is the language for the topic. In your topic file, use the codenew shortcode:

```none
{{</* codenew file="<RELPATH>/my-example-yaml>" */>}}
Copy link
Contributor

Choose a reason for hiding this comment

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

hello @anshprat .Thanks for the updates. It looks as if this content is created from:
https://kubernetes.io/docs/contribute/style/write-new-topic/#including-code-from-another-file.
Personally, I like that the content appears in the write-new-topic page.
You could include a very brief section in the main style guide page about the codenew shortcode and link to the write-new-topic page, for example:

## Downloadable code blocks

Use the [codenew shortcode](/docs/contribute/style/write-new-topic/#including-code-from-another-file) to create downloadable code samples (manifests).

You can add any additional content (lines 415 - 423) to the existing section in the write-new-topic page.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Got it, will update.

```

where `<RELPATH>` 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
{{</* codenew file="pods/storage/gce-volume.yaml" */>}}
```

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/<filename.yaml>
```

## Common Shortcode Issues

### Ordered Lists
Expand Down