Fix/re-introduce custom Jekyll tags for better glossary integration (#6163)

Gemfile

@@ -1,4 +1,53 @@
 source "https://rubygems.org"
 
-gem "github-pages", group: :jekyll_plugins
+# gem "github-pages", group: :jekyll_plugins
+
+gem "jekyll", "3.6.0"
+
+group :github_pages_compatible do
+    gem "json", "~> 1.7", ">= 1.7.7"
+    gem "coffee-script", "~> 2.4"
+    gem "coffee-script-source", "~> 1.12"
+    gem "ethon", "~> 0.10"
+    gem "execjs", "~> 2.7"
+    gem "minima", "~> 2.0"
+    gem "terminal-table", "~> 1.4"
+    gem "unicode-display_width", "~> 1.1"
+end
+
+group :jekyll_plugins do
+   gem "jekyll-feed", "~> 0.6"
+   gem "jekyll-sitemap"
+   gem "jekyll-gist"
+   gem "jekyll-paginate", "1.1.0"
+   gem "jekyll-seo-tag"
+   gem "jekyll-avatar", "~> 0.4"
+   gem "jekyll-coffeescript", "~> 1.0"
+   gem "jekyll-default-layout", "~> 0.1"
+   gem "jekyll-github-metadata", "~> 2.2"
+   gem "jekyll-optional-front-matter", "~> 0.1"
+   gem "jekyll-readme-index", "0.0.3"
+   gem "jekyll-redirect-from", "~> 0.11"
+   gem "jekyll-relative-links", "~> 0.2"
+   gem "jekyll-swiss", "~> 0.4"
+   gem "jekyll-theme-architect", "0.0.3"
+   gem "jekyll-theme-cayman", "0.0.3"
+   gem "jekyll-theme-dinky", "0.0.3"
+   gem "jekyll-theme-hacker", "0.0.3"
+   gem "jekyll-theme-leap-day", "0.0.3"
+   gem "jekyll-theme-merlot", "0.0.3"
+   gem "jekyll-theme-midnight", "0.0.3"
+   gem "jekyll-theme-minimal", "0.0.3"
+   gem "jekyll-theme-modernist", "0.0.3"
+   gem "jekyll-theme-primer", "~> 0.1"
+   gem "jekyll-theme-slate", "0.0.3"
+   gem "jekyll-theme-tactile", "0.0.3"
+   gem "jekyll-theme-time-machine", "0.0.3"
+   gem "jekyll-titles-from-headings", "~> 0.1"
+end
+
 gem "jekyll-include-cache", "~> 0.1"
+
+gem "kramdown", "~> 1.11"
+gem "rouge", "~> 2.0"
+gem "pry"

Gemfile.lock

@@ -1,123 +1,61 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (4.2.7)
+    addressable (2.5.2)
-      i18n (~> 0.7)
+      public_suffix (>= 2.0.2, < 4.0)
-      json (~> 1.7, >= 1.7.7)
+    coderay (1.1.2)
-      minitest (~> 5.1)
-      thread_safe (~> 0.3, >= 0.3.4)
-      tzinfo (~> 1.1)
-    addressable (2.5.0)
-      public_suffix (~> 2.0, >= 2.0.2)
     coffee-script (2.4.1)
       coffee-script-source
       execjs
     coffee-script-source (1.12.2)
     colorator (1.1.0)
-    ethon (0.10.1)
+    ethon (0.11.0)
       ffi (>= 1.3.0)
     execjs (2.7.0)
-    faraday (0.10.0)
+    faraday (0.13.1)
       multipart-post (>= 1.2, < 3)
-    ffi (1.9.14)
+    ffi (1.9.18)
     forwardable-extended (2.6.0)
-    gemoji (2.1.0)
+    jekyll (3.6.0)
-    github-pages (112)
-      activesupport (= 4.2.7)
-      github-pages-health-check (= 1.3.0)
-      jekyll (= 3.3.1)
-      jekyll-avatar (= 0.4.2)
-      jekyll-coffeescript (= 1.0.1)
-      jekyll-default-layout (= 0.1.4)
-      jekyll-feed (= 0.8.0)
-      jekyll-gist (= 1.4.0)
-      jekyll-github-metadata (= 2.2.0)
-      jekyll-mentions (= 1.2.0)
-      jekyll-optional-front-matter (= 0.1.2)
-      jekyll-paginate (= 1.1.0)
-      jekyll-readme-index (= 0.0.3)
-      jekyll-redirect-from (= 0.11.0)
-      jekyll-relative-links (= 0.2.1)
-      jekyll-sass-converter (= 1.3.0)
-      jekyll-seo-tag (= 2.1.0)
-      jekyll-sitemap (= 0.12.0)
-      jekyll-swiss (= 0.4.0)
-      jekyll-theme-architect (= 0.0.3)
-      jekyll-theme-cayman (= 0.0.3)
-      jekyll-theme-dinky (= 0.0.3)
-      jekyll-theme-hacker (= 0.0.3)
-      jekyll-theme-leap-day (= 0.0.3)
-      jekyll-theme-merlot (= 0.0.3)
-      jekyll-theme-midnight (= 0.0.3)
-      jekyll-theme-minimal (= 0.0.3)
-      jekyll-theme-modernist (= 0.0.3)
-      jekyll-theme-primer (= 0.1.5)
-      jekyll-theme-slate (= 0.0.3)
-      jekyll-theme-tactile (= 0.0.3)
-      jekyll-theme-time-machine (= 0.0.3)
-      jekyll-titles-from-headings (= 0.1.3)
-      jemoji (= 0.7.0)
-      kramdown (= 1.11.1)
-      liquid (= 3.0.6)
-      listen (= 3.0.6)
-      mercenary (~> 0.3)
-      minima (= 2.0.0)
-      rouge (= 1.11.1)
-      terminal-table (~> 1.4)
-    github-pages-health-check (1.3.0)
-      addressable (~> 2.3)
-      net-dns (~> 0.8)
-      octokit (~> 4.0)
-      public_suffix (~> 2.0)
-      typhoeus (~> 0.7)
-    html-pipeline (2.4.2)
-      activesupport (>= 2)
-      nokogiri (>= 1.4)
-    i18n (0.7.0)
-    jekyll (3.3.1)
       addressable (~> 2.4)
       colorator (~> 1.0)
       jekyll-sass-converter (~> 1.0)
       jekyll-watch (~> 1.1)
-      kramdown (~> 1.3)
+      kramdown (~> 1.14)
-      liquid (~> 3.0)
+      liquid (~> 4.0)
       mercenary (~> 0.3.3)
       pathutil (~> 0.9)
-      rouge (~> 1.7)
+      rouge (>= 1.7, < 3)
       safe_yaml (~> 1.0)
-    jekyll-avatar (0.4.2)
+    jekyll-avatar (0.5.0)
       jekyll (~> 3.0)
     jekyll-coffeescript (1.0.1)
       coffee-script (~> 2.2)
     jekyll-default-layout (0.1.4)
       jekyll (~> 3.0)
-    jekyll-feed (0.8.0)
+    jekyll-feed (0.9.2)
       jekyll (~> 3.3)
-    jekyll-gist (1.4.0)
+    jekyll-gist (1.4.1)
       octokit (~> 4.2)
-    jekyll-github-metadata (2.2.0)
+    jekyll-github-metadata (2.9.3)
       jekyll (~> 3.1)
       octokit (~> 4.0, != 4.4.0)
     jekyll-include-cache (0.1.0)
       jekyll (~> 3.3)
-    jekyll-mentions (1.2.0)
+    jekyll-optional-front-matter (0.3.0)
-      activesupport (~> 4.0)
-      html-pipeline (~> 2.3)
-      jekyll (~> 3.0)
-    jekyll-optional-front-matter (0.1.2)
       jekyll (~> 3.0)
     jekyll-paginate (1.1.0)
     jekyll-readme-index (0.0.3)
       jekyll (~> 3.0)
-    jekyll-redirect-from (0.11.0)
+    jekyll-redirect-from (0.12.1)
-      jekyll (>= 2.0)
-    jekyll-relative-links (0.2.1)
       jekyll (~> 3.3)
-    jekyll-sass-converter (1.3.0)
+    jekyll-relative-links (0.5.1)
-      sass (~> 3.2)
-    jekyll-seo-tag (2.1.0)
       jekyll (~> 3.3)
-    jekyll-sitemap (0.12.0)
+    jekyll-sass-converter (1.5.0)
+      sass (~> 3.4)
+    jekyll-seo-tag (2.3.0)
+      jekyll (~> 3.3)
+    jekyll-sitemap (1.1.1)
       jekyll (~> 3.3)
     jekyll-swiss (0.4.0)
     jekyll-theme-architect (0.0.3)
@@ -138,66 +76,101 @@ GEM
       jekyll (~> 3.3)
     jekyll-theme-modernist (0.0.3)
       jekyll (~> 3.3)
-    jekyll-theme-primer (0.1.5)
+    jekyll-theme-primer (0.5.2)
-      jekyll (~> 3.3)
+      jekyll (~> 3.5)
+      jekyll-github-metadata (~> 2.9)
+      jekyll-seo-tag (~> 2.2)
     jekyll-theme-slate (0.0.3)
       jekyll (~> 3.3)
     jekyll-theme-tactile (0.0.3)
       jekyll (~> 3.3)
     jekyll-theme-time-machine (0.0.3)
       jekyll (~> 3.3)
-    jekyll-titles-from-headings (0.1.3)
+    jekyll-titles-from-headings (0.5.0)
       jekyll (~> 3.3)
     jekyll-watch (1.5.0)
       listen (~> 3.0, < 3.1)
-    jemoji (0.7.0)
-      activesupport (~> 4.0)
-      gemoji (~> 2.0)
-      html-pipeline (~> 2.2)
-      jekyll (>= 3.0)
     json (1.8.6)
-    kramdown (1.11.1)
+    kramdown (1.15.0)
-    liquid (3.0.6)
+    liquid (4.0.0)
-    listen (3.0.6)
+    listen (3.0.8)
-      rb-fsevent (>= 0.9.3)
+      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (>= 0.9.7)
+      rb-inotify (~> 0.9, >= 0.9.7)
     mercenary (0.3.6)
-    mini_portile2 (2.1.0)
+    method_source (0.9.0)
-    minima (2.0.0)
+    minima (2.1.1)
-    minitest (5.10.1)
+      jekyll (~> 3.3)
     multipart-post (2.0.0)
-    net-dns (0.8.0)
+    octokit (4.7.0)
-    nokogiri (1.6.8.1)
-      mini_portile2 (~> 2.1.0)
-    octokit (4.6.2)
       sawyer (~> 0.8.0, >= 0.5.3)
-    pathutil (0.14.0)
+    pathutil (0.16.0)
       forwardable-extended (~> 2.6)
-    public_suffix (2.0.4)
+    pry (0.11.2)
-    rb-fsevent (0.9.8)
+      coderay (~> 1.1.0)
-    rb-inotify (0.9.7)
+      method_source (~> 0.9.0)
-      ffi (>= 0.5.0)
+    public_suffix (3.0.0)
-    rouge (1.11.1)
+    rb-fsevent (0.10.2)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    rouge (2.2.1)
     safe_yaml (1.0.4)
-    sass (3.4.23)
+    sass (3.5.3)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
     sawyer (0.8.1)
       addressable (>= 2.3.5, < 2.6)
       faraday (~> 0.8, < 1.0)
-    terminal-table (1.7.3)
+    terminal-table (1.8.0)
-      unicode-display_width (~> 1.1.1)
+      unicode-display_width (~> 1.1, >= 1.1.1)
-    thread_safe (0.3.5)
+    unicode-display_width (1.3.0)
-    typhoeus (0.8.0)
-      ethon (>= 0.8.0)
-    tzinfo (1.2.2)
-      thread_safe (~> 0.1)
-    unicode-display_width (1.1.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  github-pages
+  coffee-script (~> 2.4)
+  coffee-script-source (~> 1.12)
+  ethon (~> 0.10)
+  execjs (~> 2.7)
+  jekyll (= 3.6.0)
+  jekyll-avatar (~> 0.4)
+  jekyll-coffeescript (~> 1.0)
+  jekyll-default-layout (~> 0.1)
+  jekyll-feed (~> 0.6)
+  jekyll-gist
+  jekyll-github-metadata (~> 2.2)
   jekyll-include-cache (~> 0.1)
+  jekyll-optional-front-matter (~> 0.1)
+  jekyll-paginate (= 1.1.0)
+  jekyll-readme-index (= 0.0.3)
+  jekyll-redirect-from (~> 0.11)
+  jekyll-relative-links (~> 0.2)
+  jekyll-seo-tag
+  jekyll-sitemap
+  jekyll-swiss (~> 0.4)
+  jekyll-theme-architect (= 0.0.3)
+  jekyll-theme-cayman (= 0.0.3)
+  jekyll-theme-dinky (= 0.0.3)
+  jekyll-theme-hacker (= 0.0.3)
+  jekyll-theme-leap-day (= 0.0.3)
+  jekyll-theme-merlot (= 0.0.3)
+  jekyll-theme-midnight (= 0.0.3)
+  jekyll-theme-minimal (= 0.0.3)
+  jekyll-theme-modernist (= 0.0.3)
+  jekyll-theme-primer (~> 0.1)
+  jekyll-theme-slate (= 0.0.3)
+  jekyll-theme-tactile (= 0.0.3)
+  jekyll-theme-time-machine (= 0.0.3)
+  jekyll-titles-from-headings (~> 0.1)
+  json (~> 1.7, >= 1.7.7)
+  kramdown (~> 1.11)
+  minima (~> 2.0)
+  pry
+  rouge (~> 2.0)
+  terminal-table (~> 1.4)
+  unicode-display_width (~> 1.1)
 
 BUNDLED WITH
-   1.15.2
+   1.15.4

_data/glossary/_example.yml

@@ -1,5 +1,6 @@
 id: _example
 name: Example K8s Term
+full-link: kubernetes.io/docs/link-to-long-dedicated-docs-page
 aka:
 - Slang K8s Term
 - Misnomer
@@ -10,8 +11,17 @@ related:
 - id-of-commonly-used-with-term
 tags:
 - Some Tag
-short-description: |
+short-description: >
-  Required. One or two lines that provide a minimum definition. Do not repeat the term. Write about the plural of the term. Prefer fragments. Model after tooltips. End with a period.
+  Required.
-long-description: |
+  Markdown allowed (e.g. for cross-linking).
-  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.
+  One or two lines that provide a minimum definition.
+  Do not repeat the term.
+  Prefer fragments.
+  End with a period.
+long-description: >
+  Optional.
+  Markdown allowed.
+  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.
   **See /_includes/templates/glossary/README.md for the official style guide.**

_data/glossary/application-architect.yaml

@@ -4,7 +4,7 @@ related:
   - application-developer
 tags:
   - user-type
-short-description: |
+short-description: >
   A person responsible for the high-level design of an application.
 long-description: >
   An architect ensures that an app's implementation allows it to interact with its surrounding components in a scalable, maintainable way.

_data/glossary/application-developer.yaml

@@ -4,7 +4,7 @@ related:
   - application-architect
 tags:
   - user-type
-short-description: |
+short-description: >
   A person who writes an application that runs in a Kubernetes cluster.
 long-description: >
   An application developer focuses on one part of an application.

_data/glossary/approver.yaml

@@ -2,7 +2,7 @@ id: approver
 name: Approver
 tags:
 - community
-short-description: |
+short-description: >
   A person who can review and approve Kubernetes code contributions.
 long-description: >
   While code review is focused on code quality and correctness, approval is focused on the holistic acceptance of a contribution.

_data/glossary/cla.yaml

@@ -1,8 +1,9 @@
 id: cla
 name: CLA (Contributor License Agreement)
+full-link: https://github.com/kubernetes/community/blob/master/CLA.md
 tags:
 - community
-short-description: |
+short-description: >
-  Terms under which a [contributor](#term-contributor) grants a license to an open source project for their contributions.
+  Terms under which a {% glossary_tooltip text="contributor" term_id="contributor" %} grants a license to an open source project for their contributions.
-long-description: |
+long-description: >
   CLAs help resolve legal disputes involving contributed material and intellectual property (IP).

_data/glossary/cluster-architect.yaml

@@ -5,8 +5,7 @@ related:
   - cluster-operator
 tags:
   - user-type
-short-description: |
+short-description: >
   A person who designs infrastructure that involves one or more Kubernetes clusters.
-
+long-description: >
-long-description: |
   Cluster architects are concerned with best practices for distributed systems, for example: high availability and security.

_data/glossary/cluster-operator.yaml

@@ -7,9 +7,8 @@ related:
   - cluster-architect
 tags:
   - user-type
-short-description: |
+short-description: >
   A person who configures, controls, and monitors clusters.
-
 long-description: |
   Their primary responsibility is keeping a cluster up and running, which may involve periodic maintenance activities or upgrades.<br>
 

_data/glossary/cluster.yaml

@@ -3,7 +3,7 @@ name: Cluster
 tags:
 - fundamental
 - operation
-short-description: |
+short-description: >
   A set of machines, called nodes, that run containerized applications managed by Kubernetes.
-long-description: |
+long-description: >
   A cluster has several worker nodes and at least one master node.

_data/glossary/code-contributor.yaml

@@ -5,7 +5,7 @@ aka:
 tags:
 - community
 - user-type
-short-description: |
+short-description: >
   A person who develops and contributes code to the Kubernetes open source codebase.
-long-description: |
+long-description: >
-  They are also an active [community member](#term-community-member) who participates in one or more [Special Interest Groups (SIGs)](#term-sig).
+  They are also an active {% glossary_tooltip text="community member" term_id="member" %} who participates in one or more {% glossary_tooltip text="Special Interest Groups (SIGs)" term_id="sig" %}.

_data/glossary/container.yaml

@@ -1,9 +1,10 @@
 id: container
 name: Container
+full-link: /docs/concepts/overview/what-is-kubernetes/#why-containers
 tags:
 - fundamental
 - workload
-short-description: |
+short-description: >
   A lightweight and portable executable image that contains software and all of its dependencies.
-long-description: |
+long-description: >
   Containers decouple applications from underlying host infrastructure to make deployment easier in different cloud or OS environments, and for easier scaling.

_data/glossary/contributor.yaml

@@ -2,7 +2,7 @@ id: contributor
 name: Contributor
 tags:
 - community
-short-description: |
+short-description: >
   Someone who donates code, documentation, or their time to help the Kubernetes project or community.
-long-description: |
+long-description: >
-  Contributions include pull requests (PRs), issues, feedback, [special interest group (SIG)](#term-sig) participation, or organizing community events.
+  Contributions include pull requests (PRs), issues, feedback, {% glossary_tooltip text="special interest groups (SIG)" term_id="sig" %} participation, or organizing community events.

_data/glossary/cronjob.yaml

@@ -1,9 +1,10 @@
 id: cronjob
 name: CronJob
+full-link: /docs/concepts/workloads/controllers/cron-jobs/
 tags:
 - core-object
 - workload
-short-description: |
+short-description: >
-  Manages a [Job](/docs/concepts/jobs/run-to-completion-finite-workloads/) that runs on a periodic schedule.
+  Manages a [Job](/docs/concepts/workloads/controllers/jobs-run-to-completion/) that runs on a periodic schedule.
-long-description: |
+long-description: >
-  Similar to a line in a *crontab* file, a [CronJob](/docs/concepts/workloads/controllers/cron-jobs/#writing-a-cron-job-spec) object specifies a schedule using the [Cron](https://en.wikipedia.org/wiki/Cron) format.
+  Similar to a line in a *crontab* file, a Cronjob object specifies a schedule using the [Cron](https://en.wikipedia.org/wiki/Cron) format.

_data/glossary/deployment.yaml

@@ -1,10 +1,11 @@
 id: deployment
 name: Deployment
+full-link: /docs/concepts/workloads/controllers/deployment/
 tags:
 - fundamental
 - core-object
 - workload
-short-description: |
+short-description: >
   An API object that manages a replicated application.
-long-description: |
+long-description: >
-  Each replica is represented by a [Pod](#term-pod), and the Pods are distributed among the nodes of a cluster.
+  Each replica is represented by a {% glossary_tooltip term_id="pod" %}, and the Pods are distributed among the nodes of a cluster.

_data/glossary/developer.yaml

@@ -5,11 +5,7 @@ aka:
 tags:
 - community
 - user-type
-short-description: |
+short-description: >
-  May refer to: [*Application Developer*](#term-application-developer), [*Code Contributor*](#term-code-contributor), or [*Platform Developer*](#term-platform-developer).
+  May refer to: {% glossary_tooltip text="Application Developer" term_id="application-developer" %}, {% glossary_tooltip text="Code Contributor" term_id="code-contributor" %}, or {% glossary_tooltip text="Platform Developer" term_id="platform-developer" %}.
-long-description: |
+long-description: >
-  This overloaded term may have different meanings depending on the context. It could mean:
+  This overloaded term may have different meanings depending on the context
-
-  * [**Application Developer**](#term-application-developer): A person who writes an application that runs in a Kubernetes cluster.
-  * [**Code Contributor**](#term-code-contributor): A person who develops and contributes code to the Kubernetes open source codebase.
-  * [**Platform Developer**](#term-platform-developer): A person who customizes the Kubernetes platform to fit the needs of their project—for example, by extending the API.

_data/glossary/downstream.yaml

@@ -4,7 +4,7 @@ related:
 - upstream
 tags:
 - community
-short-description: |
+short-description: >
   May refer to: code in the Kubernetes ecosystem that depends upon the core Kubernetes codebase or a forked repo.
 long-description: |
   * In the **Kubernetes Community**: Conversations often use *downstream* to mean the ecosystem, code, or third-party tools that rely on the core Kubernetes codebase. For example, a new feature in Kubernetes may be adopted by applications *downstream* to improve their functionality.

_data/glossary/helm-chart.yaml

@@ -1,8 +1,9 @@
 id: helm-chart
 name: Helm Chart
+full-link: https://github.com/kubernetes/helm/blob/master/docs/charts.md
 tags:
 - tool
-short-description: |
+short-description: >
   A package of pre-configured Kubernetes resources that can be managed with the Helm tool.
 long-description: |
   Charts provide a reproducible way of creating and sharing Kubernetes applications.

_data/glossary/ingress.yaml

@@ -1,10 +1,13 @@
 id: ingress
 name: Ingress
+full-link: /docs/concepts/services-networking/ingress/
+aka:
+  - Ingress controller
 tags:
 - networking
 - architecture
 - extension
-short-description: |
+short-description: >
   An API object that manages external access to the services in a cluster, typically HTTP.
-long-description: |
+long-description: >
   Ingress can provide load balancing, SSL termination and name-based virtual hosting.

_data/glossary/istio.yaml

@@ -1,10 +1,11 @@
 id: istio
 name: Istio
+full-link: https://istio.io/docs/concepts/what-is-istio/overview.html
 tags:
 - networking
 - architecture
 - extension
-short-description: |
+short-description: >
   An open platform (not Kubernetes-specific) that provides a uniform way to integrate microservices, manage traffic flow, enforce policies, and aggregate telemetry data.
 long-description: >
   Adding Istio does not require changing application code.

_data/glossary/kops.yaml

@@ -1,9 +1,10 @@
 id: kops
 name: Kops
+full-link: /docs/getting-started-guides/kops/
 tags:
 - tool
 - operation
-short-description: |
+short-description: >
   A CLI tool that helps you create, destroy, upgrade and maintain production-grade, highly available, Kubernetes clusters. *NOTE: Officially supports AWS only, with GCE and VMware vSphere in alpha*.
 long-description: |
   `kops` provisions your cluster with:
@@ -15,4 +16,4 @@ long-description: |
     * High availability (HA) support
     * The ability to directly provision, or generate terraform manifests
 
-  You can also build your own cluster using [`kubeadm`](#term-kubeadm) as a building block. `kops` builds on the kubeadm work.
+  You can also build your own cluster using {% glossary_tooltip term_id="kubeadm" %} as a building block. `kops` builds on the kubeadm work.

_data/glossary/kubeadm.yaml

@@ -1,9 +1,10 @@
 id: kubeadm
 name: Kubeadm
+full-link: /docs/admin/kubeadm/
 tags:
 - tool
 - operation
-short-description: |
+short-description: >
   A tool for quickly installing Kubernetes and setting up a secure cluster.
-long-description: |
+long-description: >
   You can use kubeadm to install both the control plane and the worker node components.

_data/glossary/kubectl.yaml

@@ -1,9 +1,10 @@
 id: kubectl
 name: Kubectl
+full-link: /docs/user-guide/kubectl-overview/
 tags:
 - tool
 - fundamental
-short-description: |
+short-description: >
-  A command line tool for communicating with a [Kubernetes API](#term-kubernetes-api) server.
+  A command line tool for communicating with a {% glossary_tooltip text="Kubernetes API" term_id="kubernetes-api" %} server.
-long-description: |
+long-description: >
   You can use kubectl to create, inspect, update, and delete Kubernetes objects.

_data/glossary/kubernetes-api.yaml

@@ -1,9 +1,10 @@
 id: kubernetes-api
 name: Kubernetes API
+full-link: /docs/concepts/overview/kubernetes-api/
 tags:
 - fundamental
 - architecture
-short-description: |
+short-description: >
   The application that serves Kubernetes functionality through a RESTful interface and stores the state of the cluster.
 long-description: >
   Kubernetes resources and "records of intent" are all stored as API objects, and modified via RESTful calls to the API.

_data/glossary/maintainer.yaml

@@ -2,7 +2,7 @@ id: maintainer
 name: Maintainer
 tags:
 - community
-short-description: |
+short-description: >
-  A highly experienced [contributor](#term-contributor), active in multiple areas of Kubernetes, who has cross-area ownership and write access to a project's GitHub repository.
+  A highly experienced {% glossary_tooltip text="contributor" term_id="contributor" %}, active in multiple areas of Kubernetes, who has cross-area ownership and write access to a project's GitHub repository.
-long-description: |
+long-description: >
   Maintainers work holistically across the project to maintain its health and success and have made substantial contributions, both through code development and broader organizational efforts.

_data/glossary/member.yaml

@@ -2,9 +2,9 @@ id: member
 name: Member
 tags:
 - community
-short-description: |
+short-description: >
-  A continuously active [contributor](#term-contributor) in the K8s community.
+  A continuously active {% glossary_tooltip text="contributor" term_id="contributor" %} in the K8s community.
 long-description: >
-  Members can have issues and PRs assigned to them and participate in [special interest groups (SIGs)](#term-sig) through GitHub teams.
+  Members can have issues and PRs assigned to them and participate in {% glossary_tooltip text="special interest groups (SIGs)" term_id="sig" %} through GitHub teams.
   Pre-submit tests are automatically run for members' PRs.
   A member is expected to remain an active contributor to the community.

_data/glossary/minikube.yaml

@@ -1,9 +1,10 @@
 id: minikube
 name: Minikube
+full-link: /docs/getting-started-guides/minikube/
 tags:
 - fundamental
 - tool
-short-description: |
+short-description: >
   A tool for running Kubernetes locally.
-long-description: |
+long-description: >
   Minikube runs a single-node cluster inside a VM on your computer.

_data/glossary/platform-developer.yaml

@@ -4,7 +4,7 @@ aka:
   - Kubernetes Developer
 tags:
   - user-type
-short-description: |
+short-description: >
   A person who customizes the Kubernetes platform to fit the needs of their project.
 long-description: >
   A platform developer may, for example, use [Custom Resources](/docs/concepts/api-extension/custom-resources/) or [Extend the Kubernetes API with the aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/) to add functionality to their instance of Kubernetes, specifically for their application.

_data/glossary/pod.yaml

@@ -1,5 +1,6 @@
 id: pod
 name: Pod
+full-link: /docs/concepts/workloads/pods/pod-overview/
 related:
 - container
 - sidecar
@@ -8,9 +9,9 @@ related:
 tags:
 - core-object
 - fundamental
-short-description: |
+short-description: >
-  The smallest and simplest Kubernetes object. A Pod represents a set of running [containers](#term-container) on your cluster.
+  The smallest and simplest Kubernetes object. A Pod represents a set of running {% glossary_tooltip text="containers" term_id="container" %} on your cluster.
 long-description: >
   A Pod is typically set up to run a single primary container.
   It can also run optional sidecar containers that add supplementary features like logging.
-  Pods are commonly managed by a [Deployment](#term-deployment).
+  Pods are commonly managed by a {% glossary_tooltip term_id="deployment" %}.

_data/glossary/rbac.yaml

@@ -1,9 +1,10 @@
 id: rbac
 name: RBAC (Role-Based Access Control)
+full-link: /docs/admin/authorization/rbac/
 tags:
 - security
 - fundamental
-short-description: |
+short-description: >
-  Manages authorization decisions, allowing admins to dynamically configure access policies through the [Kubernetes API](#term-kubernetes-api).
+  Manages authorization decisions, allowing admins to dynamically configure access policies through the {% glossary_tooltip text="Kubernetes API" term_id="kubernetes-api" %}.
-long-description: |
+long-description: >
   RBAC utilizes *roles*, which contain permission rules, and *role bindings*, which grant the permissions defined in a role to a set of users.

_data/glossary/reviewer.yaml

@@ -2,7 +2,7 @@ id: reviewer
 name: Reviewer
 tags:
 - community
-short-description: |
+short-description: >
   A person who reviews code for quality and correctness on some part of the project.
-long-description: |
+long-description: >
   Reviewers are knowledgeable about both the codebase and software engineering principles. Reviewer status is scoped to a part of the codebase.

_data/glossary/service.yaml

@@ -1,9 +1,10 @@
 id: service
 name: Service
+full-link: /docs/concepts/services-networking/service/
 tags:
 - fundamental
 - core-object
-short-description: |
+short-description: >
-  An API object that describes how to access applications, such as a set of [Pods](#term-pod), and can describe ports and load-balancers.
+  An API object that describes how to access applications, such as a set of {% glossary_tooltip text="Pods" term_id="pod" %}, and can describe ports and load-balancers.
-long-description: |
+long-description: >
   The access point can be internal or external to the cluster.

_data/glossary/sig.yaml

@@ -1,10 +1,11 @@
 id: sig
 name: SIG (special interest group)
+full-link: https://github.com/kubernetes/community/blob/master/sig-list.md#master-sig-list
 tags:
 - community
-short-description: |
+short-description: >
-  [Members](#term-member) who collectively manage an ongoing piece or aspect of the larger Kubernetes open source project.
+  {% glossary_tooltip text="Community members" term_id="member" %} who collectively manage an ongoing piece or aspect of the larger Kubernetes open source project.
-long-description: >
+long-description: |
   Members within a SIG have a shared interest in advancing a specific area, such as architecture, API machinery, or documentation.
   SIGs must follow the [SIG Governance](https://github.com/kubernetes/community/blob/master/sig-governance.md) guidelines but can have their own contribution policy and channels of communication.
 

_data/glossary/statefulset.yml

@@ -1,5 +1,6 @@
 id: statefulset
 name: StatefulSet
+full-link: /docs/concepts/workloads/controllers/statefulset/
 aka:
 - PetSet
 related:
@@ -9,10 +10,9 @@ tags:
 - core-object
 - workload
 - storage
-short-description: |
+short-description: >
-  Manages the deployment and scaling of a set of [Pods](/docs/concepts/workloads/pods/pod), *and provides guarantees about the ordering and uniqueness* of these Pods.
+  Manages the deployment and scaling of a set of {% glossary_tooltip text="Pods" term_id="pod" %}, *and provides guarantees about the ordering and uniqueness* of these Pods.
-
 long-description: |
-  Like a [Deployment](/docs/concepts/workloads/controllers/deployment), a StatefulSet manages Pods that are based on an identical container spec. Unlike a Deployment, a StatefulSet maintains a sticky identity for each of their Pods. These pods are created from the same spec, but are not interchangeable: each has a persistent identifier that it maintains across any rescheduling.
+  Like a {% glossary_tooltip term_id="deployment" %}, a StatefulSet manages Pods that are based on an identical container spec. Unlike a Deployment, a StatefulSet maintains a sticky identity for each of their Pods. These pods are created from the same spec, but are not interchangeable: each has a persistent identifier that it maintains across any rescheduling.
 
   A StatefulSet operates under the same pattern as any other Controller. You define your desired state in a StatefulSet *object*, and the StatefulSet *controller* makes any necessary updates to get there from the current state.

_data/glossary/upstream.yaml

@@ -4,7 +4,7 @@ related:
 - downstream
 tags:
 - community
-short-description: |
+short-description: >
   May refer to: core Kubernetes or the source repo from which a repo was forked.
 long-description: |
   * In the **Kubernetes Community**: Conversations often use *upstream* to mean the core Kubernetes codebase, which the general ecosystem, other code, or third-party tools relies upon. For example, [community members](#term-member) may suggest that a feature is moved upstream so that it is in the core codebase instead of in a plugin or third-party tool.

_data/glossary/wg.yaml

@@ -1,9 +1,10 @@
 id: wg
 name: WG (working group)
+full-link: https://github.com/kubernetes/community/blob/master/sig-list.md#master-working-group-list
 tags:
 - community
-short-description: |
+short-description: >
-  Facilitates the discussion and/or implementation of a short-lived, narrow, or decoupled project for a committee, [SIG](#term-sig), or cross-SIG effort.
+  Facilitates the discussion and/or implementation of a short-lived, narrow, or decoupled project for a committee, {% glossary_tooltip text="SIG" term_id="sig" %}, or cross-SIG effort.
 long-description: |
   Working groups are a way of organizing people to accomplish a discrete task, and are relatively easy to create and deprecate when inactive.
 

_includes/head.html

@@ -8,6 +8,7 @@
     <link rel="stylesheet" type="text/css" href="/css/jquery-ui.min.css">
     <link rel="stylesheet" type="text/css" href="/css/sweetalert.css">
     <link rel="stylesheet" type="text/css" href="/css/callouts.css">
+    <link rel="stylesheet" type="text/css" href="/css/custom-jekyll/tags.css">
     {% if page.deprecated %}<link rel="stylesheet" type="text/css" href="/css/deprecation-warning.css">{% endif %}
     {% if page.class == "gridPage" %}<link rel="stylesheet" type="text/css" href="/css/gridpage.css">{% endif %}
     {% if page.css %}<link rel="stylesheet" type="text/css" href="{{ page.css }}"><!-- custom css added -->{% else %}<!-- no custom css detected -->{% endif %}
@@ -23,5 +24,6 @@
     <script src="/js/script.js"></script>
     <script src="/js/sweetalert.min.js"></script>
     <script src="/js/bootstrap.min.js"></script>
+    <script src="/js/custom-jekyll/tags.js"></script>
     {% seo %}
 </head>

_includes/templates/glossary/snippet.md

@@ -1,10 +1,10 @@
-{% assign term_data = site.data.glossary.[include.term] %}
+{% assign term_data = site.data.glossary.[include.term_id] %}
 
 {% if include.length == "all" or include.length == "short" %}
 
 {% if term_data.short-description %}
 
-{{ term_data.short-description | markdownify }}
+{{ term_data.short-description | liquify | markdownify }}
 
 {% else %}
 
@@ -18,7 +18,7 @@
 
 {% if term_data.long-description %}
 
-{{ term_data.long-description | markdownify }}
+{{ term_data.long-description | liquify | markdownify }}
 
 {% else %}
 

_plugins/README.md

@@ -0,0 +1,75 @@
+# Custom Jekyll Plugins
+
+This directory contains `*.rb` files that extend the original Jekyll classes and provide custom formatting for the docs site:
+
+### `glossary_tags.rb`
+
+A full list of glossary terms is available on the [Standardized Glossary](https://kubernetes.io/docs/reference/glossary/?fundamental=true) page. For further information about term schemas, see the [README](../_includes/templates/glossary/README.md) and the provided [`_example.yml`](../_data/glossary/_example.yml).
+
+*NOTE: The "tags" referenced here are Liquid tags like `{% include %}`, **not** the glossary canonical tags that are used to categorize terms.*
+
+#### (1) `glossary_definition` tag
+
+This renders the definition of the glossary term inside a `<div>`, preserving Markdown formatting where possible. It uses the [`snippet.md` template](../_includes/templates/glossary/snippet.md).
+
+**Usage:**
+
+```
+{% glossary_definition term_id="helm-chart" length="all" %}
+```
+
+**Parameters:**
+
+
+| Name | Default | Description |
+| --- | --- | --- |
+| `term_id` | N/A (Required) | The `id` of the glossary term whose definition will be used. (This `id` is the same as the filename of the term, i.e. `_data/glossary/<ID>.yml`.) |
+| `length` | "short" | Specifies which term definition should be used ("short" for the `short-definition`, "long" for `long-description`, "all" when both should be included). |
+
+#### (2) `glossary_tooltip` tag
+
+This renders the glossary term with a tooltip--when the term is moused over by the user, its definition is displayed above.
+
+**Usage:**
+
+```
+{% glossary_tooltip text="Helm Charts" term_id="helm-chart" %}
+```
+
+This renders the following:
+
+![glossary-tooltip](../images/metadocs/jekyll-tags-glossary-tooltip.png)
+
+**Parameters:**
+
+
+| Name | Default | Description |
+| --- | --- | --- |
+| `text` | the `name` of the glossary term | The text that the user will hover over to display the glossary definition. **You should include this if using the tooltip inside of a glossary term's YAML short-definition.** |
+| `term_id` | N/A (Required) | The `id` of the associated glossary term. (This `id` is the same as the filename of the term, i.e. `_data/glossary/<ID>.yml`.) |
+
+#### (3) `glossary_injector` tag
+
+This takes the definition of the term specified by the `term_id` and uses it to populate the contents of another HTML element specified by `placeholder_id`.
+
+**Usage:**
+
+```
+{% glossary_injector term_id="kubectl" placeholder_id="def-container" length="short" %}
+```
+
+This renders the following:
+
+![glossary-injector](../images/metadocs/jekyll-tags-glossary-injector.gif)
+
+*NOTE: Neither the placeholder nor the term's styling/CSS is determined by this Jekyll tag. You will need to specify this yourself in your Markdown/HTML files, i.e. by assigning a custom class.*
+
+**Parameters:**
+
+
+| Name | Default | Description |
+| --- | --- | --- |
+| `text` | the `name` of the glossary term | The text that the user will hover over to display the glossary definition. |
+| `term_id` | N/A (Required) | The `id` of the glossary term whose definition will be used. (This `id` is the same as the filename of the term, i.e. `_data/glossary/<ID>.yml`.) |
+| `placeholder_id` | N/A (Required) | The `id` of  the HTML element whose contents will be populated with the definition of `term_id` |
+| `length` | "short" | Specifies which term definition should be used ("short" for the `short-definition`, "long" for `long-description`, "all" when both should be included). |

_plugins/glossary_tags.rb

@@ -0,0 +1,122 @@
+# See /_plugins/README.md for full documentation of these custom Jekyll tags
+module Jekyll
+  module GlossaryTags
+    # Base class for tags (not to be instantiated)
+    class Base < Liquid::Tag
+      VALID_PARAM_NAMES = []
+      LENGTH_SHORT = "short"
+      LENGTH_LONG = "long"
+      SNIPPET_TEMPLATE = "templates/glossary/snippet.md"
+
+      def initialize(tag_name, markup, options)
+        super
+        @args = {}
+        @markup.scan(/([\S]+=['"][^=]+["'])+/).each do |arg|
+          key, val = arg.first.split("=")
+          key = key.to_sym
+          next unless val
+          if self.class::VALID_PARAM_NAMES.include?(key)
+            @args[key] = val.gsub("\"", "")
+          end
+        end
+      end
+
+      # "abstract" method
+      def render(context)
+        raise NotImplementedError
+      end
+
+      protected
+
+      def glossary_term_info(context)
+        global_glossary_hash = context.registers[:site].data["glossary"]
+        unless global_glossary_hash.keys.to_set.include?(@args[:term_id])
+          raise StandardError,
+            "#{@args[:term_id]} is not a valid glossary term id. Please " \
+            "see ./_data/glossary/* for the complete list."
+        end
+        global_glossary_hash[@args[:term_id]]
+      end
+
+      def include_snippet(context)
+        @args[:length] ||= LENGTH_SHORT
+        clean_markup = @args.keys.map { |k| "#{k}=\"#{@args[k]}\"" }.join(" ")
+
+        Jekyll::Tags::IncludeTag.parse(
+          "include",
+          "#{SNIPPET_TEMPLATE} #{clean_markup}",
+          nil,
+          @parse_context
+        ).render(context)
+      end
+    end
+
+    # Tag for displaying a glossary term's definition inline
+    class Definition < Base
+      VALID_PARAM_NAMES = [
+        :term_id,
+        :length
+      ].freeze
+
+      def render(context)
+        include_snippet(context)
+      end
+    end
+
+    # Tag to display a tooltip for a specific glossary term
+    class Tooltip < Base
+      VALID_PARAM_NAMES = [
+        :text,
+        :term_id
+      ].freeze
+      GLOSSARY_HOME = "/docs/reference/glossary/?all=true"
+      NESTED_TOOLTIPS = /{% (.*?text="(.*?)".*?) %}/
+      NESTED_MARKDOWN_LINKS = /(\[(.*?)\]\(.*?\))/
+
+      def render(context)
+        term_info = glossary_term_info(context)
+        external_link =
+          term_info["full-link"] ||
+          "#{GLOSSARY_HOME}#term-#{term_info["id"]}"
+        tooltip = term_info["short-description"].
+          gsub(NESTED_TOOLTIPS, '\2').
+          gsub(NESTED_MARKDOWN_LINKS, '\2').
+          strip
+
+        "<a class='glossary-tooltip' href='#{external_link}'>" \
+        "#{@args[:text] || term_info["name"]}" \
+        "<span class='tooltip-text'>" \
+        "#{tooltip}" \
+        "</span>" \
+        "</a>"
+      end
+    end
+
+    # Tag to inject a glossary term definition into another HTML element
+    class Injector < Base
+      VALID_PARAM_NAMES = [
+        :text,
+        :term_id,
+        :placeholder_id,
+        :length
+      ].freeze
+      RENDERED_DESCRIPTION_BLOCK = /.*<p>(.+)<\/p>.*/
+
+      def render(context)
+        term_info = glossary_term_info(context)
+        description = RENDERED_DESCRIPTION_BLOCK.match(include_snippet(context))[1]
+
+        "<span class='glossary-injector' data-placeholder-id='#{@args[:placeholder_id]}'>" \
+        "#{@args[:text] || term_info["name"]}" \
+        "<span class='injector-def hide'>" \
+        "#{description}" \
+        "</span>" \
+        "</span>"
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag('glossary_definition', Jekyll::GlossaryTags::Definition)
+Liquid::Template.register_tag('glossary_tooltip', Jekyll::GlossaryTags::Tooltip)
+Liquid::Template.register_tag('glossary_injector', Jekyll::GlossaryTags::Injector)

_plugins/liquify_filter.rb

@@ -0,0 +1,10 @@
+# Filter to force liquid parsing
+module Jekyll
+  module LiquifyFilter
+    def liquify(input)
+      Liquid::Template.parse(input).render(@context)
+    end
+  end
+end
+
+Liquid::Template.register_filter(Jekyll::LiquifyFilter)

css/custom-jekyll/tags.css

@@ -0,0 +1,56 @@
+.no-underline {
+  text-decoration: none !important;
+}
+
+.hide {
+  display: none !important;
+}
+
+/* Tooltip container */
+.glossary-tooltip {
+    position: relative;
+    display: inline-block;
+    border-bottom: 1px dotted black; /* If you want dots under the hoverable text */
+    color: black;
+    text-decoration: none !important;
+}
+
+/* Tooltip text */
+.glossary-tooltip .tooltip-text {
+    visibility: hidden;
+    width: 300px;
+    background-color: #555;
+    color: #fff;
+    text-align: center;
+    padding: 5px 8px;
+    border-radius: 6px;
+
+    /* Position the tooltip text */
+    position: absolute;
+    z-index: 1;
+    bottom: 125%;
+    left: 50%;
+    margin-left: -150px;
+
+    /* Fade in tooltip */
+    opacity: 0;
+    transition: opacity 0.3s;
+}
+
+/* Tooltip arrow */
+.glossary-tooltip .tooltip-text::after {
+    content: "";
+    position: absolute;
+    top: 100%;
+    left: 50%;
+    margin-left: -5px;
+    border-width: 5px;
+    border-style: solid;
+    border-color: #555 transparent transparent transparent;
+}
+
+/* Show the tooltip text when you mouse over the tooltip container */
+.glossary-tooltip:hover .tooltip-text {
+    visibility: visible;
+    opacity: 1;
+}

css/glossary.css

@@ -2,14 +2,6 @@
   display: inline;
 }
 
-.no-underline {
-  text-decoration: none !important;
-}
-
-.hide {
-  display: none !important;
-}
-
 .permalink {
   background-image: url(../images/link.png);
   background-repeat: no-repeat;

docs/concepts/services-networking/ingress.md

@@ -5,7 +5,7 @@ title: Ingress
 ---
 
 {% capture overview %}
-{% include templates/glossary/snippet.md term="ingress" length="all" %}
+{% glossary_definition term_id="ingress" length="all" %}
 {% endcapture %}
 
 {% capture body %}

docs/concepts/workloads/controllers/statefulset.md

@@ -10,10 +10,10 @@ title: StatefulSets
 ---
 
 {% capture overview %}
-**StatefulSet is the workload API object used to manage stateful applications. 
+**StatefulSet is the workload API object used to manage stateful applications.
 StatefulSets are beta in 1.8.**
 
-{% include templates/glossary/snippet.md term="statefulset" length="all" %}
+{% glossary_definition term_id="statefulset" length="all" %}
 {% endcapture %}
 
 {% capture body %}

docs/reference/glossary.md

@@ -56,9 +56,10 @@ default_active_tag: fundamental
 Also known as: <i>{{ term.aka | join: ", " }}</i>
 <br>
 {% endif %}
-<span class="preview-text">{{ term.short-description | markdownify }} <a href="javascript:void(0)" class="click-controller no-underline" data-target="{{ term.id }}">[+]</a></span>
+
+<span class="preview-text">{{ term.short-description | liquify | markdownify }} <a href="javascript:void(0)" class="click-controller no-underline" data-target="{{ term.id }}">[+]</a></span>
 <div id="{{ term.id }}" class="hide">
-{{ term.long-description | markdownify }}
+{{ term.long-description | liquify | markdownify }}
 </div>
 </div>
 </li>

docs/search.md

@@ -2,8 +2,11 @@
 layout: docwithnav
 title: Search Results
 ---
-<script>
+<script type="text/javascript">
+  document.write('<gcse:searchresults-only linktarget="_parent"></gcse:searchresults-only>');
+</script>
 
+<script>
   (function() {
     var cx = '013288817511911618469:elfqqbqldzg';
     var gcse = document.createElement('script');
@@ -17,4 +20,3 @@ title: Search Results
     document.querySelector('html').classList.add('search');
   })();
 </script>
-<gcse:searchresults-only linktarget="_parent"></gcse:searchresults-only>

docs/tasks/configure-pod-container/assign-memory-resource.md

@@ -124,12 +124,14 @@ Pod's 200 MiB limit.
 }
 ```
 
+
 Delete your Pod:
 
 ```shell
 kubectl delete pod memory-demo --namespace=mem-example
 ```
 
+
 ## Exceed a Container's memory limit
 
 A Container can exceed its memory request if the Node has memory available. But a Container
@@ -370,4 +372,3 @@ kubectl delete namespace mem-example
 
 
 {% include templates/task.md %}
-

docs/tasks/inject-data-application/define-command-argument-container.md

@@ -5,7 +5,7 @@ title: Define a Command and Arguments for a Container
 {% capture overview %}
 
 This page shows how to define commands and arguments when you run a container
-in a Kubernetes Pod.
+in a {% glossary_tooltip term_id="pod" %}.
 
 {% endcapture %}
 

js/custom-jekyll/tags.js

@@ -0,0 +1,15 @@
+$( document ).ready(function() {
+  // Shows permalink when term name is hovered over
+  $(".glossary-injector").each(function() {
+    var placeholder = $("#" + $(this).data("placeholder-id"));
+    var originalContent = placeholder.html();
+
+    var glossaryDef = $($(this).find(".injector-def")[0]).html();
+
+    $(this).mouseenter(function() {
+      placeholder.html(glossaryDef);
+    }).mouseleave(function(){
+      placeholder.html(originalContent);
+    });
+  });
+});