Add support for an auto-generated See Also section on every page. (#1364)

- We now automatically generate a See Also section on pages when possible.
The links are determined by a reverse index based on the keywords
assigned to each page in its front-matter.

- Do a pass to assign keywords to all our pages to populate the See Also
links.

- Leverage the keywords in the front-matter to generate a keyword metadata entry for each
generated page.
This commit is contained in:
Martin Taillefer 2018-06-11 15:07:32 -07:00 committed by GitHub
parent 9e9bcb2d5d
commit 9f3e980147
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
73 changed files with 107 additions and 16 deletions

View File

@ -25,3 +25,21 @@ enableEmoji = true
[outputs]
home = ["HTML"]
section = ["HTML"]
[related]
# Only include matches with rank >= threshold. This is a normalized rank between 0 and 100.
threshold = 80
# To get stable "See also" sections we, by default, exclude newer related pages.
includeNewer = true
# Will lower case keywords in both queries and in the indexes.
toLower = false
[[related.indices]]
name = "keywords"
weight = 150
[[related.indices]]
name = "tags"
weight = 100

View File

@ -84,20 +84,21 @@ chunk of front matter you should start with:
```yaml
---
title: <title>
description: <overview>
weight: <order>
description: <description>
weight: <weight>
keywords: [keyword1,keyword2,...]
---
```
Copy the above at the start of your new markdown file and update
the `<title>`, `<description>` and `<weight>` fields for your particular file. The available front
matter fields are:
Copy the above at the start of your new markdown file and update the information fields.
The available front matter fields are:
|Field | Description
|---------------|------------
|`title` | The short title of the page
|`description` | A one-line description of what the topic is about
|`weight` | An integer used to determine the sort order of this page relative to other pages in the same directory.
|`weight` | An integer used to determine the sort order of this page relative to other pages in the same directory
|`keywords` | An array of keywords describing the page, used to create the web of See Also links
|`draft` | When true, prevents the page from showing up in any navigation area
|`publishdate` | For blog posts, indicates the date of publication of the post
|`subtitle` | For blog posts, supplies an optional subtitle to be displayed below the main title

View File

@ -4,6 +4,7 @@ description: Using Istio to create autoscaled canary deployments
publishdate: 2017-06-14
attribution: Frank Budinsky
weight: 98
keywords: [traffic-management,canary]
aliases:
- /blog/canary-deployments-using-istio.html
---

View File

@ -5,6 +5,7 @@ publishdate: 2017-11-03
subtitle: Extending Istio to integrate with a world of infrastructure backends
attribution: Martin Taillefer
weight: 95
keywords: [adapters,mixer,policies,telemetry]
aliases:
- /blog/mixer-adapter-model.html
---

View File

@ -4,6 +4,7 @@ description: Improving availability and reducing latency
publishdate: 2017-12-07
subtitle: Improving availability and reducing latency
attribution: Martin Taillefer
keywords: [adapters,mixer,policies,telemetry,availability,latency]
weight: 94
aliases:
- /blog/posts/2017/mixer-spof-myth.html

View File

@ -5,6 +5,7 @@ publishdate: 2018-04-20
subtitle: Ingress AWS Network Load Balancer
attribution: Julien SENON
weight: 89
keywords: [ingress,traffic-management,aws]
---
This post provides instructions to use and configure ingress Istio with [AWS Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html).

View File

@ -5,6 +5,7 @@ publishdate: 2018-01-31
subtitle: Egress Rules for HTTPS traffic
attribution: Vadim Eisenberg
weight: 93
keywords: [traffic-management,egress,https]
---
In many cases, not all the parts of a microservices-based application reside in a _service mesh_. Sometimes, the microservices-based applications use functionality provided by legacy systems that reside outside the mesh. We may want to migrate these systems to the service mesh gradually. Until these systems are migrated, they must be accessed by the applications inside the mesh. In other cases, the applications use web services provided by external organizations, often over the World Wide Web.

View File

@ -5,6 +5,7 @@ publishdate: 2018-02-06
subtitle: Egress rules for TCP traffic
attribution: Vadim Eisenberg
weight: 92
keywords: [traffic-management,egress,tcp]
---
In my previous blog post, [Consuming External Web Services](/blog/2018/egress-https/), I described how external services can be consumed by in-mesh Istio applications via HTTPS. In this post, I demonstrate consuming external services over TCP. I use the [Istio Bookinfo sample application](/docs/guides/bookinfo/), the version in which the book ratings data is persisted in a MySQL database. I deploy this database outside the cluster and configure the _ratings_ microservice to use it. I define an [egress rule](/docs/reference/config/istio.routing.v1alpha1/#EgressRule) to allow the in-mesh applications to access the external database.

View File

@ -5,6 +5,7 @@ publishdate: 2018-04-19
subtitle: Using multiple Istio control planes and RBAC to create multi-tenancy
attribution: John Joyce and Rich Curran
weight: 90
keywords: [tenancy]
---
Multi-tenancy is commonly used in many environments across many different applications,

View File

@ -5,6 +5,7 @@ publishdate: 2018-02-08
subtitle: Routing rules for HTTP traffic
attribution: Christian Posta
weight: 91
keywords: [traffic-management,mirroring]
---
Trying to enumerate all the possible combinations of test cases for testing services in non-production/test environments can be daunting. In some cases, you'll find that all of the effort that goes into cataloging these use cases doesn't match up to real production use cases. Ideally, we could use live production use cases and traffic to help illuminate all of the feature areas of the service under test that we might miss in more contrived testing environments.

View File

@ -5,6 +5,7 @@ publishdate: 2018-04-25
subtitle:
attribution: Frank Budinsky (IBM) and Shriram Rajagopalan (VMware)
weight: 88
keywords: [traffic-management]
---
Up until now, Istio has provided a simple API for traffic management using four configuration resources:

View File

@ -1,6 +1,7 @@
---
title: Community
description: Information on the various ways to participate and interact with the Istio community.
keywords: [community]
sidebar_none: true
---
Istio is an open source project with an active community that supports its use and on-going development. We'd love for you

View File

@ -2,6 +2,7 @@
title: Configuration
description: An overview of the key concepts used to configure Istio's policy enforcement and telemetry collection features.
weight: 30
keywords: [policies,telemetry,control,config]
aliases:
- /docs/concepts/policy-and-control/mixer-config.html
- /docs/concepts/policy-and-control/attributes.html

View File

@ -2,6 +2,7 @@
title: Overview
description: Describes the design of the policy and telemetry mechanisms.
weight: 5
keywords: [policies,telemetry,control]
aliases:
- /docs/concepts/policy-and-control/mixer.html
---

View File

@ -2,6 +2,7 @@
title: Authentication Policy
description: Describes Istio's authentication policy
weight: 10
keywords: [security,authentication]
aliases:
- /docs/concepts/network-and-auth/auth.html
---

View File

@ -1,6 +1,7 @@
---
title: Mutual TLS Authentication
description: Describes Istio's mutual TLS authentication architecture which provides a strong service identity and secure communication channels between services.
keywords: [security,mutual-tls]
weight: 10
---

View File

@ -2,6 +2,7 @@
title: Istio Role-Based Access Control (RBAC)
description: Describes Istio RBAC which provides access control for services in Istio Mesh.
weight: 20
keywords: [security,rbac,authorization]
---
## Overview

View File

@ -2,6 +2,7 @@
title: Fault Injection
description: Introduces the idea of systematic fault injection that can be used to uncover conflicting failure recovery policies across services.
weight: 40
keywords: [traffic-management,fault-injection]
---
While Envoy sidecar/proxy provides a host of

View File

@ -2,6 +2,7 @@
title: Handling Failures
description: An overview of failure recovery capabilities in Envoy that can be leveraged by unmodified applications to improve robustness and prevent cascading failures.
weight: 30
keywords: [traffic-management,handling-failures]
---
Envoy provides a set of out-of-the-box _opt-in_ failure recovery features

View File

@ -2,6 +2,7 @@
title: Discovery & Load Balancing
description: Describes how traffic is load balanced across instances of a service in the mesh.
weight: 25
keywords: [traffic-management,load-balancing]
---
This page describes how Istio load balances traffic across instances of a

View File

@ -2,6 +2,7 @@
title: Overview
description: Provides a conceptual overview of traffic management in Istio and the features it enables.
weight: 1
keywords: [traffic-management]
---
This page provides an overview of how traffic management works

View File

@ -2,6 +2,7 @@
title: Pilot
description: Introduces Pilot, the component responsible for managing a distributed deployment of Envoy proxies in the service mesh.
weight: 10
keywords: [traffic-management,pilot]
aliases:
- /docs/concepts/traffic-management/manager.html
---

View File

@ -2,6 +2,7 @@
title: Request Routing
description: Describes how requests are routed between services in an Istio service mesh.
weight: 20
keywords: [traffic-management,routing]
---
This page describes how requests are routed between services in an Istio service mesh.

View File

@ -2,6 +2,7 @@
title: Rules Configuration
description: Provides a high-level overview of the configuration model used by Istio to configure traffic management rules in the service mesh.
weight: 50
keywords: [traffic-management,rules]
---
Istio provides a simple configuration model to

View File

@ -2,6 +2,7 @@
title: Integrating Virtual Machines
description: This sample deploys the Bookinfo services across Kubernetes and a set of virtual machines, and illustrates how to use the Istio service mesh to control this infrastructure as a single mesh.
weight: 60
keywords: [vms]
---
This sample deploys the Bookinfo services across Kubernetes and a set of

View File

@ -2,6 +2,7 @@
title: Intelligent Routing
description: This guide demonstrates how to use various traffic management capabilities of an Istio service mesh.
weight: 20
keywords: [traffic-management,routing]
---
This guide demonstrates how to use various traffic management capabilities

View File

@ -2,6 +2,7 @@
title: In-Depth Telemetry
description: This sample demonstrates how to obtain uniform metrics, logs, traces across different services using Istio Mixer and Istio sidecar.
weight: 30
keywords: [telemetry]
---
This sample demonstrates how to obtain uniform metrics, logs, traces across different services using Istio Mixer and Istio sidecar.

View File

@ -3,4 +3,5 @@ title: Nomad & Consul
description: Instructions for installing the Istio control plane in a Consul based environment, with or without Nomad.
weight: 20
type: section-index
keywords: [consul]
---

View File

@ -2,6 +2,7 @@
title: Installation
description: Instructions for installing the Istio control plane in a Consul based environment, with or without Nomad.
weight: 30
keywords: [consul]
---
> Setup on Nomad has not been tested.

View File

@ -2,6 +2,7 @@
title: Quick Start on Docker
description: Quick Start instructions to setup the Istio service mesh with Docker Compose.
weight: 10
keywords: [consul]
---
Quick Start instructions to install and configure Istio in a Docker Compose setup.

View File

@ -3,4 +3,5 @@ title: Eureka
description: Instructions for installing the Istio control plane in a Eureka based environment.
weight: 30
type: section-index
keywords: [eureka]
---

View File

@ -2,6 +2,7 @@
title: Installation
description: Instructions for installing the Istio control plane in an Eureka based environment.
weight: 30
keywords: [eureka]
---
Using Istio in a non-Kubernetes environment involves a few key tasks:

View File

@ -2,6 +2,7 @@
title: Quick Start on Docker
description: Quick Start instructions to setup the Istio service mesh with Docker Compose.
weight: 10
keywords: [eureka]
---
Quick Start instructions to install and configure Istio in a Docker Compose setup.

View File

@ -2,6 +2,7 @@
title: Kubernetes
description: Instructions for installing the Istio control plane on Kubernetes and adding VMs into the mesh.
weight: 10
keywords: [kubernetes]
type: section-index
aliases:
- /docs/tasks/installing-istio.html

View File

@ -1,8 +1,8 @@
---
title: Advanced Install Options
description: Instructions for customizing the Istio installation.
weight: 20
keywords: [kubernetes]
draft: true
---

View File

@ -2,6 +2,7 @@
title: Installation with Ansible
description: Install Istio with the included Ansible playbook.
weight: 40
keywords: [kubernetes,ansible]
---
Instructions for the installation and configuration of Istio using Ansible.

View File

@ -2,6 +2,7 @@
title: Installation with Helm
description: Install Istio with the included Helm chart.
weight: 30
keywords: [kubernetes,helm]
aliases:
- /docs/setup/kubernetes/helm.html
- /docs/tasks/integrating-services-into-istio.html

View File

@ -2,6 +2,7 @@
title: Mesh Expansion
description: Instructions for integrating VMs and bare metal hosts into an Istio mesh deployed on Kubernetes.
weight: 60
keywords: [kubernetes,vms]
---
Instructions for integrating VMs and bare metal hosts into an Istio mesh

View File

@ -2,6 +2,7 @@
title: Istio Multicluster
description: Install Istio with multicluster support.
weight: 65
keywords: [kubernetes,multicluster]
---
Instructions for the installation of Istio multicluster.

View File

@ -2,6 +2,7 @@
title: Quick Start with Google Kubernetes Engine
description: Quick Start instructions to setup the Istio service using Google Kubernetes Engine (GKE)
weight: 11
keywords: [kubernetes,gke]
---
Quick Start instructions to install and run Istio in [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/) (GKE) using [Google Cloud Deployment Manager](https://cloud.google.com/deployment-manager/).

View File

@ -2,6 +2,7 @@
title: Quick Start
description: Quick start instructions to setup the Istio service mesh in a Kubernetes cluster.
weight: 10
keywords: [kubernetes]
---
Quick start instructions to install and configure Istio in a Kubernetes cluster.

View File

@ -2,6 +2,7 @@
title: Installing the Istio Sidecar
description: Instructions for installing the Istio sidecar in application pods automatically using the sidecar injector webhook or manually using istioctl CLI.
weight: 50
keywords: [kubernetes,sidecar,sidecar-injection]
aliases:
- /docs/setup/kubernetes/automatic-sidecar-inject.html
---

View File

@ -2,6 +2,7 @@
title: Upgrading Istio
description: This guide demonstrates how to upgrade the Istio control plane and data plane independently.
weight: 70
keywords: [kubernetes,upgrading]
---
This page describes how to upgrade an existing Istio deployment (including both control plane and sidecar proxy) to a new release of Istio.

View File

@ -2,6 +2,7 @@
title: Enabling Rate Limits
description: This task shows you how to use Istio to dynamically limit the traffic to a service.
weight: 10
keywords: [policies,quotas]
aliases:
- /docs/tasks/rate-limiting.html
---

View File

@ -2,6 +2,7 @@
title: Basic Authentication Policy
description: Shows you how to use Istio authentication policy to setup mutual TLS and basic end-user authentication.
weight: 10
keywords: [security,authentication]
aliases:
- /docs/tasks/security/istio-auth.html
---

View File

@ -2,6 +2,7 @@
title: Basic Access Control
description: Shows how to control access to a service using the Kubernetes labels.
weight: 20
keywords: [security,access-control]
aliases:
- /docs/tasks/basic-access-control.html
---

View File

@ -2,6 +2,7 @@
title: Citadel health checking
description: Shows how to enable Citadel health checking with Kubernetes.
weight: 70
keywords: [security,health-check]
---
This task shows how to enable Kubernetes health checking for Citadel. Note this is an Alpha feature.

View File

@ -2,6 +2,7 @@
title: Mutual TLS over HTTPS
description: Shows how to enable mutual TLS on HTTPS services.
weight: 80
keywords: [security,mutual-tls,https]
---
This task shows how Istio Mutual TLS works with HTTPS services. It includes:

View File

@ -2,6 +2,7 @@
title: Testing Mutual TLS
description: Shows you how to verify and test Istio's automatic mutual TLS authentication.
weight: 10
keywords: [security,mutual-tls]
---
Through this task, you will learn how to:

View File

@ -2,6 +2,7 @@
title: Plugging in external CA key and certificate
description: Shows how operators can configure Citadel with existing root certificate, signing certificate and key.
weight: 60
keywords: [security,certificates]
---
This task shows how operators can configure Citadel with existing root certificate, signing certificate and key.

View File

@ -2,6 +2,7 @@
title: Role-Based Access Control
description: Shows how to set up role-based access control for services in Istio mesh.
weight: 40
keywords: [security,access-control,rbac]
---
This task shows how to set up role-based access control (RBAC) for services in Istio mesh. You can read more about Istio

View File

@ -2,6 +2,7 @@
title: Secure Access Control
description: Shows how to securely control access to a service using service accounts.
weight: 30
keywords: [security,access-control]
---
This task shows how to securely control access to a service,

View File

@ -2,6 +2,7 @@
title: Distributed Tracing
description: How to configure the proxies to send tracing requests to Zipkin or Jaeger
weight: 10
keywords: [telemetry,tracing]
aliases:
- /docs/tasks/zipkin-tracing.html
---

View File

@ -2,6 +2,7 @@
title: Logging with Fluentd
description: This task shows you how to configure Istio to log to a Fluentd daemon
weight: 60
keywords: [telemetry,logging]
---
This task shows how to configure Istio to create custom log entries

View File

@ -2,6 +2,7 @@
title: Collecting Metrics and Logs
description: This task shows you how to configure Istio to collect metrics and logs.
weight: 20
keywords: [telemetry,metrics]
aliases:
- /docs/tasks/metrics-logs.html
---

View File

@ -2,6 +2,7 @@
title: Querying Metrics from Prometheus
description: This task shows you how to query for Istio Metrics using Prometheus.
weight: 30
keywords: [telemetry,metrics]
---
This task shows you how to query for Istio Metrics using Prometheus. As part of

View File

@ -2,6 +2,7 @@
title: Generating a Service Graph
description: This task shows you how to generate a graph of services within an Istio mesh.
weight: 50
keywords: [telemetry,visualization]
---
This task shows you how to generate a graph of services within an Istio mesh.

View File

@ -2,6 +2,7 @@
title: Collecting Metrics for TCP services
description: This task shows you how to configure Istio to collect metrics for TCP services.
weight: 25
keywords: [telemetry,metrics,tcp]
---
This task shows how to configure Istio to automatically gather telemetry for TCP

View File

@ -2,6 +2,7 @@
title: Visualizing Metrics with Grafana
description: This task shows you how to setup and use the Istio Dashboard to monitor mesh traffic.
weight: 40
keywords: [telemetry,visualization]
---
This task shows you how to setup and use the Istio Dashboard to monitor mesh

View File

@ -1,6 +1,6 @@
---
title: Traffic Management
description: Describes tasks that demonstrate traffic routing features of Istio service mesh.
description: Tasks that demonstrate Istio's traffic routing features.
weight: 15
type: section-index
---

View File

@ -2,6 +2,7 @@
title: Circuit Breaking
description: This task demonstrates the circuit-breaking capability for resilient applications
weight: 50
keywords: [traffic-management,circuit-breaking]
---
> This task uses the new [v1alpha3 traffic management API](/blog/2018/v1alpha3-routing/). The old API has been deprecated and will be removed in the next Istio release. If you need to use the old version, follow the docs [here](https://archive.istio.io/v0.7/docs/tasks/traffic-management/).

View File

@ -2,6 +2,7 @@
title: Control Egress TCP Traffic
description: Describes how to configure Istio to route TCP traffic from services in the mesh to external services.
weight: 41
keywords: [traffic-management,egress,tcp]
---
> This task uses the new [v1alpha3 traffic management API](/blog/2018/v1alpha3-routing/). The old API has been deprecated and will be removed in the next Istio release. If you need to use the old version, follow the docs [here](https://archive.istio.io/v0.7/docs/tasks/traffic-management/).

View File

@ -4,6 +4,7 @@ description: Describes how to configure Istio to route traffic from services in
weight: 40
aliases:
- /docs/tasks/egress.html
keywords: [traffic-management,egress]
---
> This task uses the new [v1alpha3 traffic management API](/blog/2018/v1alpha3-routing/). The old API has been deprecated and will be removed in the next Istio release. If you need to use the old version, follow the docs [here](https://archive.istio.io/v0.7/docs/tasks/traffic-management/).

View File

@ -2,6 +2,7 @@
title: Fault Injection
description: This task shows how to inject delays and test the resiliency of your application.
weight: 20
keywords: [traffic-management,fault-injection]
aliases:
- /docs/tasks/fault-injection.html
---
@ -167,7 +168,3 @@ message.
* If you are not planning to explore any follow-on tasks, refer to the
[Bookinfo cleanup](/docs/guides/bookinfo/#cleanup) instructions
to shutdown the application.
## What's next
* Learn more about [fault injection](/docs/concepts/traffic-management/fault-injection/).

View File

@ -2,6 +2,7 @@
title: Control Ingress Traffic
description: Describes how to configure Istio to expose a service outside of the service mesh.
weight: 30
keywords: [traffic-management,ingress]
aliases:
- /docs/tasks/ingress.html
---

View File

@ -2,6 +2,7 @@
title: Mirroring
description: This task demonstrates the traffic shadowing/mirroring capabilities of Istio
weight: 60
keywords: [traffic-management,mirroring]
---
> This task uses the new [v1alpha3 traffic management API](/blog/2018/v1alpha3-routing/). The old API has been deprecated and will be removed in the next Istio release. If you need to use the old version, follow the docs [here](https://archive.istio.io/v0.7/docs/tasks/traffic-management/).

View File

@ -4,6 +4,7 @@ description: This task shows you how to configure dynamic request routing based
weight: 10
aliases:
- /docs/tasks/request-routing.html
keywords: [traffic-management,routing]
---
> This task uses the new [v1alpha3 traffic management API](/blog/2018/v1alpha3-routing/). The old API has been deprecated and will be removed in the next Istio release. If you need to use the old version, follow the docs [here](https://archive.istio.io/v0.7/docs/tasks/traffic-management/).

View File

@ -4,6 +4,7 @@ description: This task shows you how to setup request timeouts in Envoy using Is
weight: 28
aliases:
- /docs/tasks/request-timeouts.html
keywords: [traffic-management,timeouts]
---
> This task uses the new [v1alpha3 traffic management API](/blog/2018/v1alpha3-routing/). The old API has been deprecated and will be removed in the next Istio release. If you need to use the old version, follow the docs [here](https://archive.istio.io/v0.7/docs/tasks/traffic-management/).

View File

@ -2,6 +2,7 @@
title: Traffic Shifting
description: Shows you how to migrate traffic from an old to new version of a service.
weight: 25
keywords: [traffic-management,traffic-shifting]
aliases:
- /docs/tasks/traffic-management/version-migration.html
---

View File

@ -13,6 +13,12 @@
<meta name="title" content="{{ .Title }}">
<meta name="description" content="{{ template "description" . }}">
{{ if .Page.Params.keywords }}
<meta name="keywords" content="microservices,services,mesh,{{ delimit .Page.Params.keywords "," }}">
{{ else }}
<meta name="keywords" content="microservices,services,mesh">
{{ end }}
<!-- Open Graph protocol -->
<meta name="og:title" content="{{ .Title }}">
<meta name="og:description" content="{{ template "description" . }}">

View File

@ -1,2 +0,0 @@
{{ define "main" }}
{{ end }}

View File

@ -1,2 +0,0 @@
{{ define "main" }}
{{ end }}

View File

@ -1,6 +1,15 @@
{{ $toc := partial "toc.html" (dict "page" .) }}
{{ $needTOC := .Scratch.Get "needTOC" }}
{{ $related := .Site.RegularPages.Related . | first 5 }}
{{ with $related }}
<h2 id="see-also">See Also</h2>
<ul>
{{ range . }}
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a>. {{ .Description }}</li>
{{ end }}
</ul>
{{ end }}
</main>
{{ if or .NextInSection .PrevInSection }}