From 38250940c339316b7dce237ae2f2989560d088ee Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Mon, 1 Jun 2020 12:46:54 -0400 Subject: [PATCH] create page-content-types --- content/en/docs/concepts/_index.md | 4 +- .../docs/concepts/example-concept-template.md | 4 +- content/en/docs/contribute/_index.md | 2 +- .../docs/contribute/new-content/overview.md | 2 +- .../docs/contribute/review/reviewing-prs.md | 2 +- .../contribute/style/hugo-shortcodes/index.md | 4 +- .../contribute/style/page-content-types.md | 207 ++++++++++++++++ .../docs/contribute/style/page-templates.md | 223 ------------------ .../en/docs/contribute/style/style-guide.md | 11 +- .../docs/contribute/style/write-new-topic.md | 7 +- .../en/docs/tasks/example-task-template.md | 3 +- content/en/docs/tutorials/_index.md | 4 +- 12 files changed, 226 insertions(+), 247 deletions(-) create mode 100644 content/en/docs/contribute/style/page-content-types.md delete mode 100644 content/en/docs/contribute/style/page-templates.md diff --git a/content/en/docs/concepts/_index.md b/content/en/docs/concepts/_index.md index ae9ed7545d..c0ea1a2c8d 100644 --- a/content/en/docs/concepts/_index.md +++ b/content/en/docs/concepts/_index.md @@ -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. diff --git a/content/en/docs/concepts/example-concept-template.md b/content/en/docs/concepts/example-concept-template.md index d5dfd52be1..adf3741f90 100644 --- a/content/en/docs/concepts/example-concept-template.md +++ b/content/en/docs/concepts/example-concept-template.md @@ -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). diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index e518b1f975..2f93af4a35 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -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 diff --git a/content/en/docs/contribute/new-content/overview.md b/content/en/docs/contribute/new-content/overview.md index cdb7174b2a..e9ef332430 100644 --- a/content/en/docs/contribute/new-content/overview.md +++ b/content/en/docs/contribute/new-content/overview.md @@ -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). diff --git a/content/en/docs/contribute/review/reviewing-prs.md b/content/en/docs/contribute/review/reviewing-prs.md index 11a56b17c8..3c271aa44f 100644 --- a/content/en/docs/contribute/review/reviewing-prs.md +++ b/content/en/docs/contribute/review/reviewing-prs.md @@ -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. diff --git a/content/en/docs/contribute/style/hugo-shortcodes/index.md b/content/en/docs/contribute/style/hugo-shortcodes/index.md index 87033f15a5..12d00ae01a 100644 --- a/content/en/docs/contribute/style/hugo-shortcodes/index.md +++ b/content/en/docs/contribute/style/hugo-shortcodes/index.md @@ -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/). diff --git a/content/en/docs/contribute/style/page-content-types.md b/content/en/docs/contribute/style/page-content-types.md new file mode 100644 index 0000000000..e4ee461dc7 --- /dev/null +++ b/content/en/docs/contribute/style/page-content-types.md @@ -0,0 +1,207 @@ +--- +title: Page content types +content_type: concept +weight: 30 +card: + name: contribute + weight: 30 +--- + + + +The Kubernetes documentation follows several types of page content: + +- Concept +- Task +- Tutorial +- Reference + +Content pages contain HTML headings that create structure on the page. + + + +## 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, + +``` + +``` + +``` + +``` + +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/) diff --git a/content/en/docs/contribute/style/page-templates.md b/content/en/docs/contribute/style/page-templates.md deleted file mode 100644 index 7c0616e107..0000000000 --- a/content/en/docs/contribute/style/page-templates.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: Using Page Templates -content_type: concept -weight: 30 -card: - name: contribute - weight: 30 ---- - - - -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 >}} - - - - - - - -## 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 */%}} - - {{}} {{}} - - {{%/* /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 */%}} - - {{}} {{}} - - {{%/* /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/) - - diff --git a/content/en/docs/contribute/style/style-guide.md b/content/en/docs/contribute/style/style-guide.md index 64b2ec0705..78ddd4a787 100644 --- a/content/en/docs/contribute/style/style-guide.md +++ b/content/en/docs/contribute/style/style-guide.md @@ -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/). diff --git a/content/en/docs/contribute/style/write-new-topic.md b/content/en/docs/contribute/style/write-new-topic.md index a6b9e187a1..f0c972c0fd 100644 --- a/content/en/docs/contribute/style/write-new-topic.md +++ b/content/en/docs/contribute/style/write-new-topic.md @@ -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/). diff --git a/content/en/docs/tasks/example-task-template.md b/content/en/docs/tasks/example-task-template.md index b3dd5e8e43..90d14e98da 100644 --- a/content/en/docs/tasks/example-task-template.md +++ b/content/en/docs/tasks/example-task-template.md @@ -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). diff --git a/content/en/docs/tutorials/_index.md b/content/en/docs/tutorials/_index.md index 95b8ec9e1f..5551e5a8ea 100644 --- a/content/en/docs/tutorials/_index.md +++ b/content/en/docs/tutorials/_index.md @@ -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.