[glossary] Glossary MVP (#4865)

* [glossary] Glossary MVP

* resolve conflict

* initial pass at includable glossary data

* tag to term mapping

* Change StatefulSets to singular, StatefulSet

* revise glossary style guide, move

* make descriptions plural

_includes/glossary/_glossary-template.md

@@ -1,24 +0,0 @@
-
----
-term: Some Fancy K8s Term
-formerly:
-- Slang K8s Term
-- Misnomer
-- Formerly Known as Prince
-related:
-- Less Fancy K8s Term
-- Tangential Term
-- Commonly Used With
----
-
-{% capture short-description %}
-Required. One or two lines that provide a minimum definition. Do not repeat the term. Prefer fragments. Model after tooltips.
-{% endcapture %}
-
-{% capture long-description %}
-Optional. Longer additional text to appear after (in conjunction with) short description. Provide where the short description is not sufficient as the intro paragraph to a topic. Write complete but concise sentences.
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed hendrerit dictum nisi quis posuere. Integer eleifend neque lobortis ultrices viverra. Praesent viverra placerat ex sit amet aliquet. Aliquam non ipsum ut lectus viverra pulvinar id vitae nisi. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Suspendisse aliquet congue tristique. Pellentesque at condimentum orci, iaculis pellentesque urna. Aliquam ut rhoncus lorem, a tristique est. Quisque eu est sem.
-
-Suspendisse id feugiat orci. Etiam in posuere arcu, id euismod velit. Etiam pulvinar lectus at diam porta, non lobortis dolor blandit. Donec id faucibus elit. Suspendisse auctor ligula purus, id aliquam odio vehicula a. Donec pretium ligula at nulla pulvinar, sed ultrices ligula dapibus. Cras lacinia mauris ut metus rutrum volutpat. Sed fermentum lobortis ipsum, in hendrerit lectus consectetur sed. Aliquam pulvinar tortor tellus, ac luctus est euismod congue. Maecenas enim ipsum, maximus a turpis eu, blandit imperdiet lacus.
-{% endcapture %}

_includes/tag-map.md

@@ -0,0 +1,15 @@
+<!-- Use include_cached when incorporating this file, in order to reduce computation/build time -->
+
+{% assign glossary_terms = site.data.glossary | where_exp: "term", "term.id != '_example'" %}
+
+{% assign tag_map = "" | split: " " %}
+
+{% for tag in site.data.canonical-tags %}
+
+{% assign term_list = glossary_terms | where_exp:"term", "term.tags contains tag" | map: "id" %}
+
+{% assign tag_obj = "" | split: " " | push: tag | push: term_list %}
+
+{% assign tag_map = tag_map | push: tag_obj %}
+
+{% endfor %}

_includes/templates/glossary/README.md

@@ -0,0 +1,62 @@
+# Kubernetes Glossary
+
+To write a glossary snippet, start with a copy of the template, [`/_data/glossary/_example.yml`](/_data/glossary/_example.yml). Make sure to provide (or omit) values for the following fields:
+
+* (Required) `id`.
+  * This field must match the name of the glossary file itself (without the `*.yml` extension). It is *not* intended to be displayed to users, and is only used programmatically.
+* (Required) `name`.
+  * The name of the term.
+* (Required) `tags`.
+  * Must be one of the tags listed in kubernetes.github.io/_data/canonical-terms-tags.yml.
+* (Required) `short description`.
+  * Make sure to replace the instructional text in the template with your content.
+* (Optional) `formerly` and `related`.
+  * If you do not provide these values, remove the fields.
+* (Optional) `long description`.
+  * If you do not provide a long description, remove the field -- that is, the complete key-value pair.
+
+The `_example.yml` template also contains basic information about how to write your snippet. For additional guidance, continue reading this readme.
+
+## Glossary snippet style guide
+
+This style guide supplements the guidance provided in the glossary template. It's intended to help you think about what and how to write glossary definitions. For more general guidance on style, consult [the core docs style guide](https://kubernetes.io/docs/home/contribute/style-guide/).
+
+### Minimum viable snippet:
+
+Every snippet must include at least the short description. The long description is optional, but should be provided for terms that need additional clarification. For consistency with existing *Concept* definitions, *write your definitions as if the term is plural*.
+
+**short-description** (Required): One line (or two short lines) that provides a minimum definition. Do not repeat the term. Prefer fragments. Model after tooltips. End with a period.
+
+**long-description** (Optional): Longer additional text to appear after (in conjunction with) short description. Provide in cases where the short description is not sufficient for the intro paragraph to a topic. Write complete but concise sentences.
+
+### Examples
+
+```yaml
+- name: Pod
+- tags:
+  - Fundamental
+  - Workload
+  - API Object
+- short-description: The smallest and simplest Kubernetes objects. Represent a set of running processes on your cluster.
+- long-description: Pods most often run only a single container, and are managed by a Deployment.
+```
+
+```yaml
+- name: Deployment
+- tags:
+  - Fundamental
+  - Workload
+  - API Object
+- short-description: Controllers that provide declarative updates for Pods and ReplicaSets.
+- long-description: Deployments are responsible for creating and updating instances of an application.
+```
+
+### Thinking about definitions
+
+* **Think of the short description as it would appear in a tooltip.** Is it sufficient to get the reader started? Is it short enough to be read inside a small UI element?
+
+  *Tip*: look at the API reference doc content (for example, https://kubernetes.io/docs/api-reference/v1.7/). Note, however, that this content should be used with care. The concept docs for Pod, for example, are clearer than the reference docs.
+
+* **The long description should follow the short description to make a complete introduction to a topic.** (This is the content that appears at the top of the content, before any generated TOC.) Does it provide information that's not already clear from the short description? Does it provide information that readers should have a general sense of before they dive into the details of the topic it helps introduce?
+
+  *Tip:* the long description does not need to be long; it's intended to extend but not replace the short description. Look through current related docs for ideas. (The Deployment long description is taken from a tutorial, for example.)

_includes/templates/glossary/_error.md

@@ -0,0 +1,10 @@
+### ERROR: You must define a <span style="font-family: monospace">`{{ include.missing_block }}`</span> field
+{: style="color:red" }
+
+The glossary template requires that you provide text that {{ include.purpose }}.
+
+To get rid of this message and take advantage of this template, define the `{{ include.missing_block }}`
+field for the `{{ include.term }}` glossary term and populate it with content.
+
+See `_data/glossary/_example.yml` for reference.
+<!-- TEMPLATE_ERROR -->

_includes/templates/glossary/snippet.md

@@ -0,0 +1,25 @@
+{% assign term_data = site.data.glossary.[include.term] %}
+
+{% if term_data.short-description %}
+
+{{ term_data.short-description | markdownify }}
+
+{% else %}
+
+{% include templates/glossary/_error.md term=term_data.name missing_block='short-description' purpose='concisely describes the key term in 1-2 lines' %}
+
+{% endif %}
+
+{% if include.length == "long" %}
+
+{% if term_data.long-description %}
+
+{{ term_data.long-description | markdownify }}
+
+{% else %}
+
+{% include templates/glossary/_error.md term=term_data.name missing_block='long-description' purpose='describes the key term in greater depth, supplementing the short-description' %}
+
+{% endif %}
+
+{% endif %}