Reorganize docs contrib guide (#9510)
* Reorganize docs contrib guide * Address first round of feedback from Brad, Jared * Standardize on 'SIG Docs' * Address more feedback * Rewrites to participating.md * Tweak navigation titles * Document PR Wrangler * Document SIG Docs chairperson * Fix codeblock that shows how to use <codenew> It was being interpreted as a Hugo shortcode.
This commit is contained in:
Misty Linville
committed by
k8s-ci-robot
k8s-ci-robot
parent
4920a51665
commit
5ae0d0dd8d
@@ -0,0 +1,9 @@
|
||||
---
|
||||
title: Documentation style overview
|
||||
main_menu: true
|
||||
weight: 80
|
||||
---
|
||||
|
||||
The topics in this section provide guidance on writing style, content formatting
|
||||
and organization, and using Hugo customizations specific to Kubernetes
|
||||
documentation.
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
title: Content organization
|
||||
content_template: templates/concept
|
||||
weight: 40
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
This site uses Hugo. In Hugo, [content organization](https://gohugo.io/content-management/organization/) is a core concept.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
{{% note %}}
|
||||
**Hugo Tip:** Start Hugo with `hugo server --navigateToChanged` for content edit-sessions.
|
||||
{{% /note %}}
|
||||
|
||||
## Page Lists
|
||||
|
||||
### Page Order
|
||||
|
||||
The documentation side menu, the documentation page browser etc. are listed using Hugo's default sort order, which sorts by weight (from 1), date (newest first) and finally by the link title.
|
||||
|
||||
Given that, if you want to move a page or a section up, set a weight in the page's front matter:
|
||||
|
||||
```yaml
|
||||
title: My Page
|
||||
weight: 10
|
||||
```
|
||||
|
||||
|
||||
{{% note %}}
|
||||
For page weights, it can be smart not to use 1, 2, 3 ..., but some other interval, say 10, 20, 30... This allows you to insert pages where you want later.
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
### Documentation Main Menu
|
||||
|
||||
The `Documentation` main menu is built from the sections below `docs/` with the `main_menu` flag set in front matter of the `_index.md` section content file:
|
||||
|
||||
```yaml
|
||||
main_menu: true
|
||||
```
|
||||
|
||||
|
||||
Note that the link title is fetched from the page's `linkTitle`, so if you want it to be something different than the title, change it in the content file:
|
||||
|
||||
|
||||
```yaml
|
||||
main_menu: true
|
||||
title: Page Title
|
||||
linkTitle: Title used in links
|
||||
```
|
||||
|
||||
|
||||
{{% note %}}
|
||||
The above needs to be done per language. If you don't see your section in the menu, it is probably because it is not identified as a section by Hugo. Create a `_index.md` content file in the section folder.
|
||||
{{% /note %}}
|
||||
|
||||
### Documentation Side Menu
|
||||
|
||||
The documentation side-bar menu is built from the _current section tree_ starting below `docs/`.
|
||||
|
||||
It will show all sections and their pages.
|
||||
|
||||
If you want a section or page to not be listed, set the `toc_hide` flag in front matter:
|
||||
|
||||
|
||||
```yaml
|
||||
toc_hide: true
|
||||
```
|
||||
|
||||
When you navigate to a section, the page shown is the section page (e.g. `_index.md`) if it has content, else the first page inside that section.
|
||||
|
||||
### Documentation Browser
|
||||
|
||||
The page browser on the documentation home page is built from all sections and pages directly below the `docs section`.
|
||||
|
||||
If you want a section or page to not be listed, set the `toc_hide` flag in front matter:
|
||||
|
||||
```yaml
|
||||
toc_hide: true
|
||||
```
|
||||
|
||||
### The Main Menu
|
||||
|
||||
The site links in the top-right menu -- and also in the footer -- are built by page-lookups. This is to make sure that the page actually exists. So, if the `case-studies` section does not exist in a site (language), it will not be linked to.
|
||||
|
||||
|
||||
## Page Bundles
|
||||
|
||||
In addition to standalone content pages (Markdown files), Hugo supports [Page Bundles](https://gohugo.io/content-management/page-bundles/).
|
||||
|
||||
One example is [Custom Hugo Shortcodes](/docs/home/contribute/includes/). It is a socalled `leaf bundle`. Everything below the directory with the `index.md` will be part of the bundle, with page-relative links, images can be processed etc.:
|
||||
|
||||
```bash
|
||||
en/docs/home/contribute/includes
|
||||
├── example1.md
|
||||
├── example2.md
|
||||
├── index.md
|
||||
└── podtemplate.json
|
||||
```
|
||||
|
||||
Another example used widely is the `includes` bundle. It has `headless: true` set in front matter, which means that it does not get its own URL. It is only used in other pages.
|
||||
|
||||
```bash
|
||||
en/includes
|
||||
├── default-storage-class-prereqs.md
|
||||
├── federated-task-tutorial-prereqs.md
|
||||
├── federation-content-moved.md
|
||||
├── index.md
|
||||
├── partner-script.js
|
||||
├── partner-style.css
|
||||
├── task-tutorial-prereqs.md
|
||||
├── user-guide-content-moved.md
|
||||
└── user-guide-migration-notice.md
|
||||
```
|
||||
|
||||
Some important notes to the files in the bundles:
|
||||
|
||||
* For translated bundles, any missing non-content files will be inherited from languages above. This avoids duplication.
|
||||
* All the files in a bundle are what Hugo calls `Resources` and you can provide metadata per language, such as parameters and title, even if it does not supports front matter (YAML files etc.). See [Page Resources Metadata](https://gohugo.io/content-management/page-resources/#page-resources-metadata).
|
||||
* The value you get from `.RelPermalink` from a `Resource` is page-relative.
|
||||
|
||||
|
||||
## Styles
|
||||
|
||||
The `SASS` source of the stylesheets for this site is stored below `src/sass` and can be built with `make sass` (note that Hugo will get `SASS` support soon, see https://github.com/gohugoio/hugo/issues/4243).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
* [Custom Hugo shortcodes](/docs/contribute/style/hugo_shortcodes)
|
||||
* [Style guide](/docs/contribute/style/style-guide)
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
title: Example #1
|
||||
---
|
||||
|
||||
This is an **example** content file inside the **includes** leaf bundle.
|
||||
|
||||
{{< note >}}
|
||||
**Note:** Included content files can also contain shortcodes.
|
||||
{{< /note >}}
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Example #1
|
||||
---
|
||||
|
||||
This is another **example** content file inside the **includes** leaf bundle.
|
||||
|
||||
|
||||
@@ -0,0 +1,211 @@
|
||||
---
|
||||
approvers:
|
||||
- chenopis
|
||||
title: Custom Hugo Shortcodes
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
This page explains the custom Hugo shortcodes that can be used in Kubernetes documentation markdown.
|
||||
|
||||
Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content-management/shortcodes).
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
## Feature state
|
||||
|
||||
In a markdown page (.md file) on this site, you can add a shortcode to display version and state of the documented feature.
|
||||
|
||||
### Feature state demo
|
||||
|
||||
Below is a demo of the feature state snippet. Here it is used to display the feature as stable in Kubernetes version 1.10.
|
||||
|
||||
```
|
||||
{{</* feature-state for_k8s_version="v1.10" state="stable" */>}}
|
||||
```
|
||||
|
||||
Will render to:
|
||||
|
||||
{{< feature-state for_k8s_version="v1.10" state="stable" >}}
|
||||
|
||||
The valid values for `state` are:
|
||||
|
||||
* alpha
|
||||
* beta
|
||||
* deprecated
|
||||
* stable
|
||||
|
||||
### Feature state code
|
||||
|
||||
Below is the template code for each available feature state.
|
||||
|
||||
The displayed Kubernetes version defaults to that of the page or the site. This can be changed by passing the <code>for_k8s_version</code> shortcode parameter.
|
||||
|
||||
````
|
||||
{{</* feature-state for_k8s_version="v1.10" state="stable" */>}}
|
||||
````
|
||||
|
||||
Renders to:
|
||||
|
||||
{{< feature-state for_k8s_version="v1.10" state="stable" >}}
|
||||
|
||||
#### Alpha feature
|
||||
|
||||
````
|
||||
{{</* feature-state feature-state state="alpha" */>}}
|
||||
````
|
||||
|
||||
Renders to:
|
||||
|
||||
{{< feature-state state="alpha" >}}
|
||||
|
||||
|
||||
#### Beta feature
|
||||
|
||||
````
|
||||
{{</* feature-state feature-state state="beta" */>}}
|
||||
````
|
||||
|
||||
Renders to:
|
||||
|
||||
{{< feature-state state="beta" >}}
|
||||
|
||||
#### Stable feature
|
||||
|
||||
````
|
||||
{{</* feature-state feature-state state="stable" */>}}
|
||||
````
|
||||
|
||||
Renders to:
|
||||
|
||||
{{< feature-state state="stable" >}}
|
||||
|
||||
#### Deprecated feature
|
||||
|
||||
````
|
||||
{{</* feature-state feature-state state="deprecated" */>}}
|
||||
````
|
||||
|
||||
Renders to:
|
||||
|
||||
{{< feature-state state="deprecated" >}}
|
||||
|
||||
## Glossary
|
||||
|
||||
You can reference glossary terms with an inclusion that will automatically update and replace content with the relevant links from [our glossary](/docs/reference/glossary/). When the term is moused-over by someone
|
||||
using the online documentation, the glossary entry will display a tooltip.
|
||||
|
||||
The raw data for glossary terms is stored at [https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary), with a content file for each glossary term.
|
||||
|
||||
### Glossary Demo
|
||||
|
||||
For example, the following include within the markdown will render to {{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip:
|
||||
|
||||
````liquid
|
||||
{{</* glossary_tooltip text="cluster" term_id="cluster" */>}}
|
||||
````
|
||||
|
||||
## Tabs
|
||||
|
||||
In a markdown page (`.md` file) on this site, you can add a tab set to display multiple flavors of a given solution.
|
||||
|
||||
The `tabs` shortcode takes these parameters:
|
||||
|
||||
* `name`: The name as shown on the tab.
|
||||
* `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo what code language to use for highlighting.
|
||||
* `include`: The file to include in the tab. If the tab lives in a Hugo [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles), the file -- which can be any MIME type supported by Hugo -- will be looked up in the bundle itself. If not, the content page to include will be looked up relative to the current. Note that with the `include` you will not have any shortcode inner content and must use the self-closing syntax, e.g. {{</* tab name="Content File #1" include="example1" /*/>}}. Non-content files will be code-highlighted. The language to use will be taken from the filename if not provided in `codelang`.
|
||||
|
||||
* If your inner content is markdown, you must use `%`-delimiter to surorund the tab, e.g. `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
|
||||
* You can combine the variations mentioned above inside a tab set.
|
||||
|
||||
Below is a demo of the tabs shortcode.
|
||||
|
||||
{{< note >}}
|
||||
The tab **name** in a `tabs` definition must be unique within a content page.
|
||||
{{< /note >}}
|
||||
|
||||
### Tabs demo: Code highlighting
|
||||
|
||||
```go-text-template
|
||||
{{</* tabs name="tab_with_code" >}}
|
||||
{{{< tab name="Tab 1" codelang="bash" >}}
|
||||
echo "This is tab 1."
|
||||
{{< /tab >}}
|
||||
{{< tab name="Tab 2" codelang="go" >}}
|
||||
println "This is tab 2."
|
||||
{{< /tab >}}}
|
||||
{{< /tabs */>}}
|
||||
```
|
||||
|
||||
Will be rendered as:
|
||||
|
||||
{{< tabs name="tab_with_code" >}}
|
||||
{{< tab name="Tab 1" codelang="bash" >}}
|
||||
echo "This is tab 1."
|
||||
{{< /tab >}}
|
||||
{{< tab name="Tab 2" codelang="go" >}}
|
||||
println "This is tab 2."
|
||||
{{< /tab >}}
|
||||
{{< /tabs >}}
|
||||
|
||||
### Tabs demo: Inline Markdown and HTML
|
||||
|
||||
```go-html-template
|
||||
{{</* tabs name="tab_with_md" >}}
|
||||
{{% tab name="Markdown" %}}
|
||||
This is **some markdown.**
|
||||
{{< note >}}**Note:** It can even contain shortcodes.{{< /note >}}
|
||||
{{% /tab %}}
|
||||
{{< tab name="HTML" >}}
|
||||
<div>
|
||||
<h3>Plain HTML</h3>
|
||||
<p>This is some <i>plain</i> HTML.</p>
|
||||
</div>
|
||||
{{< /tab >}}
|
||||
{{< /tabs */>}}
|
||||
```
|
||||
|
||||
Will be rendered as:
|
||||
|
||||
{{< tabs name="tab_with_md" >}}
|
||||
{{% tab name="Markdown" %}}
|
||||
This is **some markdown.**
|
||||
{{< note >}}**Note:** It can even contain shortcodes.{{< /note >}}
|
||||
{{% /tab %}}
|
||||
{{< tab name="HTML" >}}
|
||||
<div>
|
||||
<h3>Plain HTML</h3>
|
||||
<p>This is some <i>plain</i> HTML.</p>
|
||||
</div>
|
||||
{{< /tab >}}
|
||||
{{< /tabs >}}
|
||||
|
||||
### Tabs demo: File include
|
||||
|
||||
```go-text-template
|
||||
{{</* tabs name="tab_with_file_include" >}}
|
||||
{{< tab name="Content File #1" include="example1" />}}
|
||||
{{< tab name="Content File #2" include="example2" />}}
|
||||
{{< tab name="JSON File" include="podtemplate" />}}
|
||||
{{< /tabs */>}}
|
||||
```
|
||||
|
||||
Will be rendered as:
|
||||
|
||||
{{< tabs name="tab_with_file_include" >}}
|
||||
{{< tab name="Content File #1" include="example1" />}}
|
||||
{{< tab name="Content File #2" include="example2" />}}
|
||||
{{< tab name="JSON File" include="podtemplate" />}}
|
||||
{{< /tabs >}}
|
||||
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
* Learn about [Hugo](https://gohugo.io/).
|
||||
* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
|
||||
* Learn about [using page templates](/docs/home/contribute/page-templates/).
|
||||
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/)
|
||||
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
|
||||
{{% /capture %}}
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"apiVersion": "v1",
|
||||
"kind": "PodTemplate",
|
||||
"metadata": {
|
||||
"name": "nginx"
|
||||
},
|
||||
"template": {
|
||||
"metadata": {
|
||||
"labels": {
|
||||
"name": "nginx"
|
||||
},
|
||||
"generateName": "nginx-"
|
||||
},
|
||||
"spec": {
|
||||
"containers": [{
|
||||
"name": "nginx",
|
||||
"image": "dockerfile/nginx",
|
||||
"ports": [{"containerPort": 80}]
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,239 @@
|
||||
---
|
||||
title: Using Page Templates
|
||||
content_template: templates/concept
|
||||
weight: 30
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
When contributing new topics, apply one of the following templates to them.
|
||||
This standardizes the user experience of a given page.
|
||||
|
||||
The page templates are in the
|
||||
[`_includes/templates`](https://git.k8s.io/website/_includes/templates)
|
||||
directory of the [`kubernetes/website`](https://github.com/kubernetes/website)
|
||||
repository.
|
||||
|
||||
{{< note >}}
|
||||
**Note**: Every new topic needs to use a template. If you are unsure which
|
||||
template to use for a new topic, start with the
|
||||
[concept template](#concept-template).
|
||||
{{< /note >}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
## Concept template
|
||||
|
||||
A concept page explains some aspect of Kubernetes. For example, a concept
|
||||
page might describe the Kubernetes Deployment object and explain the role it
|
||||
plays as an application is deployed, scaled, and updated. Typically, concept
|
||||
pages don't include sequences of steps, but instead provide links to tasks or
|
||||
tutorials.
|
||||
|
||||
|
||||
To write a new concept page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/concepts` directory, with the following characteristics:
|
||||
|
||||
- In the page's YAML front-matter, set `content_template: templates/concept`.
|
||||
- In the page's body, set the required `capture` variables and any optional
|
||||
ones you want to include:
|
||||
|
||||
| Variable | Required? |
|
||||
|===============|===========|
|
||||
| overview | yes |
|
||||
| body | yes |
|
||||
| whatsnext | no |
|
||||
|
||||
The page's body will look like this (remove any optional captures you don't
|
||||
need):
|
||||
|
||||
```
|
||||
{% raw %}
|
||||
{{% capture overview %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
{{% /capture %}}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
- Within each section, write your content. Use the following guidelines:
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- Add the `{{< toc >}}` shortcode to show an in-page table of contents.
|
||||
- For `body`, explain the concept using free-form Markdown.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
|
||||
An example of a published topic that uses the concept template is
|
||||
[Annotations](/docs/concepts/overview/working-with-objects/annotations/). The
|
||||
page you are currently reading also uses the content template.
|
||||
|
||||
## Task template
|
||||
|
||||
A task page shows how to do a single thing, typically by giving a short
|
||||
sequence of steps. Task pages have minimal explanation, but often provide links
|
||||
to conceptual topics that provide related background and knowledge.
|
||||
|
||||
To write a new task page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/tasks` directory, with the following characteristics:
|
||||
|
||||
- In the page's YAML front-matter, set `content_template: templates/task`.
|
||||
- In the page's body, set the required `capture` variables and any optional
|
||||
ones you want to include:
|
||||
|
||||
| Variable | Required? |
|
||||
|===============|===========|
|
||||
| overview | yes |
|
||||
| prerequisites | yes |
|
||||
| steps | no |
|
||||
| discussion | no |
|
||||
| whatsnext | no |
|
||||
|
||||
The page's body will look like this (remove any optional captures you don't
|
||||
need):
|
||||
|
||||
```
|
||||
{% raw %}
|
||||
{{% capture overview %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture discussion %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
{{% /capture %}}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
- Within each section, write your content. Use the following guidelines:
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- Add the `{{< toc >}}` shortcode to show an in-page table of contents.
|
||||
- For `prerequisites`, use bullet lists when possible. Add additional
|
||||
prerequisites below the ones included by the `include` in the example
|
||||
above. The default prerequisites include a running Kubernetes cluster.
|
||||
- For `steps`, use numbered lists.
|
||||
- For discussion, use normal content to expand upon the information covered
|
||||
in `steps`.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
|
||||
An example of a published topic that uses the task template is [Using an HTTP proxy to access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api).
|
||||
|
||||
## Tutorial template
|
||||
|
||||
A tutorial page shows how to accomplish a goal that is larger than a single
|
||||
task. Typically a tutorial page has several sections, each of which has a
|
||||
sequence of steps. For example, a tutorial might provide a walkthrough of a
|
||||
code sample that illustrates a certain feature of Kubernetes. Tutorials can
|
||||
include surface-level explanations, but should link to related concept topics
|
||||
for deep explanations.
|
||||
|
||||
To write a new tutorial page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/tutorials` directory, with the following characteristics:
|
||||
|
||||
- In the page's YAML front-matter, set `content_template: templates/tutorial`.
|
||||
- In the page's body, set the required `capture` variables and any optional
|
||||
ones you want to include:
|
||||
|
||||
| Variable | Required? |
|
||||
|===============|===========|
|
||||
| overview | yes |
|
||||
| prerequisites | yes |
|
||||
| objectives | yes |
|
||||
| lessoncontent | yes |
|
||||
| cleanup | no |
|
||||
| whatsnext | no |
|
||||
|
||||
The page's body will look like this (remove any optional captures you don't
|
||||
need):
|
||||
|
||||
```
|
||||
{% raw %}
|
||||
{{% capture overview %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture objectives %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture lessoncontent %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture cleanup %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
{{% /capture %}}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
- Within each section, write your content. Use the following guidelines:
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- Add the `{{< toc >}}` shortcode to show an in-page table of contents.
|
||||
- For `prerequisites`, use bullet lists when possible. Add additional
|
||||
prerequisites below the ones included by default.
|
||||
- For `objectives`, use bullet lists.
|
||||
- For `lessoncontent`, use a mix of numbered lists and narrative content as
|
||||
appropriate.
|
||||
- For `cleanup`, use numbered lists to describe the steps to clean up the
|
||||
state of the cluster after finishing the task.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
|
||||
An example of a published topic that uses the tutorial template is
|
||||
[Running a Stateless Application Using a Deployment](/docs/tutorials/stateless-application/run-stateless-application-deployment/).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
- Learn about the [style guide](/docs/contribute/style/style-guide/)
|
||||
- Learn about [content organization](/docs/contribute/style/content-organization/)
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
@@ -0,0 +1,394 @@
|
||||
---
|
||||
title: Documentation Style Guide
|
||||
linktitle: Style guide
|
||||
content_template: templates/concept
|
||||
weight: 10
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
This page gives writing style guidelines for the Kubernetes documentation.
|
||||
These are guidelines, not rules. Use your best judgment, and feel free to
|
||||
propose changes to this document in a pull request.
|
||||
|
||||
For additional information on creating new content for the Kubernetes
|
||||
docs, follow the instructions on
|
||||
[using page templates](/docs/contribute/style/page-templates/) and
|
||||
[creating a documentation pull request](/docs/contribute/start/#improve-existing-content).
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
{{< note >}}
|
||||
**Note:** Kubernetes documentation uses [Blackfriday Markdown Renderer](https://github.com/russross/blackfriday) along with a few [Hugo Shortcodes](/docs/home/contribute/includes/) to support glossary entries, tabs,
|
||||
and representing feature state.
|
||||
{{< /note >}}
|
||||
|
||||
## Language
|
||||
|
||||
Kubernetes documentation uses US English.
|
||||
|
||||
## Documentation formatting standards
|
||||
|
||||
### Use camel case for API objects
|
||||
|
||||
When you refer to an API object, use the same uppercase and lowercase letters
|
||||
that are used in the actual object name. Typically, the names of API
|
||||
objects use
|
||||
[camel case](https://en.wikipedia.org/wiki/Camel_case).
|
||||
|
||||
Don't split the API object name into separate words. For example, use
|
||||
PodTemplateList, not Pod Template List.
|
||||
|
||||
Refer to API objects without saying "object," unless omitting "object"
|
||||
leads to an awkward construction.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>The Pod has two containers.</td><td>The pod has two containers.</td></tr>
|
||||
<tr><td>The Deployment is responsible for ...</td><td>The Deployment object is responsible for ...</td></tr>
|
||||
<tr><td>A PodList is a list of Pods.</td><td>A Pod List is a list of pods.</td></tr>
|
||||
<tr><td>The two ContainerPorts ...</td><td>The two ContainerPort objects ...</td></tr>
|
||||
<tr><td>The two ContainerStateTerminated objects ...</td><td>The two ContainerStateTerminateds ...</td></tr>
|
||||
</table>
|
||||
|
||||
### Use angle brackets for placeholders
|
||||
|
||||
Use angle brackets for placeholders. Tell the reader what a placeholder
|
||||
represents.
|
||||
|
||||
1. Display information about a pod:
|
||||
|
||||
kubectl describe pod <pod-name>
|
||||
|
||||
where `<pod-name>` is the name of one of your pods.
|
||||
|
||||
### Use bold for user interface elements
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Click <b>Fork</b>.</td><td>Click "Fork".</td></tr>
|
||||
<tr><td>Select <b>Other</b>.</td><td>Select 'Other'.</td></tr>
|
||||
</table>
|
||||
|
||||
### Use italics to define or introduce new terms
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>A <i>cluster</i> is a set of nodes ...</td><td>A "cluster" is a set of nodes ...</td></tr>
|
||||
<tr><td>These components form the <i>control plane.</i></td><td>These components form the <b>control plane.</b></td></tr>
|
||||
</table>
|
||||
|
||||
### Use code style for filenames, directories, and paths
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Open the <code>envars.yaml</code> file.</td><td>Open the envars.yaml file.</td></tr>
|
||||
<tr><td>Go to the <code>/docs/tutorials</code> directory.</td><td>Go to the /docs/tutorials directory.</td></tr>
|
||||
<tr><td>Open the <code>/_data/concepts.yaml</code><!--to-unbreak-atom-highlighting_--> file.</td><td>Open the /_data/concepts.yaml<!--to-unbreak-atom-highlighting_--> file.</td></tr>
|
||||
</table>
|
||||
|
||||
### Use the international standard for punctuation inside quotes
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>events are recorded with an associated "stage".</td><td>events are recorded with an associated "stage."</td></tr>
|
||||
<tr><td>The copy is called a "fork".</td><td>The copy is called a "fork."</td></tr>
|
||||
</table>
|
||||
|
||||
## Inline code formatting
|
||||
|
||||
### Use code style for inline code and commands
|
||||
|
||||
For inline code in an HTML document, use the `<code>` tag. In a Markdown
|
||||
document, use the backtick (`).
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>The <code>kubectl run</code> command creates a Deployment.</td><td>The "kubectl run" command creates a Deployment.</td></tr>
|
||||
<tr><td>For declarative management, use <code>kubectl apply</code>.</td><td>For declarative management, use "kubectl apply".</td></tr>
|
||||
</table>
|
||||
|
||||
### Use code style for object field names
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Set the value of the <code>replicas</code> field in the configuration file.</td><td>Set the value of the "replicas" field in the configuration file.</td></tr>
|
||||
<tr><td>The value of the <code>exec</code> field is an ExecAction object.</td><td>The value of the "exec" field is an ExecAction object.</td></tr>
|
||||
</table>
|
||||
|
||||
### Use normal style for string and integer field values
|
||||
|
||||
For field values of type string or integer, use normal style without quotation marks.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Set the value of <code>imagePullPolicy</code> to Always.</td><td>Set the value of <code>imagePullPolicy</code> to "Always".</td></tr>
|
||||
<tr><td>Set the value of <code>image</code> to nginx:1.8.</td><td>Set the value of <code>image</code> to <code>nginx:1.8</code>.</td></tr>
|
||||
<tr><td>Set the value of the <code>replicas</code> field to 2.</td><td>Set the value of the <code>replicas</code> field to <code>2</code>.</td></tr>
|
||||
</table>
|
||||
|
||||
## Code snippet formatting
|
||||
|
||||
### Don't include the command prompt
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>kubectl get pods</td><td>$ kubectl get pods</td></tr>
|
||||
</table>
|
||||
|
||||
### Separate commands from output
|
||||
|
||||
Verify that the pod is running on your chosen node:
|
||||
|
||||
kubectl get pods --output=wide
|
||||
|
||||
The output is similar to this:
|
||||
|
||||
NAME READY STATUS RESTARTS AGE IP NODE
|
||||
nginx 1/1 Running 0 13s 10.200.0.4 worker0
|
||||
|
||||
### Versioning Kubernetes examples
|
||||
|
||||
Code examples and configuration examples that include version information should be consistent with the accompanying text. Identify the Kubernetes version in the **Before you begin** section.
|
||||
|
||||
To specify the Kubernetes version for a task or tutorial page, include `min-kubernetes-server-version` in the front matter of the page.
|
||||
|
||||
If the example YAML is in a standalone file, find and review the topics that include it as a reference.
|
||||
Verify that any topics using the standalone YAML have the appropriate version information defined.
|
||||
If a stand-alone YAML file is not referenced from any topics, consider deleting it instead of updating it.
|
||||
|
||||
For example, if you are writing a tutorial that is relevant to Kubernetes version 1.8, the front-matter of your markdown file should look something like:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: <your tutorial title here>
|
||||
min-kubernetes-server-version: v1.8
|
||||
---
|
||||
```
|
||||
|
||||
In code and configuration examples, do not include comments about alternative versions.
|
||||
Be careful to not include incorrect statements in your examples as comments, such as:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1 # earlier versions use...
|
||||
kind: Pod
|
||||
...
|
||||
```
|
||||
|
||||
## Kubernetes.io word list
|
||||
|
||||
A list of Kubernetes-specific terms and words to be used consistently across the site.
|
||||
|
||||
<table>
|
||||
<tr><th>Term</th><th>Usage</th></tr>
|
||||
<tr><td>Kubernetes</td><td>Kubernetes should always be capitalized.</td></tr>
|
||||
<tr><td>Docker</td><td>Docker should always be capitalized.</td></tr>
|
||||
<tr><td>SIG Docs</td><td>SIG Docs rather than SIG-DOCS or other variations.</td></tr>
|
||||
</table>
|
||||
|
||||
## Shortcodes
|
||||
Hugo [Shortcodes](https://gohugo.io/content-management/shortcodes) help create different rhetorical appeal levels. Our documentation supports three different shortcodes in this category: **Note:** {{</* note */>}}, **Caution:** {{</* caution */>}}, and **Warning:** {{</* warning */>}}.
|
||||
|
||||
1. Surround the text with an opening and closing shortcode.
|
||||
|
||||
2. Use the following syntax to apply a style:
|
||||
|
||||
```
|
||||
{{</* note */>}}
|
||||
**Note:** The prefix you use is the same text you use in the tag.
|
||||
{{</* /note */>}}
|
||||
```
|
||||
|
||||
|
||||
The output is:
|
||||
|
||||
{{< note >}}
|
||||
**Note:** The prefix you choose is the same text for the tag.
|
||||
{{< /note >}}
|
||||
|
||||
### Note
|
||||
|
||||
Use {{</* note */>}} to highlight a tip or a piece of information that may be helpful to know.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
{{</* note */>}}
|
||||
**Note:** You can _still_ use Markdown inside these callouts.
|
||||
{{</* /note */>}}
|
||||
```
|
||||
|
||||
The output is:
|
||||
|
||||
{{< note >}}
|
||||
**Note:** You can _still_ use Markdown inside these callouts.
|
||||
{{< /note >}}
|
||||
|
||||
### Caution
|
||||
|
||||
Use {{</* caution */>}} to call attention to an important piece of information to avoid pitfalls.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
{{</* caution */>}}
|
||||
**Caution:** The callout style only applies to the line directly above the tag.
|
||||
{{</* /caution */>}}
|
||||
```
|
||||
|
||||
The output is:
|
||||
|
||||
{{< caution >}}
|
||||
**Caution:** The callout style only applies to the line directly above the tag.
|
||||
{{< /caution >}}
|
||||
|
||||
### Warning
|
||||
|
||||
Use {{</* warning */>}} to indicate danger or a piece of information that is crucial to follow.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
{{</* warning */>}}
|
||||
**Warning:** Beware.
|
||||
{{</* /warning */>}}
|
||||
```
|
||||
|
||||
|
||||
The output is:
|
||||
|
||||
{{< warning >}}
|
||||
**Warning:** Beware.
|
||||
{{< /warning >}}
|
||||
|
||||
## Common Shortcode Issues
|
||||
|
||||
### Ordered Lists
|
||||
|
||||
Shortcodes will interrupt numbered lists unless you indent four spaces before the notice and the tag.
|
||||
|
||||
For example:
|
||||
|
||||
1. Preheat oven to 350˚F
|
||||
|
||||
1. Prepare the batter, and pour into springform pan.
|
||||
{{</* note */>}}**Note:** Grease the pan for best results.{{</* /note */>}}
|
||||
|
||||
1. Bake for 20-25 minutes or until set.
|
||||
|
||||
The output is:
|
||||
|
||||
1. Preheat oven to 350˚F
|
||||
|
||||
1. Prepare the batter, and pour into springform pan.
|
||||
{{< note >}}**Note:** Grease the pan for best results.{{< /note >}}
|
||||
|
||||
1. Bake for 20-25 minutes or until set.
|
||||
|
||||
## Content best practices
|
||||
|
||||
This section contains suggested best practices for clear, concise, and consistent content.
|
||||
|
||||
### Use present tense
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>This command starts a proxy.</td><td>This command will start a proxy.</td></tr>
|
||||
</table>
|
||||
|
||||
Exception: Use future or past tense if it is required to convey the correct
|
||||
meaning.
|
||||
|
||||
### Use active voice
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>You can explore the API using a browser.</td><td>The API can be explored using a browser.</td></tr>
|
||||
<tr><td>The YAML file specifies the replica count.</td><td>The replica count is specified in the YAML file.</td></tr>
|
||||
</table>
|
||||
|
||||
Exception: Use passive voice if active voice leads to an awkward construction.
|
||||
|
||||
### Use simple and direct language
|
||||
|
||||
Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>To create a ReplicaSet, ...</td><td>In order to create a ReplicaSet, ...</td></tr>
|
||||
<tr><td>See the configuration file.</td><td>Please see the configuration file.</td></tr>
|
||||
<tr><td>View the Pods.</td><td>With this next command, we'll view the Pods.</td></tr>
|
||||
|
||||
</table>
|
||||
|
||||
### Address the reader as "you"
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>You can create a Deployment by ...</td><td>We'll create a Deployment by ...</td></tr>
|
||||
<tr><td>In the preceding output, you can see...</td><td>In the preceding output, we can see ...</td></tr>
|
||||
</table>
|
||||
|
||||
### Avoid Latin phrases
|
||||
|
||||
Prefer English terms over Latin abbreviations.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>For example, ...</td><td>e.g., ...</td></tr>
|
||||
<tr><td>That is, ...</td><td>i.e., ...</td></tr>
|
||||
</table>
|
||||
|
||||
Exception: Use "etc." for et cetera.
|
||||
|
||||
## Patterns to avoid
|
||||
|
||||
### Avoid using "we"
|
||||
|
||||
Using "we" in a sentence can be confusing, because the reader might not know
|
||||
whether they're part of the "we" you're describing.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Version 1.4 includes ...</td><td>In version 1.4, we have added ...</td></tr>
|
||||
<tr><td>Kubernetes provides a new feature for ...</td><td>We provide a new feature ...</td></tr>
|
||||
<tr><td>This page teaches you how to use pods.</td><td>In this page, we are going to learn about pods.</td></tr>
|
||||
</table>
|
||||
|
||||
### Avoid jargon and idioms
|
||||
|
||||
Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Internally, ...</td><td>Under the hood, ...</td></tr>
|
||||
<tr><td>Create a new cluster.</td><td>Turn up a new cluster.</td></tr>
|
||||
</table>
|
||||
|
||||
### Avoid statements about the future
|
||||
|
||||
Avoid making promises or giving hints about the future. If you need to talk about
|
||||
an alpha feature, put the text under a heading that identifies it as alpha
|
||||
information.
|
||||
|
||||
### Avoid statements that will soon be out of date
|
||||
|
||||
Avoid words like "currently" and "new." A feature that is new today might not be
|
||||
considered new in a few months.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>In version 1.4, ...</td><td>In the current version, ...</td></tr>
|
||||
<tr><td>The Federation feature provides ...</td><td>The new Federation feature provides ...</td></tr>
|
||||
</table>
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
|
||||
* Learn about [using page templates](/docs/home/contribute/page-templates/).
|
||||
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/)
|
||||
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
|
||||
|
||||
{{% /capture %}}
|
||||
@@ -0,0 +1,181 @@
|
||||
---
|
||||
title: Writing a new topic
|
||||
content_template: templates/task
|
||||
weight: 20
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
This page shows how to create a new topic for the Kubernetes docs.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
Create a fork of the Kubernetes documentation repository as described in
|
||||
[Start contributing](/docs/contribute/start/).
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
## Choosing a page type
|
||||
|
||||
As you prepare to write a new topic, think about which of these page types
|
||||
is the best fit for your content:
|
||||
|
||||
<table>
|
||||
|
||||
<tr>
|
||||
<td>Concept</td>
|
||||
<td>A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see <a href="/docs/concepts/architecture/nodes/">Nodes</a>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Task</td>
|
||||
<td>A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see <a href="/docs/tasks/configure-pod-container/configure-volume-storage/">Configure a Pod to Use a Volume for Storage</a>. For an example of a longer task page, see <a href="/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/">Configure Liveness and Readiness Probes</a></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Tutorial</td>
|
||||
<td>A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
Use a template for each new page. Each page type has a
|
||||
[template](/docs/contribute/style/page-templates/)
|
||||
that you can use as you write your topic. Using templates helps ensure
|
||||
consistency among topics of a given type.
|
||||
|
||||
## Choosing a title and filename
|
||||
|
||||
Choose a title that has the keywords you want search engines to find.
|
||||
Create a filename that uses the words in your title separated by hyphens.
|
||||
For example, the topic with title
|
||||
[Using an HTTP Proxy to Access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api/)
|
||||
has filename `http-proxy-access-api.md`. You don't need to put
|
||||
"kubernetes" in the filename, because "kubernetes" is already in the
|
||||
URL for the topic, for example:
|
||||
|
||||
http://kubernetes.io/docs/tasks/access-kubernetes-api/http-proxy-access-api/
|
||||
|
||||
## Adding the topic title to the front matter
|
||||
|
||||
In your topic, put a `title` field in the
|
||||
[front matter](https://jekyllrb.com/docs/frontmatter/).
|
||||
The front matter is the YAML block that is between the
|
||||
triple-dashed lines at the top of the page. Here's an example:
|
||||
|
||||
---
|
||||
title: Using an HTTP Proxy to Access the Kubernetes API
|
||||
---
|
||||
|
||||
## Choosing a directory
|
||||
|
||||
Depending on your page type, put your new file in a subdirectory of one of these:
|
||||
|
||||
* /content/en/docs/tasks/
|
||||
* /content/en/docs/tutorials/
|
||||
* /content/en/docs/concepts/
|
||||
|
||||
You can put your file in an existing subdirectory, or you can create a new
|
||||
subdirectory.
|
||||
|
||||
## Placing your topic in the table of contents
|
||||
|
||||
The table of contents is built dynamicaly using the directory structure of the
|
||||
documentation source. The top-level directories under `/content/en/docs/` create
|
||||
top-level navigation, and subdirectories each have entries in the table of
|
||||
contents.
|
||||
|
||||
Each subdirectory has a file `_index.md`, which represents the "home" page for
|
||||
a given subdirectory's content. The `_index.md` does not need a template. It
|
||||
can contain overview content about the topics in the subdirectory.
|
||||
|
||||
Other files in a directory are sorted alphabetically by default. This is almost
|
||||
never the best order. To control the relative sorting of topics in a
|
||||
subdirectory, set the `weight:` front-matter key to an integer. Typically, we
|
||||
use multiples of 10, to account for adding topics later. For instance, a topic
|
||||
with weight `10` will come before one with weight `20`.
|
||||
|
||||
## Embedding code in your topic
|
||||
|
||||
If you want to include some code in your topic, you can embed the code in your
|
||||
file directly using the markdown code block syntax. This is recommended for the
|
||||
following cases (not an exhaustive list):
|
||||
|
||||
- The code shows the output from a command such as
|
||||
`kubectl get deploy mydeployment -o json | jq '.status'`.
|
||||
- The code is not generic enough for users to try out. As an example, you can
|
||||
embed the YAML
|
||||
file for creating a Pod which depends on a specific
|
||||
[FlexVolume](/docs/concepts/storage/volumes#flexvolume) implementation.
|
||||
- The code is an incomplete example because its purpose is to highlight a
|
||||
portion of a larger file. For example, when describing ways to
|
||||
customize the [PodSecurityPolicy](/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy)
|
||||
for some reasons, you can provide a short snippet directly in your topic file.
|
||||
- The code is not meant for users to try out due to other reasons. For example,
|
||||
when describing how a new attribute should be added to a resource using the
|
||||
`kubectl edit` command, you can provide a short example that includes only
|
||||
the attribute to add.
|
||||
|
||||
## Including code from another file
|
||||
|
||||
Another 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.
|
||||
|
||||
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:
|
||||
|
||||
<pre>{{< codenew file="<RELPATH>/my-example-yaml>" >}}</pre>
|
||||
|
||||
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" */>}}
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
**Note**: To show raw Hugo shortcodes as in the above example and prevent Hugo
|
||||
from interpreting them, use C-style comments directly after the `<` and before
|
||||
the `>` characters. View the code for this page for an example.
|
||||
{{< /note >}}
|
||||
|
||||
## Showing how to create an API object from a configuration file
|
||||
|
||||
If you need to demonstrate how to create an API object based on a
|
||||
configuration file, place the configuration file in one of the subdirectories
|
||||
under `<LANG>/examples`.
|
||||
|
||||
In your topic, show this command:
|
||||
|
||||
```
|
||||
kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
**Note**: When adding new YAML files to the `<LANG>/examples` directory, make
|
||||
sure the file is also included into the `<LANG>/examples_test.go` file. The
|
||||
Travis CI for the Website automatically runs this test case when PRs are
|
||||
submitted to ensure all examples pass the tests.
|
||||
{{< /note >}}
|
||||
|
||||
For an example of a topic that uses this technique, see
|
||||
[Running a Single-Instance Stateful Application](/docs/tutorials/stateful-application/run-stateful-application/).
|
||||
|
||||
## Adding images to a topic
|
||||
|
||||
Put image files in the `/images` directory. The preferred
|
||||
image format is SVG.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
* Learn about [using page templates](/docs/home/contribute/page-templates/).
|
||||
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/).
|
||||
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user