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,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 %}}
|
||||
|
||||
Reference in New Issue
Block a user