From 4ebc47d3160846efbdc0c3799a73d5a6b999071c Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Fri, 3 Jul 2020 09:41:42 -0400 Subject: [PATCH 1/4] add archetype pages for content types --- archetypes/concepts.md | 12 +++++ archetypes/tasks.md | 17 ++++++ archetypes/tutorials.md | 17 ++++++ .../docs/concepts/example-concept-template.md | 41 --------------- content/en/docs/tasks/_index.md | 4 -- .../en/docs/tasks/example-task-template.md | 52 ------------------- 6 files changed, 46 insertions(+), 97 deletions(-) create mode 100644 archetypes/concepts.md create mode 100644 archetypes/tasks.md create mode 100644 archetypes/tutorials.md delete mode 100644 content/en/docs/concepts/example-concept-template.md delete mode 100644 content/en/docs/tasks/example-task-template.md diff --git a/archetypes/concepts.md b/archetypes/concepts.md new file mode 100644 index 0000000000..33653c9114 --- /dev/null +++ b/archetypes/concepts.md @@ -0,0 +1,12 @@ +--- +title: "{{ replace .Name "-" " " | title }}" +content_type: concept +--- + + + + + + + +## {{% heading "whatsnext" %}} diff --git a/archetypes/tasks.md b/archetypes/tasks.md new file mode 100644 index 0000000000..a7bd79c9cd --- /dev/null +++ b/archetypes/tasks.md @@ -0,0 +1,17 @@ +--- +title: "{{ replace .Name "-" " " | title }}" +content_type: task +--- + + + +## {{% heading "prerequisites" %}} + +* {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + + + + + + +## {{% heading "whatsnext" %}} diff --git a/archetypes/tutorials.md b/archetypes/tutorials.md new file mode 100644 index 0000000000..223b480788 --- /dev/null +++ b/archetypes/tutorials.md @@ -0,0 +1,17 @@ +--- +title: "{{ replace .Name "-" " " | title }}" +content_type: tutorial +--- + + + +## {{% heading "prerequisites" %}} + +## {{% heading "objectives" %}} + + + +## {{% heading "cleanup" %}} + + +## {{% heading "whatsnext" %}} diff --git a/content/en/docs/concepts/example-concept-template.md b/content/en/docs/concepts/example-concept-template.md deleted file mode 100644 index adf3741f90..0000000000 --- a/content/en/docs/concepts/example-concept-template.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Example Concept Template -reviewers: -- chenopis -content_type: concept -toc_hide: true ---- - - - -{{< note >}} -Be sure to also [create an entry in the table of contents](/docs/home/contribute/write-new-topic/#creating-an-entry-in-the-table-of-contents) for your new document. -{{< /note >}} - -This page explains ... - - - - - -## Understanding ... - -Kubernetes provides ... - -## Using ... - -To use ... - - - -## {{% heading "whatsnext" %}} - - -**[Optional Section]** - -* 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/tasks/_index.md b/content/en/docs/tasks/_index.md index 552f17e48c..0d424ee4db 100644 --- a/content/en/docs/tasks/_index.md +++ b/content/en/docs/tasks/_index.md @@ -11,9 +11,5 @@ This section of the Kubernetes documentation contains pages that show how to do individual tasks. A task page shows how to do a single thing, typically by giving a short sequence of steps. - -## {{% heading "whatsnext" %}} - - If you would like to write a task page, see [Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/). diff --git a/content/en/docs/tasks/example-task-template.md b/content/en/docs/tasks/example-task-template.md deleted file mode 100644 index 90d14e98da..0000000000 --- a/content/en/docs/tasks/example-task-template.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Example Task Template -reviewers: -- chenopis -content_type: task -toc_hide: true ---- - - - -{{< note >}} -Be sure to also [create an entry in the table of contents](/docs/contribute/style/write-new-topic/#placing-your-topic-in-the-table-of-contents) for your new document. -{{< /note >}} - -This page shows how to ... - - - -## {{% heading "prerequisites" %}} - - -* {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} -* Do this. -* Do this too. - - - - - -## Doing ... - -1. Do this. -1. Do this next. Possibly read this [related explanation](#). - - - - - -## Understanding ... -**[Optional Section]** - -Here's an interesting thing to know about the steps you just did. - - - -## {{% heading "whatsnext" %}} - - -**[Optional Section]** - -* Learn more about [Writing a New Topic](/docs/home/contribute/write-new-topic/). -* Learn about [Page Content Types - Task](/docs/home/contribute/style/page-content-types/#task). From 1950c95b876a3cd929a12b9c7b14d425c93dde97 Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Fri, 3 Jul 2020 10:12:52 -0400 Subject: [PATCH 2/4] cleanup setup, contribute, tutorials index pages --- content/en/docs/contribute/_index.md | 5 +---- content/en/docs/setup/_index.md | 25 +++++-------------------- content/en/docs/tutorials/_index.md | 8 +------- 3 files changed, 7 insertions(+), 31 deletions(-) diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 2f93af4a35..d8f57e5e82 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -3,6 +3,7 @@ content_type: concept title: Contribute to Kubernetes docs linktitle: Contribute main_menu: true +no_list: true weight: 80 card: name: contribute @@ -23,8 +24,6 @@ Kubernetes documentation contributors: Kubernetes documentation welcomes improvements from all contributors, new and experienced! - - ## Getting started @@ -74,5 +73,3 @@ SIG Docs communicates with different methods: - Visit the [Kubernetes community site](/community/). Participate on Twitter or Stack Overflow, learn about local Kubernetes meetups and events, and more. - Read the [contributor cheatsheet](https://github.com/kubernetes/community/tree/master/contributors/guide/contributor-cheatsheet) to get involved with Kubernetes feature development. - Submit a [blog post or case study](/docs/contribute/new-content/blogs-case-studies/). - - diff --git a/content/en/docs/setup/_index.md b/content/en/docs/setup/_index.md index 91b734953c..59db384258 100644 --- a/content/en/docs/setup/_index.md +++ b/content/en/docs/setup/_index.md @@ -20,35 +20,20 @@ card: -This section covers different options to set up and run Kubernetes. - -Different Kubernetes solutions meet different requirements: ease of maintenance, security, control, available resources, and expertise required to operate and manage a cluster. - -You can deploy a Kubernetes cluster on a local machine, cloud, on-prem datacenter, or choose a managed Kubernetes cluster. You can also create custom solutions across a wide range of cloud providers, or bare metal environments. - -More simply, you can create a Kubernetes cluster in learning and production environments. - +This section lists the different ways to set up and run Kubernetes. +When you install Kubernetes, choose an installation type based on: ease of maintenance, security, +control, available resources, and expertise required to operate and manage a cluster. +You can deploy a Kubernetes cluster on a local machine, cloud, on-prem datacenter, or choose a managed Kubernetes cluster. There are also custom solutions across a wide range of cloud providers, or bare metal environments. ## Learning environment -If you're learning Kubernetes, use the Docker-based solutions: tools supported by the Kubernetes community, or tools in the ecosystem to set up a Kubernetes cluster on a local machine. - -{{< table caption="Local machine solutions table that lists the tools supported by the community and the ecosystem to deploy Kubernetes." >}} - -|Community |Ecosystem | -| ------------ | -------- | -| [Minikube](/docs/setup/learning-environment/minikube/) | [Docker Desktop](https://www.docker.com/products/docker-desktop)| -| [kind (Kubernetes IN Docker)](/docs/setup/learning-environment/kind/) | [Minishift](https://docs.okd.io/latest/minishift/)| -| | [MicroK8s](https://microk8s.io/)| - +If you're learning Kubernetes, use the tools supported by the Kubernetes community, or tools in the ecosystem to set up a Kubernetes cluster on a local machine. ## Production environment When evaluating a solution for a production environment, consider which aspects of operating a Kubernetes cluster (or _abstractions_) you want to manage yourself or offload to a provider. [Kubernetes Partners](https://kubernetes.io/partners/#conformance) includes a list of [Certified Kubernetes](https://github.com/cncf/k8s-conformance/#certified-kubernetes) providers. - - diff --git a/content/en/docs/tutorials/_index.md b/content/en/docs/tutorials/_index.md index 0deadcd945..2313d78e87 100644 --- a/content/en/docs/tutorials/_index.md +++ b/content/en/docs/tutorials/_index.md @@ -1,6 +1,7 @@ --- title: Tutorials main_menu: true +no_list: true weight: 60 content_type: concept --- @@ -14,8 +15,6 @@ each of which has a sequence of steps. Before walking through each tutorial, you may want to bookmark the [Standardized Glossary](/docs/reference/glossary/) page for later references. - - ## Basics @@ -64,13 +63,8 @@ Before walking through each tutorial, you may want to bookmark the * [Using Source IP](/docs/tutorials/services/source-ip/) - - ## {{% heading "whatsnext" %}} - If you would like to write a tutorial, see [Content Page Types](/docs/contribute/style/page-content-types/) for information about the tutorial page type. - - From 0249f62e65e15f0f57c5129813ee6529da29e600 Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Fri, 3 Jul 2020 11:02:08 -0400 Subject: [PATCH 3/4] add docs about archetype pages --- content/en/docs/contribute/style/write-new-topic.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/content/en/docs/contribute/style/write-new-topic.md b/content/en/docs/contribute/style/write-new-topic.md index 8bd4b8fbe2..3e4f999c08 100644 --- a/content/en/docs/contribute/style/write-new-topic.md +++ b/content/en/docs/contribute/style/write-new-topic.md @@ -28,9 +28,17 @@ 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 >}} +### Creating a new page + 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. +that you write. The docs site provides templates or +[Hugo archetypes](https://gohugo.io/content-management/archetypes/) to create +new content pages. To create a new type of page, run `hugo new` with the path to the file +you want to create. For example: + +``` +hugo new docs/concepts/my-first-concept.md +``` ## Choosing a title and filename From 23ed3ea1dd24719bb0b7656298a3a6be805acce7 Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Fri, 3 Jul 2020 13:43:24 -0400 Subject: [PATCH 4/4] make version check optional --- archetypes/tasks.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/archetypes/tasks.md b/archetypes/tasks.md index a7bd79c9cd..9067df39ce 100644 --- a/archetypes/tasks.md +++ b/archetypes/tasks.md @@ -7,7 +7,11 @@ content_type: task ## {{% heading "prerequisites" %}} -* {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} +{{< include "task-tutorial-prereqs.md" >}} + +