Revamp the glossary page. (#734)

- Better aesthetics.

- Can now navigate by clicking on a letter selector.

- Each word can now be linked to directly (although discoverability
could be better)

- The glossary is now referenced from the header.

- You can now find the glossary at istio.io/glossary

Gemfile.lock

@@ -23,7 +23,7 @@ GEM
     ffi (1.9.18)
     forwardable-extended (2.6.0)
     gemoji (3.0.0)
-    github-pages (167)
+    github-pages (169)
       activesupport (= 4.2.9)
       github-pages-health-check (= 1.3.5)
       jekyll (= 3.6.2)
@@ -201,7 +201,7 @@ GEM
     pathutil (0.16.0)
       forwardable-extended (~> 2.6)
     public_suffix (2.0.5)
-    rake (12.0.0)
+    rake (12.3.0)
     rb-fsevent (0.10.2)
     rb-inotify (0.9.10)
       ffi (>= 0.5.0, < 2)

_docs/reference/glossary.md

@@ -1,18 +0,0 @@
----
-title: Glossary
-overview: A glossary of common Istio terms.
-
-order: 40
-
-layout: docs
-type: markdown
----
-{% include home.html %}
-
-Here is a glossary of common Istio words and phrases.
-
-{% assign words = site.glossary | sort: "title" %}
-{% for w in words %}
-- **{{w.title}}**.
-{{w.content}}
-{% endfor %}

_glossary/istio-auth.md

@@ -1,6 +0,0 @@
----
-title: Istio mutual TLS Authentication
-type: markdown
----
-Provides strong service-to-service authentication using mutual TLS, with built-in identity and credential management.
-Learn more about [Istio mutual TLS authentication](../concepts/security/mutual-tls.html).

_glossary/mixer.md

@@ -2,4 +2,8 @@
 title: Mixer
 type: markdown
 ---
-The Istio component responsible for enforcing access control and usage policies across the **Service Mesh** and collecting telemetry data from **Envoy** and other services. [Learn more about Mixer](../concepts/policy-and-control/mixer.html).
+{% include home.html %}
+
+The Istio component responsible for enforcing access control and usage policies across the **Service Mesh** and collecting telemetry data
+from **Envoy** and other services.
+[Learn more about Mixer]({{home}}/docs/concepts/policy-and-control/mixer.html).

_glossary/mutual-tls.md

@@ -0,0 +1,8 @@
+---
+title: Mutual TLS Authentication
+type: markdown
+---
+{% include home.html %}
+
+Mutual TLS provides strong service-to-service authentication with built-in identity and credential management.
+Learn more about [mutual TLS authentication]({{home}}/docs/concepts/security/mutual-tls.html).

_includes/footer.html

@@ -20,6 +20,7 @@
                 <ul class="toggle">
                     <p class="header">Resources</p>
                     <li><a href="{{home}}/faq">Frequently Asked Questions</a></li>
+                    <li><a href="{{home}}/glossary">Glossary</a></li>
                     <li><a href="{{home}}/troubleshooting">Troubleshooting Guide</a></li>
                     <li><a href="{{home}}/bugs">Report a Bug</a></li>
                     <li><a href="https://github.com/istio/istio.github.io/issues/new?title=Issue with {{page.path}}">Report a Doc Issue</a></li>

_layouts/docs.html

@@ -19,7 +19,10 @@ layout: default
         </div>
 
         <div id="content-container" class="thin-left-border col-sm-9 {{ page.type }}">
-          <div id="toc" class="toc"></div>
+          {% if page.toc != false %}
+            <div id="toc" class="toc"></div>
+          {% endif %}
+
           <div id="doc-content">
             <h1>{{page.title}}</h1>
             {{ content }}

_layouts/glossary.html

@@ -0,0 +1,10 @@
+---
+layout: default
+---
+<div class="container glossary">
+    <div class="row">
+        <div class="col-sm-12 col-md-10 col-lg-7 nofloat center-block {{page.type}}">
+        {{ content }}
+        </div>
+    </div>
+</div>

_sass/layouts/_glossary.scss

@@ -0,0 +1,41 @@
+.glossary {
+  .trampolines {
+    font-size: $font-size--l;
+    text-align: center;
+    padding-top: 10px;
+  }
+
+  .entries {
+    h4 {
+      font-size: $font-size--m;
+      font-weight: 300;
+      border-bottom: 1px solid;
+      color: lighten($gray, 35%);
+      border-color: lighten($gray, 35%);
+      margin-top: 25px;
+      margin-bottom: 2px;
+    }
+
+    ul {
+      margin-left: 0px;
+
+      li {
+        margin-left: 30px
+      }
+
+      li.word {
+        font-weight: 600;
+        list-style-type: none;
+        margin-bottom: 0;
+        margin-top: 10px;
+        margin-left: 0;
+      }
+
+      li.definition {
+        list-style-type: none;
+        margin-top: 0px;
+        line-height: 130%;
+      }
+    }
+  }
+}

about/index.md

@@ -1,9 +1,6 @@
 ---
 title: About
 overview: About Istio.
-
-order: 0
-
 layout: about
 type: markdown
 ---

css/all.scss

@@ -24,6 +24,7 @@ sitemap_exclude: y
 @import "layouts/community";
 @import "layouts/docs";
 @import "layouts/faq";
+@import "layouts/glossary";
 @import "layouts/landing";
 @import "layouts/notfound";
 @import "layouts/post";

glossary/index.md

@@ -0,0 +1,46 @@
+---
+title: Glossary
+overview: A glossary of common Istio terms.
+layout: glossary
+type: markdown
+---
+{% include home.html %}
+
+# Glossary
+
+Common Istio words and phrases. Please [let us know](https://github.com/istio/istio.github.io/issues/new?title=Missing%20Glossary%20Entry) if you came here 
+looking for a definition and didn't find it.
+
+{% assign words = site.glossary | sort: "title" %}
+
+<div class="trampolines">
+  {% assign previous = "-" %}
+  {% for w in words %}
+    {% assign first = w.title | slice: 0 | upcase %}
+    {% if first != previous %}
+      {% if previous != "-" %}|{% endif %}
+
+      <a href="#{{first}}">{{first}}</a>  
+      {% assign previous = first %}
+    {% endif %}
+  {% endfor %}
+</div>
+
+<div class="entries">
+  {% assign previous = "-" %}
+  {% for w in words %}
+    {% assign first = w.title | slice: 0 | upcase %}
+    {% if first != previous %}
+      {% if previous != "-" %}</ul>{% endif %}
+      <h4 id="{{first}}">{{first}}</h4>
+      <ul>
+      {% assign previous = first %}
+    {% endif %}
+
+    {% assign title = w.title | downcase %}
+    <li class="word" id="{{title}}">{{w.title}}</li>
+    <li class="definition">{{w.content}}</li>
+  
+  {% endfor %}
+  </ul>
+</div>