whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

create page-content-types

Browse Source
This commit is contained in:
Karen Bradshaw
2020-06-01 12:46:54 -04:00
parent 758a0eceb0
commit 38250940c3
12 changed files with 226 additions and 247 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/concepts/_index.md
+2 -2
View File
@@ -66,7 +66,7 @@ The nodes in a cluster are the machines (VMs, physical servers, etc) that run yo
If you would like to write a concept page, see
[Using Page Templates](/docs/home/contribute/page-templates/)
for information about the concept page type and the concept template.
[Page Content Types](/docs/home/contribute/style/page-content-types/#concept)
for information about the concept page types.
content/en/docs/concepts/example-concept-template.md
+2 -2
View File
@@ -33,8 +33,8 @@ To use ...
**[Optional Section]**
* Learn more about [Writing a New Topic](/docs/home/contribute/write-new-topic/).
* See [Using Page Templates - Concept template](/docs/home/contribute/page-templates/#concept_template) for how to use this template.
* Learn more about [Writing a New Topic](/docs/home/contribute/style/write-new-topic/).
* See [Page Content Types - Concept](/docs/home/contribute/style/page-concept-types/#concept).
content/en/docs/contribute/_index.md
+1 -1
View File
@@ -48,7 +48,7 @@ roles and permissions.
- [Open a pull request using GitHub](/docs/contribute/new-content/new-content/#changes-using-github) to existing documentation and learn more about filing issues in GitHub.
- [Review pull requests](/docs/contribute/review/reviewing-prs/) from other Kubernetes community members for accuracy and language.
- Read the Kubernetes [content](/docs/contribute/style/content-guide/) and [style guides](/docs/contribute/style/style-guide/) so you can leave informed comments.
- Learn how to [use page templates](/docs/contribute/style/page-templates/) and [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) to make bigger changes.
- Learn about [page content types](/docs/contribute/style/page-content-types/) and [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/).
## Next steps
content/en/docs/contribute/new-content/overview.md
+1 -1
View File
@@ -19,7 +19,7 @@ This section contains information you should know before contributing new conten
- Write Kubernetes documentation in Markdown and build the Kubernetes site using [Hugo](https://gohugo.io/).
- The source is in [GitHub](https://github.com/kubernetes/website). You can find Kubernetes documentation at `/content/en/docs/`. Some of the reference documentation is automatically generated from scripts in the `update-imported-docs/` directory.
- [Page templates](/docs/contribute/style/page-templates/) control the presentation of documentation content in Hugo.
- [Page content types](/docs/contribute/style/page-content-types/) describe the presentation of documentation content in Hugo.
- In addition to the standard Hugo shortcodes, we use a number of [custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) in our documentation to control the presentation of content.
- Documentation source is available in multiple languages in `/content/`. Each language has its own folder with a two-letter code determined by the [ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php). For example, English documentation source is stored in `/content/en/docs/`.
- For more information about contributing to documentation in multiple languages or starting a new translation, see [localization](/docs/contribute/localization).
content/en/docs/contribute/review/reviewing-prs.md
+1 -1
View File
@@ -86,7 +86,7 @@ When reviewing, use the following as a starting point.
- Did this PR change or remove a page title, slug/alias or anchor link? If so, are there broken links as a result of this PR? Is there another option, like changing the page title without changing the slug?
- Does the PR introduce a new page? If so:
- Is the page using the right [page template](/docs/contribute/style/page-templates/) and associated Hugo shortcodes?
- Is the page using the right [page content type](/docs/contribute/style/page-content-types/) and associated Hugo shortcodes?
- Does the page appear correctly in the section's side navigation (or at all)?
- Should the page appear on the [Docs Home](/docs/home/) listing?
- Do the changes show up in the Netlify preview? Be particularly vigilant about lists, code blocks, tables, notes and images.
content/en/docs/contribute/style/hugo-shortcodes/index.md
+2 -2
View File
@@ -240,8 +240,8 @@ Renders to:
## {{% heading "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 [writing a new topic](/docs/home/contribute/style/write-new-topic/).
* Learn about [page content types](/docs/home/contribute/style/page-content-types/).
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/)
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
content/en/docs/contribute/style/page-content-types.md
+207
View File
@@ -0,0 +1,207 @@
---
title: Page content types
content_type: concept
weight: 30
card:
name: contribute
weight: 30
---
<!-- overview -->
The Kubernetes documentation follows several types of page content:
- Concept
- Task
- Tutorial
- Reference
Content pages contain HTML headings that create structure on the page.
<!-- body -->
## Content sections
Each page content type contains a number of sections.
Most of the main sections are outlined in the page using Markdown comments.
This page structure helps to maintain the different content types.
For example,
```
<!-- body -->
```
```
<!-- overview -->
```
To create localized headings for common headings, use the `heading` shortcode
in your content pages. Common localized headings are:
- whatsnext
- prerequisites
- objectives
- cleanup
To create a localized `whatsnext` heading on a page, you can add to your page:
```none
## {{%/* heading "whatsnext" */%}}
```
The `whatsnext` heading displays as:
## {{% heading "whatsnext" %}}
To create a localized `prerequisites` heading on a page, you can add to your page:
```none
## {{%/* heading "prerequisites" */%}}
```
The `prerequisites heading displays as:
## {{% heading "prerequisites" %}}
The `heading` shortcode takes one parameter.
The string should match the prefix of a variable in the localized file, such `i18n/en.toml`:
```
[whatsnext_heading]
other = "What's next"
```
Another localized file, such as `i18n/ko.toml`:
```
[whatsnext_heading]
other = "다음 내용"
```
## Concept
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 once it 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:
Concept pages are divided into three sections:
| Page section |
|---------------|
| overview |
| body |
| whatsnext |
Fill each section with content. Follow these guidelines:
- Organize content with H2 and H3 headings.
- For `overview`, set the topic's context with a single paragraph.
- For `body`, explain the concept.
- For `whatsnext`, provide a bulleted list of topics (5 maximum) to learn more about the concept.
[Annotations](/docs/concepts/overview/working-with-objects/annotations/) is a published example of a concept page.
## Task
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:
| Page section |
|---------------|
| overview |
| prerequisites |
| steps |
| discussion |
| whatsnext |
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.
- For `prerequisites`, use bullet lists when possible. Start adding additional
prerequisites below the `include`. 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 task topic is [Using an HTTP proxy to access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api).
## Tutorial
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:
| Page section |
|---------------|
| overview |
| prerequisites |
| objectives |
| lessoncontent |
| cleanup |
| whatsnext |
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.
- 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 tutorial topic is
[Running a Stateless Application Using a Deployment](/docs/tutorials/stateless-application/run-stateless-application-deployment/).
## Reference
A component tool reference page shows the `--help` output for a Kubernetes component tool.
Each page output depends upon the component tool's source code in `kubernetes/kubernetes`.
Typically a tool reference page has several sections:
| Page section |
|------------------------------|
| synopsis |
| options |
| options from parent commands |
| examples |
| body |
| seealso |
An example of a published tool reference topic is:
- [kubeadm init](/docs/reference/setup-tools/kubeadm/kubeadm-init/)
- [kube-apiserver](/docs/reference/command-line-tools-reference/kube-apiserver/)
- [kubectl](/docs/reference/kubectl/kubectl/)
## {{% heading "whatsnext" %}}
- Learn about the [Style guide](/docs/contribute/style/style-guide/)
- Learn about the [Content guide](/docs/contribute/style/content-guide/)
- Learn about [content organization](/docs/contribute/style/content-organization/)
content/en/docs/contribute/style/page-templates.md
-223
View File
@@ -1,223 +0,0 @@
---
title: Using Page Templates
content_type: concept
weight: 30
card:
name: contribute
weight: 30
---
<!-- 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
[`layouts/partials/templates`](https://git.k8s.io/website/layouts/partials/templates)
directory of the [`kubernetes/website`](https://github.com/kubernetes/website)
repository.
{{< 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 >}}
<!-- 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 once it 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_type: 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):
```
{{%/* capture overview */%}}
{{%/* /capture */%}}
{{%/* capture body */%}}
{{%/* /capture */%}}
{{%/* capture whatsnext */%}}
{{%/* /capture */%}}
```
- Fill each section with content. Follow these guidelines:
- Organize content with H2 and H3 headings.
- For `overview`, set the topic's context with a single paragraph.
- For `body`, explain the concept.
- For `whatsnext`, provide a bulleted list of topics (5 maximum) to learn more about the concept.
[Annotations](/docs/concepts/overview/working-with-objects/annotations/) is a published example of the concept template. This page also uses the concept 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_type: 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):
```
{{%/* capture overview */%}}
{{%/* /capture */%}}
{{%/* capture prerequisites */%}}
{{</* include "task-tutorial-prereqs.md" */>}} {{</* version-check */>}}
{{%/* /capture */%}}
{{%/* capture steps */%}}
{{%/* /capture */%}}
{{%/* capture discussion */%}}
{{%/* /capture */%}}
{{%/* capture whatsnext */%}}
{{%/* /capture */%}}
```
- 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.
- For `prerequisites`, use bullet lists when possible. Start adding additional
prerequisites below the `include`. 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_type: 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):
```
{{%/* capture overview */%}}
{{%/* /capture */%}}
{{%/* capture prerequisites */%}}
{{</* include "task-tutorial-prereqs.md" */>}} {{</* version-check */>}}
{{%/* /capture */%}}
{{%/* capture objectives */%}}
{{%/* /capture */%}}
{{%/* capture lessoncontent */%}}
{{%/* /capture */%}}
{{%/* capture cleanup */%}}
{{%/* /capture */%}}
{{%/* capture whatsnext */%}}
{{%/* /capture */%}}
```
- 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.
- 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/).
## {{% heading "whatsnext" %}}
- Learn about the [Style guide](/docs/contribute/style/style-guide/)
- Learn about the [Content guide](/docs/contribute/style/content-guide/)
- Learn about [content organization](/docs/contribute/style/content-organization/)
content/en/docs/contribute/style/style-guide.md
+4 -7
View File
@@ -11,8 +11,7 @@ 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
documentation, read the [Documentation Content Guide](/docs/contribute/style/content-guide/) and follow the instructions on
[using page templates](/docs/contribute/style/page-templates/) and [creating a documentation pull request](/docs/contribute/new-content/open-a-pr).
documentation, read the [Documentation Content Guide](/docs/contribute/style/content-guide/).
Changes to the style guide are made by SIG Docs as a group. To propose a change
or addition, [add it to the agenda](https://docs.google.com/document/d/1ddHwLK3kUMX1wVFIwlksjTk0MsqitBnWPe1LRa1Rx5A/edit) for an upcoming SIG Docs meeting, and attend the meeting to participate in the
@@ -212,7 +211,7 @@ The output is similar to this:
Code examples and configuration examples that include version information should be consistent with the accompanying text.
If the information is version specific, the Kubernetes version needs to be defined in the `prerequisites` section of the [Task template](/docs/contribute/style/page-templates/#task-template) or the [Tutorial template](/docs/contribute/style/page-templates/#tutorial-template). Once the page is saved, the `prerequisites` section is shown as **Before you begin**.
If the information is version specific, the Kubernetes version needs to be defined in the `prerequisites` section of the [Task template](/docs/contribute/style/page-content-types/#task) or the [Tutorial template](/docs/contribute/style/page-content-types/#tutorial). Once the page is saved, the `prerequisites` section is shown as **Before you begin**.
To specify the Kubernetes version for a task or tutorial page, include `min-kubernetes-server-version` in the front matter of the page.
@@ -591,8 +590,6 @@ The Federation feature provides ... | The new Federation feature provides ...
* Learn about [writing a new topic](/docs/contribute/style/write-new-topic/).
* Learn about [using page templates](/docs/contribute/style/page-templates/).
* Learn about [using page templates](/docs/contribute/style/page-content-types/).
* Learn about [staging your changes](/docs/contribute/stage-documentation-changes/)
* Learn about [creating a pull request](/docs/contribute/start/#submit-a-pull-request/).
* Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/).
content/en/docs/contribute/style/write-new-topic.md
+3 -4
View File
@@ -28,9 +28,8 @@ Task | A task page shows how to do a single thing. The idea is to give readers a
Tutorial | 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.
{{< /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
Use a [content type](/docs/contribute/style/page-content-types/) for each new page
that you write. Using page type helps ensure
consistency among topics of a given type.
## Choosing a title and filename
@@ -164,6 +163,6 @@ image format is SVG.
## {{% heading "whatsnext" %}}
* Learn about [using page templates](/docs/contribute/page-templates/).
* Learn about [using page content types](/docs/contribute/style/page-content-types/).
* Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/).
content/en/docs/tasks/example-task-template.md
+1 -2
View File
@@ -49,5 +49,4 @@ Here's an interesting thing to know about the steps you just did.
**[Optional Section]**
* Learn more about [Writing a New Topic](/docs/home/contribute/write-new-topic/).
* See [Using Page Templates - Task template](/docs/home/contribute/page-templates/#task_template) for how to use this template.
* Learn about [Page Content Types - Task](/docs/home/contribute/style/page-content-types/#task).
content/en/docs/tutorials/_index.md
+2 -2
View File
@@ -70,7 +70,7 @@ Before walking through each tutorial, you may want to bookmark the
If you would like to write a tutorial, see
[Using Page Templates](/docs/home/contribute/page-templates/)
for information about the tutorial page type and the tutorial template.
[Content Page Types](/docs/home/contribute/style/page-content-types/)
for information about the tutorial page type.